1 /* Copyright 2002-2025 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.hipparchus.analysis.differentiation.UnivariateDerivative1;
20 import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
21 import org.orekit.frames.KinematicTransform;
22 import org.orekit.frames.TopocentricFrame;
23 import org.orekit.propagation.SpacecraftState;
24 import org.orekit.propagation.events.handlers.EventHandler;
25 import org.orekit.propagation.events.handlers.StopOnIncreasing;
26 import org.orekit.utils.TimeStampedPVCoordinates;
27
28 /** Detector for elevation extremum with respect to a ground point.
29 * <p>This detector identifies when a spacecraft reaches its
30 * extremum elevation with respect to a ground point.</p>
31 * <p>
32 * As in most cases only the elevation maximum is needed and the
33 * minimum is often irrelevant, this detector is often wrapped into
34 * an {@link EventSlopeFilter event slope filter} configured with
35 * {@link FilterType#TRIGGER_ONLY_DECREASING_EVENTS} (i.e. when the
36 * elevation derivative decreases from positive values to negative values,
37 * which correspond to a maximum). Setting up this filter saves some computation
38 * time as the elevation minimum occurrences are not even looked at. It is
39 * however still often necessary to do an additional filtering
40 * </p>
41 * @author Luc Maisonobe
42 * @since 7.1
43 */
44 public class ElevationExtremumDetector extends AbstractTopocentricDetector<ElevationExtremumDetector> {
45
46 /** Build a new detector.
47 * <p>The new instance uses default values for maximal checking interval
48 * ({@link #DEFAULT_MAX_CHECK}) and convergence threshold ({@link
49 * #DEFAULT_THRESHOLD}).</p>
50 * @param topo topocentric frame centered on ground point
51 */
52 public ElevationExtremumDetector(final TopocentricFrame topo) {
53 this(DEFAULT_MAX_CHECK, DEFAULT_THRESHOLD, topo);
54 }
55
56 /** Build a detector.
57 * @param maxCheck maximal checking interval (s)
58 * @param threshold convergence threshold (s)
59 * @param topo topocentric frame centered on ground point
60 */
61 public ElevationExtremumDetector(final double maxCheck, final double threshold,
62 final TopocentricFrame topo) {
63 this(new EventDetectionSettings(maxCheck, threshold, DEFAULT_MAX_ITER), new StopOnIncreasing(), topo);
64 }
65
66 /** Protected constructor with full parameters.
67 * <p>
68 * This constructor is not public as users are expected to use the builder
69 * API with the various {@code withXxx()} methods to set up the instance
70 * in a readable manner without using a huge amount of parameters.
71 * </p>
72 * @param detectionSettings event detection settings
73 * @param handler event handler to call at event occurrences
74 * @param topo topocentric frame centered on ground point
75 * @since 13.0
76 */
77 protected ElevationExtremumDetector(final EventDetectionSettings detectionSettings, final EventHandler handler,
78 final TopocentricFrame topo) {
79 super(detectionSettings, handler, topo);
80 }
81
82 /** {@inheritDoc} */
83 @Override
84 protected ElevationExtremumDetector create(final EventDetectionSettings detectionSettings,
85 final EventHandler newHandler) {
86 return new ElevationExtremumDetector(detectionSettings, newHandler, getTopocentricFrame());
87 }
88
89 /** Get the elevation value.
90 * @param s the current state information: date, kinematics, attitude
91 * @return spacecraft elevation
92 */
93 public double getElevation(final SpacecraftState s) {
94 return getTopocentricFrame().getElevation(s.getPosition(), s.getFrame(), s.getDate());
95 }
96
97 /** Compute the value of the detection function.
98 * <p>
99 * The value is the spacecraft elevation first time derivative.
100 * </p>
101 * @param s the current state information: date, kinematics, attitude
102 * @return spacecraft elevation first time derivative
103 */
104 public double g(final SpacecraftState s) {
105
106 // get position, velocity of spacecraft in topocentric frame
107 final KinematicTransform inertToTopo = s.getFrame().getKinematicTransformTo(getTopocentricFrame(), s.getDate());
108 final TimeStampedPVCoordinates pvTopo = inertToTopo.transformOnlyPV(s.getPVCoordinates());
109
110 // convert the coordinates to UnivariateDerivative1 based vector
111 // instead of having vector position, then vector velocity then vector acceleration
112 // we get one vector and each coordinate is a Taylor expansion containing
113 // value, first time derivative (we don't need second time derivative here)
114 final FieldVector3D<UnivariateDerivative1> positionUD1 = pvTopo.toUnivariateDerivative1Vector();
115
116 // compute elevation and its first time derivative
117 final UnivariateDerivative1 elevation = positionUD1.getDelta();
118
119 // return elevation first time derivative
120 return elevation.getFirstDerivative();
121
122 }
123
124 }