roboto.formats.mcap.reader#

Module Contents#

roboto.formats.mcap.reader.END_OF_STREAM#

Sentinel returned by McapReader.next_decoded() when the stream is exhausted.

A decoded message value can legitimately be None (a JSON null payload), so exhaustion cannot be signaled with None without making a real null-valued message indistinguishable from end-of-stream. Callers test result is END_OF_STREAM to detect exhaustion and treat every other value – None included – as a delivered message.

class roboto.formats.mcap.reader.McapEnvelopeTimestamp#

Bases: NamedTuple

The pair of timestamps an MCAP message envelope carries.

Every MCAP message records two times in nanoseconds: 1. log_time, when the message was written to the file, and 2. publish_time, when its producer published it.

Both fields are math.inf when the reader is exhausted.

log_time: int | float#
publish_time: int | float#
class roboto.formats.mcap.reader.McapReader(stream, fields, start_time=None, end_time=None, log_time_order=True)#

Reader for processing MCAP files with field projection.

Provides an iterator interface for reading decoded messages from MCAP files, with support for temporal filtering and field selection. Handles multiple encoding formats including JSON, ROS1, and ROS2.

The reader automatically decodes messages using appropriate decoders and filters the output based on the specified fields and time range.

Parameters:
property field_paths: list[str]#

Get the list of fields being projected, as dot-delimited paths.

Returns the dot-delimited names of the fields provided during initialization.

Returns:

List of field names in dot notation.

Return type:

list[str]

property has_next: bool#

Check if there are more messages available to read.

Returns:

True if there are more messages to read, False otherwise.

Return type:

bool

next()#

Read and return the next decoded message.

Advances the reader to the next message and returns it as a DecodedMessage object, or None if no more messages are available.

Returns:

DecodedMessage containing the next message data, or None if no more messages.

Return type:

Union[roboto.formats.mcap.decoded_message.DecodedMessage, None]

Examples

>>> while reader.has_next:
...     message = reader.next()
...     if message:
...         data = message.to_dict()
...         print(f"Message at {data.get('log_time')}: {data}")
next_decoded()#

Read and return the next message’s raw decoded value, advancing the reader.

The raw value is what the format decoder produced – a dict for JSON-encoded messages, a dynamically created class instance for ROS1/ROS2 – with no projection applied. Callers that want projected dictionary output use next() and DecodedMessage.to_dict() instead.

A decoded value of None is a real message (a JSON null payload) and is delivered as such. Exhaustion is signaled with the dedicated END_OF_STREAM sentinel instead, so callers must test result is END_OF_STREAM rather than result is None to detect the end.

Returns:

The decoded message value, or END_OF_STREAM if no more messages are available.

Return type:

Any

property next_envelope_timestamp: McapEnvelopeTimestamp#

Get the envelope timestamps of the next message to be read.

Returns:

The next message’s log_time and publish_time in nanoseconds, or both math.inf if no more messages.

Return type:

McapEnvelopeTimestamp

next_message_is_time_aligned(timestamp)#

Check if the next message has the specified timestamp.

Used for time-aligned reading when merging data from multiple readers.

Parameters:

timestamp (Union[int, float]) – Timestamp to check against in nanoseconds.

Returns:

True if the next message has the specified timestamp, False otherwise.

Return type:

bool

property schema_encoding: str | None#

The MCAP Schema-record encoding of the next message to be read.

The encoding (e.g. "ros1msg", "ros2msg", "jsonschema") identifies the framework or format that produced the messages; roboto.formats.mcap.dialect_from_schema_encoding() maps it to an McapDialect.

Returns:

The schema record’s encoding, or None if the reader is exhausted or the next message carries no schema (a schemaless channel).

Return type:

Optional[str]

On this page