ros2bagreader

R2026b

Access ROS 2 bag log file information

expand all in page

    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.

    example

    Properties

    expand all

    This property is read-only.

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

    Data Types: char

    This property is read-only.

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

    Data Types: string

    This property is read-only.

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

    Data Types: double

    This property is read-only.

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

    Data Types: double

    This property is read-only.

    Number of messages, specified as a scalar.

    When filtering messages by Topic or TopicType, by calling the select function, the NumMessages property is available immediately. However, when filtering based on a Time range, the NumMessages property is unavailable until background message indexing completes.

    Data Types: double

    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

    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

    This property is read-only.

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

    The MessageList property is built asynchronously in the background after the ros2bagreader object is created. While loading is in progress, the object display shows <Preparing> for this property. Once the message list is fully loaded, the display updates to show the complete table. Accessing the entire property programmatically, reader.MessageList, blocks MATLAB until the full message list has been loaded.

    Data Types: table

    Object Functions

    readMessagesRead messages from ros2bagreader object
    selectSelect subset of messages in ros2bagreader
    timetableCreate timetable for selected message properties in ROS 2 bag file
    getTransformReturn transformation between two coordinate frames
    canTransformVerify if transformation is available

    Examples

    collapse all

    Open Live Script

    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\user\OneDrive - MathWorks\Documents\MATLAB\ExampleManager\user.Bdoc26b\ros-ex96596996\ros2_netwrk_bag'
      FileInformation: "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]
    CompressionFormat: 'none'
      CompressionMode: 'none'

    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\user\OneDrive - MathWorks\Documents\MATLAB\ExampleManager\user.Bdoc26b\ros-ex96596996\ros2_netwrk_bag'
      AvailableBags: "ros2_netwrk_bag.db3"
          StartTime: 1.6020e+09
            EndTime: <preparing>
    AvailableTopics: [1×3 table]
    AvailableFrames: {0×1 cell}
        MessageList: <preparing>
        NumMessages: 5275

    Get the messages in the selection.

    msgsFiltered = readMessages(bagSel);

    Version History

    Introduced in R2021a

    expand all

    See Also

    Functions

    Topics