Rerun 日志文件加载实战用 Importer 机制一行代码导入任意文件【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读本篇文章围绕 Rerun 官方示例 examples/python/log_file/README.md 展开系统讲解如何通过 Python SDK 的log_file_from_path/log_file_from_contents两个 API借助 Rerun 的Importer导入器机制将磁盘上任意 Rerun 能理解的文件RRD、MCAP、Parquet、URDF、图像等直接注入当前可视化会话。读完本文你将掌握这两种 API 的完整签名、参数语义、运行方式以及它们背后从 Python 绑定到 Rust 底层re_importer的完整调用链能够在自己项目中用最短代码完成打开任意文件的日志记录。示例概览一行 Python 加载任意文件示例的全部逻辑浓缩在 examples/python/log_file/log_file.py 中遍历命令行传入的文件路径对每个文件调用一次 Rerun SDK 的日志 API即可让 Viewer 理解并可视化该文件内容。for filepath in args.filepaths: if not args.from_contents: # 方式一直接传入文件路径 rr.log_file_from_path(filepath, entity_path_prefixlog_file_example) else: # 方式二文件内容已在内存中时直接传入字节 try: with open(filepath, rb) as file: rr.log_file_from_contents(filepath, file.read(), entity_path_prefixlog_file_example) except Exception: pass运行方式README 给出了标准的启动命令在仓库根目录执行python examples/python/log_file/log_file.py examples/assets其中examples/assets目录内置了多种示例资源如example.rrd、example.png、example.glb、example.ply、example.obj、example.txt等见 examples/assets运行后 Viewer 会把这些文件逐一分发到对应的 Importer 进行解析并可视化。命令执行前需先安装 SDKpip install rerun-sdk命令行参数结构示例脚本的参数分为两层通过rr.script_add_args(parser)注入的 Rerun SDK 标准参数如连接/保存选项、--serve等再由rr.script_setup(args, rerun_example_log_file)完成会话初始化与配置最后用rr.script_teardown(args)收尾——这也是所有官方示例的标准三段式写法示例自定义参数--from-contents切换为按内容记录模式仅适用于常规文件外部加载器不支持filepaths位置参数nargs一个或多个待加载文件的路径。核心 APIlog_file_from_path与log_file_from_contents两个 API 的权威实现位于 rerun_py/rerun_sdk/rerun/_log.py#L220-L319类型签名见 rerun_py/rerun_bindings/rerun_bindings.pyi#L911-L926。def log_file_from_path( file_path: str | Path, *, entity_path_prefix: str | None None, static: bool False, recording: RecordingStream | None None, ) - None def log_file_from_contents( file_path: str | Path, file_contents: bytes, *, entity_path_prefix: str | None None, static: bool False, recording: RecordingStream | None None, ) - None参数详解参数类型默认值说明file_pathstr \| Path必填待记录文件的路径log_file_from_contents中用于标识内容来源的文件名file_contentsbytes必填仅 contents 版本已读入内存的文件原始字节entity_path_prefixstr \| NoneNone日志实体路径的前缀便于将导入内容统一归入指定命名空间staticboolFalse为True时组件作为静态数据记录无时间关联、在所有时间线上存在、无条件遮蔽同类型时序数据为False时自动打上log_time以及启用时的log_tick时间戳同时也会带上通过 [rerun.set_time] 设置的其他时间线recordingRecordingStream \| NoneNone指定使用的 RecordingStream不传时使用当前激活的数据记录参见 [rerun.init]、[rerun.set_global_data_recording]两种 API 的取舍log_file_from_path直接把文件路径交给 Importer 框架。适合文件尚在磁盘、无需改动原始数据的场景也是默认推荐方式log_file_from_contents当你已经以二进制形式持有文件内容如从网络、数据库、内存流中拿到数据时直接传入字节即可避免先落盘再读取。示例注释特别强调该方式仅适用于常规文件外部加载器external loaders不支持。两者语义一致一个路径可能被多个 Importer 同时处理调用会阻塞直到至少一个 Importer 开始向数据流推送数据或所有 Importer 均失败。底层原理从 Python 到 Rust 的完整调用链Python 层函数只是薄封装实际工作发生在 Rust 端。1. Python 绑定层_log.py中的两个函数分别调用绑定接口bindings.log_file_from_path(...)/bindings.log_file_from_contents(...)将Path、entity_path_prefix、static_、recording转换为原生PyRecordingStream透传给rerun_py的 pyo3 绑定最终落到 crates/top/re_sdk/src/recording_stream.rs#L1455-L1482 的RecordingStream::log_file_from_path/log_file_from_contents两个方法均在importersfeature 下编译。2. 统一的log_file内部实现两条路径汇合到私有方法log_filerecording_stream.rs#L1488-L1589核心步骤为校验初始化状态若 RecordingStream 尚未正确初始化无store_info打印告警并直接返回构造日志通道通过re_log_channel::log_channel(LogSource::File { path })建立一条异步数据管道组装 ImporterSettings携带当前 recording 的application_id、recording_id、entity_path_prefix、时间点等上下文当staticfalse时会在当前线程的所有时间线上采集当前时刻并递增log_tick序号即使未启用log_tick也会递增分发导入按是否提供内容分别调用re_importer::import_from_file_contents(...)或re_importer::import_from_path(...)FileSource::Sdk后台消费单独启动一个线程线程名形如log_file_from_path(...)不断从通道接收LogMsg并调用record_msg写入当前 recording句柄被存入importer_handles统一管理。源码注释明确此调用会阻塞直到至少一个 Importer 开始流式输出或全部失败正是通道两端同步等待的结果。3. 外部导入器协议re_importer还支持发现系统中的外部导入器ExternalImporter见 crates/data_flow/re_importer/src/importer_external.rs。外部导入器会以子进程方式被调用并接收一组约定好的 CLI 参数crates/data_flow/re_importer/src/lib.rs#L106-L116例如--application-id application_id--recording-id store_id--entity-path-prefix entity_path_prefix若设置--static当时间点为 timeless 时--time_sequence timeline1seq1 timeline2seq2 ...--time_timestamp_nanos timeline1ts1 timeline2ts2 ...自 epoch 起的纳秒Importer 生态仓库内置了哪些导入器从 crates/data_flow/re_importer/src/lib.rs#L19-L58 可以看到当前仓库注册的导入器集合它们共同构成了打开任意文件的能力矩阵导入器源码模块处理的输入RrdImporterimporter_rrd.rsRerun 原生 RRD 录制文件McapImporterimporter_mcapMCAP 格式ROS 生态常见需mcapfeatureweb 端不可用ParquetImporterimporter_parquet.rsParquet 列式数据需parquetfeature非 wasmLeRobotDatasetImporterimporter_lerobot.rsLeRobot 机器人数据集目录需lerobotfeature非 wasmUrdfImporterimporter_urdfURDF 机器人模型描述文件需urdffeatureDirectoryImporterimporter_directory.rs目录这解释了示例可以传入examples/assets目录的原因ArchetypeImporterimporter_archetype.rs通用 archetype 数据ExternalImporterimporter_external.rs外部可执行导入器非 wasm此外MCAP 导入器还支持通过FOXGLOVE_LENSES_IDENTIFIERfoxglove与URDF_DECODER_IDENTIFIERurdf启用 Foxglove lenses 与从robot_description话题提取 URDF 的解码能力lib.rs#L67-L92。源码级验证官方测试与跨语言绑定仓库提供了针对该能力的测试与多语言绑定可作为正确用法的权威参考Rust 测试crates/top/re_sdk/tests/log_file.rs#L47-L69 中log_file_from_path_retargets_blueprint_to_current_application验证了一个重要行为通过log_file_from_path导入的 RRD 文件中的 blueprint会被重定向到当前 recording 的应用保证导入的蓝图与当前会话一致C 绑定crates/top/rerun_c/src/lib.rs#L1193-L1273 提供了rr_recording_stream_log_file_from_path/rr_recording_stream_log_file_from_contents两个 C API与 Python/Rust 签名一一对应说明该能力是 SDK 层的通用能力而非 Python 独有Rust SDK 文档recording_stream.rs#L1447-L1482 对两个方法给出了与 Python 侧一致的语义说明可作为跨语言的行为契约。使用建议与注意事项目录与文件皆可filepaths可以同时混传文件和目录如官方命令直接传入examples/assets目录由DirectoryImporter递归处理后分发到具体文件导入器命名空间隔离为每个文件传入不同的entity_path_prefix可避免多个文件在实体树中互相覆盖示例统一使用log_file_example前缀静态 vs 时序数据机器人数据通常带时间轴保持默认staticFalse以保留时间线信息只有无时间概念的数据才考虑staticTrue外部加载器限制--from-contents模式对外部加载器不适用若依赖外部导入器请优先走路径模式阻塞语义调用会阻塞到至少一个 Importer 开始推送数据或全部失败适合在初始化阶段同步调用避免在热路径中使用平台限制MCAP、Parquet、LeRobot、外部导入器在 wasm/web 目标下不可用桌面端native功能最全见 re_importer/src/lib.rs 各 feature 的cfg标注。小结通过rr.log_file_from_path/rr.log_file_from_contentsRerun 把打开任意文件收敛为一次 API 调用Python 侧两个函数透传给 Rust 端RecordingStream::log_file由re_importer依据文件类型分派到 RRD、MCAP、Parquet、URDF、LeRobot 等内置导入器或外部导入器并通过后台线程把解析结果流式写入当前 recording。无论你是在写数据回放工具、加载机器人数据集还是快速预览录制的日志文件都可以直接复用示例 log_file.py 的模式把文件加载逻辑压缩到几行代码之内。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Rerun 日志文件加载实战：用 Importer 机制一行代码导入任意文件
Rerun 日志文件加载实战用 Importer 机制一行代码导入任意文件【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读本篇文章围绕 Rerun 官方示例 examples/python/log_file/README.md 展开系统讲解如何通过 Python SDK 的log_file_from_path/log_file_from_contents两个 API借助 Rerun 的Importer导入器机制将磁盘上任意 Rerun 能理解的文件RRD、MCAP、Parquet、URDF、图像等直接注入当前可视化会话。读完本文你将掌握这两种 API 的完整签名、参数语义、运行方式以及它们背后从 Python 绑定到 Rust 底层re_importer的完整调用链能够在自己项目中用最短代码完成打开任意文件的日志记录。示例概览一行 Python 加载任意文件示例的全部逻辑浓缩在 examples/python/log_file/log_file.py 中遍历命令行传入的文件路径对每个文件调用一次 Rerun SDK 的日志 API即可让 Viewer 理解并可视化该文件内容。for filepath in args.filepaths: if not args.from_contents: # 方式一直接传入文件路径 rr.log_file_from_path(filepath, entity_path_prefixlog_file_example) else: # 方式二文件内容已在内存中时直接传入字节 try: with open(filepath, rb) as file: rr.log_file_from_contents(filepath, file.read(), entity_path_prefixlog_file_example) except Exception: pass运行方式README 给出了标准的启动命令在仓库根目录执行python examples/python/log_file/log_file.py examples/assets其中examples/assets目录内置了多种示例资源如example.rrd、example.png、example.glb、example.ply、example.obj、example.txt等见 examples/assets运行后 Viewer 会把这些文件逐一分发到对应的 Importer 进行解析并可视化。命令执行前需先安装 SDKpip install rerun-sdk命令行参数结构示例脚本的参数分为两层通过rr.script_add_args(parser)注入的 Rerun SDK 标准参数如连接/保存选项、--serve等再由rr.script_setup(args, rerun_example_log_file)完成会话初始化与配置最后用rr.script_teardown(args)收尾——这也是所有官方示例的标准三段式写法示例自定义参数--from-contents切换为按内容记录模式仅适用于常规文件外部加载器不支持filepaths位置参数nargs一个或多个待加载文件的路径。核心 APIlog_file_from_path与log_file_from_contents两个 API 的权威实现位于 rerun_py/rerun_sdk/rerun/_log.py#L220-L319类型签名见 rerun_py/rerun_bindings/rerun_bindings.pyi#L911-L926。def log_file_from_path( file_path: str | Path, *, entity_path_prefix: str | None None, static: bool False, recording: RecordingStream | None None, ) - None def log_file_from_contents( file_path: str | Path, file_contents: bytes, *, entity_path_prefix: str | None None, static: bool False, recording: RecordingStream | None None, ) - None参数详解参数类型默认值说明file_pathstr \| Path必填待记录文件的路径log_file_from_contents中用于标识内容来源的文件名file_contentsbytes必填仅 contents 版本已读入内存的文件原始字节entity_path_prefixstr \| NoneNone日志实体路径的前缀便于将导入内容统一归入指定命名空间staticboolFalse为True时组件作为静态数据记录无时间关联、在所有时间线上存在、无条件遮蔽同类型时序数据为False时自动打上log_time以及启用时的log_tick时间戳同时也会带上通过 [rerun.set_time] 设置的其他时间线recordingRecordingStream \| NoneNone指定使用的 RecordingStream不传时使用当前激活的数据记录参见 [rerun.init]、[rerun.set_global_data_recording]两种 API 的取舍log_file_from_path直接把文件路径交给 Importer 框架。适合文件尚在磁盘、无需改动原始数据的场景也是默认推荐方式log_file_from_contents当你已经以二进制形式持有文件内容如从网络、数据库、内存流中拿到数据时直接传入字节即可避免先落盘再读取。示例注释特别强调该方式仅适用于常规文件外部加载器external loaders不支持。两者语义一致一个路径可能被多个 Importer 同时处理调用会阻塞直到至少一个 Importer 开始向数据流推送数据或所有 Importer 均失败。底层原理从 Python 到 Rust 的完整调用链Python 层函数只是薄封装实际工作发生在 Rust 端。1. Python 绑定层_log.py中的两个函数分别调用绑定接口bindings.log_file_from_path(...)/bindings.log_file_from_contents(...)将Path、entity_path_prefix、static_、recording转换为原生PyRecordingStream透传给rerun_py的 pyo3 绑定最终落到 crates/top/re_sdk/src/recording_stream.rs#L1455-L1482 的RecordingStream::log_file_from_path/log_file_from_contents两个方法均在importersfeature 下编译。2. 统一的log_file内部实现两条路径汇合到私有方法log_filerecording_stream.rs#L1488-L1589核心步骤为校验初始化状态若 RecordingStream 尚未正确初始化无store_info打印告警并直接返回构造日志通道通过re_log_channel::log_channel(LogSource::File { path })建立一条异步数据管道组装 ImporterSettings携带当前 recording 的application_id、recording_id、entity_path_prefix、时间点等上下文当staticfalse时会在当前线程的所有时间线上采集当前时刻并递增log_tick序号即使未启用log_tick也会递增分发导入按是否提供内容分别调用re_importer::import_from_file_contents(...)或re_importer::import_from_path(...)FileSource::Sdk后台消费单独启动一个线程线程名形如log_file_from_path(...)不断从通道接收LogMsg并调用record_msg写入当前 recording句柄被存入importer_handles统一管理。源码注释明确此调用会阻塞直到至少一个 Importer 开始流式输出或全部失败正是通道两端同步等待的结果。3. 外部导入器协议re_importer还支持发现系统中的外部导入器ExternalImporter见 crates/data_flow/re_importer/src/importer_external.rs。外部导入器会以子进程方式被调用并接收一组约定好的 CLI 参数crates/data_flow/re_importer/src/lib.rs#L106-L116例如--application-id application_id--recording-id store_id--entity-path-prefix entity_path_prefix若设置--static当时间点为 timeless 时--time_sequence timeline1seq1 timeline2seq2 ...--time_timestamp_nanos timeline1ts1 timeline2ts2 ...自 epoch 起的纳秒Importer 生态仓库内置了哪些导入器从 crates/data_flow/re_importer/src/lib.rs#L19-L58 可以看到当前仓库注册的导入器集合它们共同构成了打开任意文件的能力矩阵导入器源码模块处理的输入RrdImporterimporter_rrd.rsRerun 原生 RRD 录制文件McapImporterimporter_mcapMCAP 格式ROS 生态常见需mcapfeatureweb 端不可用ParquetImporterimporter_parquet.rsParquet 列式数据需parquetfeature非 wasmLeRobotDatasetImporterimporter_lerobot.rsLeRobot 机器人数据集目录需lerobotfeature非 wasmUrdfImporterimporter_urdfURDF 机器人模型描述文件需urdffeatureDirectoryImporterimporter_directory.rs目录这解释了示例可以传入examples/assets目录的原因ArchetypeImporterimporter_archetype.rs通用 archetype 数据ExternalImporterimporter_external.rs外部可执行导入器非 wasm此外MCAP 导入器还支持通过FOXGLOVE_LENSES_IDENTIFIERfoxglove与URDF_DECODER_IDENTIFIERurdf启用 Foxglove lenses 与从robot_description话题提取 URDF 的解码能力lib.rs#L67-L92。源码级验证官方测试与跨语言绑定仓库提供了针对该能力的测试与多语言绑定可作为正确用法的权威参考Rust 测试crates/top/re_sdk/tests/log_file.rs#L47-L69 中log_file_from_path_retargets_blueprint_to_current_application验证了一个重要行为通过log_file_from_path导入的 RRD 文件中的 blueprint会被重定向到当前 recording 的应用保证导入的蓝图与当前会话一致C 绑定crates/top/rerun_c/src/lib.rs#L1193-L1273 提供了rr_recording_stream_log_file_from_path/rr_recording_stream_log_file_from_contents两个 C API与 Python/Rust 签名一一对应说明该能力是 SDK 层的通用能力而非 Python 独有Rust SDK 文档recording_stream.rs#L1447-L1482 对两个方法给出了与 Python 侧一致的语义说明可作为跨语言的行为契约。使用建议与注意事项目录与文件皆可filepaths可以同时混传文件和目录如官方命令直接传入examples/assets目录由DirectoryImporter递归处理后分发到具体文件导入器命名空间隔离为每个文件传入不同的entity_path_prefix可避免多个文件在实体树中互相覆盖示例统一使用log_file_example前缀静态 vs 时序数据机器人数据通常带时间轴保持默认staticFalse以保留时间线信息只有无时间概念的数据才考虑staticTrue外部加载器限制--from-contents模式对外部加载器不适用若依赖外部导入器请优先走路径模式阻塞语义调用会阻塞到至少一个 Importer 开始推送数据或全部失败适合在初始化阶段同步调用避免在热路径中使用平台限制MCAP、Parquet、LeRobot、外部导入器在 wasm/web 目标下不可用桌面端native功能最全见 re_importer/src/lib.rs 各 feature 的cfg标注。小结通过rr.log_file_from_path/rr.log_file_from_contentsRerun 把打开任意文件收敛为一次 API 调用Python 侧两个函数透传给 Rust 端RecordingStream::log_file由re_importer依据文件类型分派到 RRD、MCAP、Parquet、URDF、LeRobot 等内置导入器或外部导入器并通过后台线程把解析结果流式写入当前 recording。无论你是在写数据回放工具、加载机器人数据集还是快速预览录制的日志文件都可以直接复用示例 log_file.py 的模式把文件加载逻辑压缩到几行代码之内。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
