ROSBag

class ROSBag(filename: str, release: str = 'ROS1_NOETIC', topicfilter: str | list[str] | None = None, msgfilter: str | list[str] | None = 'Image', dtype: dtype | str | dict | None = None, colororder: str | dict | None = None, verbose: bool = False)

Iterate images and point clouds from a ROS 1 bag file.

Parameters:

• filename (str or Path) – path to a .bag file, or an http(s):// URL

• release (str) – ROS release name (or unique substring), e.g. "noetic", defaults to "ROS1_NOETIC"; controls the message definitions used to parse the bag file

• topicfilter (str or list of str or None) – only yield messages from this topic or list of topics; None accepts all topics

• msgfilter (str or list of str or None) – only yield messages whose type contains this substring or matches any entry in the list; None accepts all types, defaults to "Image"

• dtype (str or dict) – override the numpy dtype for all image pixel data, or by topic {topic: dtype}

• colororder (str or dict or None) – override the colour-plane order for all image, or by topic {topic: colororder}

Raises:

ImportError – if the rosbags package is not installed

The resulting object is an iterator that yields:

• Image for messages whose type ends in Image, which includes CompressedImage.

• PointCloud for PointCloud2 messages (requires open3d)

• the raw deserialised message object for all other types

Each yielded object carries a timestamp attribute (ROS nanosecond epoch from the message header) and a topic attribute (the topic on which it was published).

Usage modes

Implicit — iterating directly over the object opens and closes the bag file automatically around the loop:

from machinevisiontoolbox import ROSBag
for img in ROSBag("mybag.bag", release="noetic"):
    img.disp()

Explicit context manager — use a with statement when you need to make multiple passes over the bag, call helper methods such as topics or print, or simply want a guaranteed close even if an exception is raised:

bag = ROSBag("mybag.bag", release="noetic", msgfilter=None)
with bag:
    bag.print()                     # inspect topics
    for msg in bag:                 # iterate messages
        print(msg.topic, msg.timestamp)

Note

filename may be an http:// or https:// URL, in which case the bag file is downloaded to a temporary file on first use and that file is reused for the lifetime of the ROSBag object. The temporary file is deleted automatically when the object is garbage collected or when the script exits.

Note

If filename is a relative path that does not exist in the current working directory, it is looked up in the mvtb-data companion package automatically. Bag files placed there can therefore be referenced by their bare name, e.g. ROSBag("forest.bag").

Note

The release argument controls the ROS message definitions used to parse the bag file. This is important because message definitions can change between ROS releases, and using the wrong definitions can lead to incorrect parsing of the data. The release string is matched case-insensitively against the member names of Stores, so short names such as "noetic" or "humble" are accepted in addition to the full enum name (e.g. "ROS1_NOETIC").

Methods

disp	Display images from the source interactively.
format_duration	Format a duration in nanoseconds as hh:mm:ss.
format_local_time	Format a ROS timestamp to a local-time string.
print	Print a summary table of topics in the ROS bag.
tensor	Convert all images from this source into a single 4D PyTorch tensor.
topics	Return topics found in the ROS bag.
traffic	Message counts by type found in the ROS bag.

Attributes

colororder
dtype
filename
msgfilter	Message-type filter applied when iterating.
release
topicfilter	Topic filter applied when iterating.
verbose