SGP4 Satellite Orbit Propagator

2.25 · active · verified Sun Apr 12

The `sgp4` Python library provides a highly accurate implementation of the SGP4 and SDP4 orbital propagation algorithms, as described in the 2020 revision of the Spacetrack Report #3. It allows users to track Earth satellites given their Two-Line Element (TLE) data, predicting their position and velocity at specific times. The library is actively maintained, with version 2.25 being the latest, and typically sees several releases per year addressing minor bugs and precision improvements.

Warnings

gotcha `sgp4` expects naive UTC `datetime` objects or Julian dates. Passing timezone-aware `datetime` objects or naive `datetime` objects in a non-UTC timezone can lead to incorrect calculations or errors.
Fix: Ensure all `datetime` objects passed to `sgp4` methods are converted to naive UTC. Use `dt.astimezone(timezone.utc).replace(tzinfo=None)` for timezone-aware datetimes.
gotcha The position and velocity outputs from `satellite.sgp4()` are always in kilometers (km) and kilometers per second (km/s) respectively. Users expecting meters or other units must perform explicit conversions.
Fix: Multiply position components by 1000 to get meters, and velocity components by 1000 to get meters/second, if required.
gotcha The `Satrec.twoline2_parse` method requires TLE strings to adhere strictly to the NORAD two-line element set format (69 characters per line). Malformed TLEs (e.g., incorrect length, invalid characters) will result in `ValueError` or `IndexError`.
Fix: Validate TLE input strings for correct format and length before parsing. Use a reliable source for TLE data.
breaking In `sgp4` version 1.10, the direct return type of `Satrec.jday()` changed from a single Julian date float to a tuple of two floats (Julian date integer part, Julian date fractional part). While the `sgp4()` propagation method handles this internally, direct access to `Satrec.jday` from code written for versions prior to 1.10 will break if not updated.
Fix: For converting `datetime` objects to Julian dates, use `sgp4.api.jday_from_datetime()` which returns the correct `(jd, fr)` pair. If directly calling `Satrec.jday()`, update code to expect `(jd, fr)` instead of a single float.

Install

pip install sgp4 Install stable version

Imports

Satrec
```
from sgp4.api import Satrec
```
Main class for satellite representation and propagation.
WGS72
```
from sgp4.api import WGS72
```
WGS-72 Earth model, often used in conjunction with SGP4.
jday_from_datetime
```
from sgp4.api import jday_from_datetime
```
Utility function to convert Python datetime objects to Julian date (jd, fr) pair for SGP4. Recommended over manual conversion or direct `Satrec.jday()` for `datetime` objects.

Quickstart

This quickstart demonstrates how to parse Two-Line Element (TLE) data for a satellite, define a specific propagation time in UTC, and then use the `sgp4` method of the `Satrec` object to calculate the satellite's Earth-Centered Inertial (ECI) position and velocity. The output units are kilometers and kilometers per second.

from datetime import datetime, timezone
from sgp4.api import Satrec

# Example TLE for NOAA 15 (valid for a specific epoch)
# Use actual current TLE data for real-world applications
tle_line1 = '1 25338U 98030A   23098.50000000  .00000000  00000-0  57606-2 0  9994'
tle_line2 = '2 25338  98.7402  65.3400 0001000  90.0000  270.0000 14.28000000000000'

# Parse the TLE data into a Satrec object
satellite = Satrec.twoline2_parse(tle_line1, tle_line2)

# Define the time for propagation (example: April 8, 2023, 12:00:00 UTC)
# SGP4 expects naive UTC datetimes or Julian dates.
prop_time = datetime(2023, 4, 8, 12, 0, 0, tzinfo=timezone.utc).replace(tzinfo=None)

# Propagate the satellite to the specified time
# The sgp4 method returns (error_code, position_km, velocity_km_s)
e, r, v = satellite.sgp4(
    prop_time.year, prop_time.month, prop_time.day,
    prop_time.hour, prop_time.minute, prop_time.second + prop_time.microsecond / 1_000_000
)

if e == 0:
    print(f"Satellite ID: {satellite.satnum}")
    print(f"Propagation time: {prop_time} UTC")
    print(f"Position (km, ECI): {r}")
    print(f"Velocity (km/s, ECI): {v}")
else:
    print(f"SGP4 error code: {e}. Check TLE validity or propagation time range.")

view raw JSON →