GroundFieldOfViewDetector.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.geometry.euclidean.threed.Vector3D;
  19. import org.hipparchus.ode.events.Action;
  20. import org.orekit.frames.Frame;
  21. import org.orekit.geometry.fov.FieldOfView;
  22. import org.orekit.propagation.SpacecraftState;
  23. import org.orekit.propagation.events.handlers.EventHandler;
  24. import org.orekit.propagation.events.handlers.StopOnIncreasing;

  25. /**
  26.  * Finder for satellite entry/exit events with respect to a sensor {@link
  27.  * FieldOfView Field Of View} attached to an arbitrary frame.
  28.  *
  29.  * <p> If you only want to compute access times then you should probably use
  30.  * {@link ElevationDetector}.
  31.  *
  32.  * <p>The default implementation behavior is to {@link Action#CONTINUE
  33.  * continue} propagation at FOV entry and to {@link Action#STOP
  34.  * stop} propagation at FOV exit. This can be changed by calling {@link
  35.  * #withHandler(EventHandler)} after construction.</p>
  36.  *
  37.  * @author Luc Maisonobe
  38.  * @author Evan Ward
  39.  * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
  40.  * @see FieldOfViewDetector
  41.  * @see ElevationDetector
  42.  * @since 7.1
  43.  */
  44. public class GroundFieldOfViewDetector extends AbstractDetector<GroundFieldOfViewDetector> {

  45.     /** the reference frame attached to the sensor. */
  46.     private final Frame frame;

  47.     /** Field of view of the sensor. */
  48.     private final FieldOfView fov;

  49.     /**
  50.      * Build a new instance.
  51.      *
  52.      * <p>The maximal interval between distance to FOV boundary checks should be
  53.      * smaller than the half duration of the minimal pass to handle, otherwise
  54.      * some short passes could be missed.</p>
  55.      *
  56.      * @param frame the reference frame attached to the sensor.
  57.      * @param fov   Field Of View of the sensor.
  58.      * @since 10.1
  59.      */
  60.     public GroundFieldOfViewDetector(final Frame frame,
  61.                                      final FieldOfView fov) {
  62.         this(AdaptableInterval.of(DEFAULT_MAXCHECK), DEFAULT_THRESHOLD, DEFAULT_MAX_ITER,
  63.              new StopOnIncreasing(),
  64.              frame, fov);
  65.     }

  66.     /**
  67.      * Protected constructor with full parameters.
  68.      * <p>
  69.      * This constructor is not public as users are expected to use the builder
  70.      * API with the various {@code withXxx()} methods to set up the instance in
  71.      * a readable manner without using a huge amount of parameters. </p>
  72.      *
  73.      * @param maxCheck  maximum checking interval
  74.      * @param threshold convergence threshold (s)
  75.      * @param maxIter   maximum number of iterations in the event time search
  76.      * @param handler   event handler to call at event occurrences
  77.      * @param frame     the reference frame attached to the sensor.
  78.      * @param fov       Field Of View of the sensor.
  79.      */
  80.     protected GroundFieldOfViewDetector(final AdaptableInterval maxCheck,
  81.                                         final double threshold,
  82.                                         final int maxIter,
  83.                                         final EventHandler handler,
  84.                                         final Frame frame,
  85.                                         final FieldOfView fov) {
  86.         super(maxCheck, threshold, maxIter, handler);
  87.         this.frame = frame;
  88.         this.fov = fov;
  89.     }

  90.     /** {@inheritDoc} */
  91.     @Override
  92.     protected GroundFieldOfViewDetector create(final AdaptableInterval newMaxCheck,
  93.                                                final double newThreshold,
  94.                                                final int newMaxIter,
  95.                                                final EventHandler newHandler) {
  96.         return new GroundFieldOfViewDetector(newMaxCheck, newThreshold,
  97.                 newMaxIter, newHandler, this.frame, this.fov);
  98.     }

  99.     /**
  100.      * Get the sensor reference frame.
  101.      *
  102.      * @return the reference frame attached to the sensor.
  103.      */
  104.     public Frame getFrame() {
  105.         return this.frame;
  106.     }

  107.     /** Get the Field Of View.
  108.      * @return Field Of View
  109.      * @since 10.1
  110.      */
  111.     public FieldOfView getFOV() {
  112.         return fov;
  113.     }

  114.     /**
  115.      * {@inheritDoc}
  116.      *
  117.      * <p> The g function value is the angular offset between the satellite and
  118.      * the {@link FieldOfView#offsetFromBoundary(Vector3D, double, VisibilityTrigger)
  119.      * Field Of View boundary}. It is negative if the satellite is visible within
  120.      * the Field Of View and positive if it is outside of the Field Of View,
  121.      * including the margin. </p>
  122.      *
  123.      * <p> As per the previous definition, when the satellite enters the Field
  124.      * Of View, a decreasing event is generated, and when the satellite leaves
  125.      * the Field Of View, an increasing event is generated. </p>
  126.      */
  127.     public double g(final SpacecraftState s) {

  128.         // get line of sight in sensor frame
  129.         final Vector3D los = s.getPosition(this.frame);
  130.         return this.fov.offsetFromBoundary(los, 0.0, VisibilityTrigger.VISIBLE_ONLY_WHEN_FULLY_IN_FOV);

  131.     }

  132. }