Rerun 组件 VoxelSize 深度解析稀疏体素网格的场景单位尺寸与数据编码【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读VoxelSize是 Rerun 数据模型中的一个核心三维组件用于描述稀疏体素网格sparse voxel grid中单个体素在场景坐标下的三维尺寸。它同时是VoxelGridMap与Volume3D两个三维体数据 archetype 的关键组成部分直接决定了体素在空间中的物理跨度、包围盒计算与点选交互。本文将结合 Rerun 仓库中的类型定义、生成的 SDK 绑定代码、渲染可视化器实现以及三种语言Python / Rust / C的可运行示例完整讲解VoxelSize的语义约定、编码格式、约束校验与实战用法。组件语义一个体素在场景坐标中的尺寸根据官方组件文档docs/content/reference/types/components/voxel_size.mdVoxelSize定义为稀疏 3D 体素网格中一个体素在场景单位scene-unit下的尺寸。每个分量对应当地网格坐标轴local grid axis上体素的大小。所有分量必须为有限值finite且为正positive。这一定义包含三层关键语义单位是场景单位voxel_size不是体素数或归一化坐标而是直接映射到 3D 场景坐标系即实体坐标系的父子变换链中的物理长度数值本身不带量纲后缀具体量纲由使用者的数据约定决定如米、毫米每个分量对应一条局部网格轴x、y、z三个分量分别描述体素沿当地 X/Y/Z 轴的边长因此允许各向异性非立方体体素有限且为正这是数据不变量invariant不允许 0、负数、NaN 或无穷大避免产生退化或不可渲染的几何体。从仓库中的类型定义源文件 crates/build/re_type_definitions/rerun/components/voxel_size.def.rs 可以看到该组件由re_types_builder统一生成 Rust、Python、C 三种语言的绑定并被标记为#[rerun(state stable)]意味着其数据布局在版本演进中保持向后兼容/// The scene-unit dimensions of one voxel in a sparse 3D voxel grid. /// /// Each component is the size of a voxel along the corresponding local grid axis. /// All components must be finite and positive. #[rerun::rerun_type] #[rust(derive(Copy, PartialEq, bytemuck::Pod, bytemuck::Zeroable))] #[rust(repr transparent)] #[rerun(state stable)] pub struct VoxelSize { pub xyz: rerun::encodings::Vec3D, }体素定位约定中心与最小角点理解VoxelSize的作用必须同时理解 Rerun 对体素网格坐标的统一定位约定。在VoxelGridMap与Volume3D的文档及类型定义中约定完全一致索引为[0, 0, 0]的体素其最小角点minimum corner位于实体坐标系的原点并可通过可选的translation平移与rotation旋转字段在父坐标系中进一步偏移任意体素的中心位于(index 0.5) * voxel_size当地网格坐标相对于最小角点因此voxel_size直接决定了相邻整数索引体素中心之间的间距以及整个网格的包围盒范围。该约定定义于 crates/build/re_type_definitions/rerun/archetypes/voxel_grid_map.def.rs 与 docs/content/reference/types/archetypes/volume3d.mdA voxel center is at(index 0.5) * voxel_sizein local grid coordinates (i.e. relative to the minimum corner).这一索引 × 尺寸 半体素偏移的约定保证了同样voxel_size与位姿下的VoxelGridMap与Volume3D能够逐体素对齐voxel for voxel为混合使用稀疏体素与稠密体数据如占用网格 雷达栅格提供了统一的空间基准。Rerun 编码与 Arrow 数据类型VoxelSize在 Rerun 的序列化层采用单一封装类型Rerun encodingVec3D编码文档Arrow datatypeFixedSizeList(3 x non-null Float32)即固定长度 3、元素为非空Float32的定长列表无内层空值结构紧凑且可直接映射为 GPU/渲染侧的Vec3。生成的 Rust 绑定 crates/store/re_sdk_types/src/components/voxel_size.rs 印证了这一实现VoxelSize是Vec3D的透明包装#[repr(transparent)]并实现了bytemuck::Pod/Zeroable可直接进行无拷贝位级转换组件全名为rerun.components.VoxelSize#[repr(transparent)] pub struct VoxelSize(pub crate::encodings::Vec3D); impl ::re_types_core::WrapperComponent for VoxelSize { type Encoding crate::encodings::Vec3D; fn name() - ComponentType { rerun.components.VoxelSize.into() } // … }同时组件提供FromT: IntoVec3D泛型转换因此在三种语言的 SDK 中都可以直接用[x, y, z]数组或Vec3D构造例如 Rust 侧VoxelSize::from([0.25, 0.25, 0.25])。运行时约束校验渲染层的兜底验证有限且为正不仅是文档约定也是渲染管线中的硬性校验。在空间视图的可视化器实现 crates/views/re_view_spatial/src/visualizers/voxel_grid_map.rs 中绘制前会对voxel_size做显式检查非法值会被上报为 Viewer 错误并跳过绘制let voxel_size glam::Vec3::from_array(voxel_size.0.0); if !voxel_size.is_finite() || !voxel_size.cmpgt(glam::Vec3::ZERO).all() { results.report_for_component( VoxelGridMap::descriptor_voxel_size().component, ViewerReportSeverity::Error, voxel_size must be finite and positive, ); return Ok(None); }从该文件还可以看到voxel_size在渲染链路中的实际用途voxel_grid_map.rs通过min_index.as_vec3() * voxel_size与(max_index 1) * voxel_size计算网格局部包围盒local bbox再经实体→网格变换得到世界包围盒用于视锥剔除与绘制排序voxel_size随VoxelGridOptions一并传入渲染器用于体素几何体立方体的逐实例构建与点选picking命中计算。此外该可视化器还受NUM_VOXEL_LIMIT_PER_BATCH上限约束当体素数超限时会在不改变voxel_size的前提下对实例数封顶并给出警告可在 Settings 中放开限制。使用场景一VoxelGridMap 的必填字段VoxelSize在 VoxelGridMap 中是必填required字段。VoxelGridMap用于描述稀疏 3D 占用网格occupancy map及其他以稀疏体素存储的体积数据其必填字段为voxel_indices网格体积内的体素索引VoxelIndex见 voxel_index.mdvoxel_size单个体素单元的场景单位尺寸沿当地 X/Y/Z 轴定义每维必须有限且为正。可选的着色与位姿字段包括values标量值配合colormap/value_range映射颜色、colors显式颜色优先级高于标量色映射、translation/rotation_axis_angle/quaternion网格位姿、opacity、colormap默认 Turbo。官方 Python 示例 docs/snippets/all/archetypes/voxel_grid_map_simple.py 展示了完整的构造方式——6 个稀疏体素索引配合voxel_size[0.25, 0.25, 0.25]并通过translation[-0.5, -0.5, 0.0]将最小角点平移出原点import numpy as np import rerun as rr voxel_indices np.array( [ [-1, 0, 0], [1, 0, 0], [1, 1, 0], [3, 0, 0], [3, 0, 1], [4, 0, 1], ], dtypenp.int32, ) values np.array([0.0, 0.2, 0.4, 0.6, 0.8, 1.0], dtypenp.float32) rr.init(rerun_example_voxel_grid_map_simple, spawnTrue) rr.log( world/voxels, rr.VoxelGridMap( voxel_indices, voxel_size[0.25, 0.25, 0.25], valuesvalues, value_range[0.0, 1.0], colormaprr.components.Colormap.Turbo, translation[-0.5, -0.5, 0.0], ), )注意示例中voxel_indices含负索引[-1, 0, 0]说明稀疏网格的索引域可以是带符号整数translation与voxel_size共同决定了网格在场景中的绝对位置与尺度。使用场景二Volume3D 的推荐字段VoxelSize在 Volume3D 中是推荐recommended字段。Volume3D用于描述稠密 3D 标量场如 CT/MRI 扫描、符号距离场 SDF、规则网格上的占用概率通过光线步进ray marching渲染。其数据为维度按[z, y, x]排列的 3D 张量最后一个维度沿当地 X 轴变化最快与行主序的 Image 切片沿 Z 轴堆叠一致张量元素[k, j, i]即网格索引[i, j, k]处的体素。由于两种 archetype 遵循相同的体素定位约定文档明确指出一个Volume3D与一个具有相同voxel_size和位姿的VoxelGridMap逐体素一致稠密体覆盖索引[0,0,0]到[width-1, height-1, depth-1]。这为同一份空间数据同时以稠密场与稀疏占用两种视图呈现提供了保证。Rust 示例 docs/snippets/all/archetypes/volume3d_simple.rs 演示了在 32³ 网格上构造软球体标量场并设置voxel_size目前仅支持f16值let rec rerun::RecordingStreamBuilder::new(rerun_example_volume3d_simple).spawn()?; // Dimensions are ordered [z, y, x]. Only f16 values are supported for now. let values Array3::from_shape_fn((SIZE, SIZE, SIZE), |(z, y, x)| { // …soft sphere falloff… f16::from_f32((1.0 - distance_sq / (RADIUS * RADIUS)).max(0.0)) }); rec.log( volume, rerun::Volume3D::new(rerun::encodings::TensorData::try_from(values)?) .with_voxel_size([0.1, 0.1, 0.1]), )?;C 示例 docs/snippets/all/archetypes/volume3d_simple.cpp 与之等价通过rerun::Vec3D(0.1f, 0.1f, 0.1f)指定体素尺寸rec.log( volume, rerun::Volume3D({SIZE, SIZE, SIZE}, values) .with_voxel_size(rerun::Vec3D(0.1f, 0.1f, 0.1f)) );Python 侧volume3d_simple.py则是在rr.Volume3D(values.astype(np.float16), voxel_size[0.1, 0.1, 0.1])中作为构造参数直接传入。实践要点与常见误区综合文档与源码使用VoxelSize时有几个要点值得注意尺寸不是体素数voxel_size携带真实场景单位长度与体素数量、索引范围无关包围盒大小 索引跨度 × 体素尺寸支持各向异性三轴分量可不同如激光雷达栅格中地面分辨率高、高度方向粗只要每维有限且为正即可负索引是合法的稀疏网格的voxel_indices可为负定位公式(index 0.5) * voxel_size依然成立最小角点可通过translation偏移到期望位置非法值会导致整批不可渲染传入 0、负数或 NaN 会被可视化器拒绝并上报voxel_size must be finite and positive错误建议在日志端就完成数据清洗与稠密体数据的对齐依赖同一voxel_size若要在同一实体下混用Volume3D与VoxelGridMap务必保证二者voxel_size与位姿一致否则体素将错位。小结VoxelSize虽然只是 Rerun 类型系统中的一个组件却是三维体素数据稀疏占用网格与稠密标量场能否在场景中正确落位、缩放与拾取的关键。从 voxel_size.def.rs 的类型定义、voxel_size.rs 的Vec3D透明包装与FixedSizeList(3 x Float32)Arrow 编码到 voxel_grid_map.rs 中有限且为正的运行时校验再到VoxelGridMap/Volume3D两处 archetype 的配套示例可以看到一个完整的数据契约贯穿了日志端、序列化层与渲染端。掌握这一组件是正确使用 Rerun 进行机器人学、自动驾驶与科学可视化体数据调试的基础。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rerun 组件 VoxelSize 深度解析：稀疏体素网格的场景单位尺寸与数据编码
Rerun 组件 VoxelSize 深度解析稀疏体素网格的场景单位尺寸与数据编码【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读VoxelSize是 Rerun 数据模型中的一个核心三维组件用于描述稀疏体素网格sparse voxel grid中单个体素在场景坐标下的三维尺寸。它同时是VoxelGridMap与Volume3D两个三维体数据 archetype 的关键组成部分直接决定了体素在空间中的物理跨度、包围盒计算与点选交互。本文将结合 Rerun 仓库中的类型定义、生成的 SDK 绑定代码、渲染可视化器实现以及三种语言Python / Rust / C的可运行示例完整讲解VoxelSize的语义约定、编码格式、约束校验与实战用法。组件语义一个体素在场景坐标中的尺寸根据官方组件文档docs/content/reference/types/components/voxel_size.mdVoxelSize定义为稀疏 3D 体素网格中一个体素在场景单位scene-unit下的尺寸。每个分量对应当地网格坐标轴local grid axis上体素的大小。所有分量必须为有限值finite且为正positive。这一定义包含三层关键语义单位是场景单位voxel_size不是体素数或归一化坐标而是直接映射到 3D 场景坐标系即实体坐标系的父子变换链中的物理长度数值本身不带量纲后缀具体量纲由使用者的数据约定决定如米、毫米每个分量对应一条局部网格轴x、y、z三个分量分别描述体素沿当地 X/Y/Z 轴的边长因此允许各向异性非立方体体素有限且为正这是数据不变量invariant不允许 0、负数、NaN 或无穷大避免产生退化或不可渲染的几何体。从仓库中的类型定义源文件 crates/build/re_type_definitions/rerun/components/voxel_size.def.rs 可以看到该组件由re_types_builder统一生成 Rust、Python、C 三种语言的绑定并被标记为#[rerun(state stable)]意味着其数据布局在版本演进中保持向后兼容/// The scene-unit dimensions of one voxel in a sparse 3D voxel grid. /// /// Each component is the size of a voxel along the corresponding local grid axis. /// All components must be finite and positive. #[rerun::rerun_type] #[rust(derive(Copy, PartialEq, bytemuck::Pod, bytemuck::Zeroable))] #[rust(repr transparent)] #[rerun(state stable)] pub struct VoxelSize { pub xyz: rerun::encodings::Vec3D, }体素定位约定中心与最小角点理解VoxelSize的作用必须同时理解 Rerun 对体素网格坐标的统一定位约定。在VoxelGridMap与Volume3D的文档及类型定义中约定完全一致索引为[0, 0, 0]的体素其最小角点minimum corner位于实体坐标系的原点并可通过可选的translation平移与rotation旋转字段在父坐标系中进一步偏移任意体素的中心位于(index 0.5) * voxel_size当地网格坐标相对于最小角点因此voxel_size直接决定了相邻整数索引体素中心之间的间距以及整个网格的包围盒范围。该约定定义于 crates/build/re_type_definitions/rerun/archetypes/voxel_grid_map.def.rs 与 docs/content/reference/types/archetypes/volume3d.mdA voxel center is at(index 0.5) * voxel_sizein local grid coordinates (i.e. relative to the minimum corner).这一索引 × 尺寸 半体素偏移的约定保证了同样voxel_size与位姿下的VoxelGridMap与Volume3D能够逐体素对齐voxel for voxel为混合使用稀疏体素与稠密体数据如占用网格 雷达栅格提供了统一的空间基准。Rerun 编码与 Arrow 数据类型VoxelSize在 Rerun 的序列化层采用单一封装类型Rerun encodingVec3D编码文档Arrow datatypeFixedSizeList(3 x non-null Float32)即固定长度 3、元素为非空Float32的定长列表无内层空值结构紧凑且可直接映射为 GPU/渲染侧的Vec3。生成的 Rust 绑定 crates/store/re_sdk_types/src/components/voxel_size.rs 印证了这一实现VoxelSize是Vec3D的透明包装#[repr(transparent)]并实现了bytemuck::Pod/Zeroable可直接进行无拷贝位级转换组件全名为rerun.components.VoxelSize#[repr(transparent)] pub struct VoxelSize(pub crate::encodings::Vec3D); impl ::re_types_core::WrapperComponent for VoxelSize { type Encoding crate::encodings::Vec3D; fn name() - ComponentType { rerun.components.VoxelSize.into() } // … }同时组件提供FromT: IntoVec3D泛型转换因此在三种语言的 SDK 中都可以直接用[x, y, z]数组或Vec3D构造例如 Rust 侧VoxelSize::from([0.25, 0.25, 0.25])。运行时约束校验渲染层的兜底验证有限且为正不仅是文档约定也是渲染管线中的硬性校验。在空间视图的可视化器实现 crates/views/re_view_spatial/src/visualizers/voxel_grid_map.rs 中绘制前会对voxel_size做显式检查非法值会被上报为 Viewer 错误并跳过绘制let voxel_size glam::Vec3::from_array(voxel_size.0.0); if !voxel_size.is_finite() || !voxel_size.cmpgt(glam::Vec3::ZERO).all() { results.report_for_component( VoxelGridMap::descriptor_voxel_size().component, ViewerReportSeverity::Error, voxel_size must be finite and positive, ); return Ok(None); }从该文件还可以看到voxel_size在渲染链路中的实际用途voxel_grid_map.rs通过min_index.as_vec3() * voxel_size与(max_index 1) * voxel_size计算网格局部包围盒local bbox再经实体→网格变换得到世界包围盒用于视锥剔除与绘制排序voxel_size随VoxelGridOptions一并传入渲染器用于体素几何体立方体的逐实例构建与点选picking命中计算。此外该可视化器还受NUM_VOXEL_LIMIT_PER_BATCH上限约束当体素数超限时会在不改变voxel_size的前提下对实例数封顶并给出警告可在 Settings 中放开限制。使用场景一VoxelGridMap 的必填字段VoxelSize在 VoxelGridMap 中是必填required字段。VoxelGridMap用于描述稀疏 3D 占用网格occupancy map及其他以稀疏体素存储的体积数据其必填字段为voxel_indices网格体积内的体素索引VoxelIndex见 voxel_index.mdvoxel_size单个体素单元的场景单位尺寸沿当地 X/Y/Z 轴定义每维必须有限且为正。可选的着色与位姿字段包括values标量值配合colormap/value_range映射颜色、colors显式颜色优先级高于标量色映射、translation/rotation_axis_angle/quaternion网格位姿、opacity、colormap默认 Turbo。官方 Python 示例 docs/snippets/all/archetypes/voxel_grid_map_simple.py 展示了完整的构造方式——6 个稀疏体素索引配合voxel_size[0.25, 0.25, 0.25]并通过translation[-0.5, -0.5, 0.0]将最小角点平移出原点import numpy as np import rerun as rr voxel_indices np.array( [ [-1, 0, 0], [1, 0, 0], [1, 1, 0], [3, 0, 0], [3, 0, 1], [4, 0, 1], ], dtypenp.int32, ) values np.array([0.0, 0.2, 0.4, 0.6, 0.8, 1.0], dtypenp.float32) rr.init(rerun_example_voxel_grid_map_simple, spawnTrue) rr.log( world/voxels, rr.VoxelGridMap( voxel_indices, voxel_size[0.25, 0.25, 0.25], valuesvalues, value_range[0.0, 1.0], colormaprr.components.Colormap.Turbo, translation[-0.5, -0.5, 0.0], ), )注意示例中voxel_indices含负索引[-1, 0, 0]说明稀疏网格的索引域可以是带符号整数translation与voxel_size共同决定了网格在场景中的绝对位置与尺度。使用场景二Volume3D 的推荐字段VoxelSize在 Volume3D 中是推荐recommended字段。Volume3D用于描述稠密 3D 标量场如 CT/MRI 扫描、符号距离场 SDF、规则网格上的占用概率通过光线步进ray marching渲染。其数据为维度按[z, y, x]排列的 3D 张量最后一个维度沿当地 X 轴变化最快与行主序的 Image 切片沿 Z 轴堆叠一致张量元素[k, j, i]即网格索引[i, j, k]处的体素。由于两种 archetype 遵循相同的体素定位约定文档明确指出一个Volume3D与一个具有相同voxel_size和位姿的VoxelGridMap逐体素一致稠密体覆盖索引[0,0,0]到[width-1, height-1, depth-1]。这为同一份空间数据同时以稠密场与稀疏占用两种视图呈现提供了保证。Rust 示例 docs/snippets/all/archetypes/volume3d_simple.rs 演示了在 32³ 网格上构造软球体标量场并设置voxel_size目前仅支持f16值let rec rerun::RecordingStreamBuilder::new(rerun_example_volume3d_simple).spawn()?; // Dimensions are ordered [z, y, x]. Only f16 values are supported for now. let values Array3::from_shape_fn((SIZE, SIZE, SIZE), |(z, y, x)| { // …soft sphere falloff… f16::from_f32((1.0 - distance_sq / (RADIUS * RADIUS)).max(0.0)) }); rec.log( volume, rerun::Volume3D::new(rerun::encodings::TensorData::try_from(values)?) .with_voxel_size([0.1, 0.1, 0.1]), )?;C 示例 docs/snippets/all/archetypes/volume3d_simple.cpp 与之等价通过rerun::Vec3D(0.1f, 0.1f, 0.1f)指定体素尺寸rec.log( volume, rerun::Volume3D({SIZE, SIZE, SIZE}, values) .with_voxel_size(rerun::Vec3D(0.1f, 0.1f, 0.1f)) );Python 侧volume3d_simple.py则是在rr.Volume3D(values.astype(np.float16), voxel_size[0.1, 0.1, 0.1])中作为构造参数直接传入。实践要点与常见误区综合文档与源码使用VoxelSize时有几个要点值得注意尺寸不是体素数voxel_size携带真实场景单位长度与体素数量、索引范围无关包围盒大小 索引跨度 × 体素尺寸支持各向异性三轴分量可不同如激光雷达栅格中地面分辨率高、高度方向粗只要每维有限且为正即可负索引是合法的稀疏网格的voxel_indices可为负定位公式(index 0.5) * voxel_size依然成立最小角点可通过translation偏移到期望位置非法值会导致整批不可渲染传入 0、负数或 NaN 会被可视化器拒绝并上报voxel_size must be finite and positive错误建议在日志端就完成数据清洗与稠密体数据的对齐依赖同一voxel_size若要在同一实体下混用Volume3D与VoxelGridMap务必保证二者voxel_size与位姿一致否则体素将错位。小结VoxelSize虽然只是 Rerun 类型系统中的一个组件却是三维体素数据稀疏占用网格与稠密标量场能否在场景中正确落位、缩放与拾取的关键。从 voxel_size.def.rs 的类型定义、voxel_size.rs 的Vec3D透明包装与FixedSizeList(3 x Float32)Arrow 编码到 voxel_grid_map.rs 中有限且为正的运行时校验再到VoxelGridMap/Volume3D两处 archetype 的配套示例可以看到一个完整的数据契约贯穿了日志端、序列化层与渲染端。掌握这一组件是正确使用 Rerun 进行机器人学、自动驾驶与科学可视化体数据调试的基础。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考