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.orekit.frames.Frame;
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  
27  /**
28   * Finder for satellite entry/exit events with respect to a sensor {@link
29   * FieldOfView Field Of View} attached to an arbitrary frame.
30   *
31   * <p> If you only want to compute access times then you should probably use
32   * {@link ElevationDetector}.
33   *
34   * <p>The default implementation behavior is to {@link Action#CONTINUE
35   * continue} propagation at FOV entry and to {@link Action#STOP
36   * stop} propagation at FOV exit. This can be changed by calling {@link
37   * #withHandler(EventHandler)} after construction.</p>
38   *
39   * @author Luc Maisonobe
40   * @author Evan Ward
41   * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
42   * @see FieldOfViewDetector
43   * @see ElevationDetector
44   * @since 7.1
45   */
46  public class GroundFieldOfViewDetector extends AbstractDetector<GroundFieldOfViewDetector> {
47  
48      /** the reference frame attached to the sensor. */
49      private final Frame frame;
50  
51      /** Field of view of the sensor. */
52      private final FieldOfView fov;
53  
54      /**
55       * Build a new instance.
56       *
57       * <p>The maximal interval between distance to FOV boundary checks should be
58       * smaller than the half duration of the minimal pass to handle, otherwise
59       * some short passes could be missed.</p>
60       *
61       * @param frame the reference frame attached to the sensor.
62       * @param fov   Field Of View of the sensor.
63       * @since 10.1
64       */
65      public GroundFieldOfViewDetector(final Frame frame,
66                                       final FieldOfView fov) {
67          this(EventDetectionSettings.getDefaultEventDetectionSettings(), new StopOnIncreasing(), frame, fov);
68      }
69  
70      /**
71       * Protected constructor with full parameters.
72       * <p>
73       * This constructor is not public as users are expected to use the builder
74       * API with the various {@code withXxx()} methods to set up the instance in
75       * a readable manner without using a huge amount of parameters. </p>
76       *
77       * @param detectionSettings event detection settings
78       * @param handler   event handler to call at event occurrences
79       * @param frame     the reference frame attached to the sensor.
80       * @param fov       Field Of View of the sensor.
81       * @since 13.0
82       */
83      protected GroundFieldOfViewDetector(final EventDetectionSettings detectionSettings,
84                                          final EventHandler handler,
85                                          final Frame frame,
86                                          final FieldOfView fov) {
87          super(detectionSettings, handler);
88          this.frame = frame;
89          this.fov = fov;
90      }
91  
92      /** {@inheritDoc} */
93      @Override
94      protected GroundFieldOfViewDetector create(final EventDetectionSettings detectionSettings,
95                                                 final EventHandler newHandler) {
96          return new GroundFieldOfViewDetector(detectionSettings, newHandler, this.frame, this.fov);
97      }
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 
108     /** Get the Field Of View.
109      * @return Field Of View
110      * @since 10.1
111      */
112     public FieldOfView getFOV() {
113         return fov;
114     }
115 
116     /**
117      * {@inheritDoc}
118      *
119      * <p> The g function value is the angular offset between the satellite and
120      * the {@link FieldOfView#offsetFromBoundary(Vector3D, double, VisibilityTrigger)
121      * Field Of View boundary}. It is negative if the satellite is visible within
122      * the Field Of View and positive if it is outside of the Field Of View,
123      * including the margin. </p>
124      *
125      * <p> As per the previous definition, when the satellite enters the Field
126      * Of View, a decreasing event is generated, and when the satellite leaves
127      * the Field Of View, an increasing event is generated. </p>
128      */
129     public double g(final SpacecraftState s) {
130 
131         // get line of sight in sensor frame
132         final Vector3D los = s.getPosition(this.frame);
133         return this.fov.offsetFromBoundary(los, 0.0, VisibilityTrigger.VISIBLE_ONLY_WHEN_FULLY_IN_FOV);
134 
135     }
136 
137 }