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 AbstractDetector<ElevationExtremumDetector> {
45
46 /** Topocentric frame in which elevation should be evaluated. */
47 private final TopocentricFrame topo;
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 topo topocentric frame centered on ground point
54 */
55 public ElevationExtremumDetector(final TopocentricFrame topo) {
56 this(DEFAULT_MAX_CHECK, DEFAULT_THRESHOLD, topo);
57 }
58
59 /** Build a detector.
60 * @param maxCheck maximal checking interval (s)
61 * @param threshold convergence threshold (s)
62 * @param topo topocentric frame centered on ground point
63 */
64 public ElevationExtremumDetector(final double maxCheck, final double threshold,
65 final TopocentricFrame topo) {
66 this(new EventDetectionSettings(maxCheck, threshold, DEFAULT_MAX_ITER), new StopOnIncreasing(), topo);
67 }
68
69 /** Protected constructor with full parameters.
70 * <p>
71 * This constructor is not public as users are expected to use the builder
72 * API with the various {@code withXxx()} methods to set up the instance
73 * in a readable manner without using a huge amount of parameters.
74 * </p>
75 * @param detectionSettings event detection settings
76 * @param handler event handler to call at event occurrences
77 * @param topo topocentric frame centered on ground point
78 * @since 13.0
79 */
80 protected ElevationExtremumDetector(final EventDetectionSettings detectionSettings, final EventHandler handler,
81 final TopocentricFrame topo) {
82 super(detectionSettings, handler);
83 this.topo = topo;
84 }
85
86 /** {@inheritDoc} */
87 @Override
88 protected ElevationExtremumDetector create(final EventDetectionSettings detectionSettings,
89 final EventHandler newHandler) {
90 return new ElevationExtremumDetector(detectionSettings, newHandler, topo);
91 }
92
93 /**
94 * Returns the topocentric frame centered on ground point.
95 * @return topocentric frame centered on ground point
96 */
97 public TopocentricFrame getTopocentricFrame() {
98 return this.topo;
99 }
100
101 /** Get the elevation value.
102 * @param s the current state information: date, kinematics, attitude
103 * @return spacecraft elevation
104 */
105 public double getElevation(final SpacecraftState s) {
106 return topo.getElevation(s.getPosition(), s.getFrame(), s.getDate());
107 }
108
109 /** Compute the value of the detection function.
110 * <p>
111 * The value is the spacecraft elevation first time derivative.
112 * </p>
113 * @param s the current state information: date, kinematics, attitude
114 * @return spacecraft elevation first time derivative
115 */
116 public double g(final SpacecraftState s) {
117
118 // get position, velocity of spacecraft in topocentric frame
119 final KinematicTransform inertToTopo = s.getFrame().getKinematicTransformTo(topo, s.getDate());
120 final TimeStampedPVCoordinates pvTopo = inertToTopo.transformOnlyPV(s.getPVCoordinates());
121
122 // convert the coordinates to UnivariateDerivative1 based vector
123 // instead of having vector position, then vector velocity then vector acceleration
124 // we get one vector and each coordinate is a DerivativeStructure containing
125 // value, first time derivative (we don't need second time derivative here)
126 final FieldVector3D<UnivariateDerivative1> pvDS = pvTopo.toUnivariateDerivative1Vector();
127
128 // compute elevation and its first time derivative
129 final UnivariateDerivative1 elevation = pvDS.getZ().divide(pvDS.getNorm()).asin();
130
131 // return elevation first time derivative
132 return elevation.getDerivative(1);
133
134 }
135
136 }