Rerun segment_url 完全指南在 DataFusion 数据表中生成可点击的 Viewer 段链接【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunRerun 提供 DataFusion 工具函数segment_url可在 Catalog 数据集上按行批量生成可直接在 Viewer 中点击打开的 Rerun URL——每条 URL 都能精确定位到某个 segment并可选地设置时间游标位置、时间范围选中状态或实体选中状态。本文基于当前仓库的官方 howto 文档 docs/content/howto/query-and-transform/segment_url.md 展开结合其配套示例代码、Python 封装与 Rust 底层实现讲解如何从零搭建环境、生成基础 URL以及如何组合时间与选择条件帮助你在数据表DataFrame分析场景中快速落地从数据行直达 Viewer 视图的工作流。背景segment URL 的结构与可点击原理在深入 API 之前先理解segment_url生成的 URL 是什么。Rerun 使用自己的 URL scheme 来跨网络访问信息支持rerunhttp://、rerunhttps://以及rerun://rerun://是rerunhttps://的别名底层基于 gRPC 协议见 crates/store/re_uri/src/lib.rs。一条典型的 segment URL 形如rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_1#selection/camera/rgbwhenreal_time2023-11-14T22:13:20Z它的三个组成部分对应不同的语义源码见 crates/store/re_uri/src/endpoints/dataset.rs组成部分示例作用查询参数?segment_id...?segment_idabc123指定要打开哪个 segment片段#selection...#selection/camera/rgb指定 Viewer 打开后选中哪个实体路径可含实例索引与组件名片段#when...#whenreal_time2023-11-14T22:13:20Z指定激活哪条时间线并把时间游标移动到某个值片段#time_selection...#time_selectionreal_time2023-11-14T22:13:20Z..2023-11-14T22:13:20.5Z指定要选中的时间范围其中#fragment由Fragment结构体建模包含selection、when、time_selection三个可选字段见 crates/store/re_uri/src/fragment.rs。多个片段之间用连接输出顺序固定为selection→when→time_selection见 fragment.rs这正是本文后面各类输出示例中片段顺序的来源。提示本地运行的 Rerun 实例通常没有配置 TLS因此本地环境使用rerunhttp://scheme这意味着底层连接不加密生产/远程环境应使用rerunhttps://。环境准备加载数据集并创建段元数据表segment_url工作在 Catalog 体系之上因此首先需要启动一个本地 Catalog 服务器、加载示例数据并构造一张带段元数据的表。配套的完整示例代码位于 docs/snippets/all/howto/query-and-transform/segment_url.py下面是其 setup 部分from __future__ import annotations from datetime import datetime, timedelta from pathlib import Path import pyarrow as pa from datafusion import lit import rerun as rr from rerun.utilities.datafusion.functions.url_generation import segment_url sample_5_path ( Path(__file__).parents[5] / tests / assets / rrd / sample_5 ) server rr.server.Server(datasets{sample_dataset: sample_5_path}) client server.client() dataset client.get_dataset(namesample_dataset) # Pick 3 deterministic segment IDs and create a view filtered to them segment_ids sorted(dataset.segment_ids())[:3] view dataset.filter_segments(segment_ids) # Build a synthetic metadata table keyed by rerun_segment_id base_time datetime(2023, 11, 14, 22, 13, 20) event_times [base_time timedelta(secondsi) for i in range(3)] meta pa.record_batch( { rerun_segment_id: segment_ids, event_time: pa.array(event_times, typepa.timestamp(ns)), range_start: pa.array(event_times, typepa.timestamp(ns)), range_end: pa.array( [t timedelta(milliseconds500) for t in event_times], typepa.timestamp(ns), ), entity_path: [ /camera/rgb, /observation/joint_positions, /observation/gripper_state, ], }, ) ctx client.ctx meta_df ctx.from_arrow(meta)关键点说明rr.server.Server(datasets{sample_dataset: sample_5_path})启动一个本地 Catalog 服务器并把仓库自带的测试数据sample_5位于 tests/assets/rrd/sample_5注册为名为sample_dataset的数据集dataset.segment_ids()返回数据集内全部 segment ID底层实现见 rerun_py/src/catalog/dataset_entry.rs这里取前 3 个保证输出可复现dataset.filter_segments(segment_ids)得到一个只包含这 3 个 segment 的DatasetView实现见 dataset_entry.rs后续所有segment_table()均基于该视图元数据表meta是一张普通的 Arrow RecordBatch以rerun_segment_id为主键携带事件时间、时间范围起止、实体路径等列通过view.segment_table(join_metameta_df)与段表按rerun_segment_id关联元数据中的时间列使用pa.timestamp(ns)纳秒精度这与 Rerun 内部对 timestamp 的处理一致。基础用法生成最简单的段 URL不传任何额外参数时segment_url(dataset)只为每一行生成打开对应 segment 的基础 URL。此时函数会自动使用名为rerun_segment_id的列作为 segment ID 来源basic view.segment_table().select(rerun_segment_id).sort(rerun_segment_id) basic basic.with_column(url, segment_url(dataset)) for url in basic.select(url).to_pydict()[url]: print(url)输出rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_1 rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_2 rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_3这里DATASET_ID是数据集的 Tuid 标识SEGMENT_ID_*是具体段的 ID。URL 中不包含任何#fragment意味着 Viewer 打开后停留在段默认视图。指定时间游标位置在需要把 Viewer 直接定位到某个时刻时传入timestamp和timeline_namets view.segment_table(join_metameta_df).select( rerun_segment_id, event_time ) ts ts.sort(rerun_segment_id) ts ts.with_column( url, segment_url(dataset, timestampevent_time, timeline_namereal_time), ) for url in ts.select(url).to_pydict()[url]: print(url)输出rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_1#whenreal_time2023-11-14T22:13:20Z rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_2#whenreal_time2023-11-14T22:13:21Z rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_3#whenreal_time2023-11-14T22:13:22Z参数语义timestamp若为字符串会被解释为列名也可以传入任意 DataFusion 表达式包括字面量timeline_name指定 Viewer 要激活的时间线名称。当timestamp传入而timeline_name省略时timeline_name默认取timestamp参数的值——从 Python 封装的实现可见url_generation.py——因此示例中即使不写timeline_namereal_time结果也会是#whenevent_time...。值得注意的是when片段中的时间格式会随时间类型变化timestamp 时间线输出 ISO 8601 格式如2023-11-14T22:13:20Z序列sequence时间线输出整数刻度值。仓库的端到端测试对此有直接验证rerun_py/tests/e2e_redap_tests/test_datafusion_utils.py使用 Int64 列my_seq作为 timestamp 时输出为#whenmy_seq10、#whenmy_seq20等。选择时间范围传入time_range_start和time_range_end必须成对出现并配合timeline_name可生成指定时间范围选中状态的 URLtr view.segment_table(join_metameta_df).select( rerun_segment_id, range_start, range_end ) tr tr.sort(rerun_segment_id) tr tr.with_column( url, segment_url( dataset, time_range_startrange_start, time_range_endrange_end, timeline_namereal_time, ), ) for url in tr.select(url).to_pydict()[url]: print(url)输出rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_1#time_selectionreal_time2023-11-14T22:13:20Z..2023-11-14T22:13:20.5Z rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_2#time_selectionreal_time2023-11-14T22:13:21Z..2023-11-14T22:13:21.5Z rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_3#time_selectionreal_time2023-11-14T22:13:22Z..2023-11-14T22:13:22.5Z时间范围在 fragment 中表达为time_selectiontimelinestart..end。与timestamp一样起止两个参数既可以传列名也可以传 DataFusion 表达式。底层实现会把起止时间构造成TimeSelection含Timeline与AbsoluteTimeRange见 segment_url_udf.rs。约束规则Python 侧与 Rust 侧双重校验time_range_start与time_range_end必须同时提供或同时省略否则抛出ValueErrorPython 侧校验见 url_generation.pyRust 侧 plan 期校验见 segment_url_udf.rs只要涉及时间timestamp或时间范围就必须提供timeline_name否则报错Rust 侧校验见 segment_url_udf.rs。选择实体selection参数用于指定 Viewer 打开后要选中的实体路径、实例和/或组件。值为字符串使用实体路径语法可选地在方括号中追加实例索引并用冒号追加组件名例如/world/points—— 选中实体路径/world/points[#42]—— 选中第 42 个实例/world/points:Color—— 选中该实体上的 Color 组件/world/points[#42]:Color—— 两者同时指定。示例sel view.segment_table(join_metameta_df).select( rerun_segment_id, entity_path ) sel sel.sort(rerun_segment_id) sel sel.with_column(url, segment_url(dataset, selectionentity_path)) for url in sel.select(url).to_pydict()[url]: print(url)输出rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_1#selection/camera/rgb rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_2#selection/observation/joint_positions rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_3#selection/observation/gripper_state底层会把该字符串解析为DataPath并写入Fragment.selection见 segment_url_udf.rs若解析失败字符串不符合实体路径语法查询执行期会返回错误信息例如segment_url: failed to parse selection ...: ...。组合使用时间游标 时间范围 实体选择上述三类特性可以同时使用生成的 URL 会包含所有被指定的 fragment并按selection→when→time_selection的顺序排列combined view.segment_table(join_metameta_df).select( rerun_segment_id, event_time, range_start, range_end, entity_path ) combined combined.sort(rerun_segment_id) combined combined.with_column( url, segment_url( dataset, timestampevent_time, timeline_namereal_time, time_range_startrange_start, time_range_endrange_end, selectionentity_path, ), ) for url in combined.select(url).to_pydict()[url]: print(url)输出rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_1#selection/camera/rgbwhenreal_time2023-11-14T22:13:20Ztime_selectionreal_time2023-11-14T22:13:20Z..2023-11-14T22:13:20.5Z rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_2#selection/observation/joint_positionswhenreal_time2023-11-14T22:13:21Ztime_selectionreal_time2023-11-14T22:13:21Z..2023-11-14T22:13:21.5Z rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_3#selection/observation/gripper_statewhenreal_time2023-11-14T22:13:22Ztime_selectionreal_time2023-11-14T22:13:22Z..2023-11-14T22:13:22.5Z使用 DataFusion 表达式所有接受列名字符串的参数都同样接受任意 DataFusion 表达式。当你想给所有行提供常量值时用lit()最方便也可以构建更复杂的表达式expr view.segment_table(join_metameta_df).select( rerun_segment_id, event_time ) expr expr.sort(rerun_segment_id) expr expr.with_column( url, segment_url( dataset, timestampevent_time, timeline_namereal_time, selectionlit(/camera/rgb), ), ) for url in expr.select(url).to_pydict()[url]: print(url)输出注意所有行的selection都固定为/camera/rgbrerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_1#selection/camera/rgbwhenreal_time2023-11-14T22:13:20Z rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_2#selection/camera/rgbwhenreal_time2023-11-14T22:13:21Z rerunhttp://localhost:51234/dataset/DATASET_ID?segment_idSEGMENT_ID_3#selection/camera/rgbwhenreal_time2023-11-14T22:13:22Z表达式同样适用于segment_id仓库测试中有用segment_idlit(segment_id)把多行绑定到同一个段 ID 的用例test_datafusion_utils.py。参数速查表segment_url的完整签名来自 Python 封装 url_generation.py参数类型默认行为说明datasetDatasetEntry必填目标 Rerun 数据集用于提取 Catalog origin 与数据集 IDsegment_idstr \| Expr \| None使用列rerun_segment_id段 ID 的来源列或表达式timestampstr \| Expr \| None无设置#when时间游标字符串视为列名timeline_namestr \| None缺省时取timestamp的值时间线名称涉及时间参数时必填time_range_startstr \| Expr \| None无时间范围起点须与time_range_end成对time_range_endstr \| Expr \| None无时间范围终点须与time_range_start成对selectionstr \| Expr \| None无实体路径可含[#instance]与:Component需要注意segment_url是一个 Rerun 定制的 DataFusion 标量 UDF使用前需要环境已安装datafusion依赖若缺失调用时会抛出RerunMissingDependencyError单元测试覆盖了该场景见 rerun_py/tests/unit/test_utilities_datafusion.py。底层原理从 Python 表达式到 Rust UDF了解调用链有助于排查问题。整个流程分三层Python 封装层url_generation.py把参数规范化——字符串转col()、默认列名、lit()生成 origin 与 entry_id 标量——然后构造 8 个入参调用 Rust 侧注册的SegmentUrlUdfInternal(origin, entry_id, segment_id, ts_expr, timeline_expr, range_start_expr, range_end_expr, selection_expr)。FFI 桥接层segment_url_udf.rs通过datafusion_ffi的FFI_ScalarUDF把 Rust 实现的ScalarUDF包装成 PyCapsule 暴露给 Python 的ScalarUDF.from_pycapsule。Rust 执行层segment_url_udf.rs这是核心。它做了两件事Plan 期类型校验return_typeL72-L166固定要求 8 个入参origin/segment_id/selection 需可转换为 Utf8entry_id 必须是FixedSizeBinary(16)即 Tuidtimestamp 与时间范围必须是受支持的 Arrow 时间类型或 Null时间范围起止必须同为 Null 或同非 Null涉及时间时 timeline 必须非 Null。执行期逐行生成 URLinvoke_with_argsL168-L340对每行把segment_id解析为SegmentId时间信息解析为(TimelineName, TimeCell)范围构造成TimeSelection选择构造成DataPath最终组装为DatasetUri { origin, dataset_id, resource: Segments, segment_id, fragment }并序列化URI 组装逻辑见 crates/store/re_uri/src/endpoints/dataset.rs。UDF 的签名使用Signature::any(8)L58原因在于参数中存在可选项和多类型列用one_of描述会导致组合爆炸因此改为在执行期自查类型L50-L58 的注释对此有说明。边界行为与注意事项Null 行若某行的 segment ID 为 Null该行 URL 输出 NullL262-L265若时间、时间范围或 selection 列为 Null对应片段会被省略而不是报错。仓库测试中None行都只输出不带对应 fragment 的 URL见 test_datafusion_utils.py 等用例。时间单位timestamp 与范围列既支持pa.timestamp(ns)也支持 Int64作为序列刻度执行时统一 cast 为 Int64 后按TimeType解释L213-L250。timeline 约束只用时间范围而不用timestamp时timeline_name不会自动推断默认值逻辑只针对timestamp必须显式传入url_generation.py。行数一致性UDF 会校验所有数组参数的行数要么为 1标量展开要么一致否则报执行期错误segment_url_udf.rs。测试验证端到端测试覆盖了简单 URL、timestamp、时间范围、selection 及其组合并用占位符替换动态 origin 与数据集 ID 后进行快照比对辅助函数见 rerun_py/tests/e2e_redap_tests/_helpers.py可作为你验证本地输出格式的参考。更轻量的替代如果不走 DataFusion也可以直接用dataset.segment_url(segment_id, timeline, start, end)方法生成单条 URL签名与时间类型推断见 rerun_py/src/catalog/dataset_entry.rs适合逐条构造链接的场景。小结segment_url把在数据表中找到感兴趣的行与在 Viewer 中定位到对应画面无缝衔接起来基础用法一行代码即可为整列 segment 生成可点击链接搭配timestamp、time_range_start/time_range_end与selection还能精确控制 Viewer 打开后的时间游标、时间范围选中与实体选中状态所有参数均支持 DataFusion 表达式便于用lit()注入常量或构建复杂逻辑。理解其背后的DatasetUri/Fragment结构与三层调用链能帮助你在机器人多模态数据、传感器日志等场景中高效调试和验证所生成的链接是否符合预期。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考