1   /* Copyright 2002-2026 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.CalculusFieldElement;
20  import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
21  import org.hipparchus.ode.events.Action;
22  import org.orekit.bodies.CelestialBodies;
23  import org.orekit.propagation.FieldSpacecraftState;
24  import org.orekit.propagation.events.handlers.EventHandler;
25  import org.orekit.propagation.events.handlers.FieldEventHandler;
26  import org.orekit.propagation.events.handlers.FieldStopOnEvent;
27  import org.orekit.utils.ExtendedPositionProvider;
28  
29  /** Detects when spacecraft comes close to a moving beacon, as seen from a moving observer.
30   * <p>The main use case for this detector is when the observer is in fact a ground
31   * station, modeled as a {@link org.orekit.frames.TopocentricFrame} and when the beacon
32   * is the {@link CelestialBodies#getSun() Sun}, for computing
33   * interferences for the telemetry link. Another similar case is when the beacon is
34   * another spacecraft, for interferences computation.</p>
35   * <p>The default handler behavior is to {@link Action#STOP stop}
36   * propagation when spacecraft enters the proximity zone. This can be changed by calling
37   * {@code #withHandler(EventHandler)} after construction.</p>
38   * @param <T> type of the field elements
39   * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
40   * @author Luc Maisonobe
41   * @author Romain Serra
42   * @see AngularSeparationDetector
43   * @since 13.1
44   */
45  public class FieldAngularSeparationDetector<T extends CalculusFieldElement<T>>
46          extends FieldAbstractDetector<FieldAngularSeparationDetector<T>, T> {
47  
48      /** Beacon at the center of the proximity zone. */
49      private final ExtendedPositionProvider beacon;
50  
51      /** Observer for the spacecraft, that may also see the beacon at the same time if they are too close. */
52      private final ExtendedPositionProvider observer;
53  
54      /** Proximity angle (rad). */
55      private final T proximityAngle;
56  
57      /** Build a new angular separation detector.
58       * @param beacon beacon at the center of the proximity zone
59       * @param observer observer for the spacecraft, that may also see
60       * the beacon at the same time if they are too close to each other
61       * @param proximityAngle proximity angle as seen from observer, at which events are triggered (rad)
62       */
63      public FieldAngularSeparationDetector(final ExtendedPositionProvider beacon,
64                                            final ExtendedPositionProvider observer,
65                                            final T proximityAngle) {
66          this(new FieldEventDetectionSettings<>(proximityAngle.getField(), AngularSeparationDetector.DEFAULT_SETTINGS),
67                  new FieldStopOnEvent<>(), beacon, observer, proximityAngle);
68      }
69  
70      /** Protected constructor with full parameters.
71       * <p>
72       * This constructor is not public as users are expected to use the builder
73       * API with the various {@code withXxx()} methods to set up the instance
74       * in a readable manner without using a huge amount of parameters.
75       * </p>
76       * @param detectionSettings detection settings
77       * @param handler event handler to call at event occurrences
78       * @param beacon beacon at the center of the proximity zone
79       * @param observer observer for the spacecraft, that may also see
80       * the beacon at the same time if they are too close to each other
81       * @param proximityAngle proximity angle as seen from observer, at which events are triggered (rad)
82       * @since 13.0
83       */
84      protected FieldAngularSeparationDetector(final FieldEventDetectionSettings<T> detectionSettings,
85                                               final FieldEventHandler<T> handler,
86                                               final ExtendedPositionProvider beacon,
87                                               final ExtendedPositionProvider observer,
88                                               final T proximityAngle) {
89          super(detectionSettings, handler);
90          this.beacon         = beacon;
91          this.observer       = observer;
92          this.proximityAngle = proximityAngle;
93      }
94  
95      /** {@inheritDoc} */
96      @Override
97      protected FieldAngularSeparationDetector<T> create(final FieldEventDetectionSettings<T> detectionSettings,
98                                                         final FieldEventHandler<T> newHandler) {
99          return new FieldAngularSeparationDetector<>(detectionSettings, newHandler, beacon, observer, proximityAngle);
100     }
101 
102     /** Get the beacon at the center of the proximity zone.
103      * @return beacon at the center of the proximity zone
104      */
105     public ExtendedPositionProvider getBeacon() {
106         return beacon;
107     }
108 
109     /** Get the observer for the spacecraft.
110      * @return observer for the spacecraft
111      */
112     public ExtendedPositionProvider getObserver() {
113         return observer;
114     }
115 
116     /** Get the proximity angle (rad).
117      * @return the proximity angle
118      */
119     public T getProximityAngle() {
120         return proximityAngle;
121     }
122 
123     /** Compute the value of the switching function.
124      * <p>
125      * This function measures the angular separation between beacon and spacecraft
126      * as seen from the observer minus the proximity angle. It therefore triggers
127      * decreasing events when the spacecraft enters the proximity zone and increasing
128      * events when it leaves the proximity zone.
129      * </p>
130      * <p>
131      * No shadowing effect is taken into account, so this method is computed and
132      * may trigger events even when the spacecraft is below horizon for an observer
133      * which is a ground station. If such effects must be taken into account the
134      * detector must be associated with a {@link EventEnablingPredicateFilter predicate
135      * filter} where the {@link EnablingPredicate predicate function} is based on elevation.
136      * </p>
137      * @param s the current state information: date, kinematics, attitude
138      * @return value of the switching function
139      */
140     public T g(final FieldSpacecraftState<T> s) {
141         final FieldVector3D<T> sPos = s.getPosition();
142         final FieldVector3D<T> bP = beacon.getPosition(s.getDate(), s.getFrame());
143         final FieldVector3D<T> oP = observer.getPosition(s.getDate(), s.getFrame());
144         final T separation = FieldVector3D.angle(sPos.subtract(oP), bP.subtract(oP));
145         return separation.subtract(proximityAngle);
146     }
147 
148     /** {@inheritDoc} */
149     @Override
150     public AngularSeparationDetector toEventDetector(final EventHandler eventHandler) {
151         return new AngularSeparationDetector(beacon, observer, proximityAngle.getReal()).withHandler(eventHandler);
152     }
153 }