Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rpng/open_vins/llms.txt

Use this file to discover all available pages before exploring further.

When working with OpenVINS under ROS 2, you will often need to replay datasets that were originally recorded or distributed as ROS 1 .bag files. The two common conversion approaches are the standalone rosbags Python package (recommended) and the rosbag2 bridge that requires both ROS 1 and ROS 2 to be installed simultaneously. This page covers both methods, along with known issues and workarounds. The rosbags library is the simplest and most reliable approach. It operates as a pure Python package with no ROS installation required, making it easy to use in any environment. This is the tool used to generate the converted ROS 2 bag files for all standard OpenVINS-compatible datasets (e.g., EuRoC MAV, TUM-VI).

​
ROS 1 → ROS 2 Conversion

1

Install rosbags

Install the rosbags package via pip. Version 0.9.11 or newer is required for ROS 1 → ROS 2 conversion.
pip3 install "rosbags>=0.9.11"
2

Convert the bag file

Run the rosbags-convert command, pointing it at your source .bag file and specifying a destination folder for the ROS 2 bag:
rosbags-convert V1_01_easy.bag --dst V1_01_easy_ros2/
The --dst argument specifies the output directory for the new ROS 2 bag. The tool will create this directory and populate it with the converted metadata and data files.
3

Verify the output

After conversion, inspect the output folder to confirm the metadata file and data store were created:
ls V1_01_easy_ros2/
# metadata.yaml
# V1_01_easy_ros2_0.db3   (or similar)

​
ROS 2 → ROS 1 Conversion

If you have a ROS 2 bag (e.g., recorded from a live ROS 2 system) and need to convert it back to a ROS 1 .bag for use with Kalibr or a ROS 1 pipeline, use version 0.9.12 or newer: 
pip3 install "rosbags>=0.9.12"
rosbags-convert <ros2_bag_folder>/ --dst calib_01.bag --exclude-topic <non_img_and_imu_topics>
Use --exclude-topic to drop any topics that are not needed (e.g., pointcloud or lidar topics that may have no equivalent ROS 1 message type).

​
Creating a Bag from Images

If you need to create a ROS bag from a folder of images (e.g., to calibrate cameras with Kalibr), use the Kalibr bagcreater utility rather than rosbags-convert.

​
Option 2: rosbag2 Play Bridge

This method uses the rosbag2 ROS 2 package with the rosbag_v2 storage plugin to play ROS 1 bags directly inside ROS 2. It requires both ROS 1 and ROS 2 installed on the same machine.
This method is not recommended. You may encounter .so file corruption issues (see rosbag2 issue #94) that have no known fix short of building the plugin from source. Use the rosbags Python tool (Option 1) instead whenever possible.

​
Install Dependencies

sudo apt-get install ros-$ROS2_DISTRO-ros2bag ros-$ROS2_DISTRO-rosbag2*
sudo apt install ros-$ROS2_DISTRO-rosbag2-bag-v2-plugins
Replace $ROS2_DISTRO with your ROS 2 distribution name (e.g., foxy, galactic, humble).

​
Play a ROS 1 Bag Under ROS 2

1

Source both ROS environments

Source ROS 1 first, then ROS 2 in the same shell. The exact source commands depend on your installation paths:
source /opt/ros/noetic/setup.bash   # ROS 1
source /opt/ros/galactic/setup.bash # ROS 2
2

Play the bag using the rosbag_v2 storage plugin

ros2 bag play -s rosbag_v2 V1_01_easy.bag
This streams the ROS 1 bag through the ROS 2 topic system, allowing ROS 2 subscribers (including ov_msckf nodes) to receive the data.
The rosbag_v2 storage plugin has known .so library issues on some systems. If you see errors about missing or corrupted shared libraries, there is no reliable workaround. Build the plugin from source or switch to the rosbags Python tool.

​
Comparison of Methods

rosbags (Option 1)rosbag2 play (Option 2)
ROS install requiredNoYes (both ROS 1 and ROS 2)
ReliabilityHighLow (known .so issues)
Bidirectional conversionYesROS 1 → ROS 2 only
RecommendedYesNo

​
Common Issues

Some message types changed between ROS 1 and ROS 2 (e.g., sensor_msgs/Image headers). The rosbags library handles most standard types automatically. If a topic fails to convert, it is usually because the message type is not supported. You can exclude those topics using --exclude-topic.
Ensure the pip install target is on your PATH. If you installed with pip3 install --user, add ~/.local/bin to your shell’s PATH:
export PATH="$HOME/.local/bin:$PATH"
This is a known upstream issue (rosbag2 #94). The .so files for the rosbag_v2 storage plugin can be malformed in the binary apt packages. The only reliable fix is to build rosbag2 and its plugins from source. It is simpler to use the rosbags Python package instead.
Very high-rate IMU bags may produce large output files. Ensure the destination has sufficient disk space before converting. Typical IMU-camera datasets are a few GB; allocate at least 2× the source file size.

Build docs developers (and LLMs) love

Get started for freeTalk to us