1   /* Copyright 2002-2025 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.geometry.euclidean.threed.Vector3D;
20  import org.hipparchus.ode.events.Action;
21  import org.hipparchus.util.FastMath;
22  import org.orekit.geometry.fov.FieldOfView;
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.PVCoordinatesProvider;
27  
28  /** Finder for target entry/exit events with respect to a satellite sensor
29   * {@link FieldOfView Field Of View}.
30   * <p>Beware that this detector is unaware of any bodies occluding line-of-sight to
31   * the target. It can be therefore used for many contexts from Earth Observation to
32   * interplanetary mission design. For instance, in an Earth Observation context,
33   * it can be easily combined to an {@link ElevationDetector} using
34   * {@link BooleanDetector#andCombine(java.util.Collection)} to calculate station
35   * visibility opportunities within the satellite's field of view.
36   * <p>The default implementation behavior is to {@link Action#CONTINUE continue}
37   * propagation at FOV entry and to {@link Action#STOP stop} propagation
38   * at FOV exit. This can be changed by calling
39   * {@link #withHandler(EventHandler)} after construction.</p>
40   * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
41   * @see FootprintOverlapDetector
42   * @see VisibilityTrigger
43   * @author Luc Maisonobe
44   * @since 7.1
45   */
46  public class FieldOfViewDetector extends AbstractDetector<FieldOfViewDetector> {
47  
48      /** Position/velocity provider of the considered target. */
49      private final PVCoordinatesProvider targetPVProvider;
50  
51      /** Radius of the target, considered to be a spherical body (m). */
52      private final double radiusTarget;
53  
54      /** Visibility trigger for spherical bodies. */
55      private final VisibilityTrigger trigger;
56  
57      /** Field of view. */
58      private final FieldOfView fov;
59  
60      /** Build a new instance.
61       * <p>The maximal interval between distance to FOV boundary checks should
62       * be smaller than the half duration of the minimal pass to handle,
63       * otherwise some short passes could be missed.</p>
64       * @param pvTarget Position/velocity provider of the considered target
65       * @param fov Field Of View
66       * @since 10.1
67       */
68      public FieldOfViewDetector(final PVCoordinatesProvider pvTarget, final FieldOfView fov) {
69          this(pvTarget, 0.0, VisibilityTrigger.VISIBLE_AS_SOON_AS_PARTIALLY_IN_FOV, fov);
70      }
71  
72      /** Build a new instance.
73       * <p>The maximal interval between distance to FOV boundary checks should
74       * be smaller than the half duration of the minimal pass to handle,
75       * otherwise some short passes could be missed.</p>
76       * @param pvTarget Position/velocity provider of the considered target
77       * @param radiusTarget radius of the target, considered to be a spherical body (m)
78       * @param trigger visibility trigger for spherical bodies
79       * @param fov Field Of View
80       * @since 10.1
81       */
82      public FieldOfViewDetector(final PVCoordinatesProvider pvTarget, final double radiusTarget,
83                                 final VisibilityTrigger trigger, final FieldOfView fov) {
84          this(EventDetectionSettings.getDefaultEventDetectionSettings(), new StopOnIncreasing(),
85               pvTarget, radiusTarget, trigger, fov);
86      }
87  
88      /** Protected constructor with full parameters.
89       * <p>
90       * This constructor is not public as users are expected to use the builder
91       * API with the various {@code withXxx()} methods to set up the instance
92       * in a readable manner without using a huge amount of parameters.
93       * </p>
94       * @param detectionSettings detection settings
95       * @param handler event handler to call at event occurrences
96       * @param pvTarget Position/velocity provider of the considered target
97       * @param radiusTarget radius of the target, considered to be a spherical body (m)
98       * @param trigger visibility trigger for spherical bodies
99       * @param fov Field Of View
100      * @since 13.0
101      */
102     protected FieldOfViewDetector(final EventDetectionSettings detectionSettings,
103                                   final EventHandler handler,
104                                   final PVCoordinatesProvider pvTarget, final double radiusTarget,
105                                   final VisibilityTrigger trigger, final FieldOfView fov) {
106         super(detectionSettings, handler);
107         this.targetPVProvider = pvTarget;
108         this.radiusTarget     = radiusTarget;
109         this.trigger          = trigger;
110         this.fov              = fov;
111     }
112 
113     /** {@inheritDoc} */
114     @Override
115     protected FieldOfViewDetector create(final EventDetectionSettings detectionSettings,
116                                          final EventHandler newHandler) {
117         return new FieldOfViewDetector(detectionSettings, newHandler,
118                                        targetPVProvider, radiusTarget, trigger, fov);
119     }
120 
121     /** Get the position/velocity provider of the target .
122      * @return the position/velocity provider of the target
123      */
124     public PVCoordinatesProvider getPVTarget() {
125         return targetPVProvider;
126     }
127 
128     /** Get the Field Of View.
129      * @return Field Of View
130      * @since 10.1
131      */
132     public FieldOfView getFOV() {
133         return fov;
134     }
135 
136     /** {@inheritDoc}
137      * <p>
138      * The g function value is the angular offset between the
139      * target center and the {@link FieldOfView#offsetFromBoundary(Vector3D,
140      * double, VisibilityTrigger) Field Of View boundary}, plus or minus the
141      * target angular radius depending on the {@link VisibilityTrigger}, minus
142      * the {@link FieldOfView#getMargin() Field Of View margin}. It is therefore
143      * negative if the target is visible within the Field Of View and positive
144      * if it is outside of the Field Of View.
145      * </p>
146      * <p>
147      * As per the previous definition, when the target enters the Field Of
148      * View, a decreasing event is generated, and when the target leaves
149      * the Field Of View, an increasing event is generated.
150      * </p>
151      */
152     public double g(final SpacecraftState s) {
153 
154         // get line of sight in spacecraft frame
155         final Vector3D targetPosInert =
156                 targetPVProvider.getPosition(s.getDate(), s.getFrame());
157         final Vector3D lineOfSightSC = s.toStaticTransform().transformPosition(targetPosInert);
158 
159         final double angularRadius = FastMath.asin(radiusTarget / lineOfSightSC.getNorm());
160         return fov.offsetFromBoundary(lineOfSightSC, angularRadius, trigger);
161 
162     }
163 
164 }