Rerun

Working with MCAP

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

Supported message formats 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 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.
  • message_log_time and message_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
  • ros2_reflection: Automatically decodes ROS2 messages using reflection
  • 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.

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