Initial commit

README.md

@@ -0,0 +1,74 @@
+# odm
+
+Orbit Data Messages: read, write and convert orbital element sets.
+
+Everything ODMS knows about orbital *formats*, with nothing it knows about
+Django, HTTP or a database. Dependencies are `sgp4` and the standard library.
+
+## Why it is a library
+
+The formats used to live in the service that happened to serve them first —
+TLE rendering in a Django app's `formats.py`, the element-set catalogue in
+another app, the OPM/OEM builders in a third, and the canonical record itself
+implicit in a model row. That worked while one service read the data. It stops
+working the moment a second one does: a format two services implement separately
+is a format they will eventually disagree about, and the disagreement surfaces as
+a satellite whose OMM and TLE describe slightly different orbits.
+
+So: the OMM is the record. TLE text, OMM XML, OMM KVN and Celestrak GP CSV are
+*renderings* of it, and the CCSDS SANA element sets are conversions of the state
+it propagates to. One definition each, here.
+
+## Use
+
+```python
+from odm import OmmRecord, parse_tle, registry
+
+parsed = parse_tle(name, line1, line2)
+record = OmmRecord(omm=parsed.omm, object_name=parsed.name, line1=line1, line2=line2)
+
+xml = registry.get("omm_xml").write([record])
+csv = registry.get("csv").write([record])
+kep = registry.get("keplerian").write([record], backend=backend, at=when)
+```
+
+Every writer takes the same arguments — `write(records, *, backend=None,
+at=None)` — so a caller never has to know which kind it got. `backend` and `at`
+matter only to the element-set formats, which propagate before converting.
+
+## Modules
+
+| Module | What |
+|---|---|
+| `records` | `OmmRecord`, `ParsedTLE`, `StateVector` — what readers produce and writers consume. |
+| `tle` | TLE text in and out. Lossy by construction; see the module docstring. |
+| `omm` | CCSDS 502.0-B-3 OMM, XML and KVN. The authoritative rendering. |
+| `gp` | Celestrak GP CSV, in their exact column order. |
+| `norad` | Catalog-ID normalisation, ALPHA-5, and the temp-ID fallback. |
+| `orbits` | Mean-element derivations: period, apogee, perigee, altitudes. |
+| `conversions` | State vector → one SANA element set. |
+| `element_sets` | The SANA catalogue, and computing a set for an OMM. |
+| `messages` | CCSDS OPM/OEM: build and parse. |
+| `registry` | Every output format in one table. |
+| `propagator` | The seam a propagation backend implements. |
+
+## The propagator seam
+
+`odm` does no orbital mechanics beyond mean-element algebra. Anything needing a
+propagated state takes a `PropagatorBackend` — `element_sets.compute_element_set`,
+`messages.build_opm`, `messages.build_oem`, the element-set writers.
+
+The backend is always **passed in**, never looked up. A library that reached for
+a service's configured default would only work inside that service, which is the
+thing this package exists not to be. Implementations live in the `yksa_orbital`
+Django app (pure-Python SGP4, and an HTTP client to the Orekit sidecar).
+
+## What is deliberately not here
+
+- **Storage.** ODMS holds elements in Django, `track` holds them elsewhere, the
+  sidecar holds none. The format code works on records; the service adapts.
+- **Serving.** Content types and filenames are in `registry` because they are
+  properties of the format, but nothing here builds a response.
+- **The simulation model.** Force models, atmospheres and propagator settings
+  belong to the Orekit sidecar (`services/orekit/config.py`), which is their one
+  definition for the same reason this package is the formats' one definition.