Rerun VoxelGridMap 稀疏体素网格地图原语字段详解、坐标约定与可视化实现【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本篇围绕 Rerun 的VoxelGridMap原语archetype展开它面向 3D 占用栅格、点云体素化结果等稀疏三维体积数据的可视化与记录场景。读完本文你将掌握VoxelGridMap的全部字段与默认值、索引到世界坐标的换算约定、Python/Rust/C 三语言 SDK 的完整可运行示例以及 Rerun 查看器中该原语的渲染管线细节颜色解析优先级、不透明度处理、体素数量上限等。1. 原语定位与不稳定声明VoxelGridMap被定义为带有网格索引与体素尺寸的稀疏三维体素网格地图A sparse 3D voxel grid map with grid indices and voxel dimensions其设计目标是3D occupancy maps占用栅格地图以及其他表示为稀疏体素网格的体积数据体素沿局部 X/Y/Z 轴使用场景单位scene units尺寸。需要注意官方文档明确标注该类型为unstable不稳定——可能以不保证数据向后兼容的方式发生重大变化。因此用它记录的数据在跨版本重放时可能存在兼容性风险适合用于开发调试与原型验证若需要长期归档建议同时保留原始数据源。2. 坐标与几何约定理解VoxelGridMap的关键在于两条几何规则来自类型定义与 Rust 实现 的文档注释与 C 绑定 一致索引[0, 0, 0]的体素的最小角点minimum corner位于实体坐标系原点。在此之上还可以用可选的translation与rotation_axis_angle/quaternion字段为整个网格施加额外位姿相对于父坐标系。体素中心位置在局部网格坐标相对于最小角点下索引为index的体素中心位于center (index 0.5) * voxel_size索引可以为负数官方示例中就包含了(-1, 0, 0)这样的负索引意味着网格可以越过原点向负方向延伸。每个体素尺寸相同voxel_size是整个网格共享的一个[x, y, z]向量每个维度必须有限且为正渲染器会校验见第 5 节。下面用一个具体数值核对上面的约定。官方示例第 3 节中voxel_size [0.25, 0.25, 0.25]、translation [-0.5, -0.5, 0.0]则体素[0, 0, 0]的中心在局部坐标(0.5, 0.5, 0.5) * 0.25 (0.125, 0.125, 0.125)体素[-1, 0, 0]的中心在(-0.5, 0.5, 0.5) * 0.25 (-0.125, 0.125, 0.125)整个示例网格索引 x ∈ [-1, 4]、y ∈ [0, 1]、z ∈ [0, 1]的世界空间包围盒为[(-0.5, -0.5, 0.0), (1.25, 0.75, 0.5)]。在渲染管线中这一位姿被组合为world_from_grid world_from_entity * entity_from_grid其中entity_from_grid由translation 旋转分量构成见 可视化器实现即实体自身的 Transform 与网格内部位姿叠加生效。3. 字段参考原语共 10 个组件字段2 个必填、0 个推荐、8 个可选可从 Rust 源码 中的REQUIRED_COMPONENTS/OPTIONAL_COMPONENTS常量静态表确认NUM_COMPONENTS 10。必填字段字段组件类型说明voxel_indicesVoxelIndexi32 三元组网格体积内每个体素的整数索引可为负数量即体素数量voxel_sizeVoxelSize[f32; 3]单个体素单元的场景单位尺寸定义局部网格 X/Y/Z 方向上的体素大小每维必须有限且为正可选字段字段组件类型默认值说明valuesVoxelValuef32无每个体素的标量占用率/数值在未提供显式colors时经colormap与value_range映射为颜色colorsColoru32 RGBA无每个体素的显式颜色一旦设置优先于基于标量的 colormap 映射translationTranslation3D无即最小角点在原点体素[0,0,0]最小角点的平移与旋转字段共同定义网格相对父坐标系的位姿rotation_axis_angleRotationAxisAngle无轴 角度的旋转与quaternion二选一两者同时设置时忽略轴角度、以四元数为准quaternionRotationQuat无四元数旋转opacityOpacityf321.0完全不透明颜色/colormap 应用后的体素不透明度value_rangeValueRange[f64; 2][0.0, 1.0]标量到颜色映射的取值区间colormapColormapu8 枚举Turbo当存在values且未提供显式colors时使用的 colormap类型定义的唯一源头是 voxel_grid_map.def.rs——一份供re_types_builder解析的类型描述文件Rust/Python/C 三端绑定与本文对应的参考文档均由它自动生成字段语义因此三端严格一致。4. 完整示例Simple sparse voxel grid map官方文档附带的示例archetypes/voxel_grid_map_simple记录到实体路径world/voxels包含 6 个体素、6 个等差标量值并用 Turbo colormap 着色。三种语言的完整实现分别为 voxel_grid_map_simple.py、voxel_grid_map_simple.rs 与 voxel_grid_map_simple.cpp。4.1 Pythonimport 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], # 每个体素 0.25 场景单位必填 valuesvalues, # 每体素标量与 indices 一一对应 value_range[0.0, 1.0], # 标量归一化区间 colormaprr.components.Colormap.Turbo, translation[-0.5, -0.5, 0.0], # [0,0,0] 最小角点的平移 ), )要点rr.init(..., spawnTrue)会直接拉起查看器进程标量values必须与voxel_indices逐行对应value_range把[0.0, 1.0]线性映射到 colormap 两端。对应的参考实现为 voxel_grid_map.py其中VoxelGridMap.__init__的签名展示了全部 10 个字段的类型约束如voxel_indices: encodings.IVec3DArrayLike、colors: encodings.Rgba32ArrayLike等。4.2 Rustfn main() - Result(), Boxdyn std::error::Error { let rec rerun::RecordingStreamBuilder::new( rerun_example_voxel_grid_map_simple, ) .spawn()?; let voxel_indices [ (-1, 0, 0), (1, 0, 0), (1, 1, 0), (3, 0, 0), (3, 0, 1), (4, 0, 1), ]; let values [0.0_f32, 0.2, 0.4, 0.6, 0.8, 1.0]; rec.log( world/voxels, rerun::VoxelGridMap::new(voxel_indices, [0.25, 0.25, 0.25]) .with_values(values) .with_value_range([0.0, 1.0]) .with_colormap(rerun::components::Colormap::Turbo) .with_translation([-0.5, -0.5, 0.0]), )?; Ok(()) }Rust 端采用new(...)构造必填字段 with_*链式追加可选字段的 builder 风格见 voxel_grid_map.rs。4.3 C#include rerun.hpp #include array #include vector int main(int argc, char* argv[]) { const auto rec rerun::RecordingStream(rerun_example_voxel_grid_map_simple); rec.spawn().exit_on_failure(); const std::vectorrerun::components::VoxelIndex voxel_indices { rerun::components::VoxelIndex(-1, 0, 0), rerun::components::VoxelIndex(1, 0, 0), rerun::components::VoxelIndex(1, 1, 0), rerun::components::VoxelIndex(3, 0, 0), rerun::components::VoxelIndex(3, 0, 1), rerun::components::VoxelIndex(4, 0, 1), }; const std::vectorrerun::components::VoxelValue values { 0.0f, 0.2f, 0.4f, 0.6f, 0.8f, 1.0f, }; rec.log( world/voxels, rerun::archetypes::VoxelGridMap( voxel_indices, std::arrayfloat, 3{0.25f, 0.25f, 0.25f} ) .with_values(values) .with_value_range( rerun::components::ValueRange(std::arraydouble, 2{0.0, 1.0}) ) .with_colormap(rerun::components::Colormap::Turbo) .with_translation({-0.5f, -0.5f, 0.0f}) ); }C 端构造器接受体素索引向量与体素尺寸数组随后同样以with_*链式补齐可选字段实现位于 voxel_grid_map.cpp。5. 查看器端实现细节VoxelGridMap在 Spatial 3D View 中的渲染由 voxel_grid_map.rs 中的VoxelGridMapVisualizer完成以下规则全部有源码依据值得在写数据管线时了解必填校验查询以VoxelIndex组件为单一必填组件voxel_indices为空的实体直接跳过voxel_size若非有限正值!voxel_size.is_finite() || !voxel_size 0会向该组件上报 Error 级报告voxel_size must be finite and positive并放弃绘制L215-L223。体素数量上限常量NUM_VOXEL_LIMIT_PER_BATCH 5_000_000。当启用了查看器设置中的 visualizer limits 且体素数超过 500 万时仅渲染前 500 万个体素并输出 Warning 提示This limit can be lifted in SettingsL23、L244-L261。颜色解析优先级resolve_colorsL338-L399有显式colors直接使用并附 Info 级报告说明 colormap 被忽略有values按t (value - min) / (max - min)归一化后采样 colormap若value_span非有限或 ≤ 0则t回退为 0.5两者都没有使用Color组件的 fallback 颜色并提示 colormap 因缺少标量而失效。不透明度默认 1.0使用时钳制到[0, 1]opacity 1.0时对颜色做 gamma 乘法color.gamma_multiply(opacity)实现透明体素渲染效果有专门的回归测试test_voxel_grid_map_transparent_opacity_snapshot快照 voxel_grid_map_transparent_opacity.png。包围盒与拾取渲染器根据索引的最小/最大值计算局部包围盒[min_index * voxel_size, (max_index 1) * voxel_size]再经world_from_grid变换为世界包围盒每个体素实例支持实例级高亮描边选中某个体素时单独绘制 outline并在 picking 层注册对象 ID。位姿字段互斥规则translation与旋转分量通过entity_from_grid_transform组合成网格局部变换quaternion与rotation_axis_angle冲突时以四元数为准——与类型定义中的注释一致。6. 可用视图与测试回归按照类型定义#[docs(view_types Spatial3DView)]VoxelGridMap可以显示在Spatial3DView文档DataframeView文档仓库中与之相关的可验证材料单元/集成测试crates/store/re_sdk_types/tests/types/voxel_grid_map.rs 覆盖三端类型序列化一致性渲染回归测试crates/views/re_view_spatial/tests/voxel_grid_map.rs 包含两个快照测试——标量 colormap 实例选择选中values实体的第 2 个体素以及前方半透明红体素遮挡后方不透明绿体素的透明度验证记录产物运行官方示例生成的数据文件 voxel_grid_map_simple.rrd可用于回放比对。7. 小结与实践建议VoxelGridMap用整数索引 统一体素尺寸的紧凑表达记录稀疏体积数据天然适合 occupancy 栅格、栅格化激光/深度结果、体素滤波输出等场景数据契约很轻必填仅voxel_indices与voxel_size两个字段着色可三选一显式colors、标量valuescolormap/value_range、fallback 颜色记录时注意索引可以包含负值以覆盖原点之外的区域需要平移整个栅格时用translation而不是逐个修改索引value_range不设置时按[0, 1]归一化数据越界部分会被截断到 colormap 端点由于该类型处于 unstable 状态跨 Rerun 版本使用其.rrd数据时应关注数据兼容性关键资产建议额外留存源数据。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rerun VoxelGridMap 稀疏体素网格地图原语：字段详解、坐标约定与可视化实现
Rerun VoxelGridMap 稀疏体素网格地图原语字段详解、坐标约定与可视化实现【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本篇围绕 Rerun 的VoxelGridMap原语archetype展开它面向 3D 占用栅格、点云体素化结果等稀疏三维体积数据的可视化与记录场景。读完本文你将掌握VoxelGridMap的全部字段与默认值、索引到世界坐标的换算约定、Python/Rust/C 三语言 SDK 的完整可运行示例以及 Rerun 查看器中该原语的渲染管线细节颜色解析优先级、不透明度处理、体素数量上限等。1. 原语定位与不稳定声明VoxelGridMap被定义为带有网格索引与体素尺寸的稀疏三维体素网格地图A sparse 3D voxel grid map with grid indices and voxel dimensions其设计目标是3D occupancy maps占用栅格地图以及其他表示为稀疏体素网格的体积数据体素沿局部 X/Y/Z 轴使用场景单位scene units尺寸。需要注意官方文档明确标注该类型为unstable不稳定——可能以不保证数据向后兼容的方式发生重大变化。因此用它记录的数据在跨版本重放时可能存在兼容性风险适合用于开发调试与原型验证若需要长期归档建议同时保留原始数据源。2. 坐标与几何约定理解VoxelGridMap的关键在于两条几何规则来自类型定义与 Rust 实现 的文档注释与 C 绑定 一致索引[0, 0, 0]的体素的最小角点minimum corner位于实体坐标系原点。在此之上还可以用可选的translation与rotation_axis_angle/quaternion字段为整个网格施加额外位姿相对于父坐标系。体素中心位置在局部网格坐标相对于最小角点下索引为index的体素中心位于center (index 0.5) * voxel_size索引可以为负数官方示例中就包含了(-1, 0, 0)这样的负索引意味着网格可以越过原点向负方向延伸。每个体素尺寸相同voxel_size是整个网格共享的一个[x, y, z]向量每个维度必须有限且为正渲染器会校验见第 5 节。下面用一个具体数值核对上面的约定。官方示例第 3 节中voxel_size [0.25, 0.25, 0.25]、translation [-0.5, -0.5, 0.0]则体素[0, 0, 0]的中心在局部坐标(0.5, 0.5, 0.5) * 0.25 (0.125, 0.125, 0.125)体素[-1, 0, 0]的中心在(-0.5, 0.5, 0.5) * 0.25 (-0.125, 0.125, 0.125)整个示例网格索引 x ∈ [-1, 4]、y ∈ [0, 1]、z ∈ [0, 1]的世界空间包围盒为[(-0.5, -0.5, 0.0), (1.25, 0.75, 0.5)]。在渲染管线中这一位姿被组合为world_from_grid world_from_entity * entity_from_grid其中entity_from_grid由translation 旋转分量构成见 可视化器实现即实体自身的 Transform 与网格内部位姿叠加生效。3. 字段参考原语共 10 个组件字段2 个必填、0 个推荐、8 个可选可从 Rust 源码 中的REQUIRED_COMPONENTS/OPTIONAL_COMPONENTS常量静态表确认NUM_COMPONENTS 10。必填字段字段组件类型说明voxel_indicesVoxelIndexi32 三元组网格体积内每个体素的整数索引可为负数量即体素数量voxel_sizeVoxelSize[f32; 3]单个体素单元的场景单位尺寸定义局部网格 X/Y/Z 方向上的体素大小每维必须有限且为正可选字段字段组件类型默认值说明valuesVoxelValuef32无每个体素的标量占用率/数值在未提供显式colors时经colormap与value_range映射为颜色colorsColoru32 RGBA无每个体素的显式颜色一旦设置优先于基于标量的 colormap 映射translationTranslation3D无即最小角点在原点体素[0,0,0]最小角点的平移与旋转字段共同定义网格相对父坐标系的位姿rotation_axis_angleRotationAxisAngle无轴 角度的旋转与quaternion二选一两者同时设置时忽略轴角度、以四元数为准quaternionRotationQuat无四元数旋转opacityOpacityf321.0完全不透明颜色/colormap 应用后的体素不透明度value_rangeValueRange[f64; 2][0.0, 1.0]标量到颜色映射的取值区间colormapColormapu8 枚举Turbo当存在values且未提供显式colors时使用的 colormap类型定义的唯一源头是 voxel_grid_map.def.rs——一份供re_types_builder解析的类型描述文件Rust/Python/C 三端绑定与本文对应的参考文档均由它自动生成字段语义因此三端严格一致。4. 完整示例Simple sparse voxel grid map官方文档附带的示例archetypes/voxel_grid_map_simple记录到实体路径world/voxels包含 6 个体素、6 个等差标量值并用 Turbo colormap 着色。三种语言的完整实现分别为 voxel_grid_map_simple.py、voxel_grid_map_simple.rs 与 voxel_grid_map_simple.cpp。4.1 Pythonimport 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], # 每个体素 0.25 场景单位必填 valuesvalues, # 每体素标量与 indices 一一对应 value_range[0.0, 1.0], # 标量归一化区间 colormaprr.components.Colormap.Turbo, translation[-0.5, -0.5, 0.0], # [0,0,0] 最小角点的平移 ), )要点rr.init(..., spawnTrue)会直接拉起查看器进程标量values必须与voxel_indices逐行对应value_range把[0.0, 1.0]线性映射到 colormap 两端。对应的参考实现为 voxel_grid_map.py其中VoxelGridMap.__init__的签名展示了全部 10 个字段的类型约束如voxel_indices: encodings.IVec3DArrayLike、colors: encodings.Rgba32ArrayLike等。4.2 Rustfn main() - Result(), Boxdyn std::error::Error { let rec rerun::RecordingStreamBuilder::new( rerun_example_voxel_grid_map_simple, ) .spawn()?; let voxel_indices [ (-1, 0, 0), (1, 0, 0), (1, 1, 0), (3, 0, 0), (3, 0, 1), (4, 0, 1), ]; let values [0.0_f32, 0.2, 0.4, 0.6, 0.8, 1.0]; rec.log( world/voxels, rerun::VoxelGridMap::new(voxel_indices, [0.25, 0.25, 0.25]) .with_values(values) .with_value_range([0.0, 1.0]) .with_colormap(rerun::components::Colormap::Turbo) .with_translation([-0.5, -0.5, 0.0]), )?; Ok(()) }Rust 端采用new(...)构造必填字段 with_*链式追加可选字段的 builder 风格见 voxel_grid_map.rs。4.3 C#include rerun.hpp #include array #include vector int main(int argc, char* argv[]) { const auto rec rerun::RecordingStream(rerun_example_voxel_grid_map_simple); rec.spawn().exit_on_failure(); const std::vectorrerun::components::VoxelIndex voxel_indices { rerun::components::VoxelIndex(-1, 0, 0), rerun::components::VoxelIndex(1, 0, 0), rerun::components::VoxelIndex(1, 1, 0), rerun::components::VoxelIndex(3, 0, 0), rerun::components::VoxelIndex(3, 0, 1), rerun::components::VoxelIndex(4, 0, 1), }; const std::vectorrerun::components::VoxelValue values { 0.0f, 0.2f, 0.4f, 0.6f, 0.8f, 1.0f, }; rec.log( world/voxels, rerun::archetypes::VoxelGridMap( voxel_indices, std::arrayfloat, 3{0.25f, 0.25f, 0.25f} ) .with_values(values) .with_value_range( rerun::components::ValueRange(std::arraydouble, 2{0.0, 1.0}) ) .with_colormap(rerun::components::Colormap::Turbo) .with_translation({-0.5f, -0.5f, 0.0f}) ); }C 端构造器接受体素索引向量与体素尺寸数组随后同样以with_*链式补齐可选字段实现位于 voxel_grid_map.cpp。5. 查看器端实现细节VoxelGridMap在 Spatial 3D View 中的渲染由 voxel_grid_map.rs 中的VoxelGridMapVisualizer完成以下规则全部有源码依据值得在写数据管线时了解必填校验查询以VoxelIndex组件为单一必填组件voxel_indices为空的实体直接跳过voxel_size若非有限正值!voxel_size.is_finite() || !voxel_size 0会向该组件上报 Error 级报告voxel_size must be finite and positive并放弃绘制L215-L223。体素数量上限常量NUM_VOXEL_LIMIT_PER_BATCH 5_000_000。当启用了查看器设置中的 visualizer limits 且体素数超过 500 万时仅渲染前 500 万个体素并输出 Warning 提示This limit can be lifted in SettingsL23、L244-L261。颜色解析优先级resolve_colorsL338-L399有显式colors直接使用并附 Info 级报告说明 colormap 被忽略有values按t (value - min) / (max - min)归一化后采样 colormap若value_span非有限或 ≤ 0则t回退为 0.5两者都没有使用Color组件的 fallback 颜色并提示 colormap 因缺少标量而失效。不透明度默认 1.0使用时钳制到[0, 1]opacity 1.0时对颜色做 gamma 乘法color.gamma_multiply(opacity)实现透明体素渲染效果有专门的回归测试test_voxel_grid_map_transparent_opacity_snapshot快照 voxel_grid_map_transparent_opacity.png。包围盒与拾取渲染器根据索引的最小/最大值计算局部包围盒[min_index * voxel_size, (max_index 1) * voxel_size]再经world_from_grid变换为世界包围盒每个体素实例支持实例级高亮描边选中某个体素时单独绘制 outline并在 picking 层注册对象 ID。位姿字段互斥规则translation与旋转分量通过entity_from_grid_transform组合成网格局部变换quaternion与rotation_axis_angle冲突时以四元数为准——与类型定义中的注释一致。6. 可用视图与测试回归按照类型定义#[docs(view_types Spatial3DView)]VoxelGridMap可以显示在Spatial3DView文档DataframeView文档仓库中与之相关的可验证材料单元/集成测试crates/store/re_sdk_types/tests/types/voxel_grid_map.rs 覆盖三端类型序列化一致性渲染回归测试crates/views/re_view_spatial/tests/voxel_grid_map.rs 包含两个快照测试——标量 colormap 实例选择选中values实体的第 2 个体素以及前方半透明红体素遮挡后方不透明绿体素的透明度验证记录产物运行官方示例生成的数据文件 voxel_grid_map_simple.rrd可用于回放比对。7. 小结与实践建议VoxelGridMap用整数索引 统一体素尺寸的紧凑表达记录稀疏体积数据天然适合 occupancy 栅格、栅格化激光/深度结果、体素滤波输出等场景数据契约很轻必填仅voxel_indices与voxel_size两个字段着色可三选一显式colors、标量valuescolormap/value_range、fallback 颜色记录时注意索引可以包含负值以覆盖原点之外的区域需要平移整个栅格时用translation而不是逐个修改索引value_range不设置时按[0, 1]归一化数据越界部分会被截断到 colormap 端点由于该类型处于 unstable 状态跨 Rerun 版本使用其.rrd数据时应关注数据兼容性关键资产建议额外留存源数据。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考