mcap-ros2-support-fast

High-performance pure Python ROS2 message serialization and deserialization for MCAP files.

No dependencies on ROS2 or a ROS2 environment.

Installation

uv add mcap-ros2-support-fast

Usage

Decoding Messages

from small_mcap import read_message_decoded
from mcap_ros2_support_fast.decoder import DecoderFactory

decoder_factory = DecoderFactory()

with open("recording.mcap", "rb") as f:
    for msg in read_message_decoded(f, decoder_factories=[decoder_factory]):
        print(f"{msg.channel.topic}: {msg.decoded_message}")

For a schema constant such as uint8 STATE_ACTIVE=1, decoded messages expose the same read-only class and instance access used by ROS2 Python messages:

message = msg.decoded_message
assert type(message).STATE_ACTIVE == 1
assert message.STATE_ACTIVE == 1

Constants are metadata and are not serialized as message fields.

Encoding Messages

from small_mcap import McapWriter
from mcap_ros2_support_fast import ROS2EncoderFactory

encoder_factory = ROS2EncoderFactory()

with open("output.mcap", "wb") as f:
    writer = McapWriter(f, encoder_factory=encoder_factory)
    writer.start(profile="ros2")

    schema_id = 1
    writer.add_schema(
        schema_id,
        "geometry_msgs/msg/Point",
        "ros2msg",
        b"float64 x\nfloat64 y\nfloat64 z",
    )
    channel_id = 1
    writer.add_channel(channel_id, "/point", "cdr", schema_id)

    point = {"x": 1.0, "y": 2.0, "z": 3.0}
    writer.add_message_encode(channel_id, log_time=0, data=point, publish_time=0)

    writer.finish()

Bounded ROS 2 sequences enforce their declared maximum while encoding. Passing more elements than the schema permits raises ValueError instead of silently dropping data. Decoding remains wire-compatible and reads the length stored in the message.

Benchmarks

Median runtime from the non-slow pytest-benchmark suite on the included nuScenes dataset (data/data/nuScenes-v1.0-mini-scene-0061-ros2.mcap, 30,900 messages).

Read Performance

Note: pybag is skipped at 1000 messages because it cannot decode diagnostic_msgs/DiagnosticArray.

Read Summary (median time):

• 33-67x faster than reference mcap-ros2
• 1.37-1.84x faster than rosbags
• 3.04-4.68x faster than pybag (10-100 msgs; pybag skipped at 1000 due to decoder limitations)

Write Performance (Read + Write)

Read+Write Summary (median time):

• 23.2-53.5x faster than reference mcap-ros2
• 1.06-1.16x faster than rosbags
• 2.13-3.24x faster than pybag (10-100 msgs; pybag skipped at 1000 due to decoder limitations)

Write-Only Performance

Write-Only Summary (median time):

• 6.0-50.9x faster than reference mcap-ros2
• 0.96-1.26x similar to rosbags (rosbags remains slightly faster for write-only)
• 1.57-2.71x faster than pybag (10-100 msgs; pybag skipped at 1000 due to decoder limitations)