企业官网建设流程全解析

Rerun 组件详解：FillRatio 填充比 —— 控制深度图像点云投影中点的大小与间隙

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

导读

FillRatio（填充比）是 Rerun 可视化类型系统中的核心组件之一，它描述“一个图元在多大程度上填满其可用空间”，最常见的应用场景是控制由深度图像（DepthImage）反投影生成的三维点云中每个点的大小：填充比为 1.0 时相邻点恰好中心相接、不留缝隙，填充比为 0.5 时点仅与邻居边缘相触。读完本文，你将掌握FillRatio的语义、取值范围、默认值、底层 Arrow 数据类型，以及如何在 Rust / Python / C++ 三种 SDK 中通过DepthImage与EncodedDepthImage配置它，并结合源码理解点云半径的计算原理。

FillRatio 是什么：一个组件在类型系统中的定位

在 Rerun 的数据模型中，一切可视化数据都由 Archetype（原型）组织，每个 Archetype 由若干个 Component（组件）构成。FillRatio是一个组件（component），它的类型定义源头在 crates/build/re_type_definitions/rerun/components/fill_ratio.def.rs：

/// How much a primitive fills out the available space. /// /// Used for instance to scale the points of the point cloud created from [`rerun::archetypes::DepthImage`] projection in 3D views. /// Valid range is from 0 to max float although typically values above 1.0 are not useful. /// /// Defaults to 1.0. #[rerun::rerun_type] #[python(aliases = "float")] #[python(array_aliases = "float | npt.ArrayLike")] #[rust(derive(Copy, PartialEq, PartialOrd, bytemuck::Pod, bytemuck::Zeroable))] #[rust(repr = "transparent")] #[rerun(state = "stable")] pub struct FillRatio { pub value: rerun::encodings::Float32, }

这段定义文件透露了几个关键信息：

• 该类型通过rerun_type宏标注，属于稳定（stable）状态的类型，其语义与序列化格式在 Rerun 的兼容性承诺范围内，可放心用于长期存储的数据；
• 它在 Python 绑定中被声明了float别名，意味着在 Python 中可以直接传入普通float或 NumPy 数组（npt.ArrayLike）；
• 它是一个透明包装（#[repr(transparent)]）的单个Float32值，在 Rust 中可以实现零开销的转换与内存布局映射。

FillRatio的文档字符串给出了三句关键定义，这也是它在整个 Rerun 语义体系中的权威描述：

1. 含义：一个图元填充可用空间的程度；
2. 典型用途：缩放由深度图像投影生成的三维点云中点的尺寸；
3. 默认值：1.0。

取值范围与默认值：0 到 1.0 之间才真正有意义

官方范围声明

文档与类型定义一致声明：

• 合法范围：0到浮点数最大值（max float）；
• 实用范围：通常大于1.0的值不再有用；
• 默认值：1.0。

源码中的默认值实现

默认值1.0不只是文档描述，它在 Rust SDK 中被显式实现为Defaulttrait，见 crates/store/re_sdk_types/src/components/fill_ratio_ext.rs：

use super::FillRatio; impl Default for FillRatio { #[inline] fn default() -> Self { 1.0.into() } }

生成的组件类型位于 crates/store/re_sdk_types/src/components/fill_ratio.rs，其结构为pub struct FillRatio(pub crate::encodings::Float32);，并通过WrapperComponenttrait 关联其编码类型为Float32。从该文件可以看到，组件类型名注册为"rerun.components.FillRatio"，这正是日志数据在存储与传输中使用的稳定标识。

数值语义：1.0 意味着什么

结合可视化器的实现（见下文“底层原理”一节），FillRatio的实际几何语义是：

• fill_ratio = 1.0（默认）：点云中每个点的半径被设置为相邻像素投影点间距的一半——当相邻点处于相同深度时，点与点之间中心相接、无缝隙；
• fill_ratio = 0.5：点的大小缩小一半，相邻点仅边缘相触；
• 介于两者之间时，点的半径按比例缩放，用于在“点之间有缝”与“点之间重叠”之间调节；
• 小于 1.0 会产生缝隙（点变小），大于 1.0 则点互相重叠（视觉上可能形成更厚重的“填充”效果，因此文档说超过 1.0 通常无意义）。

Rerun 编码与 Arrow 数据类型

FillRatio的底层编码与序列化格式非常简洁：

即该组件在 Arrow 内存格式中就是一个Float32标量列。对于一条深度图像数据，point_fill_ratio对应一列单元素Float32；由于 Arrow 支持向量化批量传输，同一批数据中的多个填充比可以共享一个Float32数组列。

从生成的 Rust 代码可以看到，FillRatio与Float32之间通过From<T>泛型转换打通：impl<T: Into<crate::encodings::Float32>> From<T> for FillRatio，因此FillRatio::from(0.5f32)、(0.5f32).into()等写法都合法，这让 SDK 使用非常顺手。

使用场景：两个深度图像 Archetype 中的可选组件

FillRatio目前被两个深度图像相关的 Archetype 引用：

1. DepthImage（深度图像）；
2. EncodedDepthImage（编码深度图像）。

在 DepthImage 中

在 crates/store/re_sdk_types/src/archetypes/depth_image.rs 中，point_fill_ratio字段的定义为：

/// Scale the radii of the points in the point cloud generated from this image. /// /// A fill ratio of 1.0 (the default) means that each point is as big as to touch the center of its neighbor /// if it is at the same depth, leaving no gaps. /// A fill ratio of 0.5 means that each point touches the edge of its neighbor if it has the same depth. /// /// TODO(#6744): This applies only to 3D views! pub point_fill_ratio: Option<SerializedComponentBatch>,

其对应的组件描述符为descriptor_point_fill_ratio()，关联组件类型为"rerun.components.FillRatio"。在DepthImage的 8 个组件中，point_fill_ratio属于可选组件（optional component）——必需组件只有buffer与format两个，其余 6 个（meter、colormap、depth_range、point_fill_ratio、draw_order、magnification_filter）均为可选。

在 EncodedDepthImage 中

编码深度图像（支持 PNG / TIFF / RVL 等压缩格式）同样携带point_fill_ratio，定义见 crates/store/re_sdk_types/src/archetypes/encoded_depth_image.rs，字段注释为 “Optional point fill ratio for point-cloud projection.”。在该 Archetype 中它同样属于可选组件。

一个重要限制

源码中的TODO(#6744)明确指出：当前FillRatio仅对 3D 视图生效。在 2D 视图中，深度图像以纹理矩形方式显示，点云填充比不会影响渲染结果。要在 3D 视图中把深度图像显示为“深度点云（depth cloud）”，需要实体上方存在 Pinhole 相机模型以完成反投影。

SDK 使用方式：Python / Rust / C++ 实战

Python

在 Python 中，FillRatio被声明为float的别名，因此可以直接传普通浮点数。通过DepthImage的point_fill_ratio参数配置：

import rerun as rr import numpy as np rr.init("depth_fill_ratio_demo") rr.spawn() # 构造一张 200x300 的 uint16 深度图 image = np.full((200, 300), 65535, dtype=np.uint16) image[50:150, 50:150] = 20000 rr.log( "world/camera", rr.Pinhole( resolution=[300, 200], focal_length=[200.0, 200.0], ), ) rr.log( "world/camera/depth", rr.DepthImage( image, meter=10000.0, point_fill_ratio=0.5, # 点半径减半，相邻点仅边缘相触 ), )

注意：point_fill_ratio可以直接传float（如0.5）或 NumPy 数组（npt.ArrayLike），后者可用于批量设置多条记录。

Rust

Rust SDK 中通过with_point_fill_ratio链式方法设置（该方法同样定义于 crates/store/re_sdk_types/src/archetypes/depth_image.rs）：

use ndarray::{Array, ShapeBuilder as _, s}; fn main() -> Result<(), Box<dyn std::error::Error>> { let rec = rerun::RecordingStreamBuilder::new("rerun_example_depth_image_3d").spawn()?; let width = 300; let height = 200; let mut image = Array::<u16, _>::from_elem((height, width).f(), 65535); image.slice_mut(s![50..150, 50..150]).fill(20000); image.slice_mut(s![130..180, 100..280]).fill(45000); let depth_image = rerun::DepthImage::try_from(image)? .with_meter(10000.0) .with_colormap(rerun::components::Colormap::Viridis) .with_point_fill_ratio(0.5); // FillRatio 默认 1.0，此处调小让点之间出现缝隙 // 在实体上方记录 Pinhole 相机模型，深度图会自动反投影为 3D 点云 rec.log( "world/camera", &rerun::Pinhole::from_focal_length_and_resolution( [200.0, 200.0], [width as f32, height as f32], ), )?; rec.log("world/camera/depth", &depth_image)?; Ok(()) }

由于FillRatio实现了From<T: Into<Float32>>与Default，with_point_fill_ratio(0.5_f32)、with_point_fill_ratio(rerun::components::FillRatio::default())等写法都合法。此外with_many_point_fill_ratio可一次传入多个值，配合columns()/columns_of_unit_batches()实现按时间列（columnar）批量发送。

C++

C++ SDK 对应组件为rerun::components::FillRatio，同样通过DepthImage::with_point_fill_ratio配置：

#include <rerun.hpp> #include <rerun/archetypes/depth_image.hpp> namespace rr = rerun; int main() { rr::RecordingStream rec("depth_fill_ratio_demo"); rec.spawn().throw_on_failure(); std::vector<uint16_t> data(300 * 200, 65535); // ... 填充深度数据 ... rec.log("world/camera", rr::archetypes::Pinhole::from_focal_length_and_resolution( {200.0f, 200.0f}, {300.0f, 200.0f})); rec.log("world/camera/depth", rr::archetypes::DepthImage(std::move(data), {300, 200}) .with_meter(10000.0f) .with_point_fill_ratio(0.5f)); rec.show(); }

一个易错点

FillRatio控制的是点的半径，与DepthImage的meter（深度单位到米的换算）职责不同：meter决定点云在 3D 空间中的位置（反投影距离），point_fill_ratio决定每个点占据多大面积。二者配合使用才能得到既定位正确又不互相遮挡的深度点云。

底层原理：可视化器如何消费 FillRatio

3D 深度点云渲染路径

FillRatio的实际消费方是 3D 空间视图的深度图可视化器。在 crates/views/re_view_spatial/src/visualizers/depth_images.rs 中：

1. 可视化器首先从查询结果中读取fill_ratio字段（第 45 行声明pub fill_ratio: Option<FillRatio>）；
2. 判断实体所在的变换树中是否存在 Pinhole 相机根节点——只有在存在相机模型时，才将深度图反投影为深度点云（第 120-124 行）；
3. 若用户未设置，则取fill_ratio.unwrap_or_default()，即默认值1.0（第 124 行）；
4. 将fill_ratio传入process_entity_view_as_depth_cloud(...)（第 129-137 行），由该函数按填充比计算每个点的半径并生成点云；
5. 该路径同时支持FillRatio以批量（batch）形式出现：代码中通过iter_optional(DepthImage::descriptor_point_fill_ratio().component)读取全部填充比，再用slice::<f32>()取出f32数组（第 284-304 行），说明 Rerun 内部直接以 ArrowFloat32数组消费该组件。

编码深度图像的可视化路径与此类似，见 crates/views/re_view_spatial/src/visualizers/video/encoded_depth_image.rs，其中同样按EncodedDepthImage::descriptor_point_fill_ratio()读取组件。

从“组件描述符”到“点半径”

整条链路可以概括为：

SDK 日志（FillRatio = f32） → Arrow Float32 数组序列化 → 存储层按 "rerun.components.FillRatio" 描述符索引 → 3D 视图可视化器 iter_optional 查询 → unwrap_or_default() 取默认 1.0 → process_entity_view_as_depth_cloud 按比例计算点半径 → GPU 渲染深度点云

这也解释了为什么FillRatio是一个“小而通用”的组件：它不关心自己属于哪个 Archetype，只要数据列上带有rerun.components.FillRatio描述符，深度图可视化器就能消费它；反过来，DepthImage与EncodedDepthImage两个 Archetype 都通过descriptor_point_fill_ratio()生成完全相同的组件描述符，从而共享同一套点云缩放逻辑。

与其他组件的协作关系

FillRatio通常与以下组件协同工作（均在DepthImageArchetype 中）：

其中与FillRatio语义最相关的是meter：二者共同决定了深度点云“长什么样”——meter决定点在空间中的深度距离，fill_ratio决定点的视觉大小与疏密程度。

小结

• FillRatio是 Rerun 类型系统中一个稳定（stable）的Float32透明包装组件，语义为“图元填充可用空间的程度”；
• 合法范围为0到max float，实用范围为0到1.0之间，默认值1.0（由 crates/store/re_sdk_types/src/components/fill_ratio_ext.rs 中的Default实现保证）；
• 底层编码与 Arrow 数据类型均为Float32，类型名rerun.components.FillRatio；
• 被DepthImage与EncodedDepthImage两个 Archetype 作为可选组件point_fill_ratio引用；
• 仅对 3D 视图生效（源码TODO(#6744)标注），需配合 Pinhole 相机模型将深度图反投影为点云；
• Python 中可直接传float，Rust 中通过with_point_fill_ratio(...)链式构建，C++ 中通过同名方法配置；
• 底层由 crates/views/re_view_spatial/src/visualizers/depth_images.rs 中的深度点云处理逻辑消费：未设置时取默认值1.0，按比例计算每个点的半径。

延伸阅读：继续阅读 DepthImage 组件文档 与 EncodedDepthImage 组件文档，可进一步理解深度图像的完整组件体系；类型定义源头见 crates/build/re_type_definitions/rerun/components/fill_ratio.def.rs，生成的各语言绑定分别位于 crates/store/re_sdk_types/src/components/fill_ratio.rs 及 C++ / Python 对应生成目录。

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