satorbit 0.3.0

Satellite orbit tools: TLE propagation, SP3 parsing, and coordinate transformations

satorbit

Satellite orbit tools for Python: TLE propagation, SP3 parsing, and coordinate transformations.

Originally developed at KNMI (Royal Netherlands Meteorological Institute) as part of swxtools.

Installation

pip install satorbit

Features

• TLE handling: Query space-track.org, parse TLE data, and propagate orbits using SGP4
• SP3 parsing: Read SP3 precise orbit files into pandas DataFrames
• Coordinate transforms: Convert between ITRF, geodetic, GCRS, and Quasi-Dipole coordinates
• Orbit interpolation: High-accuracy 7th-order Lagrange interpolation with automatic handling of geodetic, magnetic, and solar angle coordinates
• Keplerian mechanics: Simulate orbits with J2 perturbation effects

Usage

TLE Propagation

import pandas as pd
from satorbit import geodetic_orbit_from_tle

# Generate orbit positions for a satellite over a time range
times = pd.date_range("2024-01-01", "2024-01-02", freq="1min")
orbit = geodetic_orbit_from_tle(norad_id=25544, times=times)  # ISS
print(orbit[['lat', 'lon', 'height']])

API calls to space-track.org are automatically rate-limited (2s between requests) and TLE results are cached in memory with merge-on-overlap, so iterating over consecutive daily ranges only hits the API once per satellite.

SP3 File Parsing

from satorbit import sp3_to_itrf_df

df = sp3_to_itrf_df("orbit.sp3")
print(df[['x_itrf', 'y_itrf', 'z_itrf']])

Coordinate Transformations

from satorbit import itrf_to_geodetic, geodetic_to_qd

# Convert ITRF to geodetic coordinates
df_geo = itrf_to_geodetic(df_orbit)

# Convert to Quasi-Dipole magnetic coordinates
df_qd = geodetic_to_qd(df_geo)

Orbit Interpolation

from satorbit import interpolate_orbit_to_datetimeindex

# Interpolate an orbit DataFrame to new timestamps
# Works with ITRF, geodetic, quasi-dipole, MLT, and solar angle columns
new_times = pd.date_range("2024-01-01", "2024-01-02", freq="1s")
df_interpolated = interpolate_orbit_to_datetimeindex(df_orbit, new_times)

Spherical and angular columns (lon, lat, height, lat_qd, lon_qd, mlt, solar_elevation, solar_azimuth) are automatically converted to Cartesian representation before interpolation, avoiding singularities at the antimeridian and poles. This allows expensive coordinate transformations to be computed once at coarse cadence and then accurately interpolated to any timestamp.

Keplerian Orbit Simulation

import numpy as np
from satorbit import simulate_orbit, unperturbed_orbitalperiod

kepler = {
    "semimajoraxis": 7000,  # km
    "eccentricity": 0.001,
    "inclination": np.radians(98),
    "argumentofperigee": np.radians(90),
    "raan": np.radians(0),
    "initial_mean_anomaly": 0,
    "mu": 398600.4415,
    "re": 6378.1363,
    "j2": 1082.6357e-6
}

period = unperturbed_orbitalperiod(kepler)
times = np.linspace(0, period, 100)
orbit = simulate_orbit(kepler, times)

Configuration

For TLE queries from space-track.org, either create ~/.spacetrackorg.txt:

[default]
username = your_username
password = your_password

Or set credentials programmatically:

from satorbit import set_credentials

set_credentials("your_username", "your_password")

License

Apache License 2.0 - see LICENSE

Acknowledgements

Developed with support from ESA through the Swarm Data Innovation and Science Cluster (Swarm DISC).