1   /* Copyright 2002-2024 CS GROUP
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    * CS 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.orekit.bodies.OneAxisEllipsoid;
20  import org.orekit.bodies.GeodeticPoint;
21  import org.orekit.propagation.SpacecraftState;
22  import org.orekit.propagation.events.handlers.EventHandler;
23  import org.orekit.propagation.events.handlers.StopOnIncreasing;
24  
25  /** Detector for geographic latitude crossing.
26   * <p>This detector identifies when a spacecraft crosses a fixed
27   * latitude with respect to a central body.</p>
28   * @author Luc Maisonobe
29   * @since 7.1
30   */
31  public class LatitudeCrossingDetector extends AbstractDetector<LatitudeCrossingDetector> {
32  
33      /** Body on which the latitude is defined. */
34      private OneAxisEllipsoid body;
35  
36      /** Fixed latitude to be crossed. */
37      private final double latitude;
38  
39      /** Build a new detector.
40       * <p>The new instance uses default values for maximal checking interval
41       * ({@link #DEFAULT_MAXCHECK}) and convergence threshold ({@link
42       * #DEFAULT_THRESHOLD}).</p>
43       * @param body body on which the latitude is defined
44       * @param latitude latitude to be crossed
45       */
46      public LatitudeCrossingDetector(final OneAxisEllipsoid body, final double latitude) {
47          this(DEFAULT_MAXCHECK, DEFAULT_THRESHOLD, body, latitude);
48      }
49  
50      /** Build a detector.
51       * @param maxCheck maximal checking interval (s)
52       * @param threshold convergence threshold (s)
53       * @param body body on which the latitude is defined
54       * @param latitude latitude to be crossed
55       */
56      public LatitudeCrossingDetector(final double maxCheck, final double threshold,
57                                      final OneAxisEllipsoid body, final double latitude) {
58          this(AdaptableInterval.of(maxCheck), threshold, DEFAULT_MAX_ITER, new StopOnIncreasing(),
59               body, latitude);
60      }
61  
62      /** Protected constructor with full parameters.
63       * <p>
64       * This constructor is not public as users are expected to use the builder
65       * API with the various {@code withXxx()} methods to set up the instance
66       * in a readable manner without using a huge amount of parameters.
67       * </p>
68       * @param maxCheck maximum checking interval
69       * @param threshold convergence threshold (s)
70       * @param maxIter maximum number of iterations in the event time search
71       * @param handler event handler to call at event occurrences
72       * @param body body on which the latitude is defined
73       * @param latitude latitude to be crossed
74       */
75      protected LatitudeCrossingDetector(final AdaptableInterval maxCheck, final double threshold,
76                                         final int maxIter, final EventHandler handler,
77                                         final OneAxisEllipsoid body, final double latitude) {
78          super(maxCheck, threshold, maxIter, handler);
79          this.body     = body;
80          this.latitude = latitude;
81      }
82  
83      /** {@inheritDoc} */
84      @Override
85      protected LatitudeCrossingDetector create(final AdaptableInterval newMaxCheck, final double newThreshold,
86                                                final int newMaxIter,
87                                                final EventHandler newHandler) {
88          return new LatitudeCrossingDetector(newMaxCheck, newThreshold, newMaxIter, newHandler,
89                                            body, latitude);
90      }
91  
92      /** Get the body on which the geographic zone is defined.
93       * @return body on which the geographic zone is defined
94       */
95      public OneAxisEllipsoid getBody() {
96          return body;
97      }
98  
99      /** Get the fixed latitude to be crossed (radians).
100      * @return fixed latitude to be crossed (radians)
101      */
102     public double getLatitude() {
103         return latitude;
104     }
105 
106     /** Compute the value of the detection function.
107      * <p>
108      * The value is the spacecraft latitude minus the fixed latitude to be crossed.
109      * It is positive if the spacecraft is northward and negative if it is southward
110      * with respect to the fixed latitude.
111      * </p>
112      * @param s the current state information: date, kinematics, attitude
113      * @return spacecraft latitude minus the fixed latitude to be crossed
114      */
115     public double g(final SpacecraftState s) {
116 
117         // convert state to geodetic coordinates
118         final GeodeticPoint gp = body.transform(s.getPosition(),
119                                                 s.getFrame(), s.getDate());
120 
121         // latitude difference
122         return gp.getLatitude() - latitude;
123 
124     }
125 
126 }