Parsing Messages

This package parses Orbit Data Messages provided as strings in the XML and KVN (Key-Value Notation) formats. The format is detected automatically from the content, or it can be selected explicitly with the file_type keyword (:auto, :xml, or :kvn) of parse_omm and parse_omms.

Parsing is strict and case-sensitive by default. Pass strict = false to parse_omm, parse_omms, or parse_odm to match XML tags and the required OMM id attribute value case-insensitively. Permissive mode also preserves an empty OMM header creation date as nothing, which accommodates known Celestrak OMM 2.0 output without inventing a timestamp. Additionally, a blank ORIGINATOR is allowed in OMM version 2.0 regardless of the parsing mode, defaulting to an empty string. Such incomplete messages cannot be written as OMM 3.0. Both modes otherwise reject unrecognized tags and malformed or incomplete OMM sections.

Throughout this page, we assume the variable omm_xml holds the XML string of a single OMM, and ndm_xml holds a Navigation Data Message (NDM) that bundles two OMMs (AMAZONIA 1 and SCD 1).

Parsing a Single OMM

Use parse_omm to obtain a single OrbitMeanElementsMessage. If the input is an NDM containing several OMMs, only the first one is returned:

julia> omm = parse_omm(omm_xml)OrbitMeanElementsMessage:
  Header
    Comment       : GENERATED VIA SPACE-TRACK.ORG API
    Creation Date : 2025-12-30T23:36:37
    Originator    : 18 SPCS
  Metadata
    Object Name         : AMAZONIA 1
    Object ID           : 2021-015A
    Center Name         : EARTH
    Ref. Frame          : TEME
    Time System         : UTC
    Mean Element Theory : SGP4
  Data
  └─ Mean Keplerian Elements
       Epoch              : 2025-12-30T18:12:04.533984
       Mean Motion        : 14.40772474 rev/day
       Eccentricity       : 0.0001124
       Inclination        : 98.3721°
       RA of Asc. Node    : 75.0877°
       Arg. of Pericenter : 97.3772°
       Mean Anomaly       : 262.7545°

If the input does not contain any OMM, the function returns nothing.

Parsing Multiple OMMs

When a document may contain several messages — as is typically the case with an NDM — use parse_omms to retrieve all OMMs as a vector:

julia> omms = parse_omms(ndm_xml)2-element Vector{OrbitMeanElementsMessage}:
 OMM: AMAZONIA 1 [2021-015A] (Epoch = 2025-12-30T18:12:04.533984)
 OMM: SCD 1 [1993-009B] (Epoch = 2025-12-30T20:30:29.736576)
julia> length(omms)2
julia> omms[2].metadata.object_name"SCD 1"

parse_omms always returns a Vector{OrbitMeanElementsMessage}, which is empty when a recognized document contains no supported OMM.

Parsing Generic Orbit Data Messages

The parse_odm function is the most general entry point. It inspects the root tag of the document and dispatches to the appropriate parser:

parse_odm always returns a Vector{OrbitDataMessage}. A stand-alone <omm> produces a single-element vector, while an <ndm> produces a vector containing every supported message.

julia> odm = parse_odm(omm_xml)1-element Vector{OrbitDataMessage}:
 OMM: AMAZONIA 1 [2021-015A] (Epoch = 2025-12-30T18:12:04.533984)
julia> odms = parse_odm(ndm_xml)2-element Vector{OrbitDataMessage}:
 OMM: AMAZONIA 1 [2021-015A] (Epoch = 2025-12-30T18:12:04.533984)
 OMM: SCD 1 [1993-009B] (Epoch = 2025-12-30T20:30:29.736576)

Note

Only OMM messages are currently extracted. Other message types found inside an NDM (such as OPM, OEM, or OCM) are skipped with a warning, since they are not yet supported.

Parsing KVN Messages

parse_omm and parse_omms also understand the KVN format, in which each field is written as a KEYWORD = value line:

julia> omm_kvn = """
       CCSDS_OMM_VERS      = 3.0
       COMMENT Generated by SatelliteToolboxOrbitDataMessages.jl
       CREATION_DATE       = 2025-12-30T23:36:37
       ORIGINATOR          = 18 SPCS
       
       OBJECT_NAME         = AMAZONIA 1
       OBJECT_ID           = 2021-015A
       CENTER_NAME         = EARTH
       REF_FRAME           = TEME
       TIME_SYSTEM         = UTC
       MEAN_ELEMENT_THEORY = SGP4
       
       EPOCH               = 2025-12-30T18:12:04.533984
       MEAN_MOTION         = 14.40772474     [rev/day]
       ECCENTRICITY        = 0.0001124
       INCLINATION         = 98.3721         [deg]
       RA_OF_ASC_NODE      = 75.0877         [deg]
       ARG_OF_PERICENTER   = 97.3772         [deg]
       MEAN_ANOMALY        = 262.7545        [deg]
       """;
julia> omm = parse_omm(omm_kvn)OrbitMeanElementsMessage:
  Header
    Comment       : Generated by SatelliteToolboxOrbitDataMessages.jl
    Creation Date : 2025-12-30T23:36:37
    Originator    : 18 SPCS
  Metadata
    Object Name         : AMAZONIA 1
    Object ID           : 2021-015A
    Center Name         : EARTH
    Ref. Frame          : TEME
    Time System         : UTC
    Mean Element Theory : SGP4
  Data
  └─ Mean Keplerian Elements
       Epoch              : 2025-12-30T18:12:04.533984
       Mean Motion        : 14.40772474 rev/day
       Eccentricity       : 0.0001124
       Inclination        : 98.3721°
       RA of Asc. Node    : 75.0877°
       Arg. of Pericenter : 97.3772°
       Mean Anomaly       : 262.7545°

The format is inferred automatically: input starting with an XML tag is parsed as XML, and anything else as KVN. Pass file_type = :xml or file_type = :kvn to skip the detection.

The KVN parser preserves the COMMENT lines, attributing each one to the section of the keyword that follows it, and reads user-defined parameters from keywords with the USER_DEFINED_ prefix. Since the CCSDS standard does not define a KVN container for multiple messages, parse_omms assumes each message starts at its CCSDS_OMM_VERS keyword:

julia> omms = parse_omms(omm_kvn ^ 2)2-element Vector{OrbitMeanElementsMessage}:
 OMM: AMAZONIA 1 [2021-015A] (Epoch = 2025-12-30T18:12:04.533984)
 OMM: AMAZONIA 1 [2021-015A] (Epoch = 2025-12-30T18:12:04.533984)
julia> length(omms)2