企业官网建设流程全解析

Rerun 增量式日志（Incremental Logging）实战：复用同一 Archetype 的跨帧数据

【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun

本篇技术指南围绕 Rerun 官方 Python 示例incremental_logging展开，讲解如何针对同一个Points3D点云实体做增量式记录：把颜色、半径等“变化缓慢”的属性只上传一次，之后每帧仅更新点位坐标，其余数据自动被后续帧复用。读完本文，你将掌握 Rerun 的实体-组件（Entity-Component）数据模型、static静态数据与时间轴（Timeline）的关系、Points3D.from_fields部分更新 API 的用法，以及示例脚本中内置的 CLI 参数（--connect、--save、--serve等）的实战意义，可以直接把这一模式套用到自己的机器人、SLAM、多模态传感器数据可视化任务中。

示例要解决的问题

在多模态机器人数据可视化中，一个常见的场景是：点云/路标/特征点的位姿坐标每帧都在变化，而它们的视觉属性（颜色、半径、标签）长时间保持不变。最朴素的做法是每一帧都把完整属性重新上传一遍，这既浪费带宽，也让录制文件迅速膨胀。

Rerun 示例incremental_logging展示的正是一种更优的做法：数据按组件（component）独立管理，每个组件都有自己独立的时间线历史。只要把不变的部分记录一次，后续帧记录变化的部分即可，查看器在查询任意时间点时会自动把不同“年龄”的组件拼合成一个完整的实体状态。

该示例位于 examples/python/incremental_logging，包含三个文件：示例脚本 incremental_logging.py、包配置 pyproject.toml 和本文依据的 README.md。

快速运行

从仓库检出（checkout）后，直接运行 Python 脚本即可（需要 Python 环境与rerun-sdk、numpy依赖）：

python examples/python/incremental_logging/incremental_logging.py

注意：原 README 中给出的命令路径写作increamental_logging.py，与仓库中实际文件名incremental_logging.py存在拼写差异，以实际文件名为准。

依赖声明见 pyproject.toml，仅需numpy与rerun-sdk两个运行时依赖：

[project] name = "incremental_logging" version = "0.1.0" readme = "README.md" dependencies = ["numpy", "rerun-sdk"]

脚本运行后会弹出 Rerun 查看器（默认spawn模式），并额外在场景中写入一段 Markdown 说明文档（见后文“内置 README 面板”一节）。

核心代码逐段解析

示例脚本 incremental_logging.py 的逻辑非常精简，主干如下：

rr.script_setup(args, "rerun_example_incremental_logging") # 只记录一次颜色与半径；用 static=True 记录静态数据同样可行 rr.set_time("frame_nr", sequence=0) rr.log("points", rr.Points3D.from_fields(colors=0xFF0000FF, radii=0.1)) rng = default_rng(12345) # 之后每帧只记录点位坐标，颜色和半径会被自动复用 for i in range(10): rr.set_time("frame_nr", sequence=i) rr.log("points", rr.Points3D.from_fields(positions=rng.uniform(-5, 5, size=[10, 3])))

下面拆解每一步。

第一步：脚本脚手架（script_setup / script_teardown）

脚本开头使用argparse构建命令行解析器，并通过rr.script_add_args(parser)注入 Rerun 通用参数，最后用rr.script_setup(args, application_id)初始化 SDK 并决定数据去向。这些辅助函数定义在 rerun_py/rerun_sdk/rerun/_script_helpers.py：

script_setup内部根据参数组合选择spawn()、connect_grpc()、save()、serve_grpc()等模式；script_teardown在--serve模式下负责保持进程存活。这意味着同一个示例脚本可以无缝切换为“本机弹窗查看”“连接远程查看器”“保存.rrd离线分析”等多种工作流。

第二步：只记录一次的颜色与半径

rr.set_time("frame_nr", sequence=0) rr.log("points", rr.Points3D.from_fields(colors=0xFF0000FF, radii=0.1))

这里在frame_nr时间轴的sequence=0时刻，为实体points写入了colors（红色，0xFF0000FF）与radii（0.1）两个组件。后续所有帧都不再写这两个组件，它们停留在第 0 帧，构成该实体的“慢变属性”。

set_time的三种重载定义在 rerun_py/rerun_sdk/rerun/time.py：sequence（整数序号，适合帧计数）、duration（时长，适合时间演进）、timestamp（时刻，适合墙钟时间）。示例统一使用sequence语义，语义清晰且便于回放。

第三步：每帧只记录点位坐标

for i in range(10): rr.set_time("frame_nr", sequence=i) rr.log("points", rr.Points3D.from_fields(positions=rng.uniform(-5, 5, size=[10, 3])))

随机数生成器以固定种子12345初始化（default_rng(12345)），因此每次运行生成的点位序列完全一致，便于对比验证。循环共 10 帧，每帧向points实体写入positions一个组件。

增量更新的底层原理：from_fields 与实体-组件模型

示例中反复使用的Points3D.from_fields定义于 rerun_py/rerun_sdk/rerun/archetypes/points3d.py。它的核心语义是：只更新传入的字段，未传入字段保持原样，从而支持对同一实体的局部增量更新。

@classmethod def from_fields( cls, *, clear_unset: bool = False, positions: encodings.Vec3DArrayLike | None = None, radii: encodings.Float32ArrayLike | None = None, colors: encodings.Rgba32ArrayLike | None = None, labels: encodings.Utf8ArrayLike | None = None, show_labels: encodings.BoolLike | None = None, point_shading: components.PointShadingLike | None = None, class_ids: encodings.ClassIdArrayLike | None = None, keypoint_ids: encodings.KeypointIdArrayLike | None = None, ) -> Points3D:

关键参数说明：

• clear_unset：若为True，所有未指定的字段会被显式清空。示例中未使用该参数（默认False），因此缺省字段不会干扰既有数据。
• colors：按 RGB/RGBA 解释，处于 sRGB gamma 空间，可传 0-1 浮点或 0-255 整数；默认情况下 alpha 通道影响亮度而非透明度。
• radii：点半径，把点渲染成圆；示例中传入标量0.1表示所有点共享同一半径。
• labels/show_labels：可选文本标签及其显示开关；show_labels未设置时，仅当实体标签数量为 1 或实例数低于阈值时自动显示。
• class_ids/keypoint_ids：分类与关键点 ID，可配合分类颜色自动着色；若只给keypoint_ids而未给class_ids，class_ids默认为 0。
• positions：点云的三维坐标，形状为[N, 3]的数组；示例中每帧rng.uniform(-5, 5, size=[10, 3])生成 10 个点。

从实现上看，from_fields把所有参数收集进kwargs后调用__attrs_init__构建实例（clear_unset=True时把None替换为空数组以显式清空），随后由rr.log把非空组件分条写入。每个字段对应一个独立的ComponentDescriptor（如Points3D:positions、Points3D:colors），这正是“组件独立时间线”能够成立的数据基础：查看器查询某一帧时，分别取回每个组件在该时刻或之前最近时刻的值，再组合成完整实体。因此第 5 帧的查询结果就是“第 5 帧的 positions + 第 0 帧的 colors/radii”。

静态数据（static）与时间轴的取舍

示例注释明确指出：

Logging as static would also work (i.e.static=True).

即完全可以把颜色与半径记录为静态数据（rr.log("points", rr.Points3D.from_fields(colors=..., radii=...), static=True)），效果等价于它们“存在于所有时刻”。两种写法的取舍在于：

• 绑定到时间轴（示例默认）：属性被记录在frame_nr=0，属于“第 0 帧的属性”，在时间轴上可见、可被查询，适合属性本身随时间演进（例如颜色渐变）的场景。
• 静态数据（static）：属性与时间无关，始终存在，不随任何时间轴变化，适合真正恒定不变的元信息（如传感器内参、坐标系定义）。

示例选择前者，是为了直观演示“跨帧复用”：当你拖动查看器的时间游标时，能看到点位每帧变化，而颜色与半径始终沿用第 0 帧的取值。示例脚本还把说明文本以静态方式记录进场景：

rr.log("readme", rr.TextDocument(README, media_type=rr.MediaType.MARKDOWN), static=True)

这使得录制的.rrd自带操作说明，打开即可看到“Move the time cursor around, and notice how the colors and radii from frame 0 are still picked up by later frames”的提示，方便复现验证。

验证方式与延伸阅读

手动验证

运行脚本后在查看器中左右拖动时间游标：

1. positions每帧变化（10 个点在[-5, 5]³立方体内随机跳动）；
2. colors（红色）与radii（0.1）从第 0 帧起保持不变，并持续作用于后续所有帧；
3. 实体树中points的组件历史时间线各不相同，直观体现“组件独立时间线”模型。

深度延伸：同主题的更多更新模式

Points3D的类文档（rerun_py/rerun_sdk/rerun/archetypes/points3d.py）还展示了同一主题下的其他三种模式，可作为增量日志的进阶参考：

• 逐行更新（row updates）：每帧通过rr.set_time+rr.log记录整行数据，点云数量可以逐帧增减（positions列表长度不一）；
• 列式批量更新（column updates）：通过rr.send_columns配合TimeColumn一次性发送 5 个时间步的全部数据，并用Points3D.columns(...).partition(lengths=[...])控制每个时间步的点数，适合离线/批量导入；
• 部分更新（partial updates）：正是本示例采用的from_fields模式——先记录positions，之后只更新colors/radii，或通过clear_unset=True在指定帧清空其余字段，实现“只改一部分、其余保持”的精确控制。

小结

incremental_logging示例用不到 20 行核心代码，演示了 Rerun 数据记录中极具价值的一条经验：把实体的属性按变化频率分层，慢变属性记录一次（或设为 static），快变属性逐帧记录。底层由实体-组件模型与组件独立时间线机制保证查询时的自动拼合，用户无需手动做任何“合并”操作。对高频传感器数据、机器人状态流等场景，这一模式能显著降低每帧日志的数据量，同时让录制文件更小、回放更清晰。

将该模式迁移到自己的项目时，只需注意三点：使用Points3D.from_fields（或其他 archetype 的from_fields）做部分更新；为“不变属性”选择合适的时间轴语义或直接static=True；利用示例脚本自带的--save、--stdout、--connect参数把演示无缝切换为离线录制或远程连接工作流。

【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun