astra.debris module

ASTRA Core debris catalog filtering and statistics. Pre-propagation filtering of debris catalogs. ALL filtering in this module operates on DebrisObject parameters (derived TLE fields, NOT propagated positions). Filtering is O(N) and involves no SGP4 calls.

astra.debris.make_debris_object(source)

Build a DebrisObject from a SatelliteTLE or SatelliteOMM with derived elements. For TLE sources, elements are parsed directly from the raw TLE lines. For OMM sources, elements are read directly from the already-converted dataclass fields (no string parsing required).

astra.debris.filter_altitude(objects, min_km, max_km)

Retain only objects whose mean orbital altitude is within bounds. Also filters objects whose perigee is pathologically low (perigee < min_km * 0.9) to discard quickly-decaying objects. :param objects: List of DebrisObjects. :param min_km: Lower altitude bound (inclusive). :param max_km: Upper altitude bound (inclusive).

Returns:

Filtered list of DebrisObjects.

astra.debris.filter_region(objects, lat_min_deg, lat_max_deg, lon_min_deg=None, lon_max_deg=None)

Retain objects whose ground track could pass through a bounding box. Uses a two-stage filter: Stage 1 - Latitude (inclination-based): An object with inclination i reaches latitudes up to i (prograde) or 180 - i (retrograde). Objects whose latitude band does not overlap [lat_min_deg, lat_max_deg] are excluded immediately. Stage 2 - Longitude (RAAN-based, if bounds are supplied): For short-period orbits (period < 1440 min / 24 h), Earth’s rotation causes the satellite’s ground track to sweep all longitudes within a day, so the longitude filter is vacuous and all Stage-1 survivors are kept. For long-period orbits (GEO / HEO / deep-space), the ascending node is anchored near RAAN for the duration of interest, so a window check around RAAN is applied with a margin equal to the longitude swept in half an orbital period. This remains an over-inclusive pre-filter. .. note:

For hard longitude exclusion use ``propagate_trajectory()`` followed
by manual geodetic post-filtering.

Parameters:

• objects – List of DebrisObjects.

• lat_min_deg – Minimum latitude bound (degrees).

• lat_max_deg – Maximum latitude bound (degrees).

• lon_min_deg – Minimum longitude bound (degrees, -180 to +180). None disables longitude filtering entirely.

• lon_max_deg – Maximum longitude bound (degrees, -180 to +180). None disables longitude filtering entirely.

Returns:

Filtered list of DebrisObjects.

Example::

# Retain objects that could pass over India (lat 8-37, lon 68-97) filtered = filter_region(

objects, lat_min_deg=8.0, lat_max_deg=37.0, lon_min_deg=68.0, lon_max_deg=97.0,

)

astra.debris.filter_time_window(objects, t_start_jd, t_end_jd)

Eliminate objects whose TLE epoch is too stale for predictions. :param objects: List of DebrisObjects. :param t_start_jd: Window start as Julian Date. :param t_end_jd: Window end as Julian Date.

Returns:

Filtered list of DebrisObjects.

astra.debris.catalog_statistics(objects)

Compute summary statistics across a debris catalog. :param objects: List of DebrisObjects.

Returns:

Dictionary of computed statistics.

astra.debris.apply_filters(catalog, config)

Execute the REQUIRED PIPELINE FUNCTION for filtering. :param catalog: List of DebrisObjects to filter. :param config: FilterConfig data class outlining constraints.

Returns:

Filtered list of DebrisObjects.