ltcodecs 4.2.0__tar.gz → 4.3.0__tar.gz

ltcodecs-4.3.0/.gitlab-ci.yml

@@ -0,0 +1,65 @@
+include:
+  - project: acomms/ci_templates
+    ref: v2.3.2
+    file:
+      - /templates/python-docs.yml
+      - /templates/python-tests.yml
+
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"'
+      when: never
+    - if: '$CI_COMMIT_BRANCH || $CI_COMMIT_TAG'
+      when: always
+
+stages:
+  - prepare
+  - test
+  - deploy
+
+variables:
+  PYTHON_DOCS_PDF_ARTIFACT: "ltcodecs.pdf"
+  PYTHON_DOCS_PDF_SOURCE: "docs/_build/latex/ltcodecs.pdf"
+
+  ROS_ACOMMS_REF: "devel"
+
+  PYTHON_PYTEST_ARGS: "-vv -rA --capture=tee-sys"
+  PYTHON_PYTEST_COVERAGE_ARGS: "--cov=ltcodecs"
+  PYTHON_PYTEST_TARGET: "tests/"
+
+native_tests:
+  extends: .armw_native_pytest_template
+  variables:
+    NATIVE_TEST_SETUP_COMMANDS: |
+      pip install .
+
+trigger-ros_acomms-pipeline:
+  stage: test
+  trigger:
+    project: acomms/ros_acomms
+    branch: $ROS_ACOMMS_REF
+    strategy: depend
+  variables:
+    LTCODEC_REF: $CI_COMMIT_SHA
+    PYACOMMS_REF: $PYACOMMS_REF
+    ARMW_REF: $ARMW_REF
+    ROS_SKIP_WORKSPACE_BUILD_IN_PIPELINES: "false"
+    ROS_SKIP_WORKSPACE_BUILD_ON_DEV_AUTODOCS: "false"
+  rules:
+    - if: '$CI_PIPELINE_SOURCE != "pipeline"'
+
+pypi:
+  image: python:3.12
+  stage: deploy
+  script:
+    - pip install -r requirements.txt
+    - pip install build twine
+    - python -m build
+    - twine upload --username __token__ --password $PYPI_TOKEN dist/*
+  artifacts:
+    paths:
+      - dist/
+  only:
+    - tags

{ltcodecs-4.2.0 → ltcodecs-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltcodecs
-Version: 4.2.0
+Version: 4.3.0
 Summary: LT Codecs: Lightweight codecs for use over low-throughput links
 Author: Woods Hole Oceanographic Institution, Acoustic Communications Group
 License: LGPL-3.0-or-later

ltcodecs-4.3.0/docs/codec_configs.rst

@@ -0,0 +1,284 @@
+Codec Configurations
+====================
+
+Most ``ltcodecs`` applications are configured with a field dictionary.  In
+Python this is a nested ``dict``.  In files it is usually written as YAML.
+Each top-level key is a field name, and each value is a mapping of parameters
+for the codec that encodes that field.
+
+Basic Shape
+-----------
+
+Every field needs a ``codec`` value.  The value is one of the aliases listed in
+:doc:`reference/codec_aliases`.
+
+.. code-block:: yaml
+
+   field_name:
+     codec: string
+     max_length: 16
+
+The remaining keys are passed to that field codec's constructor.  For example,
+``max_length`` belongs to the string codec in the example above.
+
+Scalar Fields
+-------------
+
+Use scalar codecs for values that encode as a single value in the message.
+
+.. code-block:: yaml
+
+   name:
+     codec: string
+     max_length: 10
+   count:
+     codec: integer
+     min_value: 0
+     max_value: 100
+   enabled:
+     codec: bool
+   temperature:
+     codec: float
+     min_value: -5.0
+     max_value: 35.0
+     precision: 1
+   depth:
+     codec: linspace_float
+     min_value: 0.0
+     max_value: 100.0
+     resolution: 0.5
+
+Common scalar aliases include ``string``, ``integer``, ``bool``, ``float``,
+``uint8``, ``uint16``, ``uint32``, ``int8``, ``int16``, ``float32``, and
+``float64``.  Use ``float`` when a fixed number of decimal places is the
+natural constraint, and ``linspace_float`` when a physical step size or number
+of values is the natural constraint.
+
+Nested Dictionaries
+-------------------
+
+Use ``dict`` when a field contains another mapping of named fields.
+
+.. code-block:: yaml
+
+   vehicle:
+     codec: dict
+     fields:
+       id:
+         codec: uint8
+       name:
+         codec: string
+         max_length: 12
+
+The input value for ``vehicle`` is a nested dictionary:
+
+.. code-block:: python
+
+   {
+       "vehicle": {
+           "id": 7,
+           "name": "remus",
+       },
+   }
+
+Nested ROS Messages
+-------------------
+
+Use ``msg`` when a field contains a nested ROS message.
+
+.. code-block:: yaml
+
+   position:
+     codec: msg
+     ros_type: geometry_msgs/Point
+     fields:
+       x:
+         codec: float32
+       y:
+         codec: float32
+       z:
+         codec: float32
+
+``ros_type`` may use ROS 1 style names such as ``geometry_msgs/Point`` or ROS
+2 introspection names such as ``geometry_msgs/msg/Point``.  ``ltcodecs``
+normalizes ROS 2 names internally.
+
+Variable-Length Arrays
+----------------------
+
+Use ``variable_len_array`` for a list whose encoded length is included in the
+bit stream.
+
+.. code-block:: yaml
+
+   samples:
+     codec: variable_len_array
+     max_length: 10
+     element_type: uint8
+
+``max_length`` is required.  Values longer than ``max_length`` are currently
+truncated during encoding.
+
+For element codecs that need parameters, put those parameters under
+``element_params``:
+
+.. code-block:: yaml
+
+   labels:
+     codec: variable_len_array
+     max_length: 4
+     element_type: string
+     element_params:
+       max_length: 12
+
+Set ``nullable: true`` when an empty list should encode as a single bit.  When
+``nullable`` is false, the array length is always encoded.
+
+.. code-block:: yaml
+
+   optional_samples:
+     codec: variable_len_array
+     max_length: 10
+     nullable: true
+     element_type: uint8
+
+Fixed-Length Arrays
+-------------------
+
+Use ``fixed_len_array`` when the number of elements is known from the config.
+
+.. code-block:: yaml
+
+   rgb:
+     codec: fixed_len_array
+     length: 3
+     element_type: uint8
+
+The encoded stream does not include a length field.  The decoder always reads
+``length`` elements.
+
+Arrays of Messages
+------------------
+
+Array elements can be nested dictionaries or ROS messages.  Use
+``element_type: msg`` for ROS message elements and pass the message parameters
+with ``element_params``.
+
+.. code-block:: yaml
+
+   points:
+     codec: variable_len_array
+     max_length: 5
+     element_type: msg
+     element_params:
+       ros_type: geometry_msgs/Point
+       fields:
+         x:
+           codec: float32
+         y:
+           codec: float32
+         z:
+           codec: float32
+
+Optional Fields
+---------------
+
+Use ``optional`` when a boolean field controls whether additional fields are
+present.  The controlling field itself encodes as one bit.  If it is true, each
+field in ``target_fields`` is encoded immediately after it.  If false, the
+target fields use no bits.
+
+.. code-block:: yaml
+
+   has_extra:
+     codec: optional
+     target_fields:
+       extra:
+         codec: uint8
+
+The input dictionary or ROS message must contain both ``has_extra`` and
+``extra`` when ``has_extra`` is true.
+
+Padding
+-------
+
+Use ``pad`` or ``padding`` to reserve a fixed number of zero bits.
+
+.. code-block:: yaml
+
+   reserved:
+     codec: padding
+     num_bits: 8
+
+Padding decodes to ``None``.
+
+Metadata Fields
+---------------
+
+Some codec aliases represent metadata rather than payload bits.  These fields
+are copied to or from packet metadata and are not encoded like ordinary fields.
+
+This functionality is used by ``ros_acomms``, so the currently implemented metadata fields
+are all related to encoding or decoding acoustic packet data.
+
+Available metadata decoder aliases include ``src``, ``dest``,
+``dest_decoder``, ``toa``, and ``snr_in``.  The metadata encoder alias
+currently used by top-level codecs is ``dest``.
+
+.. code-block:: yaml
+
+   dest:
+     codec: dest
+   data:
+     codec: string
+     max_length: 20
+
+When encoding, the top-level codec returns the metadata dictionary as the
+second value from ``encode()``.
+
+Checksums
+---------
+
+Checksums are configured on the top-level codec object, not inside each field.
+Both :py:class:`ltcodecs.dict_codec.DictCodec` and
+:py:class:`ltcodecs.ros_message_codec.RosMessageCodec` support ``crc8`` and
+``crc32``.
+
+.. code-block:: python
+
+   codec = ltcodecs.DictCodec.from_codec_file(
+       "message_codec.yaml",
+       checksum="crc32",
+   )
+
+The checksum is appended after the encoded payload.  During decoding, a
+mismatch raises ``ValueError``.
+
+Complete Example
+----------------
+
+.. code-block:: yaml
+
+   name:
+     codec: string
+     max_length: 10
+   count:
+     codec: integer
+     min_value: 0
+     max_value: 100
+   enabled:
+     codec: bool
+   nested:
+     codec: dict
+     fields:
+       value:
+         codec: uint8
+   has_extra:
+     codec: optional
+     target_fields:
+       extra:
+         codec: uint8
+
+This config can be loaded with
+:py:meth:`ltcodecs.dict_codec.DictCodec.from_codec_file` and used to encode a
+dictionary with the same field names.

ltcodecs-4.3.0/docs/index.rst

@@ -0,0 +1,26 @@
+ltcodecs
+========
+
+``ltcodecs`` encodes Python dictionaries and ROS messages into compact
+bitstreams using declarative codec configurations.
+
+Start with :doc:`quickstart` if you are writing your first codec config.  Use
+:doc:`codec_configs` and :doc:`ros_messages` for the full user guide.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   quickstart
+   codec_configs
+   ros_messages
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   reference/codecs
+   reference/codec_aliases
+   reference/config_schema
+   reference/python_api
+   tests

ltcodecs-4.3.0/docs/quickstart.rst

@@ -0,0 +1,230 @@
+Quick Start
+===========
+
+``ltcodecs`` encodes structured Python dictionaries and ROS messages into
+compact bit streams.  A codec is configured with a field dictionary: each field
+name maps to a codec alias and the parameters for that field codec.
+
+Install
+-------
+
+Install the package from PyPI:
+
+.. code-block:: console
+
+   pip install ltcodecs
+
+For local development, install the checkout in editable mode:
+
+.. code-block:: console
+
+   pip install -e .
+
+Encode a Dictionary
+-------------------
+
+The quickest way to use ``ltcodecs`` is with
+:py:class:`ltcodecs.dict_codec.DictCodec`.  This path does not require ROS.
+
+.. code-block:: python
+
+   from bitstring import ConstBitStream
+   import ltcodecs
+
+   fields = {
+       "name": {
+           "codec": "string",
+           "max_length": 10,
+       },
+       "count": {
+           "codec": "integer",
+           "min_value": 0,
+           "max_value": 100,
+       },
+       "enabled": {
+           "codec": "bool",
+       },
+   }
+
+   message = {
+       "name": "test",
+       "count": 21,
+       "enabled": True,
+   }
+
+   codec = ltcodecs.DictCodec(fields)
+   bits, metadata = codec.encode(message)
+
+   decoded = codec.decode(ConstBitStream(bits))
+   assert decoded == message
+
+The ``bits`` value is a ``bitstring.Bits`` object.  The ``metadata`` return
+value is usually ``None`` unless the field configuration includes one of the
+metadata encoder aliases.
+
+Encode Metadata
+---------------
+
+``encode()`` for the Message/Dictionary codecs returns a tuple of ``(bits, metadata)``.
+The first value is the encoded bit stream.
+The second value is a small metadata dictionary for values
+that should travel outside the compressed payload, such as packet routing
+fields.  Most codecs return ``None`` for metadata, and you can ignore it.
+It is possible to define fields that
+use metadata encoders rather than (or in addition to) adding bits to the output stream.
+
+Use YAML Configuration
+----------------------
+
+Codec configurations are commonly stored as YAML.  The same dictionary codec
+above can be written as:
+
+.. code-block:: yaml
+
+   name:
+     codec: string
+     max_length: 10
+   count:
+     codec: integer
+     min_value: 0
+     max_value: 100
+   enabled:
+     codec: bool
+
+Load the YAML file with
+:py:meth:`ltcodecs.dict_codec.DictCodec.from_codec_file`:
+
+.. code-block:: python
+
+   from bitstring import ConstBitStream
+   import ltcodecs
+
+   codec = ltcodecs.DictCodec.from_codec_file("message_codec.yaml")
+
+   bits, _metadata = codec.encode({
+       "name": "test",
+       "count": 21,
+       "enabled": True,
+   })
+
+   decoded = codec.decode(ConstBitStream(bits))
+
+Nested Dictionaries and Optional Fields
+---------------------------------------
+
+A field can itself be a dictionary.  Use the ``dict`` codec and provide a
+nested ``fields`` mapping:
+
+.. code-block:: yaml
+
+   nested:
+     codec: dict
+     fields:
+       value:
+         codec: uint8
+
+Optional fields are controlled by a boolean field.  If the controlling value is
+true, the target fields are encoded.  If false, those fields use no bits.
+
+.. code-block:: yaml
+
+   has_extra:
+     codec: optional
+     target_fields:
+       extra:
+         codec: uint8
+
+The input dictionary for that configuration would include both the controlling
+field and the target field:
+
+.. code-block:: python
+
+   message = {
+       "has_extra": True,
+       "extra": 42,
+   }
+
+Encode a ROS Message
+--------------------
+
+Use :py:class:`ltcodecs.ros_message_codec.RosMessageCodec` for ROS messages.
+If no field dictionary is provided, ``ltcodecs`` asks ARMW for the message
+fields and chooses codecs from the ROS field types.
+
+.. code-block:: python
+
+   from bitstring import ConstBitStream
+   import armw
+   import ltcodecs
+
+   String = armw.import_message("std_msgs", "String")
+
+   msg = String()
+   msg.data = "hello"
+
+   codec = ltcodecs.RosMessageCodec("std_msgs/String")
+   bits, metadata = codec.encode(msg)
+
+   decoded = codec.decode(ConstBitStream(bits))
+   assert decoded.data == "hello"
+
+You can also provide a YAML field configuration for a ROS message:
+
+.. code-block:: yaml
+
+   data:
+     codec: string
+     max_length: 10
+
+.. code-block:: python
+
+   codec = ltcodecs.RosMessageCodec.from_codec_file(
+       "std_msgs/String",
+       "string_msg_codec.yaml",
+   )
+
+ROS 1 and ROS 2 Type Names
+--------------------------
+
+ROS message fields may use ROS 1 style type names such as ``pkg/Msg`` and
+``pkg/Msg[]`` or ROS 2 introspection names such as ``pkg/msg/Msg`` and
+``sequence<pkg/msg/Msg>``.  ``ltcodecs`` normalizes these forms when it infers
+fields from a ROS message or when an explicit field config contains a ROS type.
+
+For arrays, use the array codecs directly when writing explicit configs:
+
+.. code-block:: yaml
+
+   samples:
+     codec: variable_len_array
+     max_length: 10
+     element_type: uint8
+
+   points:
+     codec: fixed_len_array
+     length: 3
+     element_type: msg
+     element_params:
+       ros_type: geometry_msgs/Point
+
+Checksums
+---------
+
+Top-level dictionary and ROS message codecs can append a checksum.  Supported
+values are ``crc8`` and ``crc32``.
+
+.. code-block:: python
+
+   codec = ltcodecs.DictCodec(fields, checksum="crc8")
+   bits, _metadata = codec.encode(message)
+   decoded = codec.decode(ConstBitStream(bits))
+
+If the received checksum does not match the encoded content, ``decode`` raises
+``ValueError``.
+
+Next Steps
+----------
+
+See :doc:`reference/codecs` for the codec reference,
+:doc:`reference/codec_aliases` for the full alias table, and
+:doc:`reference/python_api` for the generated API reference.

ltcodecs-4.2.0/docs/index.rst → ltcodecs-4.3.0/docs/reference/codec_aliases.rst

@@ -1,13 +1,9 @@
-.. ltcodecs documentation master file, created by
-   sphinx-quickstart on Tue Jun  6 11:03:07 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Codec Aliases
+=============
 
-Welcome to ltcodecs's documentation!
-====================================
-
-There are aliases for each codec that can be used in codec yaml files.
-Note that there are multiple aliases for some codec classes.
+Codec configurations use short aliases instead of Python class names.  Some
+codec classes have more than one alias for readability or compatibility with
+existing configs.
 
 ========================  ====================================================
 Alias                     Codec Class
@@ -30,14 +26,17 @@ Alias                     Codec Class
 ``float32``               :py:class:`~ltcodecs.ieee_float_codec.IeeeFloat32Codec`
 ``float64``               :py:class:`~ltcodecs.ieee_float_codec.IeeeFloat64Codec`
 ``bool``                  :py:class:`~ltcodecs.bool_codec.BoolCodec`
+``boolean``               :py:class:`~ltcodecs.bool_codec.BoolCodec`
 ``string``                :py:class:`~ltcodecs.string_codecs.AsciiStringCodec`
 ``ascii``                 :py:class:`~ltcodecs.string_codecs.AsciiStringCodec`
 ``bytes``                 :py:class:`~ltcodecs.bytes_codec.BytesCodec`
+``dict``                  :py:class:`~ltcodecs.dict_field_codec.DictFieldCodec`
+``dictionary``            :py:class:`~ltcodecs.dict_field_codec.DictFieldCodec`
 ``msg``                   :py:class:`~ltcodecs.ros_msg_field_codec.RosMsgFieldCodec`
 ``ros_msg``               :py:class:`~ltcodecs.ros_msg_field_codec.RosMsgFieldCodec`
 ``variable_len_array``    :py:class:`~ltcodecs.variable_len_array_codec.VariableLenArrayCodec`
 ``fixed_len_array``       :py:class:`~ltcodecs.fixed_len_array_codec.FixedLenArrayCodec`
-``ccl_latlon``            :py:class:`~ltcodecs.ccl_latlon_codec.CclLatLonCodec`,
+``ccl_latlon``            :py:class:`~ltcodecs.ccl_latlon_codec.CclLatLonCodec`
 ``ccl_latlon_bcd``        :py:class:`~ltcodecs.ccl_latlon_bcd_codec.CclLatLonBcdCodec`
 ``pad``                   :py:class:`~ltcodecs.padding_codec.PaddingCodec`
 ``padding``               :py:class:`~ltcodecs.padding_codec.PaddingCodec`
@@ -48,13 +47,22 @@ Alias                     Codec Class
 ``optional``              :py:class:`~ltcodecs.optional_field_codec.OptionalFieldCodec`
 ========================  ====================================================
 
+Metadata Aliases
+----------------
 
-.. toctree::
-   :maxdepth: 4
-   :caption: Contents:
-
-   ltcodecs
-   tests
-
+Metadata decoder aliases read values from packet metadata during decoding.
+They do not consume bits from the payload.
 
+================  ========================
+Alias             Metadata attribute
+================  ========================
+``src``           ``packet.src``
+``dest``          ``packet.dest``
+``dest_decoder``  ``packet.dest``
+``toa``           ``cst.toa``
+``snr_in``        ``cst.snr_in``
+================  ========================
 
+The metadata encoder alias currently supported by top-level codecs is
+``dest``.  During encoding, it copies the configured field into the metadata
+dictionary returned with the encoded bits.