Metadata-Version: 2.4
Name: satorbit
Version: 0.2.2
Summary: Satellite orbit tools: TLE propagation, SP3 parsing, and coordinate transformations
Project-URL: Homepage, https://gitlab.com/KNMI-OSS/spaceweather/libs/satorbit
Project-URL: Repository, https://gitlab.com/KNMI-OSS/spaceweather/libs/satorbit
Project-URL: Bug Tracker, https://gitlab.com/KNMI-OSS/spaceweather/libs/satorbit/-/issues
Author-email: Eelco Doornbos <eelco.doornbos@knmi.nl>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: orbit,satellite,sgp4,sp3,space-track,tle
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Requires-Dist: apexpy>=2.0
Requires-Dist: astropy>=5.0
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.4
Requires-Dist: requests>=2.25
Requires-Dist: scipy>=1.8
Requires-Dist: sgp4>=2.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# 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](https://gitlab.com/KNMI-OSS/spaceweather/swxtools).

## Installation

```bash
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

```python
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']])
```

### SP3 File Parsing

```python
from satorbit import sp3_to_itrf_df

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

### Coordinate Transformations

```python
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

```python
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

```python
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, create `~/.spacetrackorg.txt`:

```ini
[default]
username = your_username
password = your_password
```

## License

Apache License 2.0 - see [LICENSE](LICENSE)

## Acknowledgements

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