orbit-formats 0.1.0

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

orbit-formats

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

Status: orbit-formats reads TLE, CCSDS OEM (KVN), and GMAT report files, writes CCSDS OEM, and round-trips OEM losslessly. More formats (the rest of the CCSDS NDM family, SP3, STK, SPK, RINEX) and a real frame-rotation layer land in later versions. See the changelog 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

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 and the conversion-capability matrix.

Supported formats

Format	Read	Write	Canonical form
TLE / 3LE	✅	—	mean-element set
CCSDS OEM (KVN)	✅	✅	ephemeris
GMAT report	✅	—	ephemeris / state

The 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 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

pip install orbit-formats

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

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

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

See CONTRIBUTING.md for the full branch / PR / test workflow.

Licence

MIT. See LICENSE.