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
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(AdaptableInterval.of(DEFAULT_MAXCHECK), DEFAULT_THRESHOLD, DEFAULT_MAX_ITER,
68 new StopOnIncreasing(),
69 frame, fov);
70 }
71
72 /**
73 * Protected constructor with full parameters.
74 * <p>
75 * This constructor is not public as users are expected to use the builder
76 * API with the various {@code withXxx()} methods to set up the instance in
77 * a readable manner without using a huge amount of parameters. </p>
78 *
79 * @param maxCheck maximum checking interval
80 * @param threshold convergence threshold (s)
81 * @param maxIter maximum number of iterations in the event time search
82 * @param handler event handler to call at event occurrences
83 * @param frame the reference frame attached to the sensor.
84 * @param fov Field Of View of the sensor.
85 */
86 protected GroundFieldOfViewDetector(final AdaptableInterval maxCheck,
87 final double threshold,
88 final int maxIter,
89 final EventHandler handler,
90 final Frame frame,
91 final FieldOfView fov) {
92 super(maxCheck, threshold, maxIter, handler);
93 this.frame = frame;
94 this.fov = fov;
95 }
96
97 /** {@inheritDoc} */
98 @Override
99 protected GroundFieldOfViewDetector create(final AdaptableInterval newMaxCheck,
100 final double newThreshold,
101 final int newMaxIter,
102 final EventHandler newHandler) {
103 return new GroundFieldOfViewDetector(newMaxCheck, newThreshold,
104 newMaxIter, newHandler, this.frame, this.fov);
105 }
106
107 /**
108 * Get the sensor reference frame.
109 *
110 * @return the reference frame attached to the sensor.
111 */
112 public Frame getFrame() {
113 return this.frame;
114 }
115
116 /** Get the Field Of View.
117 * @return Field Of View
118 * @since 10.1
119 */
120 public FieldOfView getFOV() {
121 return fov;
122 }
123
124 /**
125 * {@inheritDoc}
126 *
127 * <p> The g function value is the angular offset between the satellite and
128 * the {@link FieldOfView#offsetFromBoundary(Vector3D, double, VisibilityTrigger)
129 * Field Of View boundary}. It is negative if the satellite is visible within
130 * the Field Of View and positive if it is outside of the Field Of View,
131 * including the margin. </p>
132 *
133 * <p> As per the previous definition, when the satellite enters the Field
134 * Of View, a decreasing event is generated, and when the satellite leaves
135 * the Field Of View, an increasing event is generated. </p>
136 */
137 public double g(final SpacecraftState s) {
138
139 // get line of sight in sensor frame
140 final Vector3D los = s.getPosition(this.frame);
141 return this.fov.offsetFromBoundary(los, 0.0, VisibilityTrigger.VISIBLE_ONLY_WHEN_FULLY_IN_FOV);
142
143 }
144
145 }