Rerun SchemaId 组件详解MCAP Schema 的 16 位唯一标识与跨语言实践【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunSchemaId是 Rerun 数据模型中的一个基础组件它用 16 位无符号整数UInt16为 MCAP 文件内的每个 schema 提供唯一标识是McapSchema原型Archetype的必备字段。本文以 schema_id.md 文档为核心结合仓库中的类型定义、SDK 绑定与示例代码讲解其定义、Arrow 编码、在 MCAP 数据流中的作用以及 Python / Rust / C 三种语言的实战用法。SchemaId 是什么根据组件文档的官方定义A 16-bit unique identifier for a schema within the MCAP file.即MCAP 文件内 schema 的 16 位唯一标识。它解决的核心问题是当一份 MCAP 文件中存在多个 schema例如同时有geometry_msgs/msg/Point和sensor_msgs/msg/Image的消息定义时如何用紧凑的整数低成本地区分它们并让 channel 与 message 快速引用对应的 schema。在类型定义源文件 schema_id.def.rs 中其定义被标记为#[rerun::rerun_type]声明这是一个 Rerun 类型由re_types_builder代码生成器解析用于生成 Rust、Python、C 三套绑定#[python(aliases int)]Python 端允许直接传int#[rust(repr transparent)]Rust 端是透明包装类型零额外内存开销#[rerun(state stable)]组件自身处于 stable 状态注意使用它的McapSchema原型整体仍标记为 unstable见下文。生成后的 Rust 实现位于 schema_id.rs通过WrapperComponenttrait 将SchemaId与底层编码UInt16关联/// **Component**: A 16-bit unique identifier for a schema within the MCAP file. #[derive(Clone, Debug, Copy, PartialEq, Eq, PartialOrd, Ord, ::re_byte_size::SizeBytes)] #[repr(transparent)] pub struct SchemaId(pub crate::encodings::UInt16); impl ::re_types_core::WrapperComponent for SchemaId { type Encoding crate::encodings::UInt16; fn name() - ComponentType { rerun.components.SchemaId.into() } // ... }从源码结构可以推断SchemaId是典型的薄包装组件逻辑上是一个独立的 Rerun 组件类型组件类型名为rerun.components.SchemaId物理上完全复用了UInt16的序列化实现既保持了类型安全又不引入额外存储开销。Rerun 编码与 Arrow 数据类型原文档给出了两层编码信息Rerun 编码UInt16即 16 位无符号整数编码详见 uint16.mdArrow 数据类型UInt16这意味着SchemaId在 Rerun 的列式存储中就是一个原生的 ArrowUInt16数组不做任何二次包装或重编码。Rerun 内部的数据存储re_chunk/re_chunk_store以及通过 Arrow IPC 进行的跨语言传输都直接复用 Arrow 的UInt16物理类型这也是它与ChannelIdchannel 标识、ChannelCountPair共享同一底层编码的原因见 uint16.md 的 Used by 列表。在 Rust 侧由于SchemaId实现了DerefTarget UInt16与FromT: IntoUInt16见 schema_id.rs你可以直接把它当作u16使用例如比较大小、按值排序组件本身也派生Ord或者通过u16::from(schema_id)取出原始值。在 Python 侧生成的绑定 schema_id.py 显示SchemaId直接继承自encodings.UInt16而SchemaIdBatch则是UInt16Batch与ComponentBatchMixin的组合组件类型固定为rerun.components.SchemaIdclass SchemaId(encodings.UInt16, ComponentMixin): **Component**: A 16-bit unique identifier for a schema within the MCAP file. class SchemaIdBatch(encodings.UInt16Batch, ComponentBatchMixin): _COMPONENT_TYPE: str rerun.components.SchemaId在数据模型中的位置McapSchema 的必备字段SchemaId唯一的使用者是McapSchema原型见原文档 Used by 一节。McapSchema描述了 MCAP 文件中消息的结构在 mcap_schema.md 中列出了 4 个必填字段字段组件类型含义idSchemaId文件内唯一标识channel 通过它引用 schema多个 channel 可共享同一 schemanameText人类可读的名称如geometry_msgs/msg/Twist、sensor_msgs/msg/ImageencodingText定义格式常见有protobuf、ros1msg、ros2msg、jsonschema、flatbufferdataBlobschema 定义内容的二进制数据文本格式通常是 UTF-8 编码的文本⚠️ 注意McapSchema原型整体在文档中被标记为unstablemay change significantly in a way that the data wont be backwards compatible可能会以不向后兼容的方式发生重大变化。虽然SchemaId组件本身标记为 stable但在使用McapSchema时仍应预期 API 可能演进。在 Rust 实现 mcap_schema.rs 中id字段的ComponentDescriptor将 archetype 与组件关联起来pub fn descriptor_id() - ComponentDescriptor { static DESCRIPTOR: std::sync::LazyLockComponentDescriptor std::sync::LazyLock::new(|| ComponentDescriptor { archetype: Some(rerun.archetypes.McapSchema.into()), component: McapSchema:id.into(), component_type: Some(rerun.components.SchemaId.into()), }); (*DESCRIPTOR).clone() }也就是说McapSchema:id这一 descriptor 指向的组件类型正是rerun.components.SchemaId。从整体架构看McapSchema/McapChannel/McapMessage三个原型共同还原了 MCAP 文件的schema → channel → message三层结构McapSchema本组件所属的原型描述消息数据结构McapChannel引用 schema 并定义 topic 等通道信息McapMessage实际消息负载遵循对应 schema 的约定。三者配合使用使得 Rerun 可以对 MCAP 这类机器人数据容器中的消息进行结构化解析与可视化本项目定位为 Visualize, query, and stream to train on multimodal robotics data。实战跨语言记录带 SchemaId 的 MCAP Schema官方文档配套了Simple MCAP schema示例见 mcap_schema.md对应的 Python / Rust / C 三份 snippet 都存在于仓库中。Python推荐直接传 intdocs/snippets/all/archetypes/mcap_schema_simple.py 演示了用 ROS2 消息定义格式记录一个 Point schemaid42直接传入整数——这正是#[python(aliases int)]所启用的便捷写法import rerun as rr rr.init(rerun_example_mcap_schema, spawnTrue) # 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( id42, namegeometry_msgs/msg/Point, encodingros2msg, datapoint_schema.encode(utf-8), ), )这里data字段是BlobLike因此文本 schema 需要先.encode(utf-8)转成字节流。Python 生成的McapSchema.__init__签名见 mcap_schema.py要求 4 个字段全部以关键字参数给出。Rustdocs/snippets/all/archetypes/mcap_schema_simple.rs 展示了 Rust 写法McapSchema::new的第一个参数自动IntoSchemaId因此直接传42u16即可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(), ), )?;Cdocs/snippets/all/archetypes/mcap_schema_simple.cpp 展示了 C 写法其中data需要显式包装为rerun::components::Blob#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) ) ); }字段规则小结从 Rust 实现mcap_schema.rs可以确认McapSchema共有4 个 required 组件、0 个 recommended、0 个 optional即id/name/encoding/data全部必填。因此在记录 schema 时id必须在 MCAP 文件范围内唯一且被 channel 引用以指明消息结构单个 schema 可被多个 channel 共享name通常直接使用消息类型名如 ROS2 的geometry_msgs/msg/Pointencoding需与data内容格式匹配如ros2msg对应 ROS2 消息定义文本若只需更新部分字段可基于McapSchema::update_fields()或clear_fields()构建增量而with_id/with_name/with_encoding/with_data提供了链式设置单个字段的能力。小结SchemaId虽然只是一个 16 位整数组件却是 Rerun 解析 MCAP 文件的关键一环它以UInt16编码接入 Arrow 列式存储作为McapSchema的必填字段将 schema 与 channel、message 关联起来。理解它的定义与用法是使用McapSchema/McapChannel/McapMessage家族原型处理 MCAP 机器人数据ROS1/ROS2、protobuf、JSON Schema 等的第一步。更完整的类型清单可查阅 docs/content/reference/types 目录Rust 端类型定义源文件位于 crates/build/re_type_definitions/rerunSDK 生成的实现则分别位于 re_sdk_types 与 rerun_py。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rerun SchemaId 组件详解：MCAP Schema 的 16 位唯一标识与跨语言实践
Rerun SchemaId 组件详解MCAP Schema 的 16 位唯一标识与跨语言实践【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunSchemaId是 Rerun 数据模型中的一个基础组件它用 16 位无符号整数UInt16为 MCAP 文件内的每个 schema 提供唯一标识是McapSchema原型Archetype的必备字段。本文以 schema_id.md 文档为核心结合仓库中的类型定义、SDK 绑定与示例代码讲解其定义、Arrow 编码、在 MCAP 数据流中的作用以及 Python / Rust / C 三种语言的实战用法。SchemaId 是什么根据组件文档的官方定义A 16-bit unique identifier for a schema within the MCAP file.即MCAP 文件内 schema 的 16 位唯一标识。它解决的核心问题是当一份 MCAP 文件中存在多个 schema例如同时有geometry_msgs/msg/Point和sensor_msgs/msg/Image的消息定义时如何用紧凑的整数低成本地区分它们并让 channel 与 message 快速引用对应的 schema。在类型定义源文件 schema_id.def.rs 中其定义被标记为#[rerun::rerun_type]声明这是一个 Rerun 类型由re_types_builder代码生成器解析用于生成 Rust、Python、C 三套绑定#[python(aliases int)]Python 端允许直接传int#[rust(repr transparent)]Rust 端是透明包装类型零额外内存开销#[rerun(state stable)]组件自身处于 stable 状态注意使用它的McapSchema原型整体仍标记为 unstable见下文。生成后的 Rust 实现位于 schema_id.rs通过WrapperComponenttrait 将SchemaId与底层编码UInt16关联/// **Component**: A 16-bit unique identifier for a schema within the MCAP file. #[derive(Clone, Debug, Copy, PartialEq, Eq, PartialOrd, Ord, ::re_byte_size::SizeBytes)] #[repr(transparent)] pub struct SchemaId(pub crate::encodings::UInt16); impl ::re_types_core::WrapperComponent for SchemaId { type Encoding crate::encodings::UInt16; fn name() - ComponentType { rerun.components.SchemaId.into() } // ... }从源码结构可以推断SchemaId是典型的薄包装组件逻辑上是一个独立的 Rerun 组件类型组件类型名为rerun.components.SchemaId物理上完全复用了UInt16的序列化实现既保持了类型安全又不引入额外存储开销。Rerun 编码与 Arrow 数据类型原文档给出了两层编码信息Rerun 编码UInt16即 16 位无符号整数编码详见 uint16.mdArrow 数据类型UInt16这意味着SchemaId在 Rerun 的列式存储中就是一个原生的 ArrowUInt16数组不做任何二次包装或重编码。Rerun 内部的数据存储re_chunk/re_chunk_store以及通过 Arrow IPC 进行的跨语言传输都直接复用 Arrow 的UInt16物理类型这也是它与ChannelIdchannel 标识、ChannelCountPair共享同一底层编码的原因见 uint16.md 的 Used by 列表。在 Rust 侧由于SchemaId实现了DerefTarget UInt16与FromT: IntoUInt16见 schema_id.rs你可以直接把它当作u16使用例如比较大小、按值排序组件本身也派生Ord或者通过u16::from(schema_id)取出原始值。在 Python 侧生成的绑定 schema_id.py 显示SchemaId直接继承自encodings.UInt16而SchemaIdBatch则是UInt16Batch与ComponentBatchMixin的组合组件类型固定为rerun.components.SchemaIdclass SchemaId(encodings.UInt16, ComponentMixin): **Component**: A 16-bit unique identifier for a schema within the MCAP file. class SchemaIdBatch(encodings.UInt16Batch, ComponentBatchMixin): _COMPONENT_TYPE: str rerun.components.SchemaId在数据模型中的位置McapSchema 的必备字段SchemaId唯一的使用者是McapSchema原型见原文档 Used by 一节。McapSchema描述了 MCAP 文件中消息的结构在 mcap_schema.md 中列出了 4 个必填字段字段组件类型含义idSchemaId文件内唯一标识channel 通过它引用 schema多个 channel 可共享同一 schemanameText人类可读的名称如geometry_msgs/msg/Twist、sensor_msgs/msg/ImageencodingText定义格式常见有protobuf、ros1msg、ros2msg、jsonschema、flatbufferdataBlobschema 定义内容的二进制数据文本格式通常是 UTF-8 编码的文本⚠️ 注意McapSchema原型整体在文档中被标记为unstablemay change significantly in a way that the data wont be backwards compatible可能会以不向后兼容的方式发生重大变化。虽然SchemaId组件本身标记为 stable但在使用McapSchema时仍应预期 API 可能演进。在 Rust 实现 mcap_schema.rs 中id字段的ComponentDescriptor将 archetype 与组件关联起来pub fn descriptor_id() - ComponentDescriptor { static DESCRIPTOR: std::sync::LazyLockComponentDescriptor std::sync::LazyLock::new(|| ComponentDescriptor { archetype: Some(rerun.archetypes.McapSchema.into()), component: McapSchema:id.into(), component_type: Some(rerun.components.SchemaId.into()), }); (*DESCRIPTOR).clone() }也就是说McapSchema:id这一 descriptor 指向的组件类型正是rerun.components.SchemaId。从整体架构看McapSchema/McapChannel/McapMessage三个原型共同还原了 MCAP 文件的schema → channel → message三层结构McapSchema本组件所属的原型描述消息数据结构McapChannel引用 schema 并定义 topic 等通道信息McapMessage实际消息负载遵循对应 schema 的约定。三者配合使用使得 Rerun 可以对 MCAP 这类机器人数据容器中的消息进行结构化解析与可视化本项目定位为 Visualize, query, and stream to train on multimodal robotics data。实战跨语言记录带 SchemaId 的 MCAP Schema官方文档配套了Simple MCAP schema示例见 mcap_schema.md对应的 Python / Rust / C 三份 snippet 都存在于仓库中。Python推荐直接传 intdocs/snippets/all/archetypes/mcap_schema_simple.py 演示了用 ROS2 消息定义格式记录一个 Point schemaid42直接传入整数——这正是#[python(aliases int)]所启用的便捷写法import rerun as rr rr.init(rerun_example_mcap_schema, spawnTrue) # 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( id42, namegeometry_msgs/msg/Point, encodingros2msg, datapoint_schema.encode(utf-8), ), )这里data字段是BlobLike因此文本 schema 需要先.encode(utf-8)转成字节流。Python 生成的McapSchema.__init__签名见 mcap_schema.py要求 4 个字段全部以关键字参数给出。Rustdocs/snippets/all/archetypes/mcap_schema_simple.rs 展示了 Rust 写法McapSchema::new的第一个参数自动IntoSchemaId因此直接传42u16即可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(), ), )?;Cdocs/snippets/all/archetypes/mcap_schema_simple.cpp 展示了 C 写法其中data需要显式包装为rerun::components::Blob#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) ) ); }字段规则小结从 Rust 实现mcap_schema.rs可以确认McapSchema共有4 个 required 组件、0 个 recommended、0 个 optional即id/name/encoding/data全部必填。因此在记录 schema 时id必须在 MCAP 文件范围内唯一且被 channel 引用以指明消息结构单个 schema 可被多个 channel 共享name通常直接使用消息类型名如 ROS2 的geometry_msgs/msg/Pointencoding需与data内容格式匹配如ros2msg对应 ROS2 消息定义文本若只需更新部分字段可基于McapSchema::update_fields()或clear_fields()构建增量而with_id/with_name/with_encoding/with_data提供了链式设置单个字段的能力。小结SchemaId虽然只是一个 16 位整数组件却是 Rerun 解析 MCAP 文件的关键一环它以UInt16编码接入 Arrow 列式存储作为McapSchema的必填字段将 schema 与 channel、message 关联起来。理解它的定义与用法是使用McapSchema/McapChannel/McapMessage家族原型处理 MCAP 机器人数据ROS1/ROS2、protobuf、JSON Schema 等的第一步。更完整的类型清单可查阅 docs/content/reference/types 目录Rust 端类型定义源文件位于 crates/build/re_type_definitions/rerunSDK 生成的实现则分别位于 re_sdk_types 与 rerun_py。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考