ElevationExtremumDetector.java

  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. import org.hipparchus.analysis.differentiation.UnivariateDerivative1;
  19. import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
  20. import org.orekit.frames.KinematicTransform;
  21. import org.orekit.frames.TopocentricFrame;
  22. import org.orekit.propagation.SpacecraftState;
  23. import org.orekit.propagation.events.handlers.EventHandler;
  24. import org.orekit.propagation.events.handlers.StopOnIncreasing;
  25. import org.orekit.utils.TimeStampedPVCoordinates;

  26. /** Detector for elevation extremum with respect to a ground point.
  27.  * <p>This detector identifies when a spacecraft reaches its
  28.  * extremum elevation with respect to a ground point.</p>
  29.  * <p>
  30.  * As in most cases only the elevation maximum is needed and the
  31.  * minimum is often irrelevant, this detector is often wrapped into
  32.  * an {@link EventSlopeFilter event slope filter} configured with
  33.  * {@link FilterType#TRIGGER_ONLY_DECREASING_EVENTS} (i.e. when the
  34.  * elevation derivative decreases from positive values to negative values,
  35.  * which correspond to a maximum). Setting up this filter saves some computation
  36.  * time as the elevation minimum occurrences are not even looked at. It is
  37.  * however still often necessary to do an additional filtering
  38.  * </p>
  39.  * @author Luc Maisonobe
  40.  * @since 7.1
  41.  */
  42. public class ElevationExtremumDetector extends AbstractDetector<ElevationExtremumDetector> {

  43.     /** Topocentric frame in which elevation should be evaluated. */
  44.     private final TopocentricFrame topo;

  45.     /** Build a new detector.
  46.      * <p>The new instance uses default values for maximal checking interval
  47.      * ({@link #DEFAULT_MAXCHECK}) and convergence threshold ({@link
  48.      * #DEFAULT_THRESHOLD}).</p>
  49.      * @param topo topocentric frame centered on ground point
  50.      */
  51.     public ElevationExtremumDetector(final TopocentricFrame topo) {
  52.         this(DEFAULT_MAXCHECK, DEFAULT_THRESHOLD, topo);
  53.     }

  54.     /** Build a detector.
  55.      * @param maxCheck maximal checking interval (s)
  56.      * @param threshold convergence threshold (s)
  57.      * @param topo topocentric frame centered on ground point
  58.      */
  59.     public ElevationExtremumDetector(final double maxCheck, final double threshold,
  60.                                      final TopocentricFrame topo) {
  61.         this(AdaptableInterval.of(maxCheck), threshold, DEFAULT_MAX_ITER, new StopOnIncreasing(),
  62.              topo);
  63.     }

  64.     /** Protected constructor with full parameters.
  65.      * <p>
  66.      * This constructor is not public as users are expected to use the builder
  67.      * API with the various {@code withXxx()} methods to set up the instance
  68.      * in a readable manner without using a huge amount of parameters.
  69.      * </p>
  70.      * @param maxCheck maximum checking interval
  71.      * @param threshold convergence threshold (s)
  72.      * @param maxIter maximum number of iterations in the event time search
  73.      * @param handler event handler to call at event occurrences
  74.      * @param topo topocentric frame centered on ground point
  75.      */
  76.     protected ElevationExtremumDetector(final AdaptableInterval maxCheck, final double threshold,
  77.                                         final int maxIter, final EventHandler handler,
  78.                                         final TopocentricFrame topo) {
  79.         super(maxCheck, threshold, maxIter, handler);
  80.         this.topo = topo;
  81.     }

  82.     /** {@inheritDoc} */
  83.     @Override
  84.     protected ElevationExtremumDetector create(final AdaptableInterval newMaxCheck, final double newThreshold,
  85.                                               final int newMaxIter,
  86.                                               final EventHandler newHandler) {
  87.         return new ElevationExtremumDetector(newMaxCheck, newThreshold, newMaxIter, newHandler, topo);
  88.     }

  89.     /**
  90.      * Returns the topocentric frame centered on ground point.
  91.      * @return topocentric frame centered on ground point
  92.      */
  93.     public TopocentricFrame getTopocentricFrame() {
  94.         return this.topo;
  95.     }

  96.     /** Get the elevation value.
  97.      * @param s the current state information: date, kinematics, attitude
  98.      * @return spacecraft elevation
  99.      */
  100.     public double getElevation(final SpacecraftState s) {
  101.         return topo.getElevation(s.getPosition(), s.getFrame(), s.getDate());
  102.     }

  103.     /** Compute the value of the detection function.
  104.      * <p>
  105.      * The value is the spacecraft elevation first time derivative.
  106.      * </p>
  107.      * @param s the current state information: date, kinematics, attitude
  108.      * @return spacecraft elevation first time derivative
  109.      */
  110.     public double g(final SpacecraftState s) {

  111.         // get position, velocity of spacecraft in topocentric frame
  112.         final KinematicTransform inertToTopo = s.getFrame().getKinematicTransformTo(topo, s.getDate());
  113.         final TimeStampedPVCoordinates pvTopo = inertToTopo.transformOnlyPV(s.getPVCoordinates());

  114.         // convert the coordinates to UnivariateDerivative1 based vector
  115.         // instead of having vector position, then vector velocity then vector acceleration
  116.         // we get one vector and each coordinate is a DerivativeStructure containing
  117.         // value, first time derivative (we don't need second time derivative here)
  118.         final FieldVector3D<UnivariateDerivative1> pvDS = pvTopo.toUnivariateDerivative1Vector();

  119.         // compute elevation and its first time derivative
  120.         final UnivariateDerivative1 elevation = pvDS.getZ().divide(pvDS.getNorm()).asin();

  121.         // return elevation first time derivative
  122.         return elevation.getDerivative(1);

  123.     }

  124. }