astra.omm module

ASTRA Core OMM (Orbit Mean-Elements Message) Parser.

Provides isolated ingestion and validation of CCSDS OMM JSON payloads as published by Space-Track.org and CelesTrak.

This module acts as the dedicated “parser funnel” for the modern OMM format. It does NOT contain any physics or propagation logic. Its only job is to safely translate a JSON dictionary from an API response into a SatelliteOMM dataclass, applying all necessary unit conversions so the physics engine receives correctly-scaled floats.

Key Conversions (OMM JSON → SGP4 Engine):

• Angles (inclination, RAAN, arg. perigee, mean anomaly): degrees → radians.

• Mean Motion: rev/day → rad/min.

• Epoch (ISO-8601 timestamp string): → Julian Date float.

References

CCSDS 502.0-B-3 Recommendation for Space Data System Standards. Space-Track.org API Documentation, OMM JSON format. Celestrak GP Data Documentation (https://celestrak.org/SOCRATES/help.php).

astra.omm.parse_omm_record(record)

Parse a single OMM JSON dictionary into a SatelliteOMM dataclass.

Applies all mandatory unit conversions to guarantee the returned object is ready for direct injection into the SGP4 physics engine via Satrec.sgp4init().

Parameters:

record – A single dictionary from a Space-Track or CelesTrak OMM JSON response. Must contain at minimum the Keplerian element keys.

Returns:

A fully populated SatelliteOMM instance.

Raises:

InvalidTLEError – If mandatory orbital element fields are absent or non-numeric.

astra.omm.parse_omm_json(json_text)

Parse a bulk CelesTrak / Space-Track OMM JSON response string.

Handles both a JSON array of records (CelesTrak style) and ensures robust error logging for individual malformed records without aborting the entire catalog ingestion.

Parameters:

json_text – Raw JSON string from an HTTP response body.

Returns:

List of successfully parsed SatelliteOMM instances. Malformed individual records are skipped and logged as warnings.

Raises:

AstraError – If the top-level JSON structure is unparseable.

Example:

import astra
satellites = astra.parse_omm_json(response_text)
print(f"Loaded {len(satellites)} OMM objects.")

astra.omm.xptle_to_satellite_omm(tle_objects)

Convert SatelliteTLE objects (e.g. from Spacebook XP-TLE) to SatelliteOMM.

Extracts the Keplerian elements using SGP4’s internal parser and populates a generic SatelliteOMM structure. The resulting objects will inherit metadata tags (like _spacebook_source) transparently.

Since TLEs lack mass and RCS by definition, these physical fields will be None.

Parameters:

tle_objects – List of SatelliteTLE instances.

Returns:

List of SatelliteOMM instances matching the TLE element states.

astra.omm.load_omm_file(filepath)

Load a local OMM JSON file from disk and parse it into SatelliteOMM objects.

This is the OMM equivalent of load_tle_catalog() and is intended for users who download OMM data manually from Space-Track.org or CelesTrak and want to load it from a local path.

Data formats: ✓ SatelliteOMM only (use load_tle_catalog for TLEs)

Parameters:

filepath – Path to a local .json file containing an OMM JSON array.

Returns:

List of SatelliteOMM instances.

Raises:

AstraError – If the file does not exist, is not readable, or the JSON structure is invalid.

Example:

import astra
satellites = astra.load_omm_file("starlink_omm.json")
print(f"Loaded {len(satellites)} Starlink satellites from OMM file.")

astra.omm.validate_omm(record)

Validate that an OMM JSON dictionary contains physically sensible values.

Performs lightweight sanity checks on the orbital elements without attempting a full parse. Use before parse_omm_record() to pre-screen records from untrusted sources.

Checks performed:

• Required keys are present and non-empty.

• Eccentricity is in [0, 1).

• Mean motion is positive.

• Inclination is in [0, 180].

• Epoch string is parseable.

Parameters:

record – A single OMM dictionary (as returned from json.loads()).

Returns:

True if the record passes all sanity checks, False otherwise.

Example:

import astra, json
records = json.loads(open("catalog.json").read())
valid = [r for r in records if astra.validate_omm(r)]
print(f"{len(valid)}/{len(records)} records passed validation.")