Module satellite 

Satellite tracking and pass prediction.

This module builds the conversion and prediction layer on top of the sgp4 crate, which provides the validated SGP4/SDP4 propagator. The propagator is treated as the numerical engine; this module owns the surrounding pipeline: TLE ingestion, frame conversion, observer-relative geometry, pass prediction, and ground tracks.

Frame and unit conventions

• The propagator emits position and velocity in the True Equator, Mean Equinox (TEME) frame of epoch — an Earth-centered inertial frame that does not rotate with the Earth and is distinct from J2000/ICRS.
• The supported conversion path is TEME → ECEF via a Greenwich sidereal-time rotation about the Z axis (reusing crate::time), followed by ECEF → geodetic latitude/longitude/altitude on the WGS84 ellipsoid.
• Precession and nutation are intentionally omitted, consistent with the project’s existing accuracy posture (see docs/accuracy-and-limits.md). Production propagation uses the sgp4 crate’s default WGS84 + IAU model; geodetic conversion uses the WGS84 ellipsoid (aligned). Optional PropagationModel::AfspcCompatibility selects WGS72 + legacy AFSPC sidereal/epoch handling for Vallado reference reproduction.
• Positions are kilometres, velocities kilometres per second, angles degrees, and times UTC unless stated otherwise.

The staged implementation plan lives in docs/satellite-tracking-plan.md. Companion theory for the SGP4 layer is in docs/sgp4.md, with the non-operational crate::sgp4_teaching module for Kepler / mean-motion pedagogy. Implemented so far: Tle parses and validates 2- and 3-line element sets (with structured, educational TleErrors); propagate takes a parsed element set to a TemeState via the sgp4 engine; teme_to_ecef and ecef_to_geodetic bridge TEME to WGS84 geodetic coordinates using Greenwich sidereal time (same Z-rotation convention as ECI→ECEF in crate::coordinates); subpoint combines propagation with that chain for the sub-satellite point; and look_angles completes the topocentric East–North–Up (ENU) pipeline for azimuth, elevation, slant range, and range rate; predict_passes finds visible passes over a time window using a coarse elevation scan with bisection refinement; ground_track samples the sub-satellite path with ground_track_to_csv / ground_track_to_json for plotting pipelines.

Example

use ephemerust::satellite::Tle;

let tle = Tle::parse(
    "ISS (ZARYA)\n\
     1 25544U 98067A   20194.88612269 -.00002218  00000-0 -31515-4 0  9992\n\
     2 25544  51.6461 221.2784 0001413  89.1723 280.4612 15.49507896236008",
)
.unwrap();

assert_eq!(tle.catalog_number, 25544);
assert!((tle.inclination_deg - 51.6461).abs() < 1e-6);

Structs

GroundTrackSample

One sample along a satellite ground track: UTC time plus the corresponding Subpoint.

LookAngles

Observer-relative look angles for pointing and visibility.

Pass

A single visible pass of a satellite over an observer.

Subpoint

A sub-satellite (ground) point: the geodetic position directly beneath the satellite.

TemeState

Position and velocity in the TEME frame of epoch.

Tle

A parsed and validated Two-Line Element set.

Enums

PropagationModel

Which SGP4 constant set and propagate path the sgp4 crate uses.

TleError

A structured, educational error describing why a Two-Line Element set could not be parsed.

Functions

ecef_to_geodetic

Converts WGS84 Ecef coordinates (metres) to a Subpoint with altitude in kilometres.

ground_track

Samples the satellite ground track as WGS84 sub-satellite points from window_start (inclusive) through window_end (exclusive), every step.

ground_track_to_csv

Serializes ground-track samples as CSV (RFC 4180–style: header row, comma-separated).

ground_track_to_json

Serializes ground-track samples as a JSON array (pretty-printed).

ground_track_with_model

Like ground_track with an explicit PropagationModel.

look_angles

Topocentric look angles from a TLE, time, and observer location.

look_angles_with_model

Like look_angles with an explicit PropagationModel.

predict_passes

Predicts visible passes of a satellite over an observer in a UTC time window.

predict_passes_with_model

Like predict_passes with an explicit PropagationModel.

propagate

Propagates a TLE to the given UTC time and returns the TemeState.

propagate_with_model

Propagates a TLE with an explicit PropagationModel.

subpoint

Propagates the element set to time and returns the sub-satellite point (geodetic latitude, longitude, and height above the WGS84 ellipsoid).

subpoint_with_model

Like subpoint with an explicit PropagationModel.

teme_to_ecef

Converts a TEME position to ECEF coordinates at the given UTC time.