Lots of parts are directly from the orekit documentation on [propagation](https://www.orekit.org/site-orekit-10.1/architecture/propagation.html), with some updates, simplifications and Pythonification by Petrus Hyvönen, SSC
## Learning Goals
**What are Event Detectors*: Why are these useful
**How do I use Event Detectors*: How is it implemented in Orekit and Python
## Keywords
orekit, propagation, event detectors
%% Cell type:code id: tags:
``` python
%matplotlibinline
```
%% Cell type:markdown id: tags:
Initialize orkit and bring up the python-java interface
%% Cell type:code id: tags:
``` python
importorekit
vm=orekit.initVM()
```
%% Cell type:markdown id: tags:
Now set up the pointer to the orekit-data.zip file, using one of the helper files. The file should be in current directory if not specified otherwise.
Now we are set up to import and use objects from the orekit library. Packages can be imported as they were native Python packages
%% Cell type:markdown id: tags:
# Event Detectors
_Before starting this introduction, please make sure you have refreshed the tutorials on Orbit Definition and Propagation._
%% Cell type:markdown id: tags:
The propagators in Orekit is part of an architecture that supports detecting certain discrete conditions that occur during the propagation. This can be that a spacecraft enters eclipse, becomes visible from a ground station, crosses the perigee or a number of other interesting things that may occur during the orbit.
This feature is activated by registering EventDetectors to the propagator. All proppagators in Orekit supports the EventDetector mechanism.
%% Cell type:markdown id: tags:
Users can define their own EventDetectors but there are also several predefined EventDetectors
already available, amongst which :
- a simple DateDetector, which is simply triggered at a predefined date, and can be reset to add new dates on the run (which is useful to set up delays starting when a previous event is been detected)
- an ElevationDetector, which is triggered at raising or setting time of a satellite with respect to a ground point, taking atmospheric refraction into account and either constant elevation or ground mask when threshold elevation is azimuth-dependent
- an ElevationExtremumDetector, which is triggered at maximum (or minimum) satellite elevation with respect to a ground point
- an AltitudeDetector which is triggered when satellite crosses a predefined altitude limit and can be used to compute easily operational forecasts
- a FieldOfViewDetector which is triggered when some target enters or exits a satellite sensor Field Of View (any shape),
- a CircularFieldOfViewDetector which is triggered when some target enters or exits a satellite sensor Field Of View (circular shape),
- a FootprintOverlapDetector which is triggered when a sensor Field Of View (any shape, even split in non-connected parts or containing holes) overlaps a geographic zone, which can be non-convex, split in different sub-zones, have holes, contain the pole,
- a GeographicZoneDetector, which is triggered when the spacecraft enters or leave a zone, which can be non-convex, split in different sub-zones, have holes, contain the pole,
- a GroundFieldOfViewDetector, which is triggered when the spacecraft enters or leave a ground based Field Of View, which can be non-convex, split in different sub-zones, have holes,
- an EclipseDetector, which is triggered when some body enters or exits the umbra or the penumbra of another occulting body,
- an ApsideDetector, which is triggered at apogee and perigee,
- a NodeDetector, which is triggered at ascending and descending nodes,
- a PositionAngleDetector, which is triggered when satellite angle on orbit crosses some value (works with either anomaly, latitude argument or longitude argument and with either true, eccentric or mean angles),
- LatitudeCrossingDetector, LatitudeExtremumDetector, LongitudeCrossingDetector, LongitudeExtremumDetector, which are triggered when satellite position with respect to central body reaches some predefined values,
- an AlignmentDetector, which is triggered when satellite and some body projected in the orbital plane have a specified angular separation (the term AlignmentDetector is clearly a misnomer as the angular separation may be non-zero),
- an AngularSeparationDetector, which is triggered when angular separation between satellite and some beacon as seen by an observer goes below a threshold. The beacon is typically the Sun, the observer is typically a ground station
- An EventShifter is also provided in order to slightly shift the events occurrences times. A typical use case is for handling operational delays before or after some physical event really occurs.
An EventSlopeFilter is provided when user is only interested in one kind of events that occurs in pairs like raising in the raising/setting pair for elevation detector, or eclipse entry in the entry/exit pair for eclipse detector. The filter does not simply ignore events after they have been detected, it filters them before they are located and hence save some computation time by not doing an accurate search for events that will ultimately be ignored.
An EventEnablingPredicateFilter is provided when user wants to filter out some events based on an external condition set up by a user-provided enabling predicate function. This allow for example to dynamically turn some events on and off during propagation or to set up some elaborate logic like triggering on elevation first time derivative (i.e. one elevation maximum) but only when elevation itself is above some threshold.
A BooleanDetector is provided to combine several other detectors with boolean operators and, or and not. This allows for example to detect when a satellite is both visible from a ground station and out of eclipse.
The EclipseDetector class is documented at the [Orekit API](https://www.orekit.org/site-orekit-latest/apidocs/org/orekit/propagation/events/EclipseDetector.html) and will detect entering and leaving the full shadow (Umbra) or when some part of the Sun is covered by Earth (Penumbra).
In the detector, we can also set which EventHandler that we want to use, we can also write our own. In this case we use an EventHandler that will just let the propagator continue after an event has been detected.
There are several ways to collect these events when they happen, one of the ways is to use an Orekit EventsLogger that will store the events during the propagation.
Now we can fetch the events that the logger found.
%% Cell type:code id: tags:
``` python
events=logger.getLoggedEvents()
events.size()
```
%% Output
32
%% Cell type:markdown id: tags:
This is a code snippet that goes through the events and store them in a Pandas DataFrame that is very useful for handling tables in Python. In this, the dates are converted also to Python DateTime objects. Please note that if any further use of the data in Orekit is to be done, it is advisable also to save the Orekit AbsoluteDate.
In this case you are to calculate the ground station visibilities for the above orbit, with a minimum elevation of 5 degrees above the horizon. The detector to use is the [ElevationDetector](https://www.orekit.org/site-orekit-latest/apidocs/org/orekit/propagation/events/ElevationDetector.html). Create a similar pandas table as above of the start / stop time of the visibilities.
