Events & Visibility

Event detection and visibility analysis.

Event Detection

Events are detected when a function crosses zero. The crossing property indicates the direction:

• "up": Function crosses from negative to positive
• "down": Function crosses from positive to negative

Visibility Analysis

The visibility function computes visibility windows between a ground station and a spacecraft, accounting for elevation constraints.

Quick Example

import lox_space as lox

# Find events on a trajectory
def altitude(state):
    """Returns altitude above reference radius."""
    r = (state.position()[0]**2 + state.position()[1]**2 + state.position()[2]**2)**0.5
    return r - 6378.0  # km above Earth radius

events = trajectory.find_events(altitude)
for event in events:
    print(f"{event.crossing()} crossing at {event.time()}")

# Find time windows
windows = trajectory.find_windows(altitude)
for w in windows:
    print(f"Window: {w.start()} to {w.end()}, duration: {w.duration()}")

# Visibility analysis
passes = lox.visibility(
    times=times,
    gs=ground_station,
    mask=elevation_mask,
    sc=trajectory,
    ephemeris=spk,
)

for p in passes:
    print(f"Pass: {p.window().start()} to {p.window().end()}")

---

Event

Represents a detected event (zero-crossing of a function).

Events are detected when a monitored function crosses zero. The crossing direction indicates "up" (negative to positive) or "down" (positive to negative).

Methods:

• crossing –

  Return the crossing direction ("up" or "down").

• time –

  Return the time of this event.

crossing

crossing() -> str

Return the crossing direction ("up" or "down").

time

time() -> Time

Return the time of this event.

---

Window

Represents a time window (interval between two times).

Windows represent periods when certain conditions are met, such as visibility windows.

Methods:

• duration –

  Return the duration of this window.

• end –

  Return the end time of this window.

• start –

  Return the start time of this window.

duration

duration() -> TimeDelta

Return the duration of this window.

end

end() -> Time

Return the end time of this window.

start

start() -> Time

Return the start time of this window.

---

find_events builtin

find_events(
    func: Callable[[float], float], start: Time, times: list[float]
) -> list[Event]

Find events where a function crosses zero.

This function detects zero-crossings of a user-defined function over a time span. Events can be found for any scalar function of time.

Parameters:

• func

  (Callable[[float], float]) –

  Function that takes a float (seconds from start) and returns a float.

• start

  (Time) –

  Reference time (epoch).

• times

  (list[float]) –

  Array of time offsets in seconds from start.

Returns:

• list[Event] –

  List of Event objects at the detected zero-crossings.

---

find_windows builtin

find_windows(
    func: Callable[[float], float], start: Time, end: Time, times: list[float]
) -> list[Window]

Find time windows where a function is positive.

This function finds all intervals where a user-defined function is positive. Windows are bounded by zero-crossings of the function.

Parameters:

• func

  (Callable[[float], float]) –

  Function that takes a float (seconds from start) and returns a float.

• start

  (Time) –

  Start time of the analysis period.

• end

  (Time) –

  End time of the analysis period.

• times

  (list[float]) –

  Array of time offsets in seconds from start.

Returns:

• list[Window] –

  List of Window objects for intervals where the function is positive.

---

visibility builtin

visibility(
    times: list[Time],
    gs: GroundLocation,
    mask: ElevationMask,
    sc: Trajectory,
    ephemeris: SPK,
    bodies: list[Origin] | None = None,
) -> list[Pass]

Compute visibility passes between a ground station and spacecraft.

This function finds all visibility windows where the spacecraft is above the elevation mask as seen from the ground station.

Parameters:

• times

  (list[Time]) –

  List of Time objects defining the analysis period.

• gs

  (GroundLocation) –

  Ground station location.

• mask

  (ElevationMask) –

  Elevation mask defining minimum elevation constraints.

• sc

  (Trajectory) –

  Spacecraft trajectory.

• ephemeris

  (SPK) –

  SPK ephemeris data.

• bodies

  (list[Origin] | None, default: None ) –

  Optional list of bodies for occultation checking.

Returns:

• list[Pass] –

  List of Pass objects containing visibility windows and observables.

Raises:

• ValueError –

  If ground station and spacecraft have different origins.

---

visibility_all builtin

visibility_all(
    times: list[Time],
    ground_stations: dict[str, tuple[GroundLocation, ElevationMask]],
    spacecraft: Ensemble,
    ephemeris: SPK,
    bodies: list[Origin] | None = None,
) -> dict[str, dict[str, list[Pass]]]

Compute visibility for multiple spacecraft and ground stations.

This function efficiently computes visibility passes for all combinations of spacecraft and ground stations, using parallel processing for large workloads.

Parameters:

• times

  (list[Time]) –

  List of Time objects defining the analysis period.

• ground_stations

  (dict[str, tuple[GroundLocation, ElevationMask]]) –

  Dictionary mapping station names to (location, mask) tuples.

• spacecraft

  (Ensemble) –

  Ensemble of spacecraft trajectories.

• ephemeris

  (SPK) –

  SPK ephemeris data.

• bodies

  (list[Origin] | None, default: None ) –

  Optional list of bodies for occultation checking.

Returns:

• dict[str, dict[str, list[Pass]]] –

  Nested dictionary: {spacecraft_name: {station_name: [passes]}}.