{"id":51455567,"url":"https://github.com/astro-tools/orbit-formats","last_synced_at":"2026-07-06T00:33:38.280Z","repository":{"id":361446019,"uuid":"1253953122","full_name":"astro-tools/orbit-formats","owner":"astro-tools","description":"Lossless round-trip across orbital state-vector and ephemeris formats — TLE, CCSDS NDM, SP3, SPK, STK ephemeris, GMAT report.","archived":false,"fork":false,"pushed_at":"2026-06-03T20:11:57.000Z","size":1449,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-06T00:33:36.098Z","etag":null,"topics":["aerospace","astrodynamics","ccsds","ephemeris","file-formats","mission-analysis","orbital-mechanics","pandas","python","rinex","sgp4","sp3","space","spice","tle"],"latest_commit_sha":null,"homepage":"https://astro-tools.github.io/orbit-formats/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astro-tools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T01:23:12.000Z","updated_at":"2026-06-03T20:10:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/astro-tools/orbit-formats","commit_stats":null,"previous_names":["astro-tools/orbit-formats"],"tags_count":0,"template":false,"template_full_name":"astro-tools/.repo-template","purl":"pkg:github/astro-tools/orbit-formats","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-tools%2Forbit-formats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-tools%2Forbit-formats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-tools%2Forbit-formats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-tools%2Forbit-formats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astro-tools","download_url":"https://codeload.github.com/astro-tools/orbit-formats/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astro-tools%2Forbit-formats/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35174071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aerospace","astrodynamics","ccsds","ephemeris","file-formats","mission-analysis","orbital-mechanics","pandas","python","rinex","sgp4","sp3","space","spice","tle"],"created_at":"2026-07-06T00:33:37.430Z","updated_at":"2026-07-06T00:33:38.233Z","avatar_url":"https://github.com/astro-tools.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# orbit-formats\n\n[![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)\n[![Docs](https://github.com/astro-tools/orbit-formats/actions/workflows/docs.yml/badge.svg)](https://astro-tools.github.io/orbit-formats/)\n[![PyPI](https://img.shields.io/pypi/v/orbit-formats.svg)](https://pypi.org/project/orbit-formats/)\n[![Python versions](https://img.shields.io/pypi/pyversions/orbit-formats.svg)](https://pypi.org/project/orbit-formats/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nLossless round-trip across orbital state-vector and ephemeris formats.\n\norbit-formats reads and writes the full CCSDS NDM family (OEM, OMM, OPM, OCM, AEM, APM, CDM, TDM,\nand the combined NDM, in KVN and XML), TLE (two-line / 3LE / catalogue / alpha-5), the Celestrak /\nSpace-Track flat OMM (JSON and CSV), STK ephemeris, STK attitude, SP3, and SPICE SPK (behind the\n`[spk]` extra); additionally reads GMAT report and RINEX navigation; rotates Cartesian states\nacross TEME / EME2000 / GCRF / ICRF / ITRF and projects Earth-fixed positions to geodetic\nlongitude / latitude / height; surfaces OPM / OCM maneuvers on the canonical object and projects\nevery time-series category — ephemeris, state, mean-element set, and attitude — to a DataFrame; and\nround-trips its writable formats losslessly, cross-validated against Orekit and SPICE. See the\n[changelog](CHANGELOG.md) for released functionality.\n\n## What this is\n\norbit-formats reads any supported orbital state or ephemeris format into a single\ncanonical in-memory representation, writes it back to any supported target, and\nround-trips losslessly when the two formats can express the same information. When a\nconversion cannot preserve information — covariance a target cannot hold, the\nmean-element semantics of a TLE, a value truncated to a format's field width — it emits\nan explicit, structured warning naming what was lost, never a silent drop.\n\nIt consolidates the format-I/O layer that astro-tools projects keep re-implementing into\none permissively-licensed (MIT) library that anything in the org — or outside it — can\ndepend on as the single source of format truth.\n\n## Quick start\n\n```python\nfrom orbit_formats import read, write\n\n# read auto-detects the format; an OEM becomes a canonical Ephemeris\neph = read(\"orbit.oem\")\n\n# the canonical DataFrame downstream consumers adopt: Epoch, X, Y, Z, VX, VY, VZ\ndf = eph.to_dataframe()\ndf.attrs[\"coordinate_system\"], df.attrs[\"time_scale\"]\n\n# round-trip a file byte-for-byte by retaining the source\nwrite(read(\"orbit.oem\", retain_source=True), \"copy.oem\")\n```\n\nA conversion that cannot carry every field across warns (naming what was lost) rather than\ndropping data silently; one that cannot be done without modelling — a TLE's mean elements to\nan ephemeris — is refused, not faked. See the\n[lossy-conversion contract](https://astro-tools.github.io/orbit-formats/lossy-conversions/)\nand the\n[conversion-capability matrix](https://astro-tools.github.io/orbit-formats/conversion-matrix/).\n\n## Supported formats\n\n| Format | Read | Write | Canonical form |\n|--------|:----:|:-----:|----------------|\n| TLE / 3LE | ✅ | ✅ | mean-element set |\n| CCSDS OEM (KVN + XML) | ✅ | ✅ | ephemeris |\n| CCSDS OMM (KVN + XML) | ✅ | ✅ | mean-element set |\n| OMM JSON / CSV (Celestrak / Space-Track) | ✅ | ✅ | mean-element set |\n| CCSDS OPM (KVN + XML) | ✅ | ✅ | state vector |\n| CCSDS OCM (KVN + XML) | ✅ | ✅ | ephemeris |\n| CCSDS AEM (KVN + XML) | ✅ | ✅ | attitude |\n| CCSDS APM (KVN + XML) | ✅ | ✅ | attitude |\n| CCSDS CDM (KVN + XML) | ✅ | ✅ | conjunction |\n| CCSDS TDM (KVN + XML) | ✅ | ✅ | tracking |\n| CCSDS combined NDM (KVN + XML) | ✅ | ✅ | aggregate of NDM messages |\n| GMAT report | ✅ | — | ephemeris / state |\n| STK ephemeris | ✅ | ✅ | ephemeris |\n| STK attitude | ✅ | ✅ | attitude |\n| SP3 (SP3-c / SP3-d) | ✅ | ✅ | ephemeris |\n| RINEX navigation (3.x) | ✅ | — | mean-element set / state |\n| SPK (`[spk]` extra) | ✅ | ✅ | ephemeris |\n\nThe [canonical representation](https://astro-tools.github.io/orbit-formats/canonical-representation/)\n— a small typed dataclass family unified by a metadata spine — is the format-agnostic form\neverything reads into and writes from. Every time-series category — `Ephemeris`, `StateVector`,\n`MeanElementSet`, and `Attitude` — projects to a pandas DataFrame.\n\n## What this is not\n\n- **Not** a propagator, integrator, or analysis toolkit — it does only the conversion\n  the formats themselves require.\n- **Not** a general frame-transformation engine — it performs the time-scale and frame\n  transforms cross-format conversion needs and defers arbitrary transforms to\n  [astropy](https://www.astropy.org/) or SPICE.\n- **Not** a way to turn a TLE's mean elements into an osculating state — that is a\n  propagation, not a format conversion.\n\n## Installation\n\n```bash\npip install orbit-formats\n```\n\nSPICE SPK support is kept behind an optional extra (heavier binary-kernel dependency):\n\n```bash\npip install orbit-formats[spk]\n```\n\norbit-formats requires Python 3.10, 3.11, or 3.12.\n\n## Documentation\n\nFull docs at **\u003chttps://astro-tools.github.io/orbit-formats/\u003e**.\n\n## Development\n\n```bash\ngit clone https://github.com/astro-tools/orbit-formats.git\ncd orbit-formats\nuv sync --all-groups\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full branch / PR / test workflow.\n\n## Licence\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastro-tools%2Forbit-formats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastro-tools%2Forbit-formats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastro-tools%2Forbit-formats/lists"}