Metadata-Version: 2.3
Name: mcap-codec-support
Version: 0.18.0
Summary: Reusable MCAP encoder and decoder factories for robotics codecs
Keywords: mcap,robotics,factories,video,pointcloud
Author: Marko Bausch
License: GPL-3.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Dist: small-mcap
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: mcap-codec-support[ros2,video,pointcloud,draco] ; extra == 'all'
Requires-Dist: dracopy>=1.7.0 ; extra == 'draco'
Requires-Dist: mcap-ros2-support-fast ; extra == 'draco'
Requires-Dist: numpy>=1.24.0 ; extra == 'draco'
Requires-Dist: pointcloud2 ; extra == 'draco'
Requires-Dist: mcap-ros2-support-fast ; extra == 'pointcloud'
Requires-Dist: pureini>=0.10.0 ; extra == 'pointcloud'
Requires-Dist: mcap-ros2-support-fast ; extra == 'ros2'
Requires-Dist: av>=12.0.0 ; extra == 'video'
Requires-Dist: mcap-ros2-support-fast ; extra == 'video'
Requires-Dist: nvidia-nvjpeg==13.0.0.40 ; platform_machine == 'aarch64' and sys_platform == 'linux' and extra == 'video'
Requires-Dist: pillow>=10.0 ; extra == 'video'
Requires-Dist: portable-ffmpeg>=0.3.0 ; extra == 'video'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/mrkbac/robotic-tools
Project-URL: Issues, https://github.com/mrkbac/robotic-tools/issues
Project-URL: Repository, https://github.com/mrkbac/robotic-tools
Provides-Extra: all
Provides-Extra: draco
Provides-Extra: pointcloud
Provides-Extra: ros2
Provides-Extra: video
Description-Content-Type: text/markdown

# mcap-codec-support

High-performance decoder and encoder factories for robotics data in MCAP files.
It supports regular ROS2 CDR messages, H.264/H.265/VP9/AV1 video, and
Cloudini/Draco point clouds.

Install all decoding backends:

```console
uv add "mcap-codec-support[all]"
```

The base package contains shared protocols and schema helpers and imports
without loading any codec backend. Install only the capability needed:

| Extra | Enables |
| --- | --- |
| `ros2` | Fast generic ROS 2 CDR decoding |
| `video` | Video/image codecs and `VideoDecompressFactory` |
| `pointcloud` | Cloudini point-cloud codecs and decoder factories |
| `draco` | Draco point-cloud codecs |
| `all` | Combined decoder factory and every backend |

Video, point-cloud, and Draco extras remain separate because their compiled
dependencies account for most of the download and installed footprint.

JPEG compression inputs are decoded independently with strict PyAV validation.
Each image uses a fresh decoder and must define the quantization tables its scans
reference; tables from earlier images are never inherited. Standard MJPEG Huffman
defaults remain supported.
Malformed JPEGs raise `CorruptImageError`; missing dependencies and encoder failures
remain `VideoEncoderError`. The FFmpeg backend receives validated RGB pixels, so
a damaged JPEG cannot consume bytes from the next image. GStreamer validates each
JPEG before handing it to the hardware pipeline. Install the `video` extra for all
three compression backends, including `ffmpeg-cli` and `gstreamer`.

FFmpeg CLI operations prefer `ffmpeg` and `ffprobe` on `PATH`. When missing,
`portable-ffmpeg` (included in the `video` extra) downloads and caches the binaries
on first use. The GStreamer hardware path does not discover or download FFmpeg;
FFmpeg is used only if it needs a software fallback after a hardware failure.
After both encoders fail, the topic's encoder session reports one error and stops
encoding until the session is recreated.

Read every supported message type with `small-mcap`:

```python
from mcap_codec_support import create_decoder_factories
from small_mcap import read_message_decoded

with open("input.mcap", "rb") as stream:
    messages = read_message_decoded(
        stream,
        decoder_factories=create_decoder_factories(video_format="raw"),
    )
    for message in messages:
        print(message.channel.topic, message.decoded_message)
```

`video_format="raw"` produces ROS-like `Image` dataclass instances.
`video_format="compressed"` produces JPEG `CompressedImage` instances.
Compressed point clouds are returned as `PointCloud2` instances. Their fields
use the same attribute access as messages from the generic ROS2 decoder. All
other ROS2 messages use the fast CDR decoder.

Use `CompressedPointCloudDecoderFactory` or `Pointcloud2DecoderFactory` when a
structured NumPy array is preferred over a ROS-like message.

For more control, compose the individual `VideoDecompressFactory`,
`PointCloudDecompressFactory`, and ROS2 `DecoderFactory` instances yourself.
Keep specialized factories before the general ROS2 factory.
