1   /* Copyright 2022-2025 Luc Maisonobe
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.intervals;
18  
19  import org.hipparchus.util.FastMath;
20  import org.orekit.frames.TopocentricFrame;
21  import org.orekit.frames.Transform;
22  import org.orekit.orbits.Orbit;
23  
24  /**
25   * Factory class for {@link AdaptableInterval} suitable for elevation detection on eccentric orbits.
26   * It requires {@link org.orekit.propagation.SpacecraftState} to be based on {@link Orbit} in order to work.
27   * @see AdaptableInterval
28   * @see org.orekit.propagation.events.ApsideDetector
29   * @see org.orekit.propagation.events.EventSlopeFilter
30   * @author Luc Maisonobe
31   * @since 12.1
32   */
33  public class ElevationDetectionAdaptableIntervalFactory {
34  
35      /** Default elevation above which interval should be switched to fine interval (-5°).
36       * @since 13.0
37       */
38      public static final double DEFAULT_ELEVATION_SWITCH_INF = FastMath.toRadians(-5.0);
39  
40      /** Default elevation below which interval should be switched to fine interval (+15°).
41       * @since 13.0
42       */
43      public static final double DEFAULT_ELEVATION_SWITCH_SUP = FastMath.toRadians(15.0);
44  
45      /**
46       * Private constructor.
47       */
48      private ElevationDetectionAdaptableIntervalFactory() {
49          // factory class
50      }
51  
52      /**
53       * Method providing a candidate {@link AdaptableInterval} for arbitrary elevation detection with forward propagation.
54       * It uses a Keplerian, eccentric approximation.
55       * @param topo topocentric frame centered at ground interest point
56       * @param elevationSwitchInf elevation above which interval will switch to {@code fineCheckInterval}
57       *                        (typically {@link #DEFAULT_ELEVATION_SWITCH_INF} which is -5°)
58       * @param elevationSwitchSup elevation below which interval will switch to {@code fineCheckInterval}
59       *                        (typically {@link #DEFAULT_ELEVATION_SWITCH_SUP} which is +15°)
60       * @param fineCheckInterval check interval to use when elevation is
61       *                          between {@code elevationSwitchInf} and {@code elevationSwitchSup}
62       * @return adaptable interval for detection of elevation with respect to {@code topo}
63       * @since 13.0
64       */
65      public static AdaptableInterval getAdaptableInterval(final TopocentricFrame topo,
66                                                           final double elevationSwitchInf,
67                                                           final double elevationSwitchSup,
68                                                           final double fineCheckInterval) {
69          return (state, isForward) -> {
70              final double elevation = topo.getElevation(state.getPosition(), state.getFrame(), state.getDate());
71              if (elevation <= elevationSwitchInf || elevation >= elevationSwitchSup) {
72                  // we are far from visibility switch, estimate some large interval with huge margins
73  
74                  // rotation rate of the topocentric frame
75                  final Transform topoToInertial = topo.getTransformTo(state.getFrame(), state.getDate());
76                  final double topoAngularVelocity = topoToInertial.getAngular().getRotationRate().getNorm();
77  
78                  // max angular rate of spacecraft (i.e. rate at perigee)
79                  final Orbit orbit = state.getOrbit();
80                  final double e     = orbit.getE();
81                  final double rp    = orbit.getA() * (1 - e);
82                  final double vp    = FastMath.sqrt(orbit.getMu() * (1 + e) / rp);
83                  final double rateP = vp / rp;
84  
85                  // upper boundary of elevation rate
86                  final double maxElevationRate = topoAngularVelocity + rateP;
87  
88                  // angular distance to the closest switch
89                  final double deltaElevationSwitch = elevation <= elevationSwitchInf ?
90                                                      elevationSwitchInf - elevation :
91                                                      elevation - elevationSwitchSup;
92  
93                  return FastMath.max(fineCheckInterval, deltaElevationSwitch / maxElevationRate);
94  
95              } else {
96                  // we are close to visibility change, switch to fine check interval
97                  return fineCheckInterval;
98              }
99          };
100     }
101 
102 }