Skip to content

Pre-made Events

Convenience event detectors for common scenarios. These provide ready-to-use event detection for frequently needed conditions.

Overview

Category Events
State-Derived AltitudeEvent, SpeedEvent, LongitudeEvent, LatitudeEvent
Orbital Elements SemiMajorAxisEvent, EccentricityEvent, InclinationEvent, ArgumentOfPerigeeEvent, MeanAnomalyEvent, EccentricAnomalyEvent, TrueAnomalyEvent, ArgumentOfLatitudeEvent
Node Crossings AscendingNodeEvent, DescendingNodeEvent
Eclipse/Shadow UmbraEvent, PenumbraEvent, EclipseEvent, SunlitEvent
Area of Interest AOIEntryEvent, AOIExitEvent

State-Derived Events

AltitudeEvent 

AltitudeEvent(value_altitude: float, name: str, direction: EventDirection)

Altitude-based event detector (convenience wrapper).

Detects when geodetic altitude crosses a value. This is a convenience wrapper that automatically handles ECI → ECEF → geodetic transformations to compute altitude above the WGS84 ellipsoid.

Parameters:

Name Type Description Default
value_altitude float

Geodetic altitude value in meters above WGS84

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction (INCREASING, DECREASING, or ANY)

 required
Note

Requires EOP (Earth Orientation Parameters) to be initialized for accurate transformations. Use bh.initialize_eop() or set a custom provider.

Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import brahe as bh

bh.initialize_eop()

event = bh.AltitudeEvent(
    300e3,
    "Low Altitude Warning",
    bh.EventDirection.DECREASING
)
event = event.set_terminal()

Initialize instance.

set_terminal method descriptor 

set_terminal() -> AltitudeEvent

Mark this event as terminal (stops propagation).

Returns:

Name Type Description
AltitudeEvent AltitudeEvent

Self for method chaining

with_callback method descriptor 

with_callback(callback: callable) -> AltitudeEvent

Set event callback.

Parameters:

Name Type Description Default
callback callable

Function (epoch, state) -> (Optional[state], EventAction)

 required

Returns:

Name Type Description
AltitudeEvent AltitudeEvent

Self for method chaining

with_instance method descriptor 

with_instance(instance: int) -> AltitudeEvent

Set instance number for display name.

Parameters:

Name Type Description Default
instance int

Instance number to append

 required

Returns:

Name Type Description
AltitudeEvent AltitudeEvent

Self for method chaining

with_tolerances method descriptor 

with_tolerances(time_tol: float, value_tol: float) -> AltitudeEvent

Set custom tolerances for event detection.

Parameters:

Name Type Description Default
time_tol float

Time tolerance in seconds (default: 1e-6)

 required
value_tol float

Value tolerance (default: 1e-9)

 required

Returns:

Name Type Description
AltitudeEvent AltitudeEvent

Self for method chaining

SpeedEvent 

SpeedEvent(value: float, name: str, direction: EventDirection)

Speed event detector.

Detects when velocity magnitude crosses a value value.

Parameters:

Name Type Description Default
value float

Speed value in m/s

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
Example 
1
2
3
4
5
6
7
8
import brahe as bh

# Detect when speed exceeds 8 km/s
event = bh.SpeedEvent(
    8000.0,
    "High Speed",
    bh.EventDirection.INCREASING
)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

LongitudeEvent 

LongitudeEvent(value: float, name: str, direction: EventDirection, angle_format: AngleFormat)

Longitude event detector.

Detects when geodetic longitude crosses a value value. Requires EOP initialization for ECI->ECEF transformation.

Parameters:

Name Type Description Default
value float

Longitude value

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
angle_format AngleFormat

Whether value is in degrees or radians

 required
Example 
1
2
3
4
5
6
7
8
9
import brahe as bh

# Detect when crossing prime meridian
event = bh.LongitudeEvent(
    0.0,
    "Prime Meridian",
    bh.EventDirection.ANY,
    bh.AngleFormat.DEGREES
)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

LatitudeEvent 

LatitudeEvent(value: float, name: str, direction: EventDirection, angle_format: AngleFormat)

Latitude event detector.

Detects when geodetic latitude crosses a value value. Requires EOP initialization for ECI->ECEF transformation.

Parameters:

Name Type Description Default
value float

Latitude value

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
angle_format AngleFormat

Whether value is in degrees or radians

 required
Example 
1
2
3
4
5
6
7
8
9
import brahe as bh

# Detect when crossing the equator
event = bh.LatitudeEvent(
    0.0,
    "Equator Crossing",
    bh.EventDirection.ANY,
    bh.AngleFormat.DEGREES
)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

Orbital Element Events

SemiMajorAxisEvent 

SemiMajorAxisEvent(value: float, name: str, direction: EventDirection)

Semi-major axis event detector.

Detects when orbital semi-major axis crosses a value value.

Parameters:

Name Type Description Default
value float

Semi-major axis value in meters

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
Example 
1
2
3
4
5
6
7
8
import brahe as bh

# Detect when semi-major axis drops below GEO altitude
event = bh.SemiMajorAxisEvent(
    bh.R_EARTH + 35786e3,
    "GEO value",
    bh.EventDirection.DECREASING
)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

EccentricityEvent 

EccentricityEvent(value: float, name: str, direction: EventDirection)

Eccentricity event detector.

Detects when orbital eccentricity crosses a value value.

Parameters:

Name Type Description Default
value float

Eccentricity value (dimensionless)

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
Example 
1
2
3
4
5
6
7
8
import brahe as bh

# Detect when orbit becomes nearly circular
event = bh.EccentricityEvent(
    0.001,
    "Near circular",
    bh.EventDirection.DECREASING
)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

InclinationEvent 

InclinationEvent(value: float, name: str, direction: EventDirection, angle_format: AngleFormat)

Inclination event detector.

Detects when orbital inclination crosses a value value.

Parameters:

Name Type Description Default
value float

Inclination value

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
angle_format AngleFormat

Whether value is in degrees or radians

 required
Example 
1
2
3
4
5
6
7
8
9
import brahe as bh

# Detect when inclination crosses 90 degrees (polar orbit value)
event = bh.InclinationEvent(
    90.0,
    "Polar value",
    bh.EventDirection.ANY,
    bh.AngleFormat.DEGREES
)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

ArgumentOfPerigeeEvent 

ArgumentOfPerigeeEvent(value: float, name: str, direction: EventDirection, angle_format: AngleFormat)

Argument of perigee event detector.

Detects when argument of perigee crosses a value value.

Parameters:

Name Type Description Default
value float

Argument of perigee value

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
angle_format AngleFormat

Whether value is in degrees or radians

 required

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

MeanAnomalyEvent 

MeanAnomalyEvent(value: float, name: str, direction: EventDirection, angle_format: AngleFormat)

Mean anomaly event detector.

Detects when mean anomaly crosses a value value.

Parameters:

Name Type Description Default
value float

Mean anomaly value

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
angle_format AngleFormat

Whether value is in degrees or radians

 required

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

EccentricAnomalyEvent 

EccentricAnomalyEvent(value: float, name: str, direction: EventDirection, angle_format: AngleFormat)

Eccentric anomaly event detector.

Detects when eccentric anomaly crosses a value value.

Parameters:

Name Type Description Default
value float

Eccentric anomaly value

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
angle_format AngleFormat

Whether value is in degrees or radians

 required

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

TrueAnomalyEvent 

TrueAnomalyEvent(value: float, name: str, direction: EventDirection, angle_format: AngleFormat)

True anomaly event detector.

Detects when true anomaly crosses a value value.

Parameters:

Name Type Description Default
value float

True anomaly value

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
angle_format AngleFormat

Whether value is in degrees or radians

 required

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

ArgumentOfLatitudeEvent 

ArgumentOfLatitudeEvent(value: float, name: str, direction: EventDirection, angle_format: AngleFormat)

Argument of latitude event detector.

Detects when argument of latitude (omega + true anomaly) crosses a value value.

Parameters:

Name Type Description Default
value float

Argument of latitude value

 required
name str

Event name for identification

 required
direction EventDirection

Detection direction

 required
angle_format AngleFormat

Whether value is in degrees or radians

 required

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

Node Crossing Events

AscendingNodeEvent 

AscendingNodeEvent(name: str)

Ascending node event detector.

Detects when spacecraft crosses the ascending node (equator from south to north).

Parameters:

Name Type Description Default
name str

Event name for identification

 required
Example 
1
2
3
4
import brahe as bh

# Detect ascending node crossings
event = bh.AscendingNodeEvent("Ascending Node")

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

DescendingNodeEvent 

DescendingNodeEvent(name: str)

Descending node event detector.

Detects when spacecraft crosses the descending node (equator from north to south).

Parameters:

Name Type Description Default
name str

Event name for identification

 required
Example 
1
2
3
4
import brahe as bh

# Detect descending node crossings
event = bh.DescendingNodeEvent("Descending Node")

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

Eclipse/Shadow Events

UmbraEvent 

UmbraEvent(name: str, edge: EdgeType, ephemeris_source: EphemerisSource | None)

Umbra event detector.

Detects when spacecraft enters/exits Earth's umbra (full shadow). Uses the conical shadow model.

Parameters:

Name Type Description Default
name str

Event name for identification

 required
edge EdgeType

Edge type (RISING_EDGE = entering, FALLING_EDGE = exiting)

 required
ephemeris_source EphemerisSource | None

Source for sun position (None for low-precision)

 required
Example 
1
2
3
4
5
6
7
import brahe as bh

# Detect umbra entry with low-precision ephemeris
event = bh.UmbraEvent("Umbra Entry", bh.EdgeType.RISING_EDGE, None)

# Detect umbra exit with high-precision DE440s ephemeris
event = bh.UmbraEvent("Umbra Exit", bh.EdgeType.FALLING_EDGE, bh.EphemerisSource.DE440s)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

PenumbraEvent 

PenumbraEvent(name: str, edge: EdgeType, ephemeris_source: EphemerisSource | None)

Penumbra event detector.

Detects when spacecraft enters/exits Earth's penumbra (partial shadow). Uses the conical shadow model.

Parameters:

Name Type Description Default
name str

Event name for identification

 required
edge EdgeType

Edge type (RISING_EDGE = entering, FALLING_EDGE = exiting)

 required
ephemeris_source EphemerisSource | None

Source for sun position (None for low-precision)

 required
Example 
1
2
3
4
import brahe as bh

# Detect penumbra entry
event = bh.PenumbraEvent("Penumbra Entry", bh.EdgeType.RISING_EDGE, None)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

EclipseEvent 

EclipseEvent(name: str, edge: EdgeType, ephemeris_source: EphemerisSource | None)

Eclipse event detector.

Detects when spacecraft enters/exits eclipse (either umbra or penumbra). Uses the conical shadow model.

Parameters:

Name Type Description Default
name str

Event name for identification

 required
edge EdgeType

Edge type (RISING_EDGE = entering, FALLING_EDGE = exiting)

 required
ephemeris_source EphemerisSource | None

Source for sun position (None for low-precision)

 required
Example 
1
2
3
4
5
6
7
import brahe as bh

# Detect any eclipse entry
event = bh.EclipseEvent("Eclipse Entry", bh.EdgeType.RISING_EDGE, None)

# Detect eclipse exit with high-precision ephemeris
event = bh.EclipseEvent("Eclipse Exit", bh.EdgeType.FALLING_EDGE, bh.EphemerisSource.DE440s)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

SunlitEvent 

SunlitEvent(name: str, edge: EdgeType, ephemeris_source: EphemerisSource | None)

Sunlit event detector.

Detects when spacecraft enters/exits sunlight (fully illuminated). Uses the conical shadow model.

Parameters:

Name Type Description Default
name str

Event name for identification

 required
edge EdgeType

Edge type (RISING_EDGE = entering, FALLING_EDGE = leaving)

 required
ephemeris_source EphemerisSource | None

Source for sun position (None for low-precision)

 required
Example 
1
2
3
4
5
6
7
import brahe as bh

# Detect entering sunlight
event = bh.SunlitEvent("Enter Sunlight", bh.EdgeType.RISING_EDGE, None)

# Detect leaving sunlight with high-precision ephemeris
event = bh.SunlitEvent("Leave Sunlight", bh.EdgeType.FALLING_EDGE, bh.EphemerisSource.DE440s)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> Any

Mark this event as terminal (stops propagation).

with_instance method descriptor 

with_instance(instance) -> Any

Set instance number for display name.

with_tolerances method descriptor 

with_tolerances(time_tol, value_tol) -> Any

Set custom tolerances for event detection.

Area of Interest Events

AOIEntryEvent 

AOIEntryEvent(polygon: PolygonLocation, name: str)

AOI Entry event detector.

Detects when a satellite's sub-satellite point enters a polygonal Area of Interest. The sub-satellite point is computed by transforming the ECI position to geodetic coordinates (longitude, latitude).

The polygon can be defined either from a PolygonLocation object or from raw (longitude, latitude) coordinate pairs.

Parameters:

Name Type Description Default
polygon PolygonLocation

Polygon defining the Area of Interest

 required
name str

Event name for identification

 required
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import brahe as bh

# Create from PolygonLocation
vertices = [
    [10.0, 50.0, 0.0],  # [lon, lat, alt] in degrees
    [20.0, 50.0, 0.0],
    [20.0, 55.0, 0.0],
    [10.0, 55.0, 0.0],
    [10.0, 50.0, 0.0],
]
polygon = bh.PolygonLocation(vertices)
entry_event = bh.AOIEntryEvent(polygon, "Europe Entry")

# Create from coordinates with angle format
coords = [
    (10.0, 50.0),  # (lon, lat) in degrees
    (20.0, 50.0),
    (20.0, 55.0),
    (10.0, 55.0),
    (10.0, 50.0),
]
entry_event = bh.AOIEntryEvent.from_coordinates(coords, "Europe Entry", bh.AngleFormat.DEGREES)

Initialize instance.

from_coordinates staticmethod 

from_coordinates(vertices: list[tuple[float, float]], name: str, angle_format: AngleFormat) -> AOIEntryEvent

Create an AOI entry event from raw coordinate pairs.

Parameters:

Name Type Description Default
vertices list[tuple[float, float]]

AOI vertices as (longitude, latitude) pairs

 required
name str

Event name for identification

 required
angle_format AngleFormat

Whether coordinates are in DEGREES or RADIANS

 required

Returns:

Name Type Description
AOIEntryEvent AOIEntryEvent

New AOI entry event detector
Example 
1
2
3
4
import brahe as bh

coords = [(10.0, 50.0), (20.0, 50.0), (20.0, 55.0), (10.0, 55.0), (10.0, 50.0)]
event = bh.AOIEntryEvent.from_coordinates(coords, "AOI Entry", bh.AngleFormat.DEGREES)

set_terminal method descriptor 

set_terminal() -> AOIEntryEvent

Mark this event as terminal (stops propagation).

Returns:

Name Type Description
AOIEntryEvent AOIEntryEvent

Self for method chaining

with_instance method descriptor 

with_instance(instance: int) -> AOIEntryEvent

Set instance number for display name.

Parameters:

Name Type Description Default
instance int

Instance number to append

 required

Returns:

Name Type Description
AOIEntryEvent AOIEntryEvent

Self for method chaining

with_tolerances method descriptor 

with_tolerances(time_tol: float, value_tol: float) -> AOIEntryEvent

Set custom tolerances for event detection.

Parameters:

Name Type Description Default
time_tol float

Time tolerance in seconds

 required
value_tol float

Value tolerance

 required

Returns:

Name Type Description
AOIEntryEvent AOIEntryEvent

Self for method chaining

AOIExitEvent 

AOIExitEvent(polygon: PolygonLocation, name: str)

AOI Exit event detector.

Detects when a satellite's sub-satellite point exits a polygonal Area of Interest. The sub-satellite point is computed by transforming the ECI position to geodetic coordinates (longitude, latitude).

The polygon can be defined either from a PolygonLocation object or from raw (longitude, latitude) coordinate pairs.

Parameters:

Name Type Description Default
polygon PolygonLocation

Polygon defining the Area of Interest

 required
name str

Event name for identification

 required
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import brahe as bh

# Create from PolygonLocation
vertices = [
    [10.0, 50.0, 0.0],  # [lon, lat, alt] in degrees
    [20.0, 50.0, 0.0],
    [20.0, 55.0, 0.0],
    [10.0, 55.0, 0.0],
    [10.0, 50.0, 0.0],
]
polygon = bh.PolygonLocation(vertices)
exit_event = bh.AOIExitEvent(polygon, "Europe Exit")

# Create from coordinates with angle format
coords = [
    (10.0, 50.0),  # (lon, lat) in degrees
    (20.0, 50.0),
    (20.0, 55.0),
    (10.0, 55.0),
    (10.0, 50.0),
]
exit_event = bh.AOIExitEvent.from_coordinates(coords, "Europe Exit", bh.AngleFormat.DEGREES)

Initialize instance.

from_coordinates staticmethod 

from_coordinates(vertices: list[tuple[float, float]], name: str, angle_format: AngleFormat) -> AOIExitEvent

Create an AOI exit event from raw coordinate pairs.

Parameters:

Name Type Description Default
vertices list[tuple[float, float]]

AOI vertices as (longitude, latitude) pairs

 required
name str

Event name for identification

 required
angle_format AngleFormat

Whether coordinates are in DEGREES or RADIANS

 required

Returns:

Name Type Description
AOIExitEvent AOIExitEvent

New AOI exit event detector
Example 
1
2
3
4
import brahe as bh

coords = [(10.0, 50.0), (20.0, 50.0), (20.0, 55.0), (10.0, 55.0), (10.0, 50.0)]
event = bh.AOIExitEvent.from_coordinates(coords, "AOI Exit", bh.AngleFormat.DEGREES)

set_terminal method descriptor 

set_terminal() -> AOIExitEvent

Mark this event as terminal (stops propagation).

Returns:

Name Type Description
AOIExitEvent AOIExitEvent

Self for method chaining

with_instance method descriptor 

with_instance(instance: int) -> AOIExitEvent

Set instance number for display name.

Parameters:

Name Type Description Default
instance int

Instance number to append

 required

Returns:

Name Type Description
AOIExitEvent AOIExitEvent

Self for method chaining

with_tolerances method descriptor 

with_tolerances(time_tol: float, value_tol: float) -> AOIExitEvent

Set custom tolerances for event detection.

Parameters:

Name Type Description Default
time_tol float

Time tolerance in seconds

 required
value_tol float

Value tolerance

 required

Returns:

Name Type Description
AOIExitEvent AOIExitEvent

Self for method chaining

See Also