ros2-bagutils

This repository contains packages for working with bag files in ROS 2.

baggie

The baggie package provides a Python wrapper around the C++ rosbag2 API as well as some pure Python convenience interfaces for making working with bags in ROS 2 easier. Inspired, in part, by the (forthcoming?) rosbag2_py Python API, this package exposes the necessary C++ API via Pybind11 but puts a Python interface in front of it to make the easy things easy and the hard things possible.

In the simplest of use cases, you’ll want to read from an existing bag. You can do this with a context manager like:

import baggie

[ ... ]

with baggie.BagReader("/path/to/file.bag") as bag:
    for topic, msg, stamp in bag.read_messages():
      # do something with the data

Writing a bag is similarly easy:

import baggie
from example_interfaces.msg import Int32
from datetime import datetime as DT

[ ... ]

with baggie.BagWriter("/path/to/file.bag") as bag:
    msg = Int32()
    msg.data = 1
    bag.write("/int_topic", msg, DT.now())

NOTE: In the above example we pass a datetime.datetime as the timestamp when we write the message. We do this for simplicity and convenience in this example. However, we recommend passing an rclpy.time.Time instance instead (the method accepts either). The reason for this recommendation is that datetime.datetime in Python only support usec precision whereas the ROS 2 time libraries support nanosecond precision.

The above examples are intentionally simplistic and accept many default arguments. However, since baggie exposes a significant portion of the C++ API, much more complex use cases are supported. The context manager examples above are a front-end to the central fixture of this library, the baggie.Baggie class. The Baggie class provides an interface for reading or writing ROS 2 bag files directly. A given instance of a Baggie can be instantiated as either a reader or a writer. One Baggie maps to exactly one on-disk ROS 2 bag file (which may be made of up several files). Extensive example code is available in the test directory to include manually driving the lower-level C++ interface via the Python projections. Additionally, real-world examples of using the baggie API can be seen in the code for the utility scripts provided with the baggie package.

Utility scripts

Beyond the Python library code, the baggie package provides several command-line utilities for performing common operations on bagfiles. They include:

• filter: Copy bag files with optional transformation filters
• split: Split a single input bag into multiple, smaller, output bags
• join: Join multiple input bags into a single output bag
• timeline: Print a JSON timeline of messages in a set of bags

filter

The filter script is used to copy bag files while also applying some filtering during the copying process. Here is its help string:

$ ros2 run baggie filter --help
usage: filter [-h] -i INFILE [-o OUTFILE] [--start_time START_TIME] [--end_time END_TIME] [--topics T [T ...]] [--map M [M ...]]
              [--compress | --uncompress]

Copy a bag file, optionally filtered by topic and time

optional arguments:
  -h, --help            show this help message and exit
  -i INFILE, --infile INFILE
                        Path to input bag file (default: None)
  -o OUTFILE, --outfile OUTFILE
                        Output bag file, default: <infile>-filtered.bag (default: None)
  --start_time START_TIME
                        Earliest message stamp in output bag (nanos) (default: None)
  --end_time END_TIME   Latest message stamp in output bag (nanos) (default: None)
  --topics T [T ...]    List of topics to include in output bag (default: None)
  --map M [M ...]       Topic name remappings: --map from:to (default: None)
  --compress            Compress output file (default: False)
  --uncompress          Do not compress output file (default: False)

The only required option is -i (or --infile) to specify which input bag file to operate on. When run in this way, filter acts like the Unix cp

File truncated at 100 lines see the full file