Rerun

Working with MCAP

The Rerun Viewer has built-in support for opening MCAP files, an open container format for storing timestamped messages.

āš ļø This is an early version of MCAP support that will continue to evolve and expand over time. We are actively seeking feedback from the community to guide development priorities. Reinterpretation of custom messages and enhanced query capabilities are planned for following releases.

Quick start quick-start

Loading MCAP files loading-mcap-files

The simplest way to get started is to load an MCAP file directly:

# View an MCAP file in the Rerun Viewer
rerun your_data.mcap

You can also drag and drop MCAP files into the Rerun Viewer or load them using the SDK:

"""Load an MCAP file using the Python SDK."""

import sys

import rerun as rr

path_to_mcap = sys.argv[1]

# Initialize the SDK and give our recording a unique name
rr.init("rerun_example_load_mcap", spawn=True)

# Load the MCAP file
rr.log_file_from_path(path_to_mcap)

Basic conversion basic-conversion

Convert MCAP files to Rerun's native format for faster loading:

# Convert MCAP to RRD format for faster loading
rerun mcap convert input.mcap -o output.rrd

# View the converted file
rerun output.rrd

Data model data-model

Rerun's data model is based on an entity component system (ECS) that is a bit different to the message-based model of MCAP. To map MCAP messages to Rerun entities we make the following assumptions:

  • MCAP topics corresponds to Rerun entities.
  • Messages from the same topic within an MCAP chunk will be placed into a corresponding Rerun chunk.
  • The contents of an MCAP message will be extracted to Rerun components and grouped under a corresponding Rerun archetype.
  • log_time and publish_time of an MCAP message will be carried over to Rerun as two distinct timelines.

Layered architecture layered-architecture

Rerun uses a layered architecture to process MCAP files at different levels of abstraction. This design allows the same MCAP file to be ingested in multiple ways simultaneously, from raw bytes to semantically meaningful visualizations.

Each layer extracts different types of information from the MCAP source and each of the following layers will create distinct Rerun archetypes:

  • raw: Logs the unprocessed message bytes as Rerun blobs without any interpretation
  • schema: Extracts metadata about channels, topics, and schemas
  • stats: Extracts file-level metrics like message counts, time ranges, and channel statistics
  • protobuf: Automatically decodes protobuf-encoded messages using reflection
  • ros2msg: Provides semantic conversion of common ROS2 message types into Rerun's visualization components
  • recording_info: Extracts recording metadata such as message counts, start time, and session information

By default, Rerun analyzes an MCAP file to determine which layers are active to provide the most comprehensive view of your data, while avoiding duplication. You can also choose to activate only specific layers that are relevant to your use case.

The following shows how to select specific layers:

# Use only specific layers
rerun mcap convert input.mcap -l protobuf -l stats -o output.rrd

# Use multiple layers for different perspectives
rerun mcap convert input.mcap -l ros2msg -l raw -l recording_info -o output.rrd

For a detailed explanation of how each layer works and when to use them, see Layers Explained.

Supported message formats supported-message-formats

Rerun provides automatic visualization for common ROS2 message types. Protobuf messages are automatically decoded into Arrow structs, but for now will only show up in the selection panel and in the dataframe view. The contents of these MCAP files can also be queried using the Dataframe API.

Unsupported message types (such as ROS1 messages) remain available as raw bytes in Arrow format.

The following is a screenshot of the selection panel and shows a Protobuf-encoded MCAP message. The top-level fields of the Protobuf message are imported as components in the corresponding point cloud archetype. The raw MCAP schema and message information show up as separate archetypes as well.

Screenshot of MCAP messages converted to raw Arrow data in the selection panel

For more details about all supported message types, see Message Formats.

Advanced usage advanced-usage

For advanced command-line options and automation workflows, see the CLI Reference for complete documentation of all available commands and flags.

Privacy policy