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 Codec Aliases.

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.

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.

vehicle:
  codec: dict
  fields:
    id:
      codec: uint8
    name:
      codec: string
      max_length: 12

The input value for vehicle is a nested dictionary:

{
    "vehicle": {
        "id": 7,
        "name": "remus",
    },
}

Nested ROS Messages#

Use msg when a field contains a nested ROS message.

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.

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:

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.

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.

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.

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.

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.

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.

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 ltcodecs.dict_codec.DictCodec and ltcodecs.ros_message_codec.RosMessageCodec support crc8 and crc32.

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#

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 ltcodecs.dict_codec.DictCodec.from_codec_file() and used to encode a dictionary with the same field names.

Codec Configurations

Contents