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, **kwargs: Any)[source]#

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 color-plane order for all image, or by topic {topic: colororder}

  • kwargs – options applied to image frames, see convert

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).

Filters

The message and topic filters can be a single string, or a list of strings. If a single string is provided, it is treated as a list with one element. The filter passes if any of the strings in the list are a substring of the message type (for the message filter) or topic name (for the topic filter). It is an OR condition.

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").

Base constructor for image sources.

Parameters:

kwargs (Any) – source-specific keyword arguments

On this page
Show Source