Rerun McapSchema 实战指南：在 Rerun 中记录与还原 MCAP 消息结构定义

Rerun McapSchema 实战指南：在 Rerun 中记录与还原 MCAP 消息结构定义

【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun

本文围绕 Rerun 数据模型中用于描述 MCAP 文件消息结构的McapSchema类型，讲解其四个必填字段（id、name、encoding、data）的含义与取值规范，结合官方示例给出 Python、Rust、C++ 三种 SDK 的完整记录代码，并深入源码说明该类型与McapChannel、McapMessage之间的配合关系，以及 Rerun 的 MCAP 解码器如何把文件中的 Schema 还原为McapSchema。读完本文，你将能够在自己基于 Rerun 的日志管线中正确构造并记录 MCAP 的 Schema 元数据，并能在 DataframeView 中检索与校验这些定义。

McapSchema是 Rerun 在MCAP文档分类下定义的一个**架构（Archetype）**类型，核心定义位于 crates/build/re_type_definitions/rerun/archetypes/mcap_schema.def.rs，并由re_types_builder自动生成各语言绑定。该类型描述的是 MCAP 容器中消息的结构：Schema 定义了通道（Channel）内消息所使用的数据类型与字段组织方式，是解释消息负载（payload）的"蓝图"；每条通道通过引用 Schema 来声明其消息应该如何解码与理解。

⚠️稳定性说明：与文档一致，该类型当前标注为unstable，可能在后续版本中以不向后兼容的方式发生显著变化。在数据长期存储场景中引用它时需要留意这一风险。

字段定义：一条 Schema 由四个必填字段组成

在类型定义文件 mcap_schema.def.rs 中，McapSchema声明了四个**全部为 required（必填）**的字段，且每个字段都带有no_ui_edit标记（不参与界面编辑）。其生成的 Rust 实现中NUM_COMPONENTS = 4，即 4 个必填、0 个推荐、0 个可选组件（见 mcap_schema.rs）。

其中id在 Python 绑定中对应的编码类型为encodings.UInt16Like，name与encoding为Utf8Like，data为BlobLike（见 mcap_schema.py）。Rust 侧同样通过new(id, name, encoding, data)构造器完成四个字段的序列化，并提供with_id/with_name/with_encoding/with_data以及对应的with_many_*批量写入方法，配合columns/columns_of_unit_batches可将组件数据按列（columnar）发送（见 mcap_schema.rs）。

encoding 取值规范：五种常见 Schema 格式

encoding字段声明data中 Schema 定义的格式。根据类型定义源码 mcap_schema.def.rs 及生成的 Rust/Python 文档注释，常见取值包括：

这与 MCAP 官方规范注册表中的格式约定一一对应。实际解码时，Rerun 的 MCAP 读取模块re_mcap提供了protobuf、ros2等解码器（见 crates/data_flow/re_mcap/src/decoders/mod.rs 及 decoders/protobuf.rs、decoders/ros2.rs），schema 中声明的 encoding 决定了后续消息负载按哪种解析器处理。

与 McapChannel、McapMessage 的关系

McapSchema并不是孤立存在的，它与 MCAP 家族的另外两个类型构成"三层结构"：

• McapChannel：通道定义，引用 Schema 来声明其消息结构；
• McapSchema：Schema 定义（本文主题），被通道引用；
• McapMessage：实际消息，遵循通道引用的 Schema 所规定的结构。

即：Channel 引用 Schema，Message 遵循 Schema。一份 Schema 可以被多条 Channel 共享。这种引用关系在 Rerun 的 MCAP 导入链路中被真实执行：McapSchemaDecoder在遍历 MCAP 文件的通道时，会把每条通道及其关联的 Schema 一并还原为McapChannel与McapSchema组件批次，写入以 topic 命名的静态 Chunk 中（见 crates/data_flow/re_mcap/src/decoders/schema.rs）：

components.extend( McapSchema::update_fields() .with_name(schema.name.clone()) .with_id(schema.id) .with_encoding(schema.encoding.clone()) .with_data(schema.data.clone().into_owned()) .as_serialized_batches(), );

从源码结构可以推断：导入 MCAP 文件时，Rerun 会将"通道 + 其 Schema"作为同一份静态元数据记录（TimePoint::STATIC），从而让后续的通道消息能够依据 Schema 解码。

完整示例：记录一个简单的 ROS2 消息 Schema

文档给出官方示例mcap_schema_simple（对应三个语言实现： mcap_schema_simple.rs、mcap_schema_simple.py、mcap_schema_simple.cpp，并已生成可回放的 mcap_schema_simple.rrd）。下面给出三种 SDK 的完整可运行代码。

Python

"""Log a simple MCAP schema definition.""" import rerun as rr rr.init("rerun_example_mcap_schema", spawn=True) # Example ROS2 message definition for a simple Point message point_schema = """float64 x float64 y float64 z""" rr.log( "mcap/schemas/geometry_point", rr.McapSchema( id=42, name="geometry_msgs/msg/Point", encoding="ros2msg", data=point_schema.encode("utf-8"), ), )

Rust

//! Log a simple MCAP schema definition. fn main() -> Result<(), Box<dyn std::error::Error>> { let rec = rerun::RecordingStreamBuilder::new("rerun_example_mcap_schema") .spawn()?; // Example ROS2 message definition for a simple Point message let point_schema = "float64 x\nfloat64 y\nfloat64 z"; rec.log( "mcap/schemas/geometry_point", &rerun::McapSchema::new( 42, "geometry_msgs/msg/Point", "ros2msg", point_schema.as_bytes(), ), )?; Ok(()) }

C++

// Log a simple MCAP schema definition. #include <rerun.hpp> #include <string> int main(int argc, char* argv[]) { const auto rec = rerun::RecordingStream("rerun_example_mcap_schema"); rec.spawn().exit_on_failure(); // Example ROS2 message definition for a simple Point message const std::string point_schema = "float64 x\nfloat64 y\nfloat64 z"; rec.log( "mcap/schemas/geometry_point", rerun::archetypes::McapSchema( 42, "geometry_msgs/msg/Point", "ros2msg", rerun::components::Blob(point_schema) ) ); }

三个示例的共同要点：

1. 实体路径建议：示例统一使用mcap/schemas/<name>作为实体路径（mcap/schemas/geometry_point），便于在数据中集中组织 Schema 元数据；
2. data的传参方式：Python 需显式encode("utf-8")将文本转为字节；Rust 用as_bytes()；C++ 则直接以字符串构造rerun::components::Blob——这与data字段的Blob组件类型保持一致，文本类 Schema 一律按 UTF-8 字节序列传入；
3. id的选取：示例中id=42为任意唯一整数。按 MCAP 规范，Schema ID 必须在文件内唯一，且由 Channel 引用，实际使用时建议与通道引用的 ID 保持一致。

在 DataframeView 中查看 Schema

文档说明McapSchema可以在 DataframeView 中展示。由于该类型未绑定可视化器（类型定义中带有visualizer_none标记，见 mcap_schema.def.rs），它主要用于以数据表形式检索、核对消息结构元数据，而不是在 2D/3D 视图中直接渲染。你可以在 DataframeView 中按实体路径（如mcap/schemas/geometry_point）过滤出 Schema 记录，逐条检查id、name、encoding与data四个列，验证导入的 MCAP 文件中的 Schema 定义是否完整、编码是否与消息负载匹配。

源码速览与后续深入

• 类型定义源（SDK 绑定由它生成）：crates/build/re_type_definitions/rerun/archetypes/mcap_schema.def.rs
• Rust 生成实现：crates/store/re_sdk_types/src/archetypes/mcap_schema.rs
• Python 生成实现：rerun_py/rerun_sdk/rerun/archetypes/mcap_schema.py
• C++ 头文件实现：rerun_cpp/src/rerun/archetypes/mcap_schema.hpp 与 mcap_schema.cpp
• 官方示例（三种语言）：docs/snippets/all/archetypes/mcap_schema_simple.rs、mcap_schema_simple.py、mcap_schema_simple.cpp
• MCAP 导入解码器（还原 Schema 的底层实现）：crates/data_flow/re_mcap/src/decoders/schema.rs
• 关联类型：McapChannel、McapMessage
• 字段组件：SchemaId、Text、Blob

如需了解完整的 MCAP 容器格式语义（如 Schema ID 唯一性、Channel 引用规则、注册表中各 encoding 的规范），可进一步阅读 MCAP 官方规范；而 Rerun 侧的完整类型参考则以 reference 文档目录 中的对应页面为准。

【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun