ccsds_ndm.kvn_parser

KVN parser: type identification, document dispatch, and block location.

Phase 1 implements:

1. identify_ndm_type — scan tokenised lines for CCSDS_*_VERS

2. dispatch_document — split lines into header + Segment list

   (flat / segmented / CDM structural variants)

3. locate_blocks — given a list of KvLine objects and a target

   dataclass, return the keyword-boundary spans for every instance of that class (DEFAULT locator only — no packed/covariance yet)

Functions

dispatch_document(lines)	Split a tokenised KVN line list into a KvnDocument.
identify_ndm_type(lines)	Scan tokenised KVN lines and return the matching _NdmDataType.
locate_blocks(lines, cls)	Locate every instance of cls within lines using the default keyword-set strategy (LOC_DEFAULT).
locate_covariance(lines)	Locate every covariance matrix instance in lines.
locate_packed_attitude(lines)	Locate every PackedDataLine in lines as one BlockSpan each.
locate_packed_lines(lines, cls)	Locate every instance of cls in lines using the anchor-keyword strategy, including non-KvLine rows within each span.
locate_packed_state(lines)	Locate every PackedDataLine in lines as one BlockSpan each.
locate_tdm_obs(lines)	Locate every TdmObsLine in lines as one BlockSpan each.

Classes

BlockSpan(start, end, lines)	A located sub-block within a list of KvnLines.
CdmBucket(*values)	Bucket indices for CDM document structure.
KvnDocument(ndm_type[, header, segments])	Top-level representation of a dispatched KVN file.
ParserState(*values)	State machine states for document-level dispatch.
Segment([meta, data, covariance])	One logical NDM segment as extracted by the document dispatcher.

class BlockSpan(start, end, lines)

A located sub-block within a list of KvnLines.

Parameters:

• start (int)

• end (int)

• lines (list[KvnLine])

start

Index of the first line (inclusive) in the source list.

Type:

int

end

Index one past the last line (exclusive) in the source list.

Type:

int

lines

The actual lines within [start, end).

Type:

list[KvnLine]

class CdmBucket(*values)

Bucket indices for CDM document structure.

class KvnDocument(ndm_type, header=<factory>, segments=<factory>)

Top-level representation of a dispatched KVN file.

Parameters:

• ndm_type (_NdmDataType)

• header (list[KvnLine])

• segments (list[Segment])

ndm_type

Enum member identifying the message type and xsdata class.

Type:

_NdmDataType

header

Lines that belong to the NDM header (CCSDS_*_VERS, CREATION_DATE, ORIGINATOR, and top-level COMMENT lines).

Type:

list[KvnLine]

segments

Ordered list of logical segments. One entry for flat types; one per META_START/STOP block (plus optional covariance segments) for segmented types.

Type:

list[Segment]

class ParserState(*values)

State machine states for document-level dispatch.

class Segment(meta=<factory>, data=<factory>, covariance=<factory>)

One logical NDM segment as extracted by the document dispatcher.

For segmented types (OEM, AEM, TDM) each META_START/STOP block produces one Segment; a COVARIANCE_START/STOP block also produces a Segment with only covariance populated.

For flat types (OPM, OMM, APM, RDM, CDM) there is exactly one Segment with all non-header lines in data.

Parameters:

• meta (list[KvnLine])

• data (list[KvnLine])

• covariance (list[KvnLine])

dispatch_document(lines)

Split a tokenised KVN line list into a KvnDocument.

Identifies the NDM type from the CCSDS_*_VERS header line and then routes to one of three structural variants:

• Segmented (OEM, AEM, TDM) — state machine over META_START/STOP, DATA_START/STOP, COVARIANCE_START/STOP markers.

• Flat (OPM, OMM, APM, RDM) — no markers; all lines after the first CCSDS_*_VERS line form one segment (meta lines are separated from data lines by the locator later).

• CDM — split on OBJECT_1 / OBJECT_2 keyword occurrences; RELATIVE_METADATA_DATA section handled as separate segment.

Parameters:

lines (list[KvnLine]) – Output of tokenize().

Returns:

KvnDocument

Return type:

KvnDocument

identify_ndm_type(lines)

Scan tokenised KVN lines and return the matching _NdmDataType.

Searches for the first KvLine whose key starts with "CCSDS_" and delegates to _NdmDataType.find_ndm_type_by_class_id().

Parameters:

lines (list[KvnLine]) – Output of tokenize().

Returns:

_NdmDataType

Raises:

ValueError – If no CCSDS_*_VERS line is found.

Return type:

_NdmDataType

locate_blocks(lines, cls)

Locate every instance of cls within lines using the default keyword-set strategy (LOC_DEFAULT).

The keyword set for cls is derived from its dataclass field metadata ("name" entries that are ALL_UPPER strings). A new instance of cls is considered to start whenever the anchor keyword (first declared uppercase field) is encountered, and to end just before the next occurrence of that same anchor keyword (or at end-of-list).

This covers every flat KEY = VALUE container: NdmHeader, OpmMetadata, StateVectorType, ManeuverParametersType, SpacecraftParametersType, KeplerianElementsType, etc.

Packed-data, covariance, and TDM-observation types are NOT handled here; they will be covered by their own locators in later phases.

Parameters:

• lines (list[KvnLine]) – Source lines for one segment bucket (e.g. Segment.data for flat types, or Segment.meta for metadata-only classes).

• cls (type) – The dataclass whose instances are to be located.

Returns:

list[BlockSpan] – Ordered list of located spans, one per detected instance.

Return type:

list[BlockSpan]

locate_covariance(lines)

Locate every covariance matrix instance in lines.

A covariance instance starts at an EPOCH keyword line and spans until the next EPOCH line or end-of-list. Each instance typically contains the EPOCH line, an optional COV_REF_FRAME line, and 6 CovarianceRowLine objects (21 lower-triangular values total). Used by OemCovarianceMatrixType.

Parameters:

lines (list[KvnLine]) – Typically Segment.covariance from an OEM segment.

Returns:

list[BlockSpan]

Return type:

list[BlockSpan]

locate_packed_attitude(lines)

Locate every PackedDataLine in lines as one BlockSpan each.

Identical to locate_packed_state() in structure — each packed line is one attitude state record. Column interpretation (quaternion, Euler, spin, …) is determined later by the parser using segment metadata. Used by AttitudeStateType in AEM data sections.

Parameters:

lines (list[KvnLine]) – Typically Segment.data from an AEM segment.

Returns:

list[BlockSpan]

Return type:

list[BlockSpan]

locate_packed_lines(lines, cls)

Locate every instance of cls in lines using the anchor-keyword strategy, including non-KvLine rows within each span.

Like locate_blocks() but does not clip spans at the last matching keyword — packed text lines (trajectory / attitude / covariance rows stored as plain strings) that follow the KEY=VALUE header are kept inside the span. Used by OcmTrajStateType, OcmCovarianceMatrixType, AcmAttitudeStateType, and AcmCovarianceMatrixType.

Parameters:

• lines (list[KvnLine]) – Source lines for one segment bucket.

• cls (type) – The dataclass whose instances are to be located.

Returns:

list[BlockSpan]

Return type:

list[BlockSpan]

locate_packed_state(lines)

Locate every PackedDataLine in lines as one BlockSpan each.

Each packed line represents a single epoch-led state vector record (EPOCH X Y Z X_DOT Y_DOT Z_DOT [X_DDOT …]). Used by StateVectorAccType in OEM data sections.

Parameters:

lines (list[KvnLine]) – Typically Segment.data from an OEM segment.

Returns:

list[BlockSpan]

Return type:

list[BlockSpan]

locate_tdm_obs(lines)

Locate every TdmObsLine in lines as one BlockSpan each.

Each TDM observation is a single KEY = EPOCH VALUE line. Used by TrackingDataObservationType in TDM data sections.

Parameters:

lines (list[KvnLine]) – Typically Segment.data from a TDM segment.

Returns:

list[BlockSpan]

Return type:

list[BlockSpan]