Metadata-Version: 2.3
Name: mcap-ros2-support-fast
Version: 0.1.0
Summary: High-performance pure Python ROS2 message serialization and deserialization for MCAP files
Keywords: mcap,ros2,cdr,serialization,deserialization,robotics
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: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Dist: ros-parser
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
Description-Content-Type: text/markdown

# 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

```bash
uv add mcap-ros2-support-fast
```

## Usage

### Decoding Messages

```python
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}")
```

### Encoding Messages

```python
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 = writer.add_schema(
        name="geometry_msgs/msg/Point",
        encoding="ros2msg",
        data=b"float64 x\nfloat64 y\nfloat64 z"
    )
    channel_id = writer.add_channel("/point", "cdr", schema_id=schema_id)

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

    writer.finish()
```

## Benchmarks

Full benchmark suite comparing against reference `mcap-ros2` implementation, `rosbags` library, and `pybag`.

### Read Performance

```txt
-------------------------------------------------------------------------------------- benchmark 'msgs-10': 4 tests --------------------------------------------------------------------------------------
Name (time in ms)                                  Min                 Max                Mean             StdDev              Median                IQR                 OPS            Rounds  Iterations
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_decoder[mcap_ros2_fast-10]       5.9309 (1.0)        6.6827 (1.0)        6.2876 (1.0)       0.2078 (1.0)        6.2848 (1.0)       0.3145 (1.36)     159.0425 (1.0)          24           1
test_benchmark_decoder[rosbags-10]              7.8039 (1.32)       9.4448 (1.41)       8.2345 (1.31)      0.3564 (1.72)       8.1815 (1.30)      0.2311 (1.0)      121.4397 (0.76)         17           1
test_benchmark_decoder[pybag-10]               28.2604 (4.76)      34.4526 (5.16)      29.2232 (4.65)      1.5174 (7.30)      28.7849 (4.58)      0.7441 (3.22)      34.2194 (0.22)         17           1
test_benchmark_decoder[mcap_ros2-10]          344.9453 (58.16)    393.5084 (58.88)    371.4299 (59.07)    19.4372 (93.54)    368.3629 (58.61)    30.0467 (130.00)     2.6923 (0.02)          5           1
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------- benchmark 'msgs-100': 4 tests ------------------------------------------------------------------------------------------
Name (time in ms)                                     Min                   Max                  Mean             StdDev                Median                IQR                OPS            Rounds  Iterations
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_decoder[mcap_ros2_fast-100]        36.1641 (1.0)         41.7886 (1.0)         38.7671 (1.0)       2.4714 (1.0)         37.0456 (1.0)       4.7878 (1.0)      25.7951 (1.0)          17           1
test_benchmark_decoder[rosbags-100]               64.0870 (1.77)        73.8624 (1.77)        67.7211 (1.75)      3.3350 (1.35)        66.9847 (1.81)      5.7329 (1.20)     14.7665 (0.57)         13           1
test_benchmark_decoder[pybag-100]                116.3701 (3.22)       126.1597 (3.02)       120.2669 (3.10)      3.8116 (1.54)       118.5586 (3.20)      6.1874 (1.29)      8.3148 (0.32)          7           1
test_benchmark_decoder[mcap_ros2-100]          1,304.4500 (36.07)    1,341.5722 (32.10)    1,325.5776 (34.19)    16.4693 (6.66)     1,332.5642 (35.97)    28.6133 (5.98)      0.7544 (0.03)          5           1
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------- benchmark 'msgs-1000': 3 tests -----------------------------------------------------------------------------------------
Name (time in ms)                                      Min                   Max                  Mean             StdDev                Median                IQR               OPS            Rounds  Iterations
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_decoder[mcap_ros2_fast-1000]       126.9185 (1.0)        136.1736 (1.0)        132.6490 (1.0)       3.0011 (1.22)       133.3180 (1.0)       3.0429 (1.07)     7.5387 (1.0)           7           1
test_benchmark_decoder[rosbags-1000]              230.6469 (1.82)       236.9495 (1.74)       234.7352 (1.77)      2.4632 (1.0)        235.5722 (1.77)      2.8371 (1.0)      4.2601 (0.57)          5           1
test_benchmark_decoder[mcap_ros2-1000]          4,034.0901 (31.78)    4,092.9589 (30.06)    4,075.4871 (30.72)    24.8972 (10.11)    4,087.6284 (30.66)    31.2742 (11.02)    0.2454 (0.03)          5           1
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
```

**Read Summary:**

- **31-59x faster** than reference mcap-ros2
- **1.31-1.77x faster** than rosbags
- **3.10-4.65x faster** than pybag (10-100 msgs; pybag skipped at 1000 due to decoder limitations)

### Write Performance (Read + Write)

```txt
------------------------------------------------------------------------------------------ benchmark 'write-msgs-10': 4 tests -----------------------------------------------------------------------------------------
Name (time in ms)                                                Min                 Max                Mean             StdDev              Median                IQR                OPS            Rounds  Iterations
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_read_and_write[mcap_ros2_fast_writer-10]      17.6656 (1.0)       24.6546 (1.17)      19.1740 (1.0)       1.8360 (5.76)      18.8823 (1.0)       1.1571 (2.74)     52.1540 (1.0)          12           1
test_benchmark_read_and_write[rosbags_writer-10]             19.9034 (1.13)      21.1216 (1.0)       20.3388 (1.06)      0.3189 (1.0)       20.2124 (1.07)      0.4219 (1.0)      49.1670 (0.94)         13           1
test_benchmark_read_and_write[pybag_writer-10]               61.6168 (3.49)      84.1206 (3.98)      66.9191 (3.49)      6.0055 (18.83)     65.0424 (3.44)      6.6212 (15.69)    14.9434 (0.29)         13           1
test_benchmark_read_and_write[mcap_ros2_writer-10]          920.7613 (52.12)    992.4728 (46.99)    948.9506 (49.49)    35.9130 (112.61)   925.6756 (49.02)    64.1231 (151.99)    1.0538 (0.02)          5           1
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

---------------------------------------------------------------------------------------------- benchmark 'write-msgs-100': 4 tests ----------------------------------------------------------------------------------------------
Name (time in ms)                                                   Min                   Max                  Mean              StdDev                Median                 IQR               OPS            Rounds  Iterations
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_read_and_write[mcap_ros2_fast_writer-100]       108.6150 (1.0)      2,200.8597 (15.12)      380.2710 (2.84)     735.6531 (95.09)      121.3869 (1.0)        8.9596 (1.0)      2.6297 (0.35)          8           1
test_benchmark_read_and_write[rosbags_writer-100]              125.4855 (1.16)       145.5714 (1.0)        134.0954 (1.0)        7.7364 (1.0)        136.0569 (1.12)      12.2291 (1.36)     7.4574 (1.0)           7           1
test_benchmark_read_and_write[pybag_writer-100]                264.1394 (2.43)       290.3523 (1.99)       274.4185 (2.05)       9.9997 (1.29)       273.6181 (2.25)      12.1666 (1.36)     3.6441 (0.49)          5           1
test_benchmark_read_and_write[mcap_ros2_writer-100]          3,102.7205 (28.57)    3,390.4792 (23.29)    3,253.1039 (24.26)    126.2048 (16.31)    3,229.5814 (26.61)    225.6545 (25.19)    0.3074 (0.04)          5           1
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------- benchmark 'write-msgs-1000': 3 tests ----------------------------------------------------------------------------------------------
Name (time in ms)                                                    Min                    Max                  Mean              StdDev                Median                 IQR               OPS            Rounds  Iterations
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_read_and_write[mcap_ros2_fast_writer-1000]       389.8025 (1.0)         418.4601 (1.0)        403.8736 (1.0)       12.1332 (1.0)        401.6407 (1.0)       21.0602 (1.0)      2.4760 (1.0)           5           1
test_benchmark_read_and_write[rosbags_writer-1000]              479.7473 (1.23)        513.6734 (1.23)       493.5608 (1.22)      15.2506 (1.26)       488.2160 (1.22)      27.0344 (1.28)     2.0261 (0.82)          5           1
test_benchmark_read_and_write[mcap_ros2_writer-1000]          8,899.2066 (22.83)    10,416.2178 (24.89)    9,589.6736 (23.74)    542.5575 (44.72)    9,552.1125 (23.78)    491.9584 (23.36)    0.1043 (0.04)          5           1
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
```

**Read+Write Summary:**

- **23-49x faster** than reference mcap-ros2
- **1.06-1.22x faster** than rosbags
- **2.05-3.49x faster** than pybag (10-100 msgs; pybag skipped at 1000 due to decoder limitations)

### Write-Only Performance

```txt
-------------------------------------------------------------------------------- benchmark 'write-only-msgs-10': 4 tests ---------------------------------------------------------------------------------
Name (time in ms)                                     Min                 Max                Mean            StdDev              Median               IQR                OPS            Rounds  Iterations
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_write_only[rosbags-10]             10.9500 (1.0)       14.6925 (1.0)       12.0007 (1.0)      0.8779 (1.0)       11.6257 (1.0)      1.3553 (6.55)     83.3284 (1.0)          24           1
test_benchmark_write_only[mcap_ros2_fast-10]      11.8910 (1.09)      15.5508 (1.06)      12.5770 (1.05)     0.9914 (1.13)      12.1515 (1.05)     0.2069 (1.0)      79.5100 (0.95)         23           1
test_benchmark_write_only[pybag-10]               32.2464 (2.94)      40.7300 (2.77)      34.2348 (2.85)     1.8887 (2.15)      33.4549 (2.88)     2.4743 (11.96)    29.2101 (0.35)         27           1
test_benchmark_write_only[mcap_ros2-10]          562.1606 (51.34)    564.9182 (38.45)    563.6723 (46.97)    1.1536 (1.31)     563.7195 (48.49)    1.9709 (9.52)      1.7741 (0.02)          5           1
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

--------------------------------------------------------------------------------- benchmark 'write-only-msgs-100': 4 tests --------------------------------------------------------------------------------
Name (time in ms)                                      Min                 Max                Mean            StdDev              Median               IQR                OPS            Rounds  Iterations
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_write_only[rosbags-100]             53.7435 (1.0)       87.0201 (1.30)      58.4993 (1.0)      7.7466 (4.42)      56.7353 (1.0)      2.6326 (1.0)      17.0942 (1.0)          16           1
test_benchmark_write_only[mcap_ros2_fast-100]      61.0728 (1.14)      66.7065 (1.0)       64.2220 (1.10)     1.7516 (1.0)       64.0696 (1.13)     2.7867 (1.06)     15.5710 (0.91)         14           1
test_benchmark_write_only[pybag-100]              107.3560 (2.00)     117.4027 (1.76)     112.6513 (1.93)     2.9156 (1.66)     111.6172 (1.97)     3.1993 (1.22)      8.8769 (0.52)          9           1
test_benchmark_write_only[mcap_ros2-100]          785.2788 (14.61)    792.8765 (11.89)    789.4166 (13.49)    3.3582 (1.92)     790.9028 (13.94)    5.7939 (2.20)      1.2668 (0.07)          5           1
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

------------------------------------------------------------------------------------- benchmark 'write-only-msgs-1000': 3 tests -------------------------------------------------------------------------------------
Name (time in ms)                                         Min                   Max                  Mean             StdDev                Median                IQR               OPS            Rounds  Iterations
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_write_only[rosbags-1000]              181.6391 (1.0)        204.9827 (1.0)        188.3532 (1.0)       8.4449 (2.24)       186.1796 (1.0)       4.3215 (1.0)      5.3092 (1.0)           6           1
test_benchmark_write_only[mcap_ros2_fast-1000]       207.8413 (1.14)       217.3372 (1.06)       213.3029 (1.13)      3.7784 (1.0)        214.1898 (1.15)      5.7395 (1.33)     4.6882 (0.88)          5           1
test_benchmark_write_only[mcap_ros2-1000]          1,387.1190 (7.64)     1,442.0496 (7.03)     1,402.5220 (7.45)     22.3435 (5.91)     1,394.4735 (7.49)     15.6472 (3.62)     0.7130 (0.13)          5           1
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
```

**Write-Only Summary:**

- **7-47x faster** than reference mcap-ros2
- **0.91-1.05x** similar to rosbags (rosbags slightly faster for write-only)
- **1.76-2.85x faster** than pybag (10-100 msgs; pybag skipped at 1000 due to decoder limitations)
