Rerun Plane3D 组件详解：无限三维平面（Hesse 正规式）的编码、归一化与三语言使用

Rerun Plane3D 组件详解无限三维平面Hesse 正规式的编码、归一化与三语言使用【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读Plane3D是 Rerun 中用于表示无限三维平面的核心组件其内部采用单位法向量 到原点距离的 Hesse 正规式Hesse normal form表达底层以FixedSizeList(4 x non-null Float32)的 Arrow 数据类型落盘到 datastore。本文以 components/plane3d.md 为主体结合re_sdk_types中的 Rust 定义与扩展实现、Python 与 C 绑定的真实代码说明该组件的数据结构、数学含义、Viewer 归一化行为以及如何用 Python、Rust、C 三套 SDK 构造和记录平面并给出可直接运行的实操示例。组件定义一个法向量加一个距离Plane3D表示一个无限延伸的三维平面。其官方定义与文档同源出自类型定义文件 plane3d.def.rs/// An infinite 3D plane represented by a unit normal vector and a distance. /// /// Any point P on the plane fulfills the equation dot(xyz, P) - d 0, /// where xyz is the planes normal and d the distance of the plane from the origin. /// This representation is also known as the Hesse normal form. #[rerun::rerun_type] #[rust(repr transparent)] #[rerun(state stable)] pub struct Plane3D { pub xyzd: rerun::encodings::Plane3D, }数学上平面上任意一点P满足dot(xyz, P) - d 0其中xyz是平面的法向量d是平面到原点的距离。d的符号决定了法向量方向上的平移方向d 0表示平面位于法向量指向的那一侧距原点d个单位d 0则相反。这套表述正是经典的Hesse 正规式点法式的一种规范化形式它用一个 4 元组(nx, ny, nz, d)就完整、紧凑地编码了一个无限平面无需存储顶点或多边形网格。Arrow 数据编码FixedSizeList(4 x non-null Float32)组件在数据存储层对应的 Arrow 数据类型为FixedSizeList(4 x non-null Float32)即一个固定长度为 4 的非空 Float32 列表四个分量依次为法向量(x, y, z)与距离d。其编码类型encoding同样定义在 encodings/plane3d.def.rs#[rerun::rerun_type] #[arrow(transparent)] #[rust(tuple_struct)] #[rerun(state stable)] pub struct Plane3D { pub xyzd: [f32; 4], }对应的编码说明文档见 encodings/plane3d.md。由于组件与编码均为#[arrow(transparent)]二者共享同一底层 Arrow 布局序列化时一个Plane3D组件就是一条[nx, ny, nz, d]的 FixedSizeList 记录。这一紧凑布局使得大量平面数据在 chunk 中连续存储利于 Rerun 的批量查询与按列过滤。关键行为datastore 原样存储Viewer 统一归一化文档明确指出两个容易踩坑的语义datastore 侧原样透传提交时给出的法向量不会被改写。即xyz (2, 0, 0), d 1会以原值写入数据存储。Viewer 侧始终归一化渲染时平面会被归一化处理。因此xyz (2, 0, 0), d 1与xyz (1, 0, 0), d 0.5在视图中完全等价都表示 x1 处的竖直平面。该行为在 Rust 源码中可验证encodings/plane3d_ext.rs的FromPlane3D for macaw::Plane3转换中明确调用了.normalized()见 plane3d_ext.rs组件的FromPlane3D for macaw::Plane3同样如此components/plane3d_ext.rs。Viewer 的几何网格化与 UI 展示逻辑位于 re_component_ui/src/plane3d.rs。实践建议为获得可预期的渲染结果建议在提交前自行归一化法向量并同步缩放d若不归一化渲染结果依然正确只是数据层保留的是你提交的原始形态。三语言 API 使用示例PythonPlane3D(normal, distance)Python 编码类型位于 encodings/plane3d.py其扩展实现plane3d_ext.py明确了构造签名Plane3D(normal, distanceNone)normal法向量接受Vec3DLike列表、numpy 数组等内部会转成 float32 定长 3 元组distance到原点的距离默认为 0即默认构造过原点的平面构造函数不会归一化平面提供.normal()、.distance()、.with_distance(new_d)便捷方法以及三个坐标平面常量Plane3D.YZ、Plane3D.ZX、Plane3D.XY法向量分别为 X、Y、Z距离 0。记录到 Viewer 的最小示例import rerun as rr rr.init(plane3d_demo) rr.spawn() # 法向量 X过原点的 Y^Z 平面 rr.log(world/plane_yz, rr.components.Plane3D([1.0, 0.0, 0.0])) # 自定义平面法向量 (0, 0, 1)距离 2z2 的水平面 rr.log(world/plane_xy, rr.components.Plane3D([0.0, 0.0, 1.0], distance2.0))序列化时Python 侧通过native_to_pa_array_override将 4 元素 float32 数组打包成pa.FixedSizeListArray见 plane3d_ext.py与文档声明的 Arrow 类型一一对应。RustPlane3D::new(normal, distance)与XY/YZ/ZX常量Rust 组件与编码定义在 components/plane3d.rs 与 encodings/plane3d.rs。扩展实现plane3d_ext.rs提供Plane3D::new(normal, distance)从法向量与距离构造不做归一化常量Plane3D::YZX 法向即 Y^Z 平面、Plane3D::ZXY 法向Z^X 平面、Plane3D::XYZ 法向X^Y 平面访问器normal()与distance()与macaw::Plane3glam 生态的双向转换其中macaw::Plane3 - Plane3D原样拷贝Plane3D - macaw::Plane3会调用.normalized()。示例use rerun::components::Plane3D; // 过原点的 Y^Z 平面法向量 X let plane Plane3D::YZ; // 自定义平面法向量 (0, 1, 0)距离 1 let plane Plane3D::new([0.0, 1.0, 0.0], 1.0);组件本身通过#[rust(repr transparent)]、Copy、bytemuck::Pod等 trait 支持零拷贝内存布局适合高频批量写入。Crerun::components::Plane3DC 侧自动生成的组件头文件见 components/plane3d.hpp编码结构体为rerun::encodings::Plane3D内部即std::arrayfloat, 4 xyzd见 encodings/plane3d.hpp#include rerun.hpp // 法向量 (1,0,0)、距离 0过原点的 Y^Z 平面 rerun::components::Plane3D plane rerun::encodings::Plane3D{{1.0f, 0.0f, 0.0f, 0.0f}}; rec.log(world/plane_yz, plane);C 通过Loggableencodings::Plane3D::to_arrow/fill_arrow_array_builder走arrow::FixedSizeListBuilder完成序列化与 Python/Rust 保持同一套 Arrow 编码。应用场景与实战要点地面/墙面拟合机器人学与三维重建中平面提取如 RANSAC 拟合地面可直接产出 Hesse 正规式无需换算即可交给Plane3D可视化。碰撞与投影平面点乘形式的平面方程dot(n, P) - d 0便于在 SDK 侧做点到平面距离、射线求交等计算。坐标平面常量XY/YZ/ZX三个常量Python、Rust、C 均有适合快速搭建立方体边界或参考坐标系的可视化辅助。写入要点datastore 保留原始值渲染时归一化因此同一几何平面有多种等价表示查询原始 chunk 数据时需注意这一点。参考路径速查组件文档docs/content/reference/types/components/plane3d.md编码文档docs/content/reference/types/encodings/plane3d.md类型定义Rust 代码生成源crates/build/re_type_definitions/rerun/components/plane3d.def.rs、crates/build/re_type_definitions/rerun/encodings/plane3d.def.rsRust SDKcrates/store/re_sdk_types/src/components/plane3d.rs、crates/store/re_sdk_types/src/encodings/plane3d_ext.rsPython SDKrerun_py/rerun_sdk/rerun/components/plane3d.py、rerun_py/rerun_sdk/rerun/encodings/plane3d_ext.pyC SDKrerun_cpp/src/rerun/components/plane3d.hpp、rerun_cpp/src/rerun/encodings/plane3d.hppViewer 平面 UI 实现crates/viewer_support/re_component_ui/src/plane3d.rs【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考