rosx_introspection

Parse any ROS/ROS2 message without compile-time information

• Links
  • Rosindex
  • Repository
• C++ API
  • File Hierarchy
  • Full C++ API

• Standard Documents
  • PACKAGE
  • CHANGELOG
  • README
  • LICENSE
• ROS Package Dependencies
  • ament_index_cpp
  • rclcpp
  • rosbag2_cpp

README

ROS X Introspection

A runtime message parser and introspection library for ROS. It can deserialize any ROS message into key/value pairs without compile-time type knowledge.

Supported schema formats

• ROS .msg (ROS1 and ROS2 message definitions)

• DDS IDL (OMG IDL 4.2 subset)

The subset the OMG IDL currently supported are:

• enums

• unions

• @key and @optional

• multi-dimensional arrays

• struct inheritance

Build modes

The library compiles in two modes:

• ROS2 (colcon/ament)

• Standalone (vanilla CMake, no ROS dependency)

ROS1 .msg schemas and the ROS1 serialization format (ROS_Deserializer) are still supported at runtime, but the catkin build system is no longer maintained.

How it works

To parse a message at runtime, you need:

1. The type name (e.g. sensor_msgs/JointState or my_pkg::MyIdlMessage)

2. The schema definition (a .msg file or IDL text)

3. A raw memory buffer containing the serialized message

The raw buffer is typically obtained from:

• rosbag::MessageInstance or topic_tools::ShapeShifter in ROS1.

• GenericSubscription or rosbag2_storage::SerializedBagMessage in ROS2.

• MCAP files (works without ROS).

Output writers

The MessageWriter interface allows different output formats from the same deserialization walk:

Writer	Description
FlatMessageWriter	Produces a FlatMessage (vector of key/value pairs). Default output.
MsgpackMessageWriter	Writes MessagePack binary directly, bypassing FlatMessage.
JsonMessageWriter	Produces a JSON document (requires ROSX_HAS_JSON=ON).

Custom writers can be implemented by subclassing MessageWriter.

Building and testing

# Standalone build (no ROS)
cmake -S. -B build -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build

Benchmarks

The MCAP benchmark measures deserialization throughput on real bag files:

cmake -S. -B build -DBUILD_BENCHMARKS=ON
cmake --build build

# Run with different output writers
./build/mcap_benchmark path/to/file.mcap --writer flat
./build/mcap_benchmark path/to/file.mcap --writer msgpack
./build/mcap_benchmark path/to/file.mcap --writer json

The IDL benchmark measures CDR deserialization performance:

./build/idl_benchmark

Python binding

cmake -S. -B build_python -DROSX_PYTHON_BINDINGS=ON
cmake --build build_python

PYTHONPATH=build_python/python python3 python/mcap_ros_parser.py path_to_your_rosbag.mcap