CCSDS "Navigation Data Messages" Read and Write
===============================================================

|CircleCI Status| |Codecov Status| |Documentation Status|

Description
--------------
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 files, through an object tree
API, auto-generated by these schema files.

The source code is `on Github <https://github.com/egemenimre/ccsds-ndm>`_ and the documentation is
`on Readthedocs <https://ccsds-ndm.readthedocs.io/>`_.

Usage and Examples
-------------------

There are two use cases:

-   The `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.
-   The user fills an object tree from their own attitude, orbit or trajectory object. The `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
(file type is inferred automatically):

>>> cdm = NdmIo().from_path(xml_read_path)

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. 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)

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` with:

>>> NdmIo().to_file(cdm, 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.).

More Information Regarding the 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/508x0b1e2c1.pdf>`_
and `Orbit Data Message <https://public.ccsds.org/Pubs/502x0b2c1.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>`_.

Design and Limitations
------------------------
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.

Currently the published standards are at version 1.0, but version 2.0 will be out soon. They will be integrated into
the code once they are made official.


License
-------

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
