ros2 unbag - fast ROS 2 bag export for any format

ros2 unbag is a powerful ROS 2 tool featuring an intuitive GUI and flexible CLI for extracting topics from .db3 or .mcap bag files into formats like CSV, JSON, PCD, images, and more.

• 🎨 Intuitive GUI interface for interactive bag exploration and export configuration
• ⚙️ Full-featured ROS 2 CLI plugin: ros2 unbag <args> for automation and scripting
• 🔌 Pluggable export routines enable export of any message to any type
• 🔧 Custom processors to filter, transform or enrich messages

• ⏱️ Time‐aligned resampling (last

  nearest)

• 🚀 Multi‐process export with adjustable CPU usage
• 💾 JSON config saving/loading for repeatable workflows

Table of Contents

• Introduction
• Installation
  • apt (Recommended)
  • From Source
  • Docker
• Quick Start
  • GUI Mode
  • CLI Mode
• Documentation
  • Export Routines - Built-in and custom export formats
  • Processors - Message transformation and filtering
  • Advanced Usage - Config files, resampling, CPU tuning
• Acknowledgements

Introduction

The GUI makes it easy to inspect bag contents, select topics, configure export formats, build processor chains, and manage resampling. For automation and scripting workflows, the CLI provides the same export capabilities through command-line arguments or JSON configuration files.

It comes with export routines for all message types (sensor data, point clouds, images). You need a special file format or message type? Add your own export plugin for any ROS 2 message or format, and chain custom processors to filter, transform or enrich messages (e.g. drop fields, compute derived values, remap frames).

Optional resampling synchronizes your data streams around a chosen master topic—aligning each other topic either to its last‑known sample (“last”) or to the temporally closest sample (“nearest”)—so you get a consistent sample count in your exports.

For high‑throughput workflows, ros2 unbag can spawn multiple worker processes and lets you tune CPU usage. Your topic selections, processor chains, export parameters and resampling mode (last or nearest) can be saved to and loaded from a JSON configuration, ensuring reproducibility across runs.

Whether you prefer the GUI for interactive exploration or ros2 unbag <args> for automated pipelines, you have a flexible, extensible way to turn bag files into the data you need.

Installation

apt (Recommended)

ros2 unbag is released as a binary package for ROS 2 Humble, Jazzy, Lyrical, and Rolling. Install it directly via apt:

sudo apt update
sudo apt install ros-<distro>-unbag

Replace <distro> with your ROS 2 distribution (e.g. humble, jazzy, lyrical, rolling). No need to clone or build anything—ros2 unbag is available right away after sourcing your ROS 2 installation.

From source

1. Create a ROS 2 workspace and clone the repository into src:

   mkdir -p ros2_ws/src
   git clone https://github.com/ika-rwth-aachen/ros2_unbag.git ros2_ws/src/ros2_unbag
   cd ros2_ws
   

1. Source your ROS 2 installation:

   source /opt/ros/<distro>/setup.bash
   

1. Install the package dependencies via rosdep:

   rosdep install --from-paths src --ignore-src -r -y
   

1. Build the package with colcon:

   colcon build --packages-select unbag
   

1. Source the workspace overlay:

   source install/setup.bash
   

Docker

File truncated at 100 lines see the full file