rtabmap_ros/rtabmap_python/README.md

rtabmap_python

Python helpers for reading and writing the binary formats RTAB-Map uses.

RTAB-Map is a C++ library, and the data it hands to ROS is not always plain ROS types. Several rtabmap_msgs fields — and every blob in an .db database — carry a matrix in RTAB-Map's own compressed encoding rather than as a sensor_msgs/Image or an array. This package is the Python side of that encoding, for scripts that read those fields without going through the C++ library.

There are no nodes here. It is an ament_python package that installs one importable module.

Module

rtabmap_python.cv_compression — a single-channel cv::Mat to and from bytes.

Function	Description
compress(data)	1-D or 2-D numpy array → bytearray.
uncompress(data)	those bytes → 2-D numpy array.

import numpy as np
from rtabmap_python.cv_compression import compress, uncompress

scan = np.zeros((360, 2), dtype=np.float32)
blob = compress(scan)          # what the message field carries
restored = uncompress(blob)    # (360, 2) float32

The encoding is a zlib stream followed by a 12-byte trailer holding rows, cols and the element type as three int32. It matches compressData() and uncompressData() in RTAB-Map's corelib/src/Compression.cpp byte for byte, so either side can read what the other wrote. The module docstring has the exact layout, and the generated Python API reference renders it alongside the two functions.

Things worth knowing

The result is read-only. uncompress views the decompressed buffer instead of copying it, so the array it returns has writeable=False and assigning into it raises. Call .copy() if you need to modify it.

Single-channel only. The C++ encoder packs the channel count into the type code; the tables here cover the single-channel depths CV_8U through CV_64F. A multi-channel matrix written by the C++ side raises KeyError rather than decoding wrongly. So does an unsupported dtype on the way in — int64 and float16 have no encoding.

The trailer is host-endian, because the C++ side writes raw ints. A blob is not portable between machines of opposite endianness.

Building and testing

colcon build --packages-select rtabmap_python
colcon test --packages-select rtabmap_python
colcon test-result --verbose

The tests cover the round trip for every supported depth, the exact trailer bytes against the codes RTAB-Map's serializeMatType() produces, and each of the behaviours above. Alongside them, the standard ament_copyright, ament_flake8 and ament_pep257 linters run over the package.

License

BSD-3-Clause. See the repository root.