|CircleCI Status| |Codecov Status| |Documentation Status| |DOI|
The Consultative Committee for Space Data Systems (CCSDS) develops communications and data systems standards
for spaceflight. CCSDS Navigation Data Messages (NDM) <https://public.ccsds.org/Publications/MOIMS.aspx>_
is the set of file standards to define common data types such as trajectory, orbit, attitude and conjunction events.
These data types are routinely generated and exchanged within and between spacecraft operators, space agencies,
researchers, amateurs and commercial companies. As such, accurate definition and common interpretation of the data
is crucial (and sometimes mission-critical).
The standard description for each data type is encapsulated in an XML Schema file. This project ccsds-ndm aims to
be the reference open-source Python implementation to read and write the NDM XML and KVN files, through an object tree
API, auto-generated by these schema files. It supports the up-to-date NDM XML 2.0.0 standard.
The source code is on Github <https://github.com/egemenimre/ccsds-ndm> and the documentation is
on Readthedocs <https://ccsds-ndm.readthedocs.io/>.
Current functionality:
.. csv-table:: :header: "", "Read", "Write" :widths: 20, 50, 50
"XML", "All NDM Types", "All NDM Types" "KVN", "All except NDM Combined Instantiation", "All except NDM Combined Instantiation" "JSON", "Not specified in CCSDS Standards", "Not specified in CCSDS Standards"
There are two use cases:
ccsds-ndm library reads the NDM file, fills an object tree and offers it to the users. The users will then
have to fill their own attitude, orbit or trajectory objects used in their libraries.ccsds-ndm library
writes the NDM file using this object tree.For the first use case, reading an OEM file from xml_read_path is as simple as:
cdm = NdmIo().from_path(xml_read_path)
Note that file format (XML or KVN) and data type (e.g. CDM or NDM) are inferred automatically.
The output cdm is the object tree for a Conjunction Data Message (CDM). The contents can then be reached
going deeper in the object tree as specified in the corresponding NDM Standard. This example shows how to reach the
orbit normal position component of the relative state vector:
print(cdm.body.relative_metadata_data.relative_state_vector.relative_position_n)
The data can sometimes be of type NDM Combined Instantiation. This means that there are multiple NDM data bodies
(e.g. 2 AEMs, 3 OEMs and one OMM) within a single file. The file reader supports these types as well and they are
kept within the Ndm object as individual lists for each of the file types. The following example retrieves the
second Omm object in the NDM file and then continues to dive deeper into the object tree to retrieve the
eccentricity value.
print(ndm.omm[1].body.segment.data.mean_elements.eccentricity)
If the file is of the type NDM Combined Instantiation but there is only a single data (e.g. OMM) in it, the ndm tags are stripped and only the single data is presented to the user.
Filling the objects with data properly requires some care. As the standard is understandably strict, the object tree derived from the XSD files are also rather exacting in how they accept data. The recommended way to fill the objects is with value and unit information:
This is the proper way to write data into the object
cdm.body.relative_metadata_data.relative_state_vector.relative_position_t = LengthType(Decimal(800), LengthUnits.M)
Finally, once filled with the relevant data, the cdm object can be written to xml_write_path in XML data format as:
NdmIo().to_file(cdm, NDMFileFormats.XML, xml_write_path)
The ndm object trees are not very user friendly and most probably will have to be filled by the users'
own equivalent objects (trajectory, orbit, attitude etc.).
ccsds-ndmThe ccsds-ndm package is on PyPI_ and you can install it simply by running::
pip install ccsds_ndmYou can also install it via conda-forge_::
conda install -c conda-forge ccsds_ndmDo not install ccsds-ndm using sudo.
.. _PyPI: https://pypi.org/project/ccsds_ndm/
.. _conda-forge: https://anaconda.org/conda-forge/ccsds_ndm
The top-level description of the standard is given in the
Navigation Data — Definitions and Conventions Green Book <https://public.ccsds.org/Pubs/500x0g4.pdf> and
Navigation Data Messages Overview Green Book <https://public.ccsds.org/Pubs/500x2g2.pdf>. Individual data types are
defined in their individual definitions (e.g. Conjunction Data Message <https://public.ccsds.org/Pubs/508x0b1e2c2.pdf>
and Orbit Data Message <https://public.ccsds.org/Pubs/502x0b2c1e2.pdf>). The centre for all the standards are
CCSDS Mission Operations and Information Management Services Area <https://public.ccsds.org/Publications/MOIMS.aspx>_.
The Schema files are found in the SANA Registry <https://sanaregistry.org/r/ndmxml>_.
The object tree is created by xsdata <https://xsdata.readthedocs.io/en/latest/>_ library, which also handles parsing
and writing of the XML data. As such, there is no documentation generated for this object tree.
File read is usually fast (on the order of seconds) for small files. That said, KVN parsing for large files can take some time. A 12 MB OEM file lasts about a minute to parse on a good consumer grade computer. Due to the fragility of the KVN format and the restrictions the standards put on the order of keys, no parallelization has been attempted.
xsData is used to read and write XML files (and also to generate the object tree)lxml to support XML object creationPlease use the DOI for citations. This is the latest version:
|DOI|
This project is Copyright (c) Egemen Imre and licensed under the terms of the GNU GPL v3+ license.
.. |Documentation Status| image:: https://readthedocs.org/projects/ccsds-ndm/badge/?version=latest :target: https://ccsds-ndm.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
.. |CircleCI Status| image:: https://img.shields.io/circleci/build/github/egemenimre/ccsds-ndm.svg?style=svg :target: https://circleci.com/gh/egemenimre/ccsds-ndm :alt: CCSDS-NDM CircleCI Status
.. |Codecov Status| image:: https://codecov.io/gh/egemenimre/ccsds-ndm/branch/main/graph/badge.svg?token=Z53pKJ5agN :target: https://codecov.io/gh/egemenimre/ccsds-ndm :alt: CCSDS-NDM Codecov Status
.. |DOI| image:: https://zenodo.org/badge/312698629.svg :target: https://zenodo.org/badge/latestdoi/312698629 :alt: DOI