Metadata-Version: 2.4
Name: orbit-formats
Version: 0.3.0
Summary: Lossless round-trip across orbital state-vector and ephemeris formats.
Project-URL: Homepage, https://github.com/astro-tools/orbit-formats
Project-URL: Repository, https://github.com/astro-tools/orbit-formats
Project-URL: Issues, https://github.com/astro-tools/orbit-formats/issues
Project-URL: Documentation, https://astro-tools.github.io/orbit-formats/
Project-URL: Changelog, https://github.com/astro-tools/orbit-formats/blob/main/CHANGELOG.md
Author: Dimitrije Jankovic
License-Expression: MIT
License-File: LICENSE
Keywords: astrodynamics,ccsds,ephemeris,orbital-mechanics,space,spice,tle
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: astropy>=6.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: sgp4>=2.20
Requires-Dist: xsdata>=26.2
Provides-Extra: spk
Requires-Dist: spiceypy>=6.0; extra == 'spk'
Description-Content-Type: text/markdown

# orbit-formats

[![CI](https://github.com/astro-tools/orbit-formats/actions/workflows/ci.yml/badge.svg)](https://github.com/astro-tools/orbit-formats/actions/workflows/ci.yml)
[![Docs](https://github.com/astro-tools/orbit-formats/actions/workflows/docs.yml/badge.svg)](https://astro-tools.github.io/orbit-formats/)
[![PyPI](https://img.shields.io/pypi/v/orbit-formats.svg)](https://pypi.org/project/orbit-formats/)
[![Python versions](https://img.shields.io/pypi/pyversions/orbit-formats.svg)](https://pypi.org/project/orbit-formats/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Lossless round-trip across orbital state-vector and ephemeris formats.

> **Status:** orbit-formats reads and writes the full CCSDS NDM family (OEM, OMM, OPM, OCM, AEM,
> APM, CDM, TDM, and the combined NDM, in KVN and XML), TLE, STK ephemeris, and SPICE SPK (behind
> the `[spk]` extra); additionally reads SP3, GMAT report, and RINEX navigation; rotates Cartesian
> states across TEME / EME2000 / GCRF / ICRF / ITRF; and round-trips its writable formats
> losslessly, cross-validated against Orekit and SPICE. Vendor and alternative encodings (STK
> attitude, the Celestrak / Space-Track OMM encodings, an SP3 writer) follow in later versions.
> See the [changelog](CHANGELOG.md) for released functionality.

## What this is

orbit-formats reads any supported orbital state or ephemeris format into a single
canonical in-memory representation, writes it back to any supported target, and
round-trips losslessly when the two formats can express the same information. When a
conversion cannot preserve information — covariance a target cannot hold, the
mean-element semantics of a TLE, a value truncated to a format's field width — it emits
an explicit, structured warning naming what was lost, never a silent drop.

It consolidates the format-I/O layer that astro-tools projects keep re-implementing into
one permissively-licensed (MIT) library that anything in the org — or outside it — can
depend on as the single source of format truth.

## Quick start

```python
from orbit_formats import read, write

# read auto-detects the format; an OEM becomes a canonical Ephemeris
eph = read("orbit.oem")

# the canonical DataFrame downstream consumers adopt: Epoch, X, Y, Z, VX, VY, VZ
df = eph.to_dataframe()
df.attrs["coordinate_system"], df.attrs["time_scale"]

# round-trip a file byte-for-byte by retaining the source
write(read("orbit.oem", retain_source=True), "copy.oem")
```

A conversion that cannot carry every field across warns (naming what was lost) rather than
dropping data silently; one that cannot be done without modelling — a TLE's mean elements to
an ephemeris — is refused, not faked. See the
[lossy-conversion contract](https://astro-tools.github.io/orbit-formats/lossy-conversions/)
and the
[conversion-capability matrix](https://astro-tools.github.io/orbit-formats/conversion-matrix/).

## Supported formats

| Format | Read | Write | Canonical form |
|--------|:----:|:-----:|----------------|
| TLE / 3LE | ✅ | ✅ | mean-element set |
| CCSDS OEM (KVN + XML) | ✅ | ✅ | ephemeris |
| CCSDS OMM (KVN + XML) | ✅ | ✅ | mean-element set |
| CCSDS OPM (KVN + XML) | ✅ | ✅ | state vector |
| CCSDS OCM (KVN + XML) | ✅ | ✅ | ephemeris |
| CCSDS AEM (KVN + XML) | ✅ | ✅ | attitude |
| CCSDS APM (KVN + XML) | ✅ | ✅ | attitude |
| CCSDS CDM (KVN + XML) | ✅ | ✅ | conjunction |
| CCSDS TDM (KVN + XML) | ✅ | ✅ | tracking |
| CCSDS combined NDM (KVN + XML) | ✅ | ✅ | aggregate of NDM messages |
| GMAT report | ✅ | — | ephemeris / state |
| STK ephemeris | ✅ | ✅ | ephemeris |
| SP3 (SP3-c / SP3-d) | ✅ | — | ephemeris |
| RINEX navigation (3.x) | ✅ | — | mean-element set / state |
| SPK (`[spk]` extra) | ✅ | ✅ | ephemeris |

The [canonical representation](https://astro-tools.github.io/orbit-formats/canonical-representation/)
— a small typed dataclass family unified by a metadata spine — is the format-agnostic form
everything reads into and writes from.

## What this is not

- **Not** a propagator, integrator, or analysis toolkit — it does only the conversion
  the formats themselves require.
- **Not** a general frame-transformation engine — it performs the time-scale and frame
  transforms cross-format conversion needs and defers arbitrary transforms to
  [astropy](https://www.astropy.org/) or SPICE.
- **Not** a way to turn a TLE's mean elements into an osculating state — that is a
  propagation, not a format conversion.

## Installation

```bash
pip install orbit-formats
```

SPICE SPK support is kept behind an optional extra (heavier binary-kernel dependency):

```bash
pip install orbit-formats[spk]
```

orbit-formats requires Python 3.10, 3.11, or 3.12.

## Documentation

Full docs at **<https://astro-tools.github.io/orbit-formats/>**.

## Development

```bash
git clone https://github.com/astro-tools/orbit-formats.git
cd orbit-formats
uv sync --all-groups
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full branch / PR / test workflow.

## Licence

MIT. See [LICENSE](LICENSE).
