ROS Bag: Complete Guide for Robotics Data

ROS 1 bags (.bag) use a custom binary format storing serialized messages with timestamps and topic names. ROS 2 bags (.db3) use SQLite3 databases with a messages table. Both store arbitrary ROS message types: sensor_msgs/Image, sensor_msgs/JointState, geometry_msgs/Pose, etc. MCAP is the emerging successor format for ROS 2.

A ROS bag is fundamentally a time-ordered log of publish-subscribe messages. Each message has a timestamp, a topic name (e.g., /camera/rgb/image_raw, /joint_states, /wrench), and a serialized payload matching a ROS message definition (.msg file). ROS 1 bags use a custom binary container with an index section at the end for fast topic-based seeking. ROS 2 bags default to SQLite3 (.db3 files) with a schema table mapping topic IDs to message types and a messages table storing serialized payloads with timestamps. Since ROS 2 Humble, MCAP has become the recommended storage backend due to better random access performance and smaller file sizes.

The critical challenge with ROS bags for ML training is multi-rate sensor synchronization. A typical robot publishes camera images at 30 Hz, joint states at 100 Hz, and force/torque readings at 1000 Hz. These streams are not synchronized at the hardware level, so converting a bag to a structured dataset requires choosing a reference clock (usually the camera timestamps) and interpolating or nearest-neighbor matching all other streams to that clock. Message types are defined by .msg files which specify field names and types, and the rosbag library handles deserialization automatically.

For ROS 1 bags, the rosbag Python package provides the standard interface. Open a bag with bag = rosbag.Bag('data.bag'), then iterate with for topic, msg, t in bag.read_messages(topics=['/camera/rgb/image_raw', '/joint_states']). Image messages (sensor_msgs/Image) can be converted to NumPy arrays using the cv_bridge package: bridge.imgmsg_to_cv2(msg, 'bgr8'). Joint states arrive as sensor_msgs/JointState with .position, .velocity, and .effort arrays. For ROS 2 bags, the rosbag2_py library or the mcap Python package (if stored as MCAP) provides equivalent functionality.

Converting a ROS bag to an ML-ready format involves four steps: topic selection (choose which sensor streams to include), time synchronization (align all streams to a common clock), episode segmentation (split continuous recording into task-bounded episodes), and format writing (output to HDF5, RLDS, or WebDataset). The most reliable synchronization approach is approximate time synchronization using the message_filters.ApproximateTimeSynchronizer from ROS, which buffers messages from multiple topics and emits synchronized tuples when timestamps are within a configurable tolerance (typically 30-50ms for camera-joint alignment). For post-hoc conversion without ROS installed, the rosbags library (pip install rosbags) provides a pure-Python reader that works without a ROS installation.

The ROS bag to ML-ready format conversion is the single most common data engineering task in robotics ML. The process begins with bag inspection: use rosbag info data.bag (ROS 1) or ros2 bag info data/ (ROS 2) to list all topics, their message types, message counts, and time ranges. Identify your observation topics (cameras, joint states, force/torque), action topics (joint commands, end-effector velocities), and metadata topics (task labels, episode markers). For multi-bag collections from fleet operations, write a manifest CSV mapping bag paths to metadata (robot ID, task type, collection date).

Time synchronization is the hardest part of the conversion. The gold standard is hardware-triggered synchronization where all sensors share a common trigger signal, but most research setups use software timestamps with 10-50ms jitter. For post-hoc synchronization, implement a SyncBuffer class that queues incoming messages per topic and emits synchronized tuples when all topics have messages within a tolerance window. For camera-joint alignment at 30 Hz camera rate, 33ms tolerance works well. Interpolate proprioceptive signals (joint positions, velocities) to camera timestamps rather than nearest-neighbor matching, since joint states typically arrive at higher rates (100-1000 Hz).

Episode segmentation can be done manually (annotating start/end times in a CSV), automatically (detecting gripper open/close events, task completion signals, or velocity-to-zero transitions), or by recording explicit markers during collection (publishing to a /episode_marker topic). After segmentation, write each episode to your target format. Claru's conversion pipeline handles all of these steps, accepting raw bag files from your robot fleet and delivering synchronized, segmented, ML-ready datasets in your format of choice.

Claru accepts ROS bag uploads from your robot fleet and converts them to ML-ready formats (RLDS, HDF5, WebDataset, LeRobot). Our pipeline handles topic synchronization, image decompression, and timestamp alignment across multi-rate sensor streams.

The Claru conversion pipeline supports both ROS 1 bags (.bag) and ROS 2 bags (.db3, .mcap) without requiring a ROS installation. We automatically detect message types, identify camera and proprioceptive streams, and apply the appropriate synchronization strategy. For fleets collecting thousands of bags per week, Claru provides a batch ingestion API that accepts S3 paths or direct uploads, processes bags in parallel, and delivers consolidated ML-ready datasets with episode-level metadata and quality reports. Each delivery includes a provenance log mapping every training sample back to its source bag, topic, and timestamp range.