astra.ocm module

ASTRA Core — STK Ephemeris & Orbit State Parser.

Parses the AGI/STK .e (DotE) ephemeris format returned by the COMSPOC Spacebook /api/entity/synthetic-covariance/{guid} endpoint, converting numerically propagated state vectors into ASTRA NumericalState objects for direct use in propagation validation, benchmarking, and conjunction analysis.

Background

The Spacebook Synthetic Covariance endpoint returns a STK v12.0 DotE ephemeris file — not JSON. This was verified empirically on 2026-04-09. The file contains:

• Scenario epoch (in STK calendar string format)

• Coordinate system: TEMEOfDate (the same frame ASTRA’s RK87 uses internally)

• Distance unit: Kilometers

• An EphemerisTimePosVel data block with per-epoch 7-column rows: t_offset_sec  x_km  y_km  z_km  vx_km_s  vy_km_s  vz_km_s

Since the coordinate frame (TEME) and units (km, km/s) match ASTRA’s internal conventions exactly, no frame rotation or unit conversion is needed.

Note on Reference Ephemerides

The Spacebook /api/entity/reference-ephemerides/{guid} and /api/entity/reference-ephemerides/ocm/{guid} endpoints returned HTTP 500 during our 2026-04-09 live testing. The Synthetic Covariance endpoint is functionally equivalent (same COMSPOC numerical propagation, same state vectors) and was used as the file source instead.

Usage Example

from astra.spacebook import fetch_synthetic_covariance_stk
from astra.ocm import parse_stk_ephemeris

stk_text = fetch_synthetic_covariance_stk(norad_id=25544)   # ISS
states = parse_stk_ephemeris(stk_text)

print(f"{len(states)} state vectors")
print(f"First epoch JD: {states[0].t_jd:.4f}")
print(f"Position (km):  {states[0].position_km}")
print(f"Velocity (km/s):{states[0].velocity_km_s}")

astra.ocm.parse_stk_ephemeris(text)

Parse an AGI/STK DotE ephemeris file into a list of NumericalState objects.

The STK DotE format is returned by the Spacebook synthetic covariance endpoint. Each row in the EphemerisTimePosVel data block provides: t_sec  x_km  y_km  z_km  vx_km_s  vy_km_s  vz_km_s

where t_sec is seconds elapsed since the ScenarioEpoch.

The coordinate system is always TEMEOfDate (verified from live data), which is the same frame used by ASTRA’s RK87 numerical propagator — no frame rotation is required.

Parameters:

text – Raw STK ephemeris file content as a string.

Returns:

List of NumericalState objects sorted by ascending Julian Date, with position in km and velocity in km/s in the TEME frame.

Raises:

AstraError – If the file is malformed (missing epoch or data block).

astra.ocm.parse_ocm(text)

Unified entry point for parsing CCSDS OCM (XML or KVN).

Automatically detects the format based on the first non-empty line.

astra.ocm.parse_ocm_xml(xml_text)

Parse a CCSDS OCM XML message into ASTRA NumericalState objects.

Supports the OCM standard (CCSDS 502.0-B-2), including state vectors and metadata for coordinate frames and units.

Parameters:

xml_text – Raw XML content of the OCM.

Returns:

List of NumericalState objects.

astra.ocm.export_ocm_xml(states, object_name='ASTRA_SAT')

Export ASTRA orbit states to a CCSDS OCM XML string.

Parameters:

• states – List of state vectors to export.

• object_name – Identifier for the satellite.

Returns:

XML string in CCSDS OCM format.

astra.ocm.parse_ocm_kvn(kvn_text)

Parse a CCSDS OCM KVN (Key-Value Notation) message.

Format defined in CCSDS 502.0-B-2. Processes one or more segments containing metadata and state vectors.