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
  • 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

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

2. Source your ROS 2 installation:

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

3. Install the package dependencies via rosdep:

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

4. Build the package with colcon:

   colcon build --packages-select unbag

5. Source the workspace overlay:

   source install/setup.bash

Docker

You can skip local installs by running our ready‑to‑go Docker image:

docker pull ghcr.io/ika-rwth-aachen/ros2_unbag:latest

This image comes with ROS 2 Jazzy and ros2 unbag preinstalled. To launch it:

1. Clone or download the docker/docker-compose.yml in this repo.

2. Run:

   docker compose -f docker/docker-compose.yml up

3. If you need the GUI, first enable X11 forwarding on your host (at your own risk!):

   xhost +local:

   Then start the container as above—the GUI will appear on your desktop.

Quick Start

ros2 unbag offers both an intuitive GUI for interactive workflows and a powerful CLI for automation and scripting.

GUI Mode (Recommended for First-Time Users)

Launch the interactive graphical interface:

ros2 unbag

CLI Mode (For Automation & Scripting)

Run the CLI tool by calling ros2 unbag with a path to a rosbag and an export config, consisting of one or more topic:format:[subdirectory] combinations:

ros2 unbag <path_to_rosbag> --export </topic:format[:subdir]>…

Alternatively, you can load a config file. In this case, you do not need any --export flag:

ros2 unbag <path_to_rosbag> --config <config.json>

The config file structure is described here.

In addition to these required arguments, the following optional flags are available:

Example:

ros2 unbag rosbag/rosbag.mcap 
    --output-dir /docker-ros/ws/example/ --export /lidar/point_cloud:pointcloud/pcd:lidar --export /radar/point_cloud:pointcloud/pcd:radar --resample /lidar/point_cloud:last,0.2

⚠️ If you specify the --config option (e.g., --config configs/my_config.json), the tool will load all export settings from the given JSON configuration file. In this case, all other command-line options except <path_to_rosbag> are ignored, and the export process is fully controlled by the config file. The <path_to_rosbag> is always required in CLI use.

Documentation

For detailed information on advanced features, see the following guides:

• Export Routines - Complete guide to built-in export formats (images, point clouds, CSV, JSON, etc.) and creating custom export routines
• Processors - Message transformation and filtering, including processor chains and custom processors
• Advanced Usage - Configuration files, resampling strategies, and CPU utilization tuning

Acknowledgements

This research is accomplished within the following research projects:

Project	Funding Source
	Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) DFG Proj. Nr. 503852364
	Funded by the European Union’s Horizon Europe Research and Innovation Programme under Grant Agreement No 101146091
	Funded by the European Union’s Horizon Europe Research and Innovation Programme under Grant Agreement No 101146542

Notice

[!IMPORTANT]
This repository is open-sourced and maintained by the Institute for Automotive Engineering (ika) at RWTH Aachen University.
We cover a wide variety of research topics within our Vehicle Intelligence & Automated Driving domain.
If you would like to learn more about how we can support your automated driving or robotics efforts, feel free to reach out to us!
:email: opensource@ika.rwth-aachen.de