企业官网建设流程全解析

Rerun Boxes3D 原理解析与实战：三维边界框的可视化、旋转与批处理指南

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

本文以 Rerun 官方类型参考文档 Boxes3D 为主体，结合仓库中的类型定义（boxes3d.def.rs）、三端 SDK 生成代码与官方示例，系统讲解Boxes3D这一空间数据类型的字段语义、批量广播规则、变换叠加顺序，并给出 Python / Rust / C++ 三种语言的完整可运行示例。读完本文，你将能够用 Rerun 记录单个 3D 盒子与成批的带旋转、颜色、标签的有向边界框（OBB），理解半边长（half-size）语义与各字段间的广播关系。

Boxes3D 是什么

Boxes3D是 Rerun 中用于描述「三维盒子」的 Archetype（原型类型）：以半边长（half-extents）为核心，可选附带中心位置、旋转、颜色等属性。它属于Spatial 3D类别的稳定类型（state = "stable"），由Boxes3DVisualizer 负责渲染（见 boxes3d.def.rs）。

在 Rerun 中，Archetype 是由多个 Component（组件）聚合而成的高层数据类型。Boxes3D是典型的实例化类型：一条日志消息可以携带任意多个盒子（batch），每个盒子对应一批实例。其类型定义如下（节选自 boxes3d.def.rs）：

#[rerun::rerun_type] #[docs(category = "Spatial 3D")] #[docs(view_types = "Spatial3DView, Spatial2DView: if logged above active projection")] #[rerun(state = "stable")] #[rerun(visualizer = "Boxes3D")] pub struct Boxes3D { #[rerun(required)] pub half_sizes: Vec<rerun::components::HalfSize3D>, #[rerun(recommended)] pub centers: Option<Vec<rerun::components::Translation3D>>, #[rerun(optional)] pub rotation_axis_angles: Option<Vec<rerun::components::RotationAxisAngle>>, #[rerun(optional)] pub quaternions: Option<Vec<rerun::components::RotationQuat>>, #[rerun(recommended)] pub colors: Option<Vec<rerun::components::Color>>, #[rerun(optional)] pub radii: Option<Vec<rerun::components::Radius>>, #[rerun(optional)] pub fill_mode: Option<rerun::components::FillMode>, #[rerun(optional)] pub labels: Option<Vec<rerun::components::Text>>, #[rerun(optional)] pub show_labels: Option<rerun::components::ShowLabels>, #[rerun(optional)] pub class_ids: Option<Vec<rerun::components::ClassId>>, }

这套def.rs声明会由re_types_builder统一生成 Rust、Python、C++ 三端绑定（见 boxes3d.py 与 boxes3d.rs 的自动生成头注释），因此三个语言的字段与语义完全一致。

字段语义详解

官方文档将字段分为「Required / Recommended / Optional」三个层级，分别对应「必须提供」「推荐提供」「按需提供」，其具体含义如下。

Required：half_sizes（半边长）

half_sizes是唯一必填字段，类型为HalfSize3D。

理解这一字段的关键在于「半」字：盒子沿每个轴同时在正负两个方向延伸，因此给定half_sizes=[2.0, 2.0, 1.0]得到的盒子在 x 轴跨度为[-2, 2]、y 轴跨度为[-2, 2]、z 轴跨度为[-1, 1]，即完整尺寸为[4, 4, 2]。根据 half_size3d.md 的说明：

• 半边长在盒子的局部坐标系中度量；
• 负半边长表示盒子沿对应轴翻转，但不影响显示效果；
• 其 Rerun 编码为Vec3D，Arrow 数据类型为FixedSizeList(3 x non-null Float32)。

Recommended：centers与colors

• centers（类型Translation3D）：盒子的中心位置。如果不指定，所有盒子默认中心在局部原点(0, 0, 0)（见 boxes3d.def.rs）。Translation3D同样是编码为Vec3D的三维平移向量。
• colors（类型Color）：盒子的颜色。注意其 Alpha 通道在实体填充（solid fill）模式下用于透明度（见 boxes3d.def.rs）。

Optional：旋转、线宽、填充、标签与类别

其中fill_mode的可选值由FillMode组件定义，与Boxes3D直接相关的取值有：

• MajorWireframe(1)/DenseWireframe(2)：对盒子而言两者都绘制盒子的棱边，表现相同（线框模式）；
• Solid(3)：实体填充表面，不绘制线条；
• TransparentFillMajorWireframe(4)：透明填充表面并叠加主要棱边线框，是兼顾表面与结构的默认外观。

FillMode的 Arrow 底层类型为UInt8。

标签相关的两条广播规则同样来自官方文档与类型定义：

• 若实体上只有单个标签，它会被放置在实体的中心；
• 若有多个标签，则每个实例各有一个标签；
• 未设置show_labels时，标签会在「实体上恰好只有一个标签」或「实例数量低于某阈值」时自动显示（见 boxes3d.def.rs）。

广播规则与变换叠加顺序

Boxes3D有两个重要的语义细节，理解它们才能避免可视化结果与预期不符。

1. 盒子的朝向按最后一个盒子的朝向广播。官方文档明确说明："If there's more instance poses than half sizes, the last box's orientation will be repeated for the remaining poses."也就是说，当传入的旋转数量少于盒子数量时，最后一个盒子的朝向会复制给剩余的盒子，而不是缺失的旋转被置为默认朝向。

2. 盒子的摆放与朝向形成一次独立的变换，叠加顺序先于InstancePoses3D和Transform3D。原文为："Orienting and placing boxes forms a separate transform that is applied prior toInstancePoses3DandTransform3D."这意味着渲染一个Boxes3D实体时，其完整的空间变换链为：

box local geometry → (half_sizes 定义形状) → centers + rotations（Boxes3D 自身的摆放/朝向） → InstancePoses3D（实例位姿） → Transform3D（实体变换） → 父实体变换链 → 世界坐标系

因此在做「盒子自身放置 + 实例位姿 + 实体级变换」的复合表达时，必须清楚Boxes3D内置的centers/旋转是先于外部位姿与变换生效的。

支持哪些视图

根据官方文档，「Can be shown in」部分指明Boxes3D可以显示在以下视图中：

• Spatial3DView：3D 空间视图，Boxes3D是其可视化 Archetype 清单中的成员；
• Spatial2DView：当盒子被记录在活动投影之上时（例如投影到图像平面），也可在 2D 视图中显示；
• DataframeView：以表格形式查询与展示任意存储数据。

渲染侧的实现位于 crates/views/re_view_spatial/src/visualizers/boxes3d.rs，其中定义了Boxes3DVisualizer作为该类型在空间视图中的默认可视化器，负责把half_sizes、centers、旋转、颜色、fill_mode等组件装配成可绘制的几何体。

三端实战示例

官方文档挂载了两个示例：boxes3d_simple（单个 3D 盒子）与boxes3d_batch（一批有向边界框）。源码位于 docs/snippets/all/archetypes/，并有对应的录制数据 boxes3d_simple.rrd 与 boxes3d_batch.rrd 可直接在 Viewer 中回放。

示例一：单个 3D 盒子（simple）

Python（boxes3d_simple.py）：

"""Log a single 3D Box.""" import rerun as rr rr.init("rerun_example_box3d", spawn=True) rr.log("simple", rr.Boxes3D(half_sizes=[2.0, 2.0, 1.0]))

Rust（boxes3d_simple.rs）：

//! Log a single 3D box. fn main() -> Result<(), Box<dyn std::error::Error>> { let rec = rerun::RecordingStreamBuilder::new("rerun_example_box3d").spawn()?; rec.log("simple", &rerun::Boxes3D::from_half_sizes([(2.0, 2.0, 1.0)]))?; Ok(()) }

C++（boxes3d_simple.cpp）：

// Log a single 3D box. #include <rerun.hpp> int main(int argc, char* argv[]) { const auto rec = rerun::RecordingStream("rerun_example_box3d"); rec.spawn().exit_on_failure(); rec.log("simple", rerun::Boxes3D::from_half_sizes({{2.f, 2.f, 1.0f}})); }

注意此处只提供了half_sizes，未指定centers，因此盒子中心落在局部原点(0, 0, 0)，且三轴与局部坐标系对齐（无旋转）。

示例二：一批有向边界框（batch）

Python（boxes3d_batch.py）：

"""Log a batch of oriented bounding boxes.""" import rerun as rr rr.init("rerun_example_box3d_batch", spawn=True) rr.log( "batch", rr.Boxes3D( centers=[[2, 0, 0], [-2, 0, 0], [0, 0, 2]], half_sizes=[[2.0, 2.0, 1.0], [1.0, 1.0, 0.5], [2.0, 0.5, 1.0]], quaternions=[ rr.Quaternion.identity(), rr.Quaternion(xyzw=[0.0, 0.0, 0.382683, 0.923880]), # 45 degrees around Z ], radii=0.025, colors=[(255, 0, 0), (0, 255, 0), (0, 0, 255)], fill_mode="solid", labels=["red", "green", "blue"], ), )

Rust（boxes3d_batch.rs）：

//! Log a batch of oriented bounding boxes. fn main() -> Result<(), Box<dyn std::error::Error>> { let rec = rerun::RecordingStreamBuilder::new("rerun_example_box3d_batch").spawn()?; rec.log( "batch", &rerun::Boxes3D::from_centers_and_half_sizes( [(2.0, 0.0, 0.0), (-2.0, 0.0, 0.0), (0.0, 0.0, 2.0)], [(2.0, 2.0, 1.0), (1.0, 1.0, 0.5), (2.0, 0.5, 1.0)], ) .with_quaternions([ rerun::Quaternion::IDENTITY, rerun::Quaternion::from_xyzw([0.0, 0.0, 0.382683, 0.923880]), // 45 degrees around Z ]) .with_radii([0.025]) .with_colors([ rerun::Color::from_rgb(255, 0, 0), rerun::Color::from_rgb(0, 255, 0), rerun::Color::from_rgb(0, 0, 255), ]) .with_fill_mode(rerun::FillMode::Solid) .with_labels(["red", "green", "blue"]), )?; Ok(()) }

C++（boxes3d_batch.cpp）：

// Log a batch of oriented bounding boxes. #include <rerun.hpp> int main(int argc, char* argv[]) { const auto rec = rerun::RecordingStream("rerun_example_box3d_batch"); rec.spawn().exit_on_failure(); rec.log( "batch", rerun::Boxes3D::from_centers_and_half_sizes( {{2.0f, 0.0f, 0.0f}, {-2.0f, 0.0f, 0.0f}, {0.0f, 0.0f, 2.0f}}, {{2.0f, 2.0f, 1.0f}, {1.0f, 1.0f, 0.5f}, {2.0f, 0.5f, 1.0f}} ) .with_quaternions({ rerun::Quaternion::IDENTITY, // 45 degrees around Z rerun::Quaternion::from_xyzw(0.0f, 0.0f, 0.382683f, 0.923880f), }) .with_radii({0.025f}) .with_colors({ rerun::Rgba32(255, 0, 0), rerun::Rgba32(0, 255, 0), rerun::Rgba32(0, 0, 255), }) .with_fill_mode(rerun::FillMode::Solid) .with_labels({"red", "green", "blue"}) ); }

这个示例可以清晰印证前文的广播规则：

• 有3 个盒子（3 组centers/half_sizes），但只给了2 个四元数——第二个盒子绕 Z 轴旋转 45°，第三个盒子会沿用第二个盒子的朝向（45° 旋转），而非回到默认朝向；
• radii=0.025与colors长度不足时按实例广播填充；
• fill_mode="solid"/FillMode::Solid让盒子实体着色，此时colors的 Alpha 通道可用于半透明效果。

便捷构造器：从全尺寸与最小角点创建盒子

half_sizes是半边长，而实际业务中（如目标检测的检测框、机器人感知的障碍物框）往往拿到的是「完整尺寸」或「最小角点 + 尺寸」。为此，三端 SDK 都提供了便捷构造方法，底层实现见 boxes3d_ext.rs：

例如 Rust 的from_sizes实现会逐轴做size.x() / 2.0生成HalfSize3D（boxes3d_ext.rs），C++ 端同样在 boxes3d_ext.cpp 中实现了from_sizes与from_mins_and_sizes。Python 端（boxes3d_ext.py）则在__init__中接受sizes、mins等关键字参数：

• 同时传入sizes与half_sizes会触发警告（二者互斥），内部通过np.asarray(sizes) / 2.0换算半边长；
• 传入mins时要求必须同时提供sizes或half_sizes，否则警告并回退到默认半边长[1, 1, 1]，随后按centers = mins + half_sizes推导中心；
• 兼容性参数rotations会先尝试按四元数解析、再尝试按轴角解析，官方建议优先使用quaternions或rotation_axis_angles。

小结

Boxes3D是 Rerun 空间数据模型中表达三维边界框的标准 Archetype，以半边长half_sizes为唯一必填字段，配合centers、quaternions/rotation_axis_angles、colors、fill_mode、labels、class_ids等组件即可表达从简单立方体到成批有向边界框的各种场景。使用时重点把握三点：半边长语义（局部坐标系、双向延伸）、旋转不足时按最后一个盒子朝向广播、以及Boxes3D内置变换先于InstancePoses3D与Transform3D生效。三端 SDK 均提供from_sizes、from_centers_and_sizes、from_mins_and_sizes等便捷构造器，可将感知任务中常见的完整尺寸、最小角点形式直接换算为 Rerun 需要的半边长数据。

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