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) 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 data from messages that are transmitted over a ROS 2 network. You can use the resulting bag file for offline analysis, visualization, and storage of ROS 2 messages.

You can read a single DB3 file in the bag folder by specifying the folderpath as a single file. You can also read all the DB3 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.

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
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\echakrab\OneDrive - MathWorks\Documents\MATLAB\ExampleManager\echakrab.Bdoc22b.ros2bagExamples\ros-ex96596996\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");

Get the messages in the selection.

msgsFiltered = readMessages(bagSel);

Version History

Introduced in R2021a

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.