Metadata-Version: 2.4
Name: satorbit
Version: 0.2.0
Summary: Satellite orbit tools: TLE propagation, SP3 parsing, and coordinate transformations
Project-URL: Homepage, https://gitlab.com/KNMI-OSS/spaceweather/satorbit
Project-URL: Bug Tracker, https://gitlab.com/KNMI-OSS/spaceweather/satorbit/-/issues
Author-email: Eelco Doornbos <eelco.doornbos@knmi.nl>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Requires-Dist: apexpy
Requires-Dist: astropy
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: requests
Requires-Dist: scipy
Requires-Dist: sgp4
Provides-Extra: test
Requires-Dist: pytest; 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
- **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)
```

### 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).
