Rerun DataFrame 查询入门用 Python 从 RRD 录制中提取前 10 行数据并支持实体路径过滤【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文是 Rerun 开源仓库中 examples/python/dataframe_query 示例的完整技术指南。你将学会如何通过rerun.server.Server在本地启动一个 Rerun 服务、加载任意.rrd录制文件再借助 DataFrame API底层基于 DataFusion以表格形式在终端中查询并展示数据的前 10 行同时掌握实体路径过滤表达式如/helix/structure/**的写法与底层实现原理。读完本文后你既能直接运行示例脚本也能把这套服务端过滤 DataFrame 读取的查询范式迁移到自己的数据处理流程中。一、示例定位终端里的 DataFrame 查询dataframe_query是 Rerun 仓库中用于演示 DataFrame API 基础用法的 Python 示例。它的目标非常聚焦打开一个 Rerun 录制文件.rrd查询其中的数据并把前 10 行以表格形式打印到终端。该示例的完整代码位于 examples/python/dataframe_query/dataframe_query.py核心执行逻辑只有约 30 行非常适合作为理解 Rerun 数据查询 API 的入门入口。其依赖声明在 examples/python/dataframe_query/pyproject.toml 中唯一的运行时依赖是rerun-sdk且同时将dataframe_query注册为可执行脚本入口dataframe_query dataframe_query:main安装后即可直接用命令调用。examples/python/dataframe_query/ ├── README.md # 示例说明文档 ├── dataframe_query.py # 示例主脚本 └── pyproject.toml # 项目配置与依赖声明示例的完整调用形式如下python dataframe_query.py path_to_rrd [entity_path_filter]其中第一个参数path_to_rrd是必填的 RRD 文件路径第二个可选参数entity_path_filter是实体路径过滤表达式默认为/**匹配所有实体。二、获取测试数据下载官方托管示例录制如果没有现成的 Rerun 录制文件可以从 Rerun 官方托管的示例中下载一个。例如下载dnaDNA 双螺旋结构示例的录制curl https://app.rerun.io/version/latest/examples/dna.rrd -o - /tmp/dna.rrd这条命令通过 curl 把远程 RRD 文件直接写入本地/tmp/dna.rrd。dna示例包含/helix/structure等实体路径非常适合用来测试实体路径过滤功能。当然也可以使用你自己通过rr.log系列 API 生成或从其他途径获得的任意 RRD 文件。仓库的 tests/assets/rrd 目录下也存放着大量可用于测试的.rrd录制文件。三、运行示例两种典型用法3.1 查询全部数据的前 10 行直接指定录制文件路径不传过滤表达式此时默认匹配所有实体python dataframe_query.py /tmp/dna.rrd脚本会启动本地服务、加载录制、读取全部实体的数据并将结果以 pandas 表格形式打印前 10 行。3.2 按实体路径过滤后查询第二个参数用于指定实体路径过滤表达式只查询匹配的实体子树。例如只查看 DNA 示例中helix/structure子树下的数据python dataframe_query.py my_recording.rrd /helix/structure/**注意在 Shell 中**有被路径通配展开的风险因此建议像文档示例那样对表达式加引号或直接在字符串参数中使用转义确保过滤表达式原样传给脚本。例如python dataframe_query.py my_recording.rrd /helix/structure/**四、代码逐段拆解三步完成查询dataframe_query.py 的query()函数完整呈现了 Rerun DataFrame 查询的经典三步流程def query(path_to_rrd: str, entity_path_filter: str) - None: with rr.server.Server(datasets{recording: [path_to_rrd]}) as server: dataset server.client().get_dataset(recording) # Query the data view dataset.filter_contents([entity_path_filter]) df view.reader(indexlog_time) # Convert to pandas and show first 10 rows table df.to_pandas() print(table.head(10))4.1 第一步启动本地 Server 并注册数据集with rr.server.Server(datasets{recording: [path_to_rrd]}) as server:rr.server.Server是 Rerun SDK 提供的服务端类位于 rerun_py/rerun_sdk/rerun/server.py它托管录制并通过 HTTP 提供服务客户端连接后可访问 catalog数据目录。作为上下文管理器使用时退出with块会自动关闭服务无需手动清理。构造函数的datasets参数是一个字典键为数据集名称值为路径。从源码server.py第 48-122 行可以看到其取值规则单一路径str/PathLike必须是目录启动时会把目录内所有 RRD 文件都注册为该数据集路径序列list每个路径必须是一个 RRD 文件全部注册为该数据集。示例中datasets{recording: [path_to_rrd]}传入的是单文件列表因此recording数据集只包含这一个录制。其他值得了解的参数host默认0.0.0.0绑定所有网卡便于从其他机器连接查看器、port默认None/0由操作系统随机分配空闲端口可通过server.url()获取实际地址、tables可选加载 Lance 表文件。此外 SDK 还提供了server.client()获取连接本服务的 CatalogClient、server.is_running()检查服务状态、server.shutdown()手动关闭等接口。4.2 第二步获取数据集并构建过滤视图dataset server.client().get_dataset(recording) view dataset.filter_contents([entity_path_filter])server.client()返回一个 CatalogClient需要安装datafusion包否则初始化会报错get_dataset(recording)按名称取回刚注册的数据集DatasetEntry。随后调用DatasetEntry.filter_contents()得到DatasetView。根据 rerun_py/rerun_sdk/rerun/catalog/_entry.py 中的源码注释DatasetView是对数据集分段与实体路径的惰性过滤视图过滤条件会延迟组合直到真正读取数据时才生效——这意味着构建视图本身开销很低可以放心地链式叠加多个过滤条件。4.3 第三步以 log_time 为索引读取 DataFramedf view.reader(indexlog_time) table df.to_pandas() print(table.head(10))view.reader(indexlog_time)返回一个DataFusion DataFrame并以名为log_time的时间轴timeline作为行索引。随后to_pandas()将其转换为 pandas DataFramehead(10)只显示前 10 行。需要说明的是log_time只是该示例选用的索引实际索引名取决于录制中注册的时间轴timeline常见的时间轴还有real_time等。可以按自己的数据选择对应的索引名如view.reader(indexreal_time)。reader()还支持更多进阶参数详见_entry.py第 763-857 行与第 1028-1139 行indexNone只读取静态数据无时间索引的数据include_semantically_empty_columns是否包含语义上为空的列include_tombstone_columns是否包含墓碑删除标记列fill_latest_at是否用最近的有效值填充 nullusing_index_values指定索引值集合进行重采样此时每个(segment, index_value)组合返回一行支持数组、字典按 segment ID 映射或 DataFrame 三种形式。4.4 命令行入口main()使用标准库argparse解析两个位置参数parser.add_argument(path_to_rrd, typestr, helpPath to the .rrd file) parser.add_argument( entity_path_filter, typestr, nargs?, default/**, helpOptional entity path filter expression, )entity_path_filter通过nargs?设为可选缺省值为/**匹配全部实体。同时pyproject.toml中注册了dataframe_query控制台脚本因此安装示例后也可以直接运行dataframe_query /tmp/dna.rrd。五、实体路径过滤表达式详解5.1 表达式语法实体路径过滤表达式以/开头支持通配符**。按 rerun_py/rerun_sdk/rerun/catalog/_content_filter.py 与_entry.py中的文档/points/**匹配/points下的所有实体-/text/**排除/text下的所有实体前缀-表示排除多个表达式可组合成列表传入如[/points/**, -/text/**]表示包含/points/**且排除/text/**传入空列表[]表示过滤掉全部内容。传入字符串时会自动包装成单元素列表见_entry.py第 756-761 行所以单表达式和列表两种写法等价。5.2 ContentFilter 流式构建器除了裸字符串filter_contents()还接受ContentFilter对象。它是不变immutable的流式构建器从everything()等价于/**默认自动排除__properties子树或nothing()等价于空列表出发链式调用.include(path, subtreeFalse)包含匹配路径的实体subtreeTrue时自动追加/**.exclude(path, subtreeFalse)排除匹配路径的实体生成带-前缀的表达式.include_properties()把默认自动排除的__properties/**子树重新包含进来。例如from rerun.catalog import ContentFilter # 排除原始机器人数据但保留其中一条特定路径 view dataset.filter_contents( ContentFilter.everything() .exclude(/robot/raw/**) .include(/robot/raw/i_need_this) ) # 从什么都不含开始只允许指定子树 view dataset.filter_contents( ContentFilter.nothing() .include(/points, subtreeTrue) .include(/world/camera) )_build_path_expr_content_filter.py第 4-9 行会校验路径必须以/开头并在需要时自动追加/**。对于路径片段中包含空格、感叹号等特殊字符的实体还可以用include_path/exclude_path按路径片段列表传入实现自动转义。六、底层原理服务端过滤与 DataFusion示例中filter_contents(...)加reader(index...)的组合背后是 Rerun 的数据查询架构惰性视图filter_contents返回的DatasetView只是记录了过滤表达式并不立即读取数据见_entry.py第 900-926 行的类文档Filters are composed lazily and only applied when data is actually read。DataFusion 即所得reader()直接返回 DataFusion 的datafusion.DataFrame因此view.reader(...)的结果天然支持 DataFusion 的全部能力——filter、select、join、聚合等都可以继续链式调用最后再to_pandas()落入本地。服务端下推过滤_entry.py中reader()与DatasetView.reader()的文档明确说明返回的 DataFrame 对rerun_segment_id和索引列timeline的过滤会在 Rerun 服务端执行可显著提升性能。例如from datafusion import col, lit # 按 segment 过滤服务端执行 dataset.reader(indexreal_time).filter(col(rerun_segment_id) aabbccddee) # 按时间窗口过滤服务端执行 df dataset.reader(indexreal_time).filter( (col(real_time) lit(t0)) (col(real_time) lit(t1)) )换句话说实体路径过滤 分段过滤 索引范围过滤这类重活可以在服务端完成客户端只接收精简后的结果这正是大数据量下保持查询效率的关键。七、运行前提与环境说明Python 版本pyproject.toml中被注释掉的requires-python 3.12提示该示例预期在 Python 3.12 以下版本运行若使用更高版本可能需要按当前 SDK 的约束调整依赖需要rerun-sdk运行client()还需要datafusion包数据需要准备一个.rrd录制文件本地录制或按上文 curl 下载均可过滤表达式Shell 中注意对**加引号防止被通配展开。八、进一步探索如果想把这个示例扩展到更复杂的场景可以从仓库中找到大量现成材料完整 DataFrame 查询 APIDatasetEntry与DatasetView的全部方法filter_segments、segment_table、get_index_ranges、schema、arrow_schema等见 rerun_py/rerun_sdk/rerun/catalog/_entry.py服务端实现与数据集管理Rust 侧相关逻辑集中在 crates/store_app/re_server更多查询用例Python 端集成测试位于 rerun_py/tests/e2e_redap_tests其中包含大量针对 catalog / dataframe 查询链路的断言用例可对照学习参数边界与预期行为。至此你已经掌握了从启动本地服务、注册 RRD、按实体路径过滤、按时间轴读取 DataFrame、输出表格的完整查询链路可以直接把该模式复用到自己的录制数据处理与调试流程中。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考