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