ros2bagreader

Access ROS 2 bag log file information

Since R2021a

Description

The ros2bagreader object is an index of the messages within a ROS 2 bag file. You can use this object to extract message data from a ROS 2 bag file or select messages based on specific criteria. The ros2bagreader object supports sqlite3 (DB3) and MCAP storage format.

Creation

Syntax

bagReader = ros2bagreader(folderpath)

Description

bagReader = ros2bagreader(folderpath) creates a ros2bagreader object, bagReader, that contains all the messages from the ROS 2 bag file in the input file or folder. The folderpath input sets the FilePath property.

You can use the ROS 2 bag files for storing messages that are transmitted over a ROS 2 network. You can then use the resulting bag file for offline analysis and visualization.

You can read a single DB3 or MCAP file in the bag folder by specifying the folderpath as a single file. You can also read all the DB3 or MCAP files in the bag folder by specifying the folderpath as a folder. Ensure that you have read and write access to the bag folder that contains the DB3 files. However, for reading a MCAP file, you must have read access to the bag folder only.

You can read compressed ROS 2 bag files in file or message compression mode and ZSTD compression format.

Note

To read compressed ROS 2 bag files, specify the folderpath as the folder location.

If a ROS 2 bag file contains custom messages, create custom messages for MATLAB using the ros2genmsg function before creating the ros2bagreader object.

Properties

FilePath — Absolute path to ROS 2 bag file or folder

character vector

This property is read-only.

Absolute path to the ROS 2 bag file or folder with , specified as a character vector.

Data Types: char

AvailableBags — List of available ROS 2 bag files

string array

This property is read-only.

List of available ROS 2 bag files, specified as a string array.

Data Types: string

StartTime — Timestamp of first message

scalar

This property is read-only.

Timestamp of the first message, specified as a scalar in seconds.

Data Types: double

EndTime — Timestamp of last message

scalar

This property is read-only.

Timestamp of the last message, specified as a scalar in seconds.

Data Types: double

NumMessages — Number of messages

scalar

This property is read-only.

Number of messages, specified as a scalar.

Data Types: double

AvailableTopics — Table of available topics

table

This property is read-only.

Table of available topics, specified as a table. Each row in the table lists one topic, the number of messages for this topic, the message type, and the message definition.

Data Types: table

AvailableFrames — List of available coordinate frames

cell array

This property is read-only.

List of available coordinate frames, specified as a cell array of character vectors. To check whether specific transformations between frames are available, use the canTransform object function. To query a transformation, use the getTransform object function.

Data Types: cell

MessageList — List of messages

table

This property is read-only.

List of messages, specified as a table. Each row in the table lists one message.

Data Types: table

Object Functions

readMessages	Read messages from ros2bagreader object
select	Select subset of messages in ros2bagreader
timetable	Create timetable for selected message properties in ROS 2 bag file
getTransform	Return transformation between two coordinate frames
canTransform	Verify if transformation is available

Examples

Read Messages from ROS 2 Bag Log File

Extract the ZIP file that contains the ROS 2 bag log file and specify the full path to the log folder.

unzip("ros2_netwrk_bag.zip");
folderPath = fullfile(pwd,"ros2_netwrk_bag");

Create a ros2bagreader object that contains all the messages in the log file.

bagReader = ros2bagreader(folderPath);

Get information about the contents of the ros2bagreader object.

baginfo = ros2("bag","info",folderPath)

baginfo = struct with fields:
         Path: 'C:\Users\ros2_netwrk_bag\ros2_netwrk_bag.db3'
      Version: '1'
    StorageId: 'sqlite3'
     Duration: 207.9020
        Start: [1×1 struct]
          End: [1×1 struct]
         Size: 16839538
     Messages: 166867
        Types: [4×1 struct]
       Topics: [4×1 struct]

Get all the messages in the ros2bagreader object.

msgs = readMessages(bagReader);

Select a subset of the messages, filtered by topic.

bagSel = select(bagReader,"Topic","/odom")

bagSel = 
  ros2bagreader with properties:

           FilePath: 'C:\Users\ros2_netwrk_bag'
      AvailableBags: "ros2_netwrk_bag.db3"
          StartTime: 1.6020e+09
            EndTime: 1.6020e+09
    AvailableTopics: [1×3 table]
    AvailableFrames: {0×1 cell}
        MessageList: [5275×3 table]
        NumMessages: 5275

Get the messages in the selection.

msgsFiltered = readMessages(bagSel);

Version History

Introduced in R2021a

R2024a: MCAP Storage Format Support

You can now read data from a bag folder containing one or more MCAP files.

R2023b: AvailableBags and AvailableFrames Properties

You can now see the list of available ROS 2 bag files using AvailableBags property. You can also see the list of available coordinate frames using AvailableFrames property.

R2023b: getTrasnform and canTransform Object Functions

You can now check the availability of specific transformations between frames using canTransform object function or query a transformation using getTrasnform object function.

R2022b: ros2bagreader was renamed

The ros2bagreader object was renamed from ros2bag. Use ros2bagreader when creating the object.

R2022a: folderpath Input

• The ros2bagreader object in Foxy can accept file name of the ROS 2 bag log file (.db3) as the folderpath input, when there is no metadata.yaml file.

• If there is metadata.yaml file along with the .db3 file in a folder, it accepts the folder name as the folderpath input.

R2022a: ROS 2 Bag Log File Version

The ros2bagreader object in Foxy can accept different versions of bag file from version 1 to 4.

R2022a: Empty Messages

The ros2bagreader object in Foxy discards empty messages recorded on a topic. Whereas in Dashing the ros2bagreader object accepts /rosout and /param_events topics.