Rerun 数据类型详解Utf8Pair 编码类型的定义、Arrow 表示与实战使用【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读本文围绕 Rerun 类型系统中的Utf8Pair编码类型展开详细解析其在 类型定义源文件 中的声明方式、两个必填字段first/second的语义、底层 Arrow Struct 数据布局以及它如何支撑GraphEdge与KeyValuePairs两个高频组件。读完本文你将掌握在 Rust / Python / C 三种 SDK 中构造和传递 Utf8Pair 的实际方法并理解其自动生成的序列化代码的内部原理。一、Utf8Pair 是什么一对 UTF-8 字符串的原子封装Utf8Pair是 Rerun 类型系统re_types_core/re_sdk_types中定义的一种编码类型encoding type其作用非常简单直观存储一对 UTF-8 字符串。根据官方类型文档 utf8pair.md 的描述Stores a tuple of UTF-8 strings.在 Rerun 的架构中编码类型encoding不直接作为用户可见的组件被记录到实体上而是作为组件的内部数据类型存在。Utf8Pair正是两个重要组件的底层数据类型GraphEdge—— 图的边用来描述两个节点之间的有向/无向连接KeyValuePairs—— 键值对列表用来在一条记录中携带任意键值元数据。也就是说你并不会直接log一个Utf8Pair而是在记录图边或键值对时由 SDK 自动构造并序列化它。二、类型定义与字段语义2.1 定义源一份“类型即代码”的 DSLUtf8Pair的规范定义并不在某个手写的 Rust 结构体里而是位于 Rerun 的类型定义 DSL 文件utf8_pair.def.rs/// Stores a tuple of UTF-8 strings. #[rerun::rerun_type] #[python(aliases Tuple[encodings.Utf8Like, encodings.Utf8Like])] #[python(array_aliases npt.NDArray[np.str_])] #[rust(arrow_opt)] #[rust(derive(Default, PartialEq, Eq, PartialOrd, Ord))] #[rerun(state stable)] pub struct Utf8Pair { /// The first string. pub first: rerun::encodings::Utf8, /// The second string. pub second: rerun::encodings::Utf8, }这份文件由re_types_builder解析进而生成 Rust、Python、C 三种语言的绑定生成入口见 crates/build/re_types_builder/src/codegen。几个属性含义如下属性含义#[rerun::rerun_type]标记这是一个 Rerun 数据类型参与代码生成#[python(aliases ...)]Python 侧允许直接传Tuple[str, str]之类的元组作为别名#[rust(arrow_opt)]Rust 侧生成基于Option的 Arrow 序列化实现ToArrowOpt/FromArrowOpt#[rerun(state stable)]该类型的 API 状态为 stable可放心长期依赖2.2 两个必填字段字段类型说明firstnon-nullUtf8第一个字符串secondnon-nullUtf8第二个字符串注意两个字段都是non-null非空这意味着序列化时不允许字段级缺失整个结构体是否为空则由外层 validity mask 控制。字段顺序first→second是稳定的存储与传输都依赖这个固定顺序。三、底层 Arrow 数据布局一个双字段 StructRerun 的数据管道基于 Apache Arrow。Utf8Pair对应的 Arrow 逻辑类型是一个Struct结构体包含两个非空 Utf8 字段Struct( first: non-null Utf8 second: non-null Utf8 )这一点在生成的 Rust 实现中有精确对应。查看自动生成的 utf8pair.rs 中的ArrowDataType实现impl ::re_types_core::ArrowDataType for Utf8Pair { fn arrow_data_type() - arrow::datatypes::DataType { DataType::Struct(Fields::from(vec![ Field::new(first, crate::encodings::Utf8::arrow_data_type(), false), Field::new(second, crate::encodings::Utf8::arrow_data_type(), false), ])) } }Field::new(..., false)的第三个参数即nullable为false与文档中 non-null 的表述完全一致。每个字符串在物理上以 ArrowStringArrayUTF-8 字节缓冲区 offset 数组承载。3.1 序列化ToArrowOpt 实现要点生成代码实现了ToArrowOpt其序列化流程utf8pair.rs值得拆解构造两个字段的Fields元数据将输入的OptionSelf迭代器拆分为somes是否存在的标记与data值本身通过OffsetBuffer::from_lengths按每个字符串字节长度构建 offset 缓冲区用BufferBuilder::u8拼接所有 UTF-8 字节用StringArray::new_unchecked组装两个字符串列最终以StructArray::new(fields, vec![first_col, second_col], validity)输出一个完整 StructArrayvalidity由somes推导。也就是说一个 Utf8Pair 批量序列化时两个字符串列是分别独立压缩存储的外层只维护“这一行是否存在”的有效性位图。3.2 反序列化FromArrowOpt 实现要点反序列化utf8pair.rs则是对称的逆过程将输入try_cast为StructArray按字段名first、second在哈希表中查找子数组缺少任一字段直接返回missing_struct_field错误对应文档中 non-null 约束对每个子数组做StringArray校验与 offset 越界检查offset_slice_oob最后用ZipValidity把两列按行 zip 起来组装出VecOptionUtf8Pair。这保证了从.rrd文件、gRPC 流或其他来源读回的 Arrow 数据都能严格还原成结构化的Utf8Pair。四、便捷构造From 元组转换为提升使用体验Utf8Pair通过扩展文件 utf8pair_ext.rs 提供了从元组的直接转换implT: IntoUtf8 From(T, T) for Utf8Pair { fn from(value: (T, T)) - Self { Self { first: value.0.into(), second: value.1.into() } } } impl From(str, str) for Utf8Pair { /* ... */ }因此 Rust 侧可以直接写(node_a, node_b).into()得到Utf8Pair。同时定义源中的#[python(aliases Tuple[...])]让 Python 侧同样可以传入普通元组。类型整体实现了Default、PartialEq、Eq、PartialOrd、Ord与SizeBytes派生见 utf8pair.rs可参与排序、比较与内存计量。五、实际应用GraphEdge 与 KeyValuePairs5.1 GraphEdge以 Utf8Pair 承载边的两端GraphEdge是一个典型的“薄包装”组件其内部直接就是一个Utf8Pairpub struct GraphEdge(pub crate::encodings::Utf8Pair);源码见 components/graph_edge.rs。first是边的起点、second是终点具体方向语义以GraphEdge组件文档为准。由于GraphEdge实现了DerefTarget Utf8Pair用户代码可以像操作元组一样读取边的两端。在 Rust 中记录一条边rec.log(graph/my_edge, rerun::GraphEdge::from((a, b)))?;5.2 KeyValuePairs以 Utf8Pair 列表表达键值对KeyValuePairs则把一个VecUtf8Pair作为其内部数据每个Utf8Pair即一对(key, value)pub struct KeyValuePairs(pub Veccrate::encodings::Utf8Pair);源码见 components/key_value_pairs.rs。其 Arrow 表示为ListStructfirst: Utf8, second: Utf8序列化时逐元素调用Utf8Pair::to_arrow见 key_value_pairs.rs反序列化时调用Utf8Pair::from_arrow_opt见 key_value_pairs.rs。使用时同样借助From(T, T)的转换能力批量构造let kv rerun::KeyValuePairs::from(vec![ (sensor, lidar), (resolution, 64), ]);5.3 在 Python / C 中的对应用法Pythonrerun.encodings.Utf8Pair接受任意Utf8Likestr 或可转字符串的对象别名Tuple[Utf8Like, Utf8Like]允许直接传(a, b)数组别名支持numpy的NDArray[np.str_]批量构造。对应组件如rerun.components.GraphEdge、rerun.components.KeyValuePairs均可直接以元组列表赋值。Crerun::encodings::Utf8Pair提供rerun::Utf8Pair类型与组件构造函数文档参考 GraphEdge 组件文档。六、在 Rerun 类型体系中的位置Utf8Pair与Angle、Blob、ClassId、Mat3x3、Quaternion、TensorData、ViewCoordinates等并列同属rerun.encodings命名空间模块声明见 encodings/mod.rs。它们共同遵循同一套“DSL 定义 → 代码生成 → Arrow 序列化”的流水线*.def.rs类型 DSL │ re_types_builder 代码生成 ▼ Rust 绑定re_sdk_types Python 绑定rerun_py C 绑定rerun_cpp │ ToArrowOpt / FromArrowOpt ▼ Arrow StructArray / ListArray ──► .rrd 文件 / gRPC 流 / 内存共享如果希望深入了解其兄弟类型可继续阅读 utf8.md单字符串编码以及组件层文档 graph_edge.md 与 key_value_pairs.md。七、总结与注意事项Utf8Pair是稳定stable状态的双字符串编码类型字段first、second均非空其 Arrow 表示为双字段 Struct序列化/反序列化由 utf8pair.rs 自动生成代码实现字段缺失或 offset 越界都会在反序列化阶段报错它不直接用于log而是作为GraphEdge与KeyValuePairs的底层数据载体构造时优先使用(T, T)元组转换代码更简洁类型定义与实现均由re_types_builder从 utf8_pair.def.rs 自动生成手动修改生成文件会被覆盖。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考