Repository files navigation

This Python package wraps and documents functionality for reading data from bagfiles generated byROS2. Bag files (or "bags") are the standard viawhich ROS2 stores data to disk. For an introduction to bag files, please seethe ROS2 documentation that explainsrecording and playing back data.

The purpose of this package is to facilitate direct reading of data from bagfiles that have been recorded by ROS.¹ TheROS 2 bag design document explains the motivation andapproach to data storage, and therosbag2 package providesan official implementation (C++ and Python). However, documentation of therosbag2 API iscurrently both scattered and limited, as arerecommended best practices for working with bags. This package is intended toaggregate documentation about existing ROS2 functionality and to illustrate itsusage. This package is intended only to fill a temporary gap, and it isexpected that later versions of ROS2 (Jazzy and beyond) will make it obsolete.

Therosbag2 package must be installed. This does notnecessarily require that ROS2 must beinstalled.

With the rosbag2 package installed, no further steps are required, as long asthe package is available on the Python path (e.g., viaPYTHONPATH).

Asetup.cfg file has been provided, to facilitate package installation viasetuptools. Package installation can be accomplished via thecommand:

pip install path/to/nml_bag

Basic usage of the package follows this pattern:

1. Initialize a ROS2 command prompt bysourcing the ROS2 environment.
2. Import the package:

   importnml_bag

3. Initialize a Reader object:

   reader=nml_bag.Reader('path/to/bag.mcap',topics=['topic_a','/topic_b'])

4. Iterate through message records:

   for message_record in reader: print(message_record)

5. Alternatively, therecords property will return all available messagerecords:

   records = reader.records

A usageexample is included in this package asexample.py. The example initializes a bag directory anda MCAP filebag_test_0.mcap. The bag file contains a single topictest, onwhich two string-type messages are recorded.

Roughly following the quickstart outline, the code for reading the bag is:

frompprintimportpprintimportnml_bagreader=nml_bag.Reader('path/to/bag_test_0.mcap')pprint(reader.records)

And the output is similar to:

[{'data': 'Hello World!',  'time_ns': 1654207659885697659,  'topic': 'test',  'type': 'example_interfaces/msg/String'}, {'data': 'Goodybye World!',  'time_ns': 1654207659885798001,  'topic': 'test',  'type': 'example_interfaces/msg/String'}]

Bydefault, ROS2 messages are serialized using theCommon Data Representation (CDR) standard and stored usingMCAP(since Iron) -- "an open source container file format for multimodal logdata". Formerly, data were stored usingsqlite 3.

Note: Although thesqlite3 package is part of the standarddistribution of Python 3 -- and it can be used to interpret bag files -- it isrecommended that the ROS2 API be used for decoding bag files wherever possible.