Rerun 数据模型中的 Vec3D 编码Arrow 表示、SDK 用法与组件引用全解析【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunVec3D是 Rerun 类型系统中一个稳定的编码类型encoding type用于表达三维空间中的一个向量。本文以docs/content/reference/types/encodings/vec3d.md为骨架深入剖析其 Arrow 数据表示、Rust/Python 双端 SDK 实现、与各 3D 组件的引用关系并给出可直接运行的代码示例帮助你在 Rerun 中正确记录位置、尺寸、位移、旋转轴等三维数据。一、Vec3D 是什么按官方类型定义Vec3D的语义一句话即可概括A vector in 3D space.三维空间中的一个向量。它本身是一个编码类型Rerun 将其归类为Encoding而非组件Component意味着它不直接作为日志数据的入口而是作为若干三维组件的底层数据结构被复用。例如Position3D、Scale3D、Translation3D、Vector3D等组件在底层存储的都是Vec3D。在 Rerun 的类型分层中编码类型与组件类型的界限由类型构建器re_types_builder统一管理其定义文件位于 crates/build/re_type_definitions/rerun/encodings/vec3d.def.rs声明为/// A vector in 3D space. #[rerun::rerun_type] #[arrow(transparent)] #[python(aliases npt.NDArray[Any] | npt.ArrayLike | Sequence[float])] #[python( array_aliases npt.NDArray[Any] | npt.ArrayLike | Sequence[Sequence[float]] | Sequence[float] )] #[rust(derive(Default, Copy, PartialEq, bytemuck::Pod, bytemuck::Zeroable))] #[rust(repr C)] #[rust(tuple_struct)] #[rerun(state stable)] pub struct Vec3D { pub xyz: [f32; 3], }该定义文件中的关键属性值得逐一解读#[arrow(transparent)]指明Vec3D在 Arrow 层采用透明布局即只保留单个字段xyz不产生额外嵌套层级对应下文的FixedSizeList表示#[rerun(state stable)]说明该类型已处于稳定stable状态其数据表示与 API 有长期兼容保证#[rust(...)]为 Rust 侧生成Copy、Default、PartialEq、bytemuck::Pod/Zeroable以及repr(C)布局等派生便于零拷贝与底层互操作#[python(...)]声明 Python 侧的类型别名允许直接传入 NumPy 数组、任意数组型对象ArrayLike或float序列。二、Arrow 数据表示FixedSizeList(3 × Float32)参考文档给出了Vec3D的 Arrow datatype 描述FixedSizeList(3 x non-null Float32)Rust 侧的生成代码 crates/store/re_sdk_types/src/encodings/vec3d.rs 给出了完全一致、可供校验的实现impl ::re_types_core::ArrowDataType for Vec3D { #[inline] fn arrow_data_type() - arrow::datatypes::DataType { use arrow::datatypes::*; DataType::FixedSizeList( std::sync::Arc::new(Field::new(item, DataType::Float32, false)), 3, ) } }这段代码揭示了Vec3D在内存中的精确布局属性取值说明Arrow 类型FixedSizeList定长列表元素个数固定列表长度3对应 x、y、z 三个分量元素类型Float32f32每个分量是 32 位单精度浮点子字段名item列表内部字段的固定命名可空性non-nullfalse三个分量均不允许为空对应的 Python 侧 batch 定义见 rerun_py/rerun_sdk/rerun/encodings/vec3d.pyclass Vec3DBatch(BaseBatch[Vec3DArrayLike]): _ARROW_DATATYPE pa.list_(pa.field(item, pa.float32(), nullableFalse, metadata{}), 3)由于使用FixedSizeList而非变长List批量向量数据在 Arrow 中以扁平化的连续缓冲存储所有向量的 9 个f32分量按顺序拼接反序列化时可直接通过bytemuck::try_cast_slice一次性转为[f32; 3]切片见 vec3d.rs 中的from_arrow实现实现了真正意义上的零拷贝读取这对海量三维点云、轨迹数据的可视化与查询至关重要。三、Rust 侧实现元组结构体与丰富的转换接口3.1 核心类型定义Rust 侧生成的Vec3D是一个元组结构体直接包装一个[f32; 3]#[repr(C)] pub struct Vec3D(pub [f32; 3usize]);它在 crates/store/re_sdk_types/src/encodings/vec3d.rs 中派生/实现了Clone / Debug / Default / Copy / PartialEq常规值语义bytemuck::Pod / bytemuck::Zeroable允许按字节直接解释与零初始化re_byte_size::SizeBytes用于内存统计与性能分析ArrowDataType / ToArrow / FromArrow完成与 Arrow 数组的双向反序列化From[f32; 3]与FromVec3D for [f32; 3]与定长数组互转。3.2 便捷扩展方法手写扩展文件 crates/store/re_sdk_types/src/encodings/vec3d_ext.rs 提供了日常开发最常用的 APIimpl Vec3D { /// The zero vector, i.e. the additive identity. pub const ZERO: Self Self([0.0; 3]); /// [1, 1, 1], i.e. the multiplicative identity. pub const ONE: Self Self([1.0; 3]); /// Create a new vector. #[inline] pub const fn new(x: f32, y: f32, z: f32) - Self { Self([x, y, z]) } /// The x-coordinate, i.e. index 0. #[inline] pub fn x(self) - f32 { self.0[0] } /// The y-coordinate, i.e. index 1. #[inline] pub fn y(self) - f32 { self.0[1] } /// The z-coordinate, i.e. index 2. #[inline] pub fn z(self) - f32 { self.0[2] } }即Vec3D::ZERO/Vec3D::ONE零向量与全 1 向量常量Vec3D::new(x, y, z)最常用的构造入口x() / y() / z()分量访问器同时实现了std::ops::Index/IndexMut支持v[0]、v[1]、v[2]下标读写。3.3 与常见数学库的互操作扩展文件在 feature 开关下提供了与第三方数学库的双向转换方便在既有渲染/物理代码中使用glamfeature与glam::Vec3、glam::Vec3A互转mintfeature与mint::Vector3f32互转另有From(f32, f32, f32)、From[f64; 3]、以及对应引用形式的转换覆盖了元组、f64 数组、切片等常见输入形态。此外Display实现支持精度参数例如format!({:.2}, v)可控制小数位数输出。四、Python 侧实现类型别名与自动转换Python 侧由类型构建器生成 rerun_py/rerun_sdk/rerun/encodings/vec3d.py再配合手写的 vec3d_ext.py 完成数据转换。4.1 类型别名Vec3DLike Vec3D | npt.NDArray[Any] | npt.ArrayLike | Sequence[float] A type alias for any Vec3D-like object. Vec3DArrayLike ( Vec3D | Sequence[Vec3DLike] | npt.NDArray[Any] | npt.ArrayLike | Sequence[Sequence[float]] | Sequence[float] ) A type alias for any Vec3D-like array object.Vec3DLike单个向量可传入Vec3D实例、NumPy 数组NDArray、任意数组型对象或长度为 3 的float序列Vec3DArrayLike批量向量可以是Vec3D、向量序列、二维 NumPy 数组等。这意味着在 Python 中你无需显式构造Vec3D直接传[1.0, 2.0, 3.0]或np.array(...)即可被组件 API 接受。4.2 数据转换管线构造函数将输入经to_np_float32转换为npt.NDArray[np.float32]并存入xyz字段define(initFalse) class Vec3D(Vec3DExt): **Encoding**: A vector in 3D space. def __init__(self: Any, xyz: Vec3DLike) - None: self.__attrs_init__(xyzxyz) xyz: npt.NDArray[np.float32] field(converterto_np_float32) def __array__(self, dtype: npt.DTypeLike None, copy: bool | None None) - npt.NDArray[Any]: return asarray(self.xyz, dtypedtype, copycopy) def __len__(self) - int: return len(self.xyz)Vec3D还实现了__array__可被np.asarray拾取与__len__行为上贴近原生 NumPy 数组。批量写入时由Vec3DBatch._native_to_pa_array调用扩展实现将输入拍平为float32连续内存后构造成pa.FixedSizeListArraystaticmethod def native_to_pa_array_override(data: Vec3DArrayLike, data_type: pa.DataType) - pa.Array: points flat_np_float32_array_from_array_like(data, 3) points np.ascontiguousarray(points) return pa.FixedSizeListArray.from_arrays(points, typedata_type)其中flat_np_float32_array_from_array_like(data, 3)定义于rerun_py/rerun_sdk/rerun/_validators.py负责把各类数组型输入统一校验并展平为每 3 个一组的f32数据。五、Vec3D 被哪些组件引用参考文档明确列出Vec3D作为底层编码被以下组件复用链接均已转换为仓库根目录相对路径组件仓库文档位置用途HalfSize3Ddocs/content/reference/types/components/half_size3d.md包围盒/椭球的半尺寸LineStrip3Ddocs/content/reference/types/components/line_strip3d.md三维折线的顶点Position3Ddocs/content/reference/types/components/position3d.md三维空间中的位置点RotationAxisAngledocs/content/reference/types/encodings/rotation_axis_angle.md旋转轴编码类型间的组合Scale3Ddocs/content/reference/types/components/scale3d.md三维缩放Translation3Ddocs/content/reference/types/components/translation3d.md三维平移Vector3Ddocs/content/reference/types/components/vector3d.md三维向量箭头VoxelSizedocs/content/reference/types/components/voxel_size.md体素尺寸从源码结构可以验证这种“组件继承编码”的关系例如Position3D在 Python 侧直接继承Vec3D并混入组件语义class Position3D(encodings.Vec3D, ComponentMixin): ... class Position3DBatch(encodings.Vec3DBatch, ComponentBatchMixin): ...见 rerun_py/rerun_sdk/rerun/components/position3d.py。这说明Vec3D是整个 Rerun 三维数据栈的基石型数值编码几乎所有涉及空间几何的组件都在其上构建。六、实战示例在 SDK 中如何使用6.1 Python记录三维点位置借助Vec3DLike的宽松别名最直观的用法是直接传入序列import rerun as rr rr.init(vec3d_demo, spawnTrue) # 单个位置点直接传入 (x, y, z) 序列即可 rr.log(point, rr.Position3D([1.0, 2.0, 3.0])) # 批量位置点二维数组或序列的序列 rr.log( points, rr.Points3D( positions[ [0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], ] ), )Position3D的xyz字段最终以FixedSizeList(3 × Float32)写入 Arrow 记录批次chunk底层即Vec3D编码。6.2 Rust使用Vec3D::new构造组件use rerun::components::Position3D; use rerun::encodings::Vec3D; // 直接构造向量 let v Vec3D::new(1.0, 2.0, 3.0); // 组件可直接从 Vec3D 转换 let pos: Position3D v.into(); // 与 glam 互转需启用 glam feature let gv: glam::Vec3 v.into();6.3 适用的运行前提本文示例面向 Rerun 的 Python SDKrerun_py/与 Rust SDKcrates/top/re_sdkVec3D为稳定stable编码长期可放心使用更完整的类型列表可查阅 docs/content/reference/types 目录下的各组件与编码文档。七、小结Vec3D是 Rerun 中定义最简单、却支撑起全部三维可视化能力的核心编码Arrow 侧为FixedSizeList(3 × non-null Float32)Rust 侧为repr(C)的[f32; 3]元组结构体并支持glam/mint互转Python 侧则通过宽松类型别名接受序列与 NumPy 数组。无论是Position3D、Scale3D、Vector3D还是RotationAxisAngle底层都复用了这一编码。理解Vec3D的表示与转换链路是深入使用 Rerun 记录和分析机器人、视觉与几何数据的必要基础。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
