1   /* Copyright 2023-2024 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_MAXCHECK}) 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_MAXCHECK, 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(AdaptableInterval.of(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 maxCheck maximum checking interval (s)
81       * @param threshold convergence threshold (s)
82       * @param maxIter maximum number of iterations in the event time search
83       * @param handler event handler to call at event occurrences
84       * @param body body on which the latitude is defined
85       * @param fromLatitude latitude to be crossed, lower range boundary
86       * @param toLatitude latitude to be crossed, upper range boundary
87       */
88      protected LatitudeRangeCrossingDetector(final AdaptableInterval maxCheck, final double threshold, final int maxIter,
89                                              final EventHandler handler,
90                                              final OneAxisEllipsoid body, final double fromLatitude, final double toLatitude) {
91          super(maxCheck, threshold, maxIter, handler);
92          this.body     = body;
93          this.fromLatitude = fromLatitude;
94          this.toLatitude = toLatitude;
95          this.sign = FastMath.signum(toLatitude - fromLatitude);
96      }
97  
98      /** {@inheritDoc} */
99      @Override
100     protected LatitudeRangeCrossingDetector create(final AdaptableInterval newMaxCheck,
101                                                    final double newThreshold,
102                                                    final int newMaxIter,
103                                                    final EventHandler newHandler) {
104         return new LatitudeRangeCrossingDetector(newMaxCheck, newThreshold, newMaxIter, newHandler,
105             body, fromLatitude, toLatitude);
106     }
107 
108     /** Get the body on which the geographic zone is defined.
109      * @return body on which the geographic zone is defined
110      */
111     public OneAxisEllipsoid getBody() {
112         return body;
113     }
114 
115     /** Get the fixed latitude range to be crossed (radians), lower boundary.
116      * @return fixed lower boundary latitude range to be crossed (radians)
117      */
118     public double getFromLatitude() {
119         return fromLatitude;
120     }
121 
122     /** Get the fixed latitude range to be crossed (radians), upper boundary.
123      * @return fixed lower boundary latitude range to be crossed (radians)
124      */
125     public double getToLatitude() {
126         return toLatitude;
127     }
128 
129     /** Compute the value of the detection function.
130      * <p>
131      * The value is positive if the spacecraft latitude is inside the latitude range.
132      * It is positive if the spacecraft is northward to lower boundary range and southward to upper boundary range,
133      * with respect to the fixed latitude range.
134      * </p>
135      * @param s the current state information: date, kinematics, attitude
136      * @return positive if spacecraft inside the range
137      */
138     public double g(final SpacecraftState s) {
139 
140         // convert state to geodetic coordinates
141         final GeodeticPoint gp = body.transform(s.getPVCoordinates().getPosition(),
142             s.getFrame(), s.getDate());
143 
144         // point latitude
145         final double latitude = gp.getLatitude();
146 
147         // inside or outside latitude range
148         return sign * (latitude - fromLatitude) * (toLatitude - latitude);
149 
150     }
151 
152 }