rerun-mcap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rerun MCAP ingestion

Rerun MCAP 导入

McapReader

turns an MCAP file into a lazy chunk stream: one entity per topic at the topic's path, message payloads decoded by pluggable decoders. This skill covers the reader's options, what each topic becomes, and the failure modes that yield an empty stream with no error. Stream mechanics (filter, drop, lenses, merge, write) are in

rerun-chunk-processing

McapReader

可将 MCAP 文件转换为惰性块流：每个主题对应一个实体（位于主题路径下），消息负载通过可插拔解码器解码。本技能介绍了该阅读器的选项、各主题的转换结果，以及导致流为空且无错误提示的故障模式。流机制（过滤、丢弃、透镜、合并、写入）相关内容请参考

rerun-chunk-processing

。

The API

API 说明

python

from rerun.experimental import McapReader

reader = McapReader(mcap_path)  # see help(McapReader) for the full option set
stream = reader.stream()

A URDF embedded in the MCAP can be ingested as well (then see

rerun-urdf

python

from rerun.experimental import McapReader

reader = McapReader(mcap_path)  # 查看 help(McapReader) 获取完整选项列表
stream = reader.stream()

MCAP 中嵌入的 URDF 文件也可被导入（相关内容请参考

rerun-urdf

）。

What a topic becomes

主题的转换规则

With the default decoders (

decoders=None

), the message schema name decides what a topic becomes — pass archetypes through, lens only the raw
:message
topics:

MCAP schema name	decodes to	what to do
`foxglove.FrameTransforms`	`Transform3D`	pass through; do not hand-build
`foxglove.CameraCalibration`	`Pinhole`	pass through
`foxglove.CompressedVideo`	`VideoStream` (real sample bytes) + `CoordinateFrame`	pass through
other `foxglove.*` well-known types	the matching archetype	pass through
ros2 well-known types ( `ros2msg` / `ros2_reflection` )	archetype	pass through
your own `schemas.proto.*` / custom protobuf	one `<schema.name>:message` struct	attach semantics with a `DeriveLens` + `Selector`

So a camera topic already arrives as

Pinhole

, its video as

VideoStream

, and a

frame_transforms

topic as

Transform3D

— only custom messages (e.g. a custom joint states schema, a custom gripper status enum) come through reflection or raw only and need lenses.

The

foxglove

decoder does the schema→archetype mapping; because foxglove messages are protobuf-encoded it rides on the

protobuf

decoder, so keep

decoders=None

(verified:

decoders=["protobuf"]

alone leaves

foxglove.CameraCalibration

a raw

:message

; adding

foxglove

makes it a

Pinhole

). Confirm on your file:

McapReader(path).stream()

, then read

McapSchema:name

and a few

Chunk.format()

before deciding anything is missing or needs rebuilding.

Entity path = topic name (

/sensors/joint_states

stays

/sensors/joint_states

). Filter early:

McapReader(path).stream().filter(content="/sensors/**")

A reflection-decoded message lands as one struct component named
```
<fully.qualified.MessageName>:message
```
. Navigate it with
```
Selector
```
(
```
Selector(".joint_positions")
```
) inside lenses; this is how custom messages get Rerun semantics attached (see the DeriveLens patterns in
```
rerun-chunk-processing
```
).
Topic regexes use RE2 syntax and are not anchored:
```
cam
```
matches
```
/external/cam_low
```
and
```
/camera_info
```
. Anchor explicitly (
```
^/external/cam
```
) when it matters. Prefer reader-level topic filtering over
```
.filter(...)
```
when you can, so excluded topics are never decoded at all.

使用默认解码器（

decoders=None

）时，消息模式名称决定主题的转换结果——直接传递原型，仅对原始
:message
主题应用透镜：

MCAP 模式名称	解码为	处理方式
`foxglove.FrameTransforms`	`Transform3D`	直接传递；请勿手动构建
`foxglove.CameraCalibration`	`Pinhole`	直接传递
`foxglove.CompressedVideo`	`VideoStream` （真实采样字节） + `CoordinateFrame`	直接传递
其他 `foxglove.*` 知名类型	匹配的原型	直接传递
ros2 知名类型（ `ros2msg` / `ros2_reflection` ）	原型	直接传递
自定义 `schemas.proto.*` / 自定义 protobuf	单个 `<schema.name>:message` 结构体	通过 `DeriveLens` + `Selector` 添加语义

因此，相机主题会直接转换为

Pinhole

，视频主题转换为

VideoStream

，

frame_transforms

主题转换为

Transform3D

——只有自定义消息（如自定义关节状态模式、自定义夹爪状态枚举）会通过反射或仅以原始形式传递，需要使用透镜处理。

foxglove

解码器负责模式→原型的映射；由于 foxglove 消息采用 protobuf 编码，它依赖于

protobuf

解码器，因此请保持

decoders=None

（已验证：仅设置

decoders=["protobuf"]

会使

foxglove.CameraCalibration

保持为原始

:message

；添加

foxglove

解码器后会转换为

Pinhole

）。请在你的文件上验证：执行

McapReader(path).stream()

，然后查看

McapSchema:name

和部分

Chunk.format()

，再判断是否有内容缺失或需要重新构建。

实体路径 = 主题名称（

/sensors/joint_states

保持为

/sensors/joint_states

）。尽早过滤：

McapReader(path).stream().filter(content="/sensors/**")

。

反射解码的消息会作为一个名为
```
<fully.qualified.MessageName>:message
```
的结构体组件存在。使用透镜内的
```
Selector
```
（如
```
Selector(".joint_positions")
```
）进行导航；这是为自定义消息添加 Rerun 语义的方式（请参考
```
rerun-chunk-processing
```
中的 DeriveLens 模式）。
主题正则表达式采用 RE2 语法，且未锚定：
```
cam
```
会匹配
```
/external/cam_low
```
和
```
/camera_info
```
。必要时请显式锚定（如
```
^/external/cam
```
）。如果可以，优先在阅读器层面进行主题过滤，而非使用
```
.filter(...)
```
，这样被排除的主题根本不会被解码。

When to use the low-level

mcap

package instead

何时改用底层

mcap

包

McapReader

keeps payloads in columnar chunk streams; that is almost always what you want. Drop to

mcap.reader.make_reader

only when you need raw record metadata without payloads, or when you need to rewrite the container itself (re-registering schemas, channels, and messages).

McapReader

将负载保存在列式块流中；这几乎是所有场景的最优选择。仅当你需要不带负载的原始记录元数据，或者需要重写容器本身（重新注册模式、通道和消息）时，才使用

mcap.reader.make_reader

。

Gotchas

注意事项

Empty stream, no error: a topic regex that matched nothing, or a channel whose decoder produced no rows. Check
```
Chunk.format()
```
on a few chunks of
```
reader.stream().to_chunks()
```
against a tiny test file, or compare topic names with the
```
mcap
```
CLI / package first.
Topic regexes are unanchored RE2; excludes run after includes.
```
timeline_type="timestamp"
```
interprets MCAP log times as wall-clock ns since epoch. If the recording's clock is wrong, fix it at the reader with
```
timestamp_offset_ns
```
rather than mutating timestamps downstream.
Decoder subsets silently skip topics no decoder claims; when a topic is missing, retry with
```
decoders=None
```
to rule out decoder selection.
Example fix-lenses are dataset-specific. Before copying a
```
MutateLens
```
like the
```
Pinhole:resolution
```
swap from the
```
robot_data_preprocessing
```
example, read the raw component from
```
McapReader(path).stream()
```
and confirm the defect exists in your data — applied blindly it corrupts correct calibration (a correct 648×480 flipped to 480×648).
```
foxglove
```
derives both the camera's
```
Pinhole:child_frame
```
and the video's
```
CoordinateFrame:frame
```
from each message's
```
.frame_id
```
(plus an image-plane suffix), so they match when the calibration and video topics share a
```
frame_id
```
. Only when those topics carry different
```
frame_id
```
s does the video frame diverge and orphan the video from its image plane — re-home it then with a per-camera
```
MutateLens
```
on
```
CoordinateFrame:frame
```
.

流为空但无错误：主题正则表达式未匹配到任何内容，或通道的解码器未生成任何行。请针对小型测试文件，检查
```
reader.stream().to_chunks()
```
的部分块的
```
Chunk.format()
```
，或先通过
```
mcap
```
CLI / 包对比主题名称。
主题正则表达式是未锚定的 RE2；排除规则在包含规则之后执行。
```
timeline_type="timestamp"
```
将 MCAP 日志时间解释为自 epoch 以来的 wall-clock 纳秒。如果录制的时钟有误，请在阅读器层面使用
```
timestamp_offset_ns
```
修正，而非在下游修改时间戳。
解码器子集会静默跳过无解码器认领的主题；当主题缺失时，请重试设置
```
decoders=None
```
，以排除解码器选择的问题。
示例修复透镜是特定于数据集的。在复制
```
robot_data_preprocessing
```
示例中的
```
MutateLens
```
（如
```
Pinhole:resolution
```
交换）之前，请从
```
McapReader(path).stream()
```
读取原始组件，确认你的数据中存在该问题——盲目应用会损坏正确的校准（如将正确的 648×480 翻转成 480×648）。
```
foxglove
```
从每条消息的
```
.frame_id
```
（加上图像平面后缀）派生相机的
```
Pinhole:child_frame
```
和视频的
```
CoordinateFrame:frame
```
，因此当校准和视频主题共享同一个
```
frame_id
```
时，二者会匹配。只有当这些主题携带不同的
```
frame_id
```
时，视频帧才会偏离并与图像平面脱节——此时需要针对每个相机在
```
CoordinateFrame:frame
```
上使用
```
MutateLens
```
重新关联。

References

参考资料

End-to-end MCAP pipeline:

https://github.com/rerun-io/rerun/tree/main/examples/python/robot_data_preprocessing

```
rerun-chunk-processing
```
(stream/lens mechanics),
```
rerun-urdf
```
(FK from joint-state topics),
```
rerun-data-model
```
(modeling decisions)

端到端 MCAP 流水线：

https://github.com/rerun-io/rerun/tree/main/examples/python/robot_data_preprocessing

```
rerun-chunk-processing
```
（流/透镜机制）、
```
rerun-urdf
```
（关节状态主题的正向运动学）、
```
rerun-data-model
```
（建模规则）