diff --git a/examples/Event_Detectors.ipynb b/examples/Event_Detectors.ipynb
new file mode 100644
index 0000000000000000000000000000000000000000..8fdde6bd300265cdbee6c423b517675aa47fd412
--- /dev/null
+++ b/examples/Event_Detectors.ipynb
@@ -0,0 +1,620 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Event Detectors in Orekit"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Authors\n",
+ "\n",
+ "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\n",
+ "\n",
+ "## Learning Goals\n",
+ "* *What are Event Detectors*: Why are these useful\n",
+ "* *How do I use Event Detectors*: How is it implemented in Orekit and Python\n",
+ "\n",
+ "## Keywords\n",
+ "orekit, propagation, event detectors"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 18,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "%matplotlib inline"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Initialize orkit and bring up the python-java interface"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 19,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import orekit\n",
+ "vm = orekit.initVM()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "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."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 20,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from orekit.pyhelpers import setup_orekit_curdir, absolutedate_to_datetime\n",
+ "setup_orekit_curdir()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "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",
+ "metadata": {},
+ "source": [
+ "# Event Detectors\n",
+ "\n",
+ "_Before starting this introduction, please make sure you have refreshed the tutorials on Orbit Definition and Propagation._"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "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.\n",
+ "\n",
+ "This feature is activated by registering EventDetectors to the propagator. All proppagators in Orekit supports the EventDetector mechanism."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Users can define their own EventDetectors but there are also several predefined EventDetectors\n",
+ "already available, amongst which :\n",
+ "\n",
+ "- 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)\n",
+ "\n",
+ "- 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\n",
+ "\n",
+ "- an ElevationExtremumDetector, which is triggered at maximum (or minimum) satellite elevation with respect to a ground point\n",
+ "\n",
+ "- an AltitudeDetector which is triggered when satellite crosses a predefined altitude limit and can be used to compute easily operational forecasts\n",
+ "\n",
+ "- a FieldOfViewDetector which is triggered when some target enters or exits a satellite sensor Field Of View (any shape),\n",
+ "- a CircularFieldOfViewDetector which is triggered when some target enters or exits a satellite sensor Field Of View (circular shape),\n",
+ "- 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,\n",
+ "- 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,\n",
+ "- 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,\n",
+ "- an EclipseDetector, which is triggered when some body enters or exits the umbra or the penumbra of another occulting body,\n",
+ "- an ApsideDetector, which is triggered at apogee and perigee,\n",
+ "- a NodeDetector, which is triggered at ascending and descending nodes,\n",
+ "- 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),\n",
+ "- LatitudeCrossingDetector, LatitudeExtremumDetector, LongitudeCrossingDetector, LongitudeExtremumDetector, which are triggered when satellite position with respect to central body reaches some predefined values,\n",
+ "- 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),\n",
+ "- 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\n",
+ "- 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.\n",
+ "\n",
+ "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.\n",
+ "\n",
+ "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. \n",
+ "\n",
+ "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."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 21,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from org.orekit.orbits import KeplerianOrbit, PositionAngle\n",
+ "from org.orekit.propagation.analytical import KeplerianPropagator\n",
+ "from org.orekit.time import AbsoluteDate, TimeScalesFactory\n",
+ "from org.orekit.utils import Constants, IERSConventions\n",
+ "from org.orekit.frames import FramesFactory\n",
+ "from org.orekit.bodies import OneAxisEllipsoid, CelestialBodyFactory"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 22,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from math import radians, degrees\n",
+ "import pandas as pd"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 23,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "utc = TimeScalesFactory.getUTC()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Let us do a small example, based on the orbit we used in the Propagation tutorial."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 24,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "<KeplerianOrbit: Keplerian parameters: {a: 6828137.0; e: 0.007322641593160761; i: 86.99999999999999; pa: 20.0; raan: 10.0; v: 0.0;}>"
+ ]
+ },
+ "execution_count": 24,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "ra = 500 * 1000 # Apogee\n",
+ "rp = 400 * 1000 # Perigee\n",
+ "i = radians(87.0) # inclination\n",
+ "omega = radians(20.0) # perigee argument\n",
+ "raan = radians(10.0) # right ascension of ascending node\n",
+ "lv = radians(0.0) # True anomaly\n",
+ "\n",
+ "epochDate = AbsoluteDate(2020, 1, 1, 0, 0, 00.000, utc)\n",
+ "initial_date = epochDate\n",
+ "\n",
+ "a = (rp + ra + 2 * Constants.WGS84_EARTH_EQUATORIAL_RADIUS) / 2.0 \n",
+ "e = 1.0 - (rp + Constants.WGS84_EARTH_EQUATORIAL_RADIUS) / a\n",
+ "\n",
+ "## Inertial frame where the satellite is defined\n",
+ "inertialFrame = FramesFactory.getEME2000()\n",
+ "\n",
+ "## Orbit construction as Keplerian\n",
+ "initialOrbit = KeplerianOrbit(a, e, i, omega, raan, lv,\n",
+ " PositionAngle.TRUE,\n",
+ " inertialFrame, epochDate, Constants.WGS84_EARTH_MU)\n",
+ "initialOrbit"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 25,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "propagator = KeplerianPropagator(initialOrbit)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Adding Event Detectors"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In the first example we create an EventDetector for eclipse, when the satellite is not illuminated by the Sun, and is in the full shadow of the Earth."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 26,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "ITRF = FramesFactory.getITRF(IERSConventions.IERS_2010, True)\n",
+ "earth = OneAxisEllipsoid(Constants.WGS84_EARTH_EQUATORIAL_RADIUS, \n",
+ " Constants.WGS84_EARTH_FLATTENING, \n",
+ " ITRF)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 27,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "sun = CelestialBodyFactory.getSun()\n",
+ "sunRadius = 696000000.0"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 28,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from org.orekit.propagation.events import EclipseDetector, EventsLogger\n",
+ "from org.orekit.propagation.events.handlers import ContinueOnEvent"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "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). \n",
+ "\n",
+ "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."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 29,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "eclipse_detector = EclipseDetector(sun, sunRadius, earth).withUmbra().withHandler(ContinueOnEvent())"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "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."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 30,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "logger = EventsLogger()\n",
+ "logged_detector = logger.monitorDetector(eclipse_detector)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We add the eclipse detector, together with the eventslogger to our propagator."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 31,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "propagator.addEventDetector(logged_detector)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The propagation is executed in same way as in previous examples."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 32,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "<AbsoluteDate: 2020-01-02T00:00:00.000>"
+ ]
+ },
+ "execution_count": 32,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "state = propagator.propagate(initial_date, initial_date.shiftedBy(3600.0 * 24))\n",
+ "state.getDate()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now we can fetch the events that the logger found."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 33,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "32"
+ ]
+ },
+ "execution_count": 33,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "events = logger.getLoggedEvents()\n",
+ "events.size()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "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."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 35,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "<div>\n",
+ "<style scoped>\n",
+ " .dataframe tbody tr th:only-of-type {\n",
+ " vertical-align: middle;\n",
+ " }\n",
+ "\n",
+ " .dataframe tbody tr th {\n",
+ " vertical-align: top;\n",
+ " }\n",
+ "\n",
+ " .dataframe thead th {\n",
+ " text-align: right;\n",
+ " }\n",
+ "</style>\n",
+ "<table border=\"1\" class=\"dataframe\">\n",
+ " <thead>\n",
+ " <tr style=\"text-align: right;\">\n",
+ " <th></th>\n",
+ " <th>EclipseDuration</th>\n",
+ " <th>Start</th>\n",
+ " <th>Stop</th>\n",
+ " </tr>\n",
+ " </thead>\n",
+ " <tbody>\n",
+ " <tr>\n",
+ " <th>0</th>\n",
+ " <td>18.077653</td>\n",
+ " <td>2020-01-01 00:08:45.102790</td>\n",
+ " <td>2020-01-01 00:26:49.761988</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>1</th>\n",
+ " <td>18.068964</td>\n",
+ " <td>2020-01-01 01:42:22.923764</td>\n",
+ " <td>2020-01-01 02:00:27.061606</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>2</th>\n",
+ " <td>18.060506</td>\n",
+ " <td>2020-01-01 03:16:00.738934</td>\n",
+ " <td>2020-01-01 03:34:04.369298</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>3</th>\n",
+ " <td>18.052280</td>\n",
+ " <td>2020-01-01 04:49:38.548244</td>\n",
+ " <td>2020-01-01 05:07:41.685056</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>4</th>\n",
+ " <td>18.044287</td>\n",
+ " <td>2020-01-01 06:23:16.351637</td>\n",
+ " <td>2020-01-01 06:41:19.008874</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>5</th>\n",
+ " <td>18.036528</td>\n",
+ " <td>2020-01-01 07:56:54.149057</td>\n",
+ " <td>2020-01-01 08:14:56.340741</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>6</th>\n",
+ " <td>18.029003</td>\n",
+ " <td>2020-01-01 09:30:31.940450</td>\n",
+ " <td>2020-01-01 09:48:33.680649</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>7</th>\n",
+ " <td>18.021714</td>\n",
+ " <td>2020-01-01 11:04:09.725763</td>\n",
+ " <td>2020-01-01 11:22:11.028587</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>8</th>\n",
+ " <td>18.014660</td>\n",
+ " <td>2020-01-01 12:37:47.504944</td>\n",
+ " <td>2020-01-01 12:55:48.384546</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>9</th>\n",
+ " <td>18.007843</td>\n",
+ " <td>2020-01-01 14:11:25.277944</td>\n",
+ " <td>2020-01-01 14:29:25.748515</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>10</th>\n",
+ " <td>18.001263</td>\n",
+ " <td>2020-01-01 15:45:03.044716</td>\n",
+ " <td>2020-01-01 16:03:03.120486</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>11</th>\n",
+ " <td>17.994921</td>\n",
+ " <td>2020-01-01 17:18:40.805211</td>\n",
+ " <td>2020-01-01 17:36:40.500451</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>12</th>\n",
+ " <td>17.988817</td>\n",
+ " <td>2020-01-01 18:52:18.559383</td>\n",
+ " <td>2020-01-01 19:10:17.888399</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>13</th>\n",
+ " <td>17.982952</td>\n",
+ " <td>2020-01-01 20:25:56.307186</td>\n",
+ " <td>2020-01-01 20:43:55.284322</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>14</th>\n",
+ " <td>17.977327</td>\n",
+ " <td>2020-01-01 21:59:34.048572</td>\n",
+ " <td>2020-01-01 22:17:32.688210</td>\n",
+ " </tr>\n",
+ " <tr>\n",
+ " <th>15</th>\n",
+ " <td>17.971943</td>\n",
+ " <td>2020-01-01 23:33:11.783493</td>\n",
+ " <td>2020-01-01 23:51:10.100051</td>\n",
+ " </tr>\n",
+ " </tbody>\n",
+ "</table>\n",
+ "</div>"
+ ],
+ "text/plain": [
+ " EclipseDuration Start Stop\n",
+ "0 18.077653 2020-01-01 00:08:45.102790 2020-01-01 00:26:49.761988\n",
+ "1 18.068964 2020-01-01 01:42:22.923764 2020-01-01 02:00:27.061606\n",
+ "2 18.060506 2020-01-01 03:16:00.738934 2020-01-01 03:34:04.369298\n",
+ "3 18.052280 2020-01-01 04:49:38.548244 2020-01-01 05:07:41.685056\n",
+ "4 18.044287 2020-01-01 06:23:16.351637 2020-01-01 06:41:19.008874\n",
+ "5 18.036528 2020-01-01 07:56:54.149057 2020-01-01 08:14:56.340741\n",
+ "6 18.029003 2020-01-01 09:30:31.940450 2020-01-01 09:48:33.680649\n",
+ "7 18.021714 2020-01-01 11:04:09.725763 2020-01-01 11:22:11.028587\n",
+ "8 18.014660 2020-01-01 12:37:47.504944 2020-01-01 12:55:48.384546\n",
+ "9 18.007843 2020-01-01 14:11:25.277944 2020-01-01 14:29:25.748515\n",
+ "10 18.001263 2020-01-01 15:45:03.044716 2020-01-01 16:03:03.120486\n",
+ "11 17.994921 2020-01-01 17:18:40.805211 2020-01-01 17:36:40.500451\n",
+ "12 17.988817 2020-01-01 18:52:18.559383 2020-01-01 19:10:17.888399\n",
+ "13 17.982952 2020-01-01 20:25:56.307186 2020-01-01 20:43:55.284322\n",
+ "14 17.977327 2020-01-01 21:59:34.048572 2020-01-01 22:17:32.688210\n",
+ "15 17.971943 2020-01-01 23:33:11.783493 2020-01-01 23:51:10.100051"
+ ]
+ },
+ "execution_count": 35,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "start_time = None\n",
+ "result = pd.DataFrame()\n",
+ "\n",
+ "for event in logger.getLoggedEvents():\n",
+ " \n",
+ " if not event.isIncreasing():\n",
+ " start_time = event.getState().getDate()\n",
+ " elif start_time:\n",
+ " stop_time = event.getState().getDate()\n",
+ " result = result.append({\"Start\":absolutedate_to_datetime(start_time), \n",
+ " \"Stop\":absolutedate_to_datetime(stop_time), \n",
+ " \"EclipseDuration\": stop_time.durationFrom(start_time)/60},\n",
+ " ignore_index=True)\n",
+ " start_time = None\n",
+ "result"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Exercise 1"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "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."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Exercise 2"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The satellite you are simulating does not have any batteries onboard, so it needs to be fully in sunlight to operate. Perform a calculation of when your ground station has visibility to the spacecraft, and that the spacecraft is in full sunlight. \n",
+ "\n",
+ "Hint: Check the BooleanDetector, but there are other ways to do this too!\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.7.1"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}