1 /* Copyright 2023-2025 Alberto Ferrero
2 * Licensed to CS GROUP (CS) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * Alberto Ferrero licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.orekit.propagation.events;
18
19 import org.hipparchus.util.FastMath;
20 import org.orekit.bodies.GeodeticPoint;
21 import org.orekit.bodies.OneAxisEllipsoid;
22 import org.orekit.propagation.SpacecraftState;
23 import org.orekit.propagation.events.handlers.EventHandler;
24 import org.orekit.propagation.events.handlers.StopOnDecreasing;
25
26
27 /** Detector for geographic latitude crossing.
28 * <p>This detector identifies when a spacecraft crosses a fixed
29 * latitude range with respect to a central body.</p>
30 * @author Alberto Ferrero
31 * @since 12.0
32 */
33 public class LatitudeRangeCrossingDetector extends AbstractDetector<LatitudeRangeCrossingDetector> {
34
35 /** Body on which the latitude is defined. */
36 private final OneAxisEllipsoid body;
37
38 /** Fixed latitude to be crossed, lower boundary in radians. */
39 private final double fromLatitude;
40
41 /** Fixed latitude to be crossed, upper boundary in radians. */
42 private final double toLatitude;
43
44 /**
45 * Sign, to get reversed inclusion latitude range (lower > upper).
46 */
47 private final double sign;
48
49 /** Build a new detector.
50 * <p>The new instance uses default values for maximal checking interval
51 * ({@link #DEFAULT_MAX_CHECK}) and convergence threshold ({@link
52 * #DEFAULT_THRESHOLD}).</p>
53 * @param body body on which the latitude is defined
54 * @param fromLatitude latitude to be crossed, lower range boundary
55 * @param toLatitude latitude to be crossed, upper range boundary
56 */
57 public LatitudeRangeCrossingDetector(final OneAxisEllipsoid body, final double fromLatitude, final double toLatitude) {
58 this(DEFAULT_MAX_CHECK, DEFAULT_THRESHOLD, body, fromLatitude, toLatitude);
59 }
60
61 /** Build a detector.
62 * @param maxCheck maximal checking interval (s)
63 * @param threshold convergence threshold (s)
64 * @param body body on which the latitude is defined
65 * @param fromLatitude latitude to be crossed, lower range boundary
66 * @param toLatitude latitude to be crossed, upper range boundary
67 */
68 public LatitudeRangeCrossingDetector(final double maxCheck, final double threshold,
69 final OneAxisEllipsoid body, final double fromLatitude, final double toLatitude) {
70 this(new EventDetectionSettings(maxCheck, threshold, DEFAULT_MAX_ITER), new StopOnDecreasing(),
71 body, fromLatitude, toLatitude);
72 }
73
74 /** Private constructor with full parameters.
75 * <p>
76 * This constructor is private as users are expected to use the builder
77 * API with the various {@code withXxx()} methods to set up the instance
78 * in a readable manner without using a huge amount of parameters.
79 * </p>
80 * @param detectionSettings event detection settings
81 * @param handler event handler to call at event occurrences
82 * @param body body on which the latitude is defined
83 * @param fromLatitude latitude to be crossed, lower range boundary
84 * @param toLatitude latitude to be crossed, upper range boundary
85 * @since 13.0
86 */
87 protected LatitudeRangeCrossingDetector(final EventDetectionSettings detectionSettings,
88 final EventHandler handler,
89 final OneAxisEllipsoid body, final double fromLatitude, final double toLatitude) {
90 super(detectionSettings, handler);
91 this.body = body;
92 this.fromLatitude = fromLatitude;
93 this.toLatitude = toLatitude;
94 this.sign = FastMath.signum(toLatitude - fromLatitude);
95 }
96
97 /** {@inheritDoc} */
98 @Override
99 protected LatitudeRangeCrossingDetector create(final EventDetectionSettings detectionSettings,
100 final EventHandler newHandler) {
101 return new LatitudeRangeCrossingDetector(detectionSettings, newHandler, body, fromLatitude, toLatitude);
102 }
103
104 /** Get the body on which the geographic zone is defined.
105 * @return body on which the geographic zone is defined
106 */
107 public OneAxisEllipsoid getBody() {
108 return body;
109 }
110
111 /** Get the fixed latitude range to be crossed (radians), lower boundary.
112 * @return fixed lower boundary latitude range to be crossed (radians)
113 */
114 public double getFromLatitude() {
115 return fromLatitude;
116 }
117
118 /** Get the fixed latitude range to be crossed (radians), upper boundary.
119 * @return fixed lower boundary latitude range to be crossed (radians)
120 */
121 public double getToLatitude() {
122 return toLatitude;
123 }
124
125 /** Compute the value of the detection function.
126 * <p>
127 * The value is positive if the spacecraft latitude is inside the latitude range.
128 * It is positive if the spacecraft is northward to lower boundary range and southward to upper boundary range,
129 * with respect to the fixed latitude range.
130 * </p>
131 * @param s the current state information: date, kinematics, attitude
132 * @return positive if spacecraft inside the range
133 */
134 public double g(final SpacecraftState s) {
135
136 // convert state to geodetic coordinates
137 final GeodeticPoint gp = body.transform(s.getPVCoordinates().getPosition(),
138 s.getFrame(), s.getDate());
139
140 // point latitude
141 final double latitude = gp.getLatitude();
142
143 // inside or outside latitude range
144 return sign * (latitude - fromLatitude) * (toLatitude - latitude);
145
146 }
147
148 }