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