Working with MCAP - Rerun

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

Supported message formats

Here's a quick summary of Rerun's MCAP data loader:

Automatic conversion to Rerun archetypes is supported for common ROS 2 & Foxglove messages.
Other ROS 2 & Foxglove messages are decoded into queryable components via reflection.

For a detailed overview of Rerun's built-in MCAP support, please refer to our Supported Message Formats page. We are continually expanding the supported MCAP message types and are interested in your feedback.

Quick start

Loading MCAP files

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

bash

# 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:

snippet: howto/load_mcap

Basic conversion

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

bash

# 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

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.
message_log_time and message_publish_time of an MCAP message will be carried over to Rerun as two distinct timelines.

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
metadata Extracts metadata records (if present) into the __properties of the RRD
protobuf: Automatically decodes protobuf-encoded messages using reflection
ros2msg: Provides semantic conversion of common ROS2 message types into Rerun's visualization components
ros2_reflection: Automatically decodes ROS2 messages using reflection
recording_info: Extracts recording metadata such as message counts, start time, and session information
urdf: Uses Rerun's built-in URDF loader when a ROS 2 /robot_description string topic is present

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

The following shows how to select specific decoders:

# Use only specific decoders
rerun mcap convert input.mcap -d protobuf -d stats -o output.rrd

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

# Add robot geometry from robot_description topics
rerun mcap convert input.mcap -d ros2msg -d urdf -o output.rrd

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

Advanced usage

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