企业官网建设流程全解析

Rerun Rust 最小示例深度解析：用 20 行代码在 3D 空间中记录彩色点云

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

导读

本文以 Rerun 官方 Rust 示例中最精简的 minimal 示例 为核心，逐行拆解"生成一个 3D 彩色立方体点云并实时可视化"的完整链路：从RecordingStreamBuilder建立流式连接，到demo_util::grid生成网格点，再到Points3D组件化日志记录。读完本文，你将掌握 Rerun Rust SDK 最核心的"创建 RecordingStream → 组织数据 → rec.log() 上报"三段式编程模型，并能立即在自己的 Rust 项目中复现这一最小可视化闭环。

一、示例概览：最短路径的可视化

minimal 示例是整个仓库中最简洁的 Rerun 使用示范。它不做任何花哨的展示，只做一件事：把 1000 个带颜色的三维点作为一个点云记录下来，并在 Rerun Viewer 中渲染出来。官方将其定位为"通向可用可视化的最短路径"（the shortest path to a working visualization），也是 Rerun Rust 快速入门指南的配套代码。

整个示例仅包含三个文件：

在仓库根目录执行即可运行：

cargo run --release

命令执行后会发生两件事：

1. 构建 minimal 示例并启动程序；
2. 程序自动拉起 Rerun Viewer 窗口（若 Viewer 未运行则通过spawn自动启动），随后在 3D 视图中出现一个由彩色点组成的立方体点云。

--release是官方推荐的运行方式：Rerun SDK 的数据管线（Chunk 批处理、序列化、gRPC 传输）在 release 模式下性能远优于 debug 模式，能避免 debug 构建下日志频率较高时出现的卡顿。

二、逐行拆解 main.rs 的实现

完整源码见 examples/rust/minimal/src/main.rs，下面按逻辑分段解读。

2.1 建立 RecordingStream：与 Viewer 建立连接

let rec = rerun::RecordingStreamBuilder::new("rerun_example_minimal").spawn()?;

这是整段代码的"入口"。RecordingStreamBuilder::new(application_id)以应用标识（ApplicationId）创建构建器，本例中的应用 ID 为"rerun_example_minimal"；随后调用.spawn()：

• 从$PATH中查找并启动一个 Rerun Viewer 进程；
• 通过 gRPC 建立一条流式通道，将数据实时推送给该 Viewer；
• 如果该端口上已有 Viewer 在监听，则不会重复启动新进程，而是直接复用现有 Viewer（从源码注释可见这一行为，见 crates/top/re_sdk/src/recording_stream.rs）。

从源码结构看，RecordingStreamBuilder是一个典型的构建器模式：其字段包括application_id、store_kind、recording_id、batcher_config、blueprint等（见 crates/top/re_sdk/src/recording_stream.rs）。除了spawn()，它还提供多个同级的"数据出口"选择，这将在第五节展开。

2.2 生成点云数据：demo_util::grid

use rerun::demo_util::grid; use rerun::external::glam; let points = grid(glam::Vec3::splat(-10.0), glam::Vec3::splat(10.0), 10);

grid(from, to, n)是 Rerun SDK 为示例提供的网格生成工具，实现在 crates/top/rerun/src/demo_util.rs：

pub fn grid(from: glam::Vec3, to: glam::Vec3, n: usize) -> impl Iterator<Item = glam::Vec3> { linspace(from.z, to.z, n).flat_map(move |z| { linspace(from.y, to.y, n) .flat_map(move |y| linspace(from.x, to.x, n).map(move |x| (x, y, z).into())) }) }

其工作原理是：在 X、Y、Z 三个轴上分别调用linspace（线性插值，见同文件 crates/top/rerun/src/demo_util.rs，本质上是对lerp(a, b, t) = a - t*a + t*b的封装），再用flat_map做三层嵌套笛卡尔积。

因此本例中grid(Vec3::splat(-10.0), Vec3::splat(10.0), 10)表示：在-10.0到10.0之间每个轴取 10 个采样点，共生成10 × 10 × 10 = 1000 个三维点，均匀铺满一个边长为 20 的立方体空间——这正是最终渲染出"彩色立方体点云"的几何来源。

2.3 为每个点生成颜色

let colors = grid(glam::Vec3::ZERO, glam::Vec3::splat(255.0), 10) .map(|v| rerun::Color::from_rgb(v.x as u8, v.y as u8, v.z as u8));

这里再次调用grid，但范围从(0,0,0)到(255,255,255)，同样采样 10 步。由于两次grid的嵌套展开顺序完全一致（先 Z、再 Y、最后 X），因此points与colors两个迭代器按位置一一对应：空间位置与 RGB 颜色通道线性绑定——越靠近立方体 X 正方向越红、Y 正方向越绿、Z 正方向越蓝，从而形成平滑渐变的彩色立方体。

rerun::Color::from_rgb(r, g, b)是 SDK 提供的 RGBA 颜色构造器，as u8将 0~255 的浮点值截断为 8 位通道值。

2.4 记录点云：rec.log() 与 Points3D 组件

rec.log( "my_points", &rerun::Points3D::new(points) .with_colors(colors) .with_radii([0.5]), )?;

这一行是整个示例的数据上报核心，包含三个层次：

（1）实体路径"my_points"：Rerun 使用类似文件系统的层级路径组织数据（如"robot/arm/link1"）。这里使用根级路径"my_points"，点云的所有数据都将挂在名为my_points的实体下，并显示在 Viewer 的实体树（Blueprint Tree）中。

（2）Points3D架构（Archetype）：Points3D是 Rerun 预定义的数据架构之一，定义在 crates/store/re_sdk_types/src/archetypes/points3d.rs（文件头注释明确指出该文件由re_types_builder代码生成，是 Rerun 类型系统的产物）。其官方定义为："A 3D point cloud with positions and optional colors, radii, labels, etc."（带位置及可选颜色、半径、标签等的 3D 点云）。

Points3D::new(positions)接受任何可迭代为Position3D的类型（见 points3d.rs），并支持一系列链式构造方法，本例用到的两个：

从Points3D的字段定义（positions、radii、colors、labels、show_labels、point_shading、class_ids、keypoint_ids）可以看出，该架构还支持标签、分类 ID、关键点 ID、着色模式等更多扩展能力，minimal 示例只使用了最基础的三个字段。

（3）log方法签名：RecordingStream::log(ent_path, as_components)是 SDK 最常用的行式（row-oriented）日志接口，实现在 crates/top/re_sdk/src/recording_stream.rs，要求第二个参数实现AsComponentstrait——Points3D正是一个实现了该 trait 的组件包（component bundle）。SDK 内部会将其序列化为 Arrow 列数据，交给 ChunkBatcher 进行微批处理（micro batching）后异步发送给 Viewer。

三、数据流全景：从一行 log 到屏幕上的点云

综合源码调用链，这 20 行代码背后实际发生了如下数据流：

main.rs 生成 points + colors │ ▼ Points3D::new(...).with_colors(...).with_radii(...) ← 组件打包 │ ▼ rec.log("my_points", &points3d) ← 行式日志 API │ ▼ ChunkBatcher 微批处理 / Arrow 序列化 ← re_chunk_store 数据模型 │ ▼ gRPC 流式传输 ← spawn() 建立的通道 │ ▼ Rerun Viewer 渲染 Points3D 可视化器

其中spawn()建立的是 SDK 与 Viewer 之间的 gRPC 通道；log的数据经 re_chunk 的 Chunk 模型组织后落库。这也解释了为什么 minimal 示例既是"最短路径"，又完整覆盖了 Rerun "log → stream → visualize" 的核心设计哲学。

四、Cargo.toml：极简依赖声明

examples/rust/minimal/Cargo.toml 的依赖部分只有一行：

[dependencies] rerun = { path = "../../../crates/top/rerun" }

• 直接以相对路径依赖仓库内的crates/top/rerun顶层 crate，该 crate 会 re-exportRecordingStreamBuilder、Points3D、demo_util、external::glam等全部所需 API（demo_util模块在 crates/top/rerun/src/lib.rs 中声明）。
• 示例的version为0.38.0-alpha.1+dev，publish = false，属于仓库内部开发版示例，不发布到 crates.io。
• edition = "2024"、rust-version = "1.96"，对工具链版本有明确要求，请确保使用足够新的 Rust 工具链编译。

在实际业务项目中，你既可以像本示例一样以 path 依赖本地源码（便于调试 SDK 自身），也可以改为rerun = "0.x"从 crates.io 引入正式发布版。

五、从 minimal 出发的三种演进方向

minimal 示例是 Rerun Rust 用法的"最小公倍数"，基于RecordingStreamBuilder的其余出口与logAPI 的扩展能力，可以自然演化出更多实战形态：

1. 切换数据出口：spawn → save / stdout

spawn()只是RecordingStreamBuilder众多出口之一。同文件还提供了.save("my_recording.rrd")（写入本地.rrd录制文件，见 recording_stream.rs）与.stdout()（经标准输出管道传给外部进程，见 recording_stream.rs，终端为 TTY 时自动回退为 buffered 模式）。将spawn()换成save()，即可把同样的点云数据离线落盘，之后用 Viewer 打开复盘。

2. 加入时间维度：set_time + 循环 log

minimal 示例记录的是单帧静态数据。实际机器人/多模态数据通常是时序的，只需在循环中调用rec.set_time_seconds("timeline", t)并反复log即可形成随时间演化的动画。

3. 组合更多架构（Archetype）

Points3D只是 Rerun 类型系统中数百个架构之一。仓库中 crates/store/re_sdk_types/src/archetypes 目录还包含Arrows3D、Boxes3D、Image、Mesh3D、Tensor、Transform3D等常用架构，均遵循与Points3D一致的new(...).with_xxx(...)链式构造风格，掌握 minimal 示例后即可平滑迁移。

六、总结

minimal 示例用最少的代码完整展示了 Rerun Rust SDK 的三个核心抽象：

1. RecordingStream：数据采集与传输的载体，通过RecordingStreamBuilder的spawn/save/stdout决定数据去向；
2. Archetype（架构）：如Points3D，把位置、颜色、半径等组件（Component）打包成可日志化的数据单元；
3. log(ent_path, &archetype)：以实体路径为坐标、以组件包为内容的行式日志接口。

对照 examples/rust/minimal/src/main.rs 亲自运行一遍cargo run --release，你将直观看到 1000 个渐变彩色点组成的立方体在 Viewer 中呈现——这是理解整个 Rerun 数据可视化管线的最佳起点。

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