Rerun GraphEdge 组件详解图数据边定义的 Arrow 编码与跨语言使用【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文以 Rerun 数据模型中的GraphEdge组件为核心讲解图数据中边的表示方式它如何通过Utf8Pair编码用一对 UTF-8 字符串连接两个节点如何以 ArrowStruct数据类型落地存储以及如何在GraphEdges原型archetype中与GraphNodes、GraphType配合在 Python、Rust、C 三端 SDK 中完成有向图与无向图的记录与可视化。读完本文你将掌握GraphEdge的完整定义链路——从类型定义文件到生成代码、再到真实示例的运行方式。GraphEdge用两个节点标识符定义一条边在 Rerun 的图Graph数据模型中节点由GraphNodes原型管理而节点之间的连接关系则由GraphEdge组件描述。官方文档对其的定义只有一句话An edge in a graph connecting two nodes.即连接两个节点的图中一条边。GraphEdge本身不携带坐标、权重或样式信息它只负责回答一个最基础的问题这条边连接了哪两个节点。从类型定义看GraphEdge是一个极简的透明包装结构。在crates/build/re_type_definitions/rerun/components/graph_edge.def.rs中/// An edge in a graph connecting two nodes. #[rerun::rerun_type] #[rust(derive(Default, PartialEq, Eq, PartialOrd, Ord))] #[rust(repr transparent)] #[rerun(state stable)] pub struct GraphEdge { pub edge: rerun::encodings::Utf8Pair, }几个值得注意的细节#[rerun(state stable)]表明该组件已进入稳定状态属于 SDK 对外承诺的稳定类型#[rust(repr transparent)]与#[rust(derive(...))]说明生成的 Rust 绑定是一个透明表示的新类型newtype并自动派生了PartialEq、Eq、PartialOrd、Ord、Default等 trait组件唯一的字段edge是Utf8Pair编码类型即一对 UTF-8 字符串。这种一个组件 一个编码类型的设计是 Rerun 类型系统的典型模式编码encoding类型负责底层的 Arrow 数据布局组件component类型负责语义原型archetype负责把它们组装成可记录的日志对象。Rerun 编码底层是 Utf8PairGraphEdge在 Rerun 中的序列化编码是Utf8Pair见 encoding 文档。Utf8Pair的定义是存储一个 UTF-8 字符串元组包含两个非空字段first类型为non-null Utf8即第一个字符串second类型为non-null Utf8即第二个字符串。需要特别说明的是字段名为first/second只是Utf8Pair这一编码层的通用命名。在GraphEdge的语义层这两个字符串分别对应起始节点from与目标节点to的标识符。节点的标识符可以任意 UTF-8 字符串但必须与GraphNodes中记录的node_ids严格一致否则图中会出现无法对应到节点的悬空边。在docs/content/reference/types/components/graph_edge.md中文档明确给出了GraphEdge的 Arrow 数据类型Struct( first: non-null Utf8 second: non-null Utf8 )Arrow 数据类型一个双字段 StructGraphEdge对应的 Arrow 数据类型是一个双字段 Struct两个字段均非空non-null字段Arrow 类型语义在图中firstUtf8非空边的起始节点标识符secondUtf8非空边的目标节点标识符这一布局是 Rerun 类型系统由定义文件.def.rs经过re_types_builder代码生成器自动翻译而来的。在crates/store/re_sdk_types/src/components/graph_edge.rs自动生成文件中可以看到GraphEdge被生成为#[repr(transparent)] pub struct GraphEdge(pub crate::encodings::Utf8Pair);并实现了WrapperComponenttrait其Encoding关联类型被固定为Utf8Pair组件名称为rerun.components.GraphEdge。同时生成代码还为GraphEdge提供了FromT: IntoUtf8Pair转换因此任何能转换为Utf8Pair的类型如二元组都能直接构造GraphEdgeBorrowUtf8Pair、Deref、DerefMut实现使其在使用体验上几乎等同于直接操作一个Utf8Pair。这就是为什么在 SDK 调用层面你可以直接写GraphEdges::new([(a, b), (b, c)])——字符串二元组会被自动转换为Utf8Pair再包装成GraphEdge最终按 Struct 布局序列化进 Arrow 数组。所在原型GraphEdges 中的角色GraphEdge并不是独立记录的它作为必填组件隶属于GraphEdges原型。GraphEdges的定义见crates/build/re_type_definitions/rerun/archetypes/graph_edges.def.rspub struct GraphEdges { /// A list of node tuples. #[rerun(no_ui_edit)] #[rerun(required)] pub edges: Vecrerun::components::GraphEdge, /// Specifies if the graph is directed or undirected. #[rerun(recommended)] pub graph_type: Optionrerun::components::GraphType, }GraphEdges共包含两个字段这也是生成代码中NUM_COMPONENTS 21 个 required 1 个 recommended 0 个 optional的来源edges必填VecGraphEdge一条边的列表。文档注释将其描述为A list of node tuples节点二元组列表即每条边就是(节点A, 节点B)这样一个节点对。注意#[rerun(no_ui_edit)]表明该字段在 Viewer 界面中不支持直接编辑graph_type推荐OptionGraphType指定图是有向还是无向。如果不提供图默认按无向图处理这一点在graph_edges.md文档与graph_edges.def.rs注释中均有明确说明。GraphType 与有向/无向语义GraphType是一个u8表示的枚举见crates/build/re_type_definitions/rerun/components/graph_type.def.rsUndirected 1且是默认值#[default]——无向边Directed 2——有向边。在 Rust SDK 中GraphEdges额外提供了两个便捷方法见crates/store/re_sdk_types/src/archetypes/graph_edges_ext.rsimpl GraphEdges { pub fn with_undirected_edges(self) - Self { self.with_graph_type(crate::components::GraphType::Undirected) } pub fn with_directed_edges(self) - Self { self.with_graph_type(crate::components::GraphType::Directed) } }因此边的方向性语义完全由GraphType决定GraphEdge本身只负责提供(first, second)节点对在无向图中(a, b)与(b, a)等价在有向图中则代表方向相反的两种连接。跨语言使用Python / Rust / C 三端示例GraphEdge最常见的用法是配合GraphNodes一起记录先用GraphNodes声明节点及其位置再用GraphEdges声明边。仓库在docs/snippets/all/archetypes/下提供了完整的官方示例以下展示无向图与有向图两种写法。Python无向图docs/snippets/all/archetypes/graph_undirected.pyLog a simple undirected graph. import rerun as rr rr.init(rerun_example_graph_undirected, spawnTrue) rr.log( simple, rr.GraphNodes( node_ids[a, b, c], positions[(0.0, 100.0), (-100.0, 0.0), (100.0, 0.0)], labels[A, B, C], ), rr.GraphEdges( edges[(a, b), (b, c), (c, a)], # Optional: graphs are undirected by default. graph_typeundirected, ), )要点GraphEdges的edges参数接收节点标识符二元组列表Python 端会将其转换为Utf8Pair编码的GraphEdge序列graph_typeundirected是可选项——注释明确提示graphs are undirected by default图默认是无向的即使省略此行三个节点a、b、c之间的三条边也会按无向渲染节点标识符a、b、c必须与GraphNodes的node_ids一一对应。Rust有向图docs/snippets/all/archetypes/graph_directed.rs//! Log a simple directed graph. fn main() - Result(), Boxdyn std::error::Error { let rec rerun::RecordingStreamBuilder::new(rerun_example_graph_directed) .spawn()?; rec.log( simple, [ rerun::GraphNodes::new([a, b, c]) .with_positions([(0.0, 100.0), (-100.0, 0.0), (100.0, 0.0)]) .with_labels([A, B, C]) as dyn rerun::AsComponents, rerun::GraphEdges::new([(a, b), (b, c), (c, a)]) .with_directed_edges(), ], )?; Ok(()) }要点GraphEdges::new([(a, b), ...])直接接受字符串二元组数组得益于GraphEdge: FromT: IntoUtf8Pair的自动转换.with_directed_edges()等价于.with_graph_type(GraphType::Directed)将三条边标记为有向边在 Viewer 的 GraphView 中会渲染出方向箭头rec.log可以一次记录多个实现了AsComponents的对象因此GraphNodes与GraphEdges被放在同一个数组中按同一 entity 路径simple记录。C 版本仓库同样提供 C 版本docs/snippets/all/archetypes/graph_undirected.cpp与docs/snippets/all/archetypes/graph_directed.cpp。三者Python/Rust/C在语义上完全一致均遵循GraphNodes定义节点 GraphEdges定义边的模式这也是 round-trip 测试能够跨语言对齐的基础。渲染与查看GraphView 与 DataframeViewGraphEdge所在的原型GraphEdges在官方文档中声明可显示于两种视图见graph_edges.mdGraphView图拓扑渲染视图直接展示节点与边的连接关系是图数据的首选查看方式DataframeView数据表视图将每条GraphEdge以(first, second)两列的形式展开便于检查与导出原始边数据。在类型定义中GraphEdges通过#[docs(category Graph)]、#[docs(view_types GraphView)]以及#[rerun(visualizer GraphEdges)]见graph_edges.def.rs与 GraphView 的GraphEdges可视化器visualizer绑定这也是数据链路中组件 → 原型 → 可视化器三层解耦的体现。内部原理从定义文件到跨语言代码GraphEdge文档头部有一行注释DO NOT EDIT! This file was auto-generated by crates/build/re_types_builder/src/codegen/docs/website.rs。这揭示了整个类型系统的构建流程人类维护类型定义文件.def.rs如 graph_edge.def.rsre_types_builder位于 crates/build/re_types_builder解析定义一次性生成 Rust、Python、C 三端绑定以及本文所见的 Markdown 文档生成的 Rust 绑定落在 crates/store/re_sdk_types/src/components/graph_edge.rs原型代码落在 crates/store/re_sdk_types/src/archetypes/graph_edges.rs文档页面 graph_edge.md 与 utf8pair.md 同样是这一流水线的产物。因此GraphEdge文档中列出的三项 API 参考C 的GraphEdge、Python 的rerun.components.GraphEdge、Rust 的rerun::components::GraphEdge在语义上完全等价只是分别面向三种语言生态的消费者。Utf8Pair编码还被KeyValuePairs组件复用可见其作为通用字符串键值对底层编码的通用性。总结GraphEdge是 Rerun 中定义图中一条边的稳定组件核心信息只有两个节点标识符它的 Rerun 编码是Utf8PairArrow 数据类型为双字段Struct(first: Utf8, second: Utf8)它作为必填组件隶属于GraphEdges原型配合GraphType默认Undirected决定图的有向/无向语义使用上GraphEdges::new([(a, b), ...])的二元组写法在 Python / Rust / C 三端保持一致节点的node_ids必须与GraphNodes对齐完整的定义 → 生成 → 序列化 → 可视化链路可以从 graph_edge.def.rs 出发沿re_types_builder与生成代码逐层追踪再通过graph_undirected.py/graph_directed.rs示例直接运行验证。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考