InterSatDirectViewDetector.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.orekit.bodies.GeodeticPoint;
  19. import org.orekit.bodies.OneAxisEllipsoid;
  20. import org.orekit.frames.Frame;
  21. import org.orekit.propagation.PropagatorsParallelizer;
  22. import org.orekit.propagation.SpacecraftState;
  23. import org.orekit.propagation.events.handlers.ContinueOnEvent;
  24. import org.orekit.propagation.events.handlers.EventHandler;
  25. import org.orekit.time.AbsoluteDate;
  26. import org.orekit.utils.PVCoordinatesProvider;


  27. /** Detector for inter-satellites direct view (i.e. no masking by central body limb).
  28.  * <p>
  29.  * As this detector needs two satellites, it embeds one {@link
  30.  * PVCoordinatesProvider coordinates provider} for the secondary satellite
  31.  * and is registered as an event detector in the propagator of the primary
  32.  * satellite. The secondary satellite provider will therefore be driven by this
  33.  * detector (and hence by the propagator in which this detector is registered).
  34.  * </p>
  35.  * <p>
  36.  * In order to avoid infinite recursion, care must be taken to have the secondary
  37.  * satellite provider being <em>completely independent</em> from anything else.
  38.  * In particular, if the provider is a propagator, it should <em>not</em> be run
  39.  * together in a {@link PropagatorsParallelizer propagators parallelizer} with
  40.  * the propagator this detector is registered in. It is fine however to configure
  41.  * two separate propagators PsA and PsB with similar settings for the secondary satellite
  42.  * and one propagator Pm for the primary satellite and then use Psa in this detector
  43.  * registered within Pm while Pm and Psb are run in the context of a {@link
  44.  * PropagatorsParallelizer propagators parallelizer}.
  45.  * </p>
  46.  * <p>
  47.  * For efficiency reason during the event search loop, it is recommended to have
  48.  * the secondary provider be an analytical propagator or an ephemeris. A numerical propagator
  49.  * as a secondary propagator works but is expected to be computationally costly.
  50.  * </p>
  51.  * <p>
  52.  * The {@code g} function of this detector is positive when satellites can see
  53.  * each other directly and negative when the central body limb is in between and
  54.  * blocks the direct view.
  55.  * </p>
  56.  * <p>
  57.  * This detector only checks masking by central body limb, it does not take into
  58.  * account satellites antenna patterns. If these patterns must be considered, then
  59.  * this detector can be {@link BooleanDetector#andCombine(EventDetector...) and combined}
  60.  * with  the {@link BooleanDetector#notCombine(EventDetector) logical not} of
  61.  * {@link FieldOfViewDetector field of view detectors}.
  62.  * </p>
  63.  * @author Luc Maisonobe
  64.  * @since 9.3
  65.  */
  66. public class InterSatDirectViewDetector extends AbstractDetector<InterSatDirectViewDetector> {

  67.     /** Central body. */
  68.     private final OneAxisEllipsoid body;

  69.     /** Skimming altitude.
  70.      * @since 12.0
  71.      */
  72.     private final double skimmingAltitude;

  73.     /** Coordinates provider for the secondary satellite. */
  74.     private final PVCoordinatesProvider secondary;

  75.     /** simple constructor.
  76.      *
  77.      * @param body central body
  78.      * @param secondary provider for the secondary satellite
  79.      */
  80.     public InterSatDirectViewDetector(final OneAxisEllipsoid body, final PVCoordinatesProvider secondary) {
  81.         this(body, 0.0, secondary, s -> DEFAULT_MAXCHECK, DEFAULT_THRESHOLD, DEFAULT_MAX_ITER,
  82.              new ContinueOnEvent());
  83.     }

  84.     /** Private constructor.
  85.      * @param body central body
  86.      * @param skimmingAltitude skimming altitude at which events are triggered
  87.      * @param secondary provider for the secondary satellite
  88.      * @param maxCheck  maximum checking interval
  89.      * @param threshold convergence threshold (s)
  90.      * @param maxIter   maximum number of iterations in the event time search
  91.      * @param handler   event handler to call at event occurrences
  92.      * @since 12.0
  93.      */
  94.     protected InterSatDirectViewDetector(final OneAxisEllipsoid body,
  95.                                          final double skimmingAltitude,
  96.                                          final PVCoordinatesProvider secondary,
  97.                                          final AdaptableInterval maxCheck,
  98.                                          final double threshold,
  99.                                          final int maxIter,
  100.                                          final EventHandler handler) {
  101.         super(maxCheck, threshold, maxIter, handler);
  102.         this.body             = body;
  103.         this.skimmingAltitude = skimmingAltitude;
  104.         this.secondary        = secondary;
  105.     }

  106.     /** Get the central body.
  107.      * @return central body
  108.      */
  109.     public OneAxisEllipsoid getCentralBody() {
  110.         return body;
  111.     }

  112.     /** Get the skimming altitude.
  113.      * @return skimming altitude at which events are triggered
  114.      * @since 12.0
  115.      */
  116.     public double getSkimmingAltitude() {
  117.         return skimmingAltitude;
  118.     }

  119.     /** Get the provider for the secondary satellite.
  120.      * @return provider for the secondary satellite
  121.      */
  122.     public PVCoordinatesProvider getSecondary() {
  123.         return secondary;
  124.     }

  125.     /** {@inheritDoc} */
  126.     @Override
  127.     protected InterSatDirectViewDetector create(final AdaptableInterval newMaxCheck,
  128.                                                 final double newThreshold,
  129.                                                 final int newMaxIter,
  130.                                                 final EventHandler newHandler) {
  131.         return new InterSatDirectViewDetector(body, skimmingAltitude, secondary,
  132.                                               newMaxCheck, newThreshold, newMaxIter, newHandler);
  133.     }

  134.     /**
  135.      * Setup the skimming altitude.
  136.      * <p>
  137.      * The skimming altitude is the lowest altitude of the path between satellites
  138.      * at which events should be triggered. If set to 0.0, events are triggered
  139.      * exactly when the path passes just at central body limb.
  140.      * </p>
  141.      * @param newSkimmingAltitude skimming altitude (m)
  142.      * @return a new detector with updated configuration (the instance is not changed)
  143.      * @see #getSkimmingAltitude()
  144.      * @since 12.0
  145.      */
  146.     public InterSatDirectViewDetector withSkimmingAltitude(final double newSkimmingAltitude) {
  147.         return new InterSatDirectViewDetector(body, newSkimmingAltitude, secondary,
  148.                                               getMaxCheckInterval(), getThreshold(),
  149.                                               getMaxIterationCount(), getHandler());
  150.     }

  151.     /** {@inheritDoc}
  152.      * <p>
  153.      * The {@code g} function of this detector is the difference between the minimum
  154.      * altitude of intermediate points along the line of sight between satellites and the
  155.      * {@link #getSkimmingAltitude() skimming altitude}. It is therefore positive when
  156.      * all intermediate points are above the skimming altitude, meaning satellites can see
  157.      * each other and it is negative when some intermediate points (which may be either
  158.      * endpoints) dive below this altitude, meaning satellites cannot see each other.
  159.      * </p>
  160.      */
  161.     @Override
  162.     public double g(final SpacecraftState state) {

  163.         // get the lowest point between primary and secondary
  164.         final AbsoluteDate  date   = state.getDate();
  165.         final Frame         frame  = body.getBodyFrame();
  166.         final GeodeticPoint lowest = body.lowestAltitudeIntermediate(state.getPosition(frame),
  167.                                                                      secondary.getPosition(date, frame));

  168.         // compute switching function value as altitude difference
  169.         return lowest.getAltitude() - skimmingAltitude;

  170.     }

  171. }