Satellites

Predict satellite overpasses, compute ground-track swaths, and find temporal coincidences between airborne and spaceborne observations. Supports 14+ Earth-observing satellites with auto-fetched TLEs.

Satellite overpass prediction and coordination.

Fetches TLE (Two-Line Element) sets from CelesTrak, propagates orbits using Skyfield’s SGP4 implementation, and computes ground tracks, swath footprints, and spatial overlap with study areas. Supports 15+ satellite missions including PACE, Landsat-8/9, Sentinel-2A/B, and ICESat-2.

Satellite references

Rhodes, B. (2019). Skyfield: High precision research-grade positions for planets and Earth satellites generator. https://rhodesmill.org/skyfield/

TLE data source: CelesTrak (https://celestrak.org), maintained by T.S. Kelso.

class SatelliteInfo

Bases: object

Descriptor for an Earth observation satellite.

name: str

norad_id: int

swath_width_km: float

celestrak_group: str = 'earth-observation'

max_sza: float = 90.0

aliases: List[str]

__init__(name, norad_id, swath_width_km, celestrak_group='earth-observation', max_sza=90.0, aliases=<factory>)

Parameters:

• name (str)

• norad_id (int)

• swath_width_km (float)

• celestrak_group (str)

• max_sza (float)

• aliases (List[str])

Return type:

None

get_satellite(name)

Look up a satellite by name or alias.

Parameters:

name (str) – Satellite name (key in SATELLITE_REGISTRY) or an alias.

Return type:

SatelliteInfo

Returns:

SatelliteInfo for the requested satellite.

Raises:

ValueError – If the satellite is not found.

fetch_tle(satellite, max_age_hours=24.0)

Fetch the TLE for a satellite, using cache when available.

Downloads from CelesTrak if the cache is missing or stale.

Parameters:

• satellite (Union[str, SatelliteInfo]) – Satellite name or SatelliteInfo object.

• max_age_hours (float) – Maximum age of cached TLE before re-fetching.

Returns:

Loaded satellite object.

Return type:

skyfield.sgp4lib.EarthSatellite

Raises:

RuntimeError – If the TLE cannot be fetched or parsed.

clear_tle_cache(confirm=True)

Clear the TLE cache directory.

Parameters:

confirm (bool) – If True, prompt the user for confirmation before clearing.

Return type:

None

compute_ground_track(satellite, start_time, end_time, time_step_s=30.0, max_tle_age_hours=24.0)

Compute the satellite ground track over a time window.

Parameters:

• satellite (Union[str, SatelliteInfo]) – Satellite name or SatelliteInfo object.

• start_time (datetime) – Start of the time window (UTC datetime).

• end_time (datetime) – End of the time window (UTC datetime).

• time_step_s (float) – Time step for propagation in seconds.

• max_tle_age_hours (float) – Maximum TLE cache age.

Returns:

satellite_name, norad_id, timestamp, latitude, longitude, altitude_km, solar_zenith. Geometry is Point.

Return type:

GeoDataFrame with columns

compute_swath_footprint(ground_track_gdf, swath_width_km=None)

Generate swath footprint polygons from a ground track GeoDataFrame.

For each pass segment, constructs a polygon by offsetting perpendicular to the track direction by half the swath width on each side.

Parameters:

• ground_track_gdf (GeoDataFrame) – GeoDataFrame from compute_ground_track().

• swath_width_km (Optional[float]) – Override swath width in km. If None, looks up the satellite’s swath_width_km from SATELLITE_REGISTRY.

Returns:

satellite_name, norad_id, pass_start, pass_end, ascending, geometry (Polygon).

Return type:

GeoDataFrame with one row per pass segment. Columns

find_overpasses(satellite, region, start_time, end_time, time_step_s=10.0, max_sza=None, include_swath=True, max_tle_age_hours=24.0)

Find satellite passes over a geographic region within a time window.

Parameters:

• satellite (Union[str, SatelliteInfo]) – Satellite name or SatelliteInfo object.

• region (Union[Polygon, GeoDataFrame]) – Shapely Polygon or GeoDataFrame defining the area of interest.

• start_time (datetime) – Start of search window (UTC datetime).

• end_time (datetime) – End of search window (UTC datetime).

• time_step_s (float) – Time step in seconds for propagation.

• max_sza (Optional[float]) – Maximum solar zenith angle for usable passes. If None, uses the satellite’s default max_sza.

• include_swath (bool) – If True, geometry is swath Polygon. If False, geometry is ground track LineString.

• max_tle_age_hours (float) – Maximum TLE cache age.

Returns:

satellite_name, norad_id, pass_start, pass_end, ascending, ground_track, solar_zenith_at_center, is_usable.

Return type:

GeoDataFrame with one row per overpass. Columns

find_all_overpasses(satellites=None, region=None, start_time=None, end_time=None, max_sza=None, **kwargs)

Find overpasses for multiple satellites and concatenate results.

Parameters:

• satellites (Optional[List[Union[str, SatelliteInfo]]]) – List of satellite names or SatelliteInfo objects. If None, uses all entries in SATELLITE_REGISTRY.

• region (Union[Polygon, GeoDataFrame]) – Geographic region of interest.

• start_time (Optional[datetime]) – Start of search window (UTC).

• end_time (Optional[datetime]) – End of search window (UTC).

• max_sza (Optional[float]) – Override max SZA for all satellites. If None, uses each satellite’s default.

• **kwargs – Additional keyword arguments passed to find_overpasses().

Return type:

GeoDataFrame

Returns:

GeoDataFrame of combined overpass results, sorted by pass_start.

compute_overpass_overlap(flight_plan_gdf, overpasses_gdf, flight_time_utc, max_time_offset_min=60.0)

Compute spatial overlap between flight plan segments and satellite overpasses.

Parameters:

• flight_plan_gdf (GeoDataFrame) – GeoDataFrame from flight_plan.compute_flight_plan().

• overpasses_gdf (GeoDataFrame) – GeoDataFrame from find_overpasses().

• flight_time_utc (datetime) – UTC datetime when the flight starts (used to compute absolute times for flight plan segments).

• max_time_offset_min (float) – Maximum time offset (minutes) to consider as a valid overlap.

Returns:

satellite_name, segment_name, time_offset_min, overlap_area_km2, geometry.

Return type:

GeoDataFrame with overlap results. Columns

overpasses_to_kml(overpasses_gdf, kml_filename)

Export overpass results to a KML file.

Each pass becomes a KML Placemark with the satellite name and time in the description.

Parameters:

• overpasses_gdf (GeoDataFrame) – GeoDataFrame from find_overpasses().

• kml_filename (str) – Output KML file path.

Return type:

None