Rerun 组件 ValueRange 详解：深度/张量/体素数据的数值范围定义与底层实现

Rerun 组件 ValueRange 详解深度/张量/体素数据的数值范围定义与底层实现【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读ValueRange是 Rerun 数据模型re_sdk_types中一个用于声明数据期望或合法取值区间的组件类型它由一个浮点下界和一个浮点上界构成在深度图、张量、体素网格等场景中扮演着数据范围标注与可视化映射依据的角色。本文以 docs/content/reference/types/components/value_range.md 为主线结合仓库中的类型定义、Rust 生成代码、扩展实现与可视化面板源码完整讲解其语义、Arrow 编码、跨语言 API 形态、使用方式与底层存储细节帮助你理解并正确使用这一组件。⚠️稳定性提示ValueRange当前处于unstable状态后续可能发生不保证向后兼容的显著变更。在生产数据管道中引用该类型时请留意 Rerun 的版本更新与变更日志。一、组件语义它到底描述什么Rerun 的类型体系将语义组件component与数据结构datatype严格分层组件表达业务语义而结构只负责承载原始数据。ValueRange属于前者其官方定义非常精炼Range of expected or valid values, specifying a lower and upper bound. 期望值或合法值区间指定一个下界与上界。这意味着该组件并不包含数据本体而是对同一实体entity上其他数据的取值约束声明。从类型定义源码 crates/build/re_type_definitions/rerun/components/value_range.def.rs 可以看到它的声明方式/// Range of expected or valid values, specifying a lower and upper bound. #[rerun::rerun_type] #[rerun(state unstable)] #[rust(derive(Copy, PartialEq, bytemuck::Pod, bytemuck::Zeroable))] #[rust(repr transparent)] pub struct ValueRange { pub range: rerun::encodings::Range1D, }三个关键信息结构体内只有单一字段range类型是内建的Range1D编码encodingstate unstable是文档页开头不稳定警告的直接来源repr transparent说明它仅仅是Range1D的一层薄封装运行期没有额外开销。Rerun 使用这些.def.rs类型定义文件位于 crates/build/re_type_definitions/rerun/components/通过re_types_builder代码生成器统一产出 Rust、Python、C 三套语言绑定——这正是文档页底部三个语言 API 链接的由来。文档页顶部DO NOT EDIT注释也表明该 Markdown 是由 crates/build/re_types_builder/src/codegen/docs/website.rs 自动生成的类型参考页。二、Rerun 编码Range1D 与它的实现ValueRange的底层编码为Range1D其定义在 docs/content/reference/types/encodings/range1d.md一个一维区间同样由下界与上界组成。对应到 Rust 实现 crates/store/re_sdk_types/src/encodings/range1d.rsRange1D是一个包含两个f64的透明元组结构体#[repr(C)] pub struct Range1D(pub [f64; 2usize]);下标 0 为下界start下标 1 为上界end。因为ValueRange对Range1D实现了Deref/DerefMut见下文所以通过ValueRange实例可以直接按索引访问这两个值。Range1D同时也是其他区间类类型的共享基础编码——从 docs/content/reference/types/encodings/range1d.md 的 Used by 列表可知除ValueRange外Range1D组件与Range2D编码也复用了同一套区间概念体现 Rerun 中编码可被多个组件复用的设计。三、Arrow 数据格式FixedSizeList(2 x non-null Float64)ValueRange的官方文档给出其 Arrow 数据格式为FixedSizeList(2 x non-null Float64)这一格式由Range1D的序列化实现直接决定。在 crates/store/re_sdk_types/src/encodings/range1d.rs 中可以看到 Arrow 类型声明fn arrow_data_type() - arrow::datatypes::DataType { use arrow::datatypes::*; DataType::FixedSizeList( std::sync::Arc::new(Field::new(item, DataType::Float64, false)), 2, ) }逐项解读记号含义对应实现FixedSizeList定长列表每个元素恰好包含 2 个子项DataType::FixedSizeList(_, 2)2列表长度恒为 2下界、上界各一构造参数2non-null Float64每个子项都是非空的 64 位浮点数Field::new(item, DataType::Float64, false)false即不允许 null序列化路径ToArrow会将Range1D([start, end])展平为连续的两个f64打包进FixedSizeListArray反序列化路径FromArrow则按相同布局还原见同一文件的impl FromArrow。选择FixedSizeList而非变长List的原因也很直接区间结构长度恒定定长布局在内存中紧凑连续、便于 SIMD 与随机访问也避免了每行存储长度前缀的开销。由于子项与列表本身均声明为非空一个合法的ValueRange不会出现只给了下界或包含 null的半残状态。四、跨语言 APIValueRange 在不同 SDK 中的形态Rerun 从同一份类型定义生成多语言绑定ValueRange在三种官方 SDK 中均有对应入口Crerun::components::ValueRange见 C API 参考Pythonrerun.components.ValueRange见 Python API 参考Rustrerun::components::ValueRange见 docs.rs 文档4.1 Rust 侧透明封装与便捷构造生成的组件代码位于 crates/store/re_sdk_types/src/components/value_range.rs核心是一个repr(transparent)的包装类型pub struct ValueRange(pub crate::encodings::Range1D);并实现了WrapperComponent组件注册名为rerun.components.ValueRange第 40-42 行编码类型为Range1DFromT: IntoRange1D任何能转成Range1D的值如[f64; 2]都能直接into()成ValueRangeDeref/DerefMut可直接以Range1D的视角操作BorrowRange1D、Clone、Copy、PartialEq以及bytemuck::Pod/Zeroable内存零拷贝、可直接按字节解释等底层 trait。真正面向使用者的构造与访问方法定义在扩展文件 crates/store/re_sdk_types/src/components/value_range_ext.rs 中Rerun 将手写逻辑与生成代码分离的典型模式impl ValueRange { pub fn new(start: f64, end: f64) - Self; // 构造 [start, end] pub fn start(self) - f64; // 下界 pub fn end(self) - f64; // 上界 pub fn start_mut(mut self) - mut f64; // 可变下界 pub fn end_mut(mut self) - mut f64; // 可变上界 }其Display输出格式为[start, end]例如[0.0, 1.0]。值得注意的默认值实现impl Default for ValueRange { fn default() - Self { Self::new(0.0, 1.0) } }即未显式指定时默认区间为[0.0, 1.0]。4.2 Python 侧列表字面量直接传入在 Python SDK 中ValueRange通常无需手动构造直接传[start, end]形式的双元素列表即可被自动转换。以体素网格示例 docs/snippets/all/archetypes/voxel_grid_map_simple.py 为例voxel_grid_map rr.archetypes.VoxelGridMap( ..., value_range[0.0, 1.0], )同主题的 Cvoxel_grid_map_simple.cpp与 Rustvoxel_grid_map_simple.rs示例位于 docs/snippets/all/archetypes/ 下可对照三种语言的使用差异。4.3 C 侧C 绑定由相同定义生成结构与 Rust 一致rerun::components::ValueRange内部持有rerun::encodings::Range1D同样提供区间构造与访问接口。五、使用场景哪些 Archetype 用到了 ValueRange根据文档页 Used by 列表ValueRange被以下五种 archetype 作为可选字段使用Archetype字段名语义对应定义文件DepthImagedepth_range深度值的显示/有效范围depth_image.def.rsEncodedDepthImagedepth_range编码深度流的深度范围encoded_depth_image.def.rsTensorvalue_range张量元素的数值范围tensor.def.rsVolume3Dvalue_range体数据的取值窗口volume_3d.def.rsVoxelGridMapvalue_range体素场数值的显示范围voxel_grid_map.def.rs5.1 典型例子DepthImage以 docs/content/reference/types/archetypes/depth_image.md 为例DepthImage的可选字段包括buffer必填ImageBufferformat必填ImageFormatmeterDepthMeter深度单位换算colormapColormapdepth_rangeValueRange← 本文主题point_fill_ratio、draw_order、magnification_filter深度图由深度相机采集每个像素是一个按DepthMeter单位解释的深度值。depth_range在此处用于声明深度值的期望区间可视化端据此决定色彩映射等处理所覆盖的数值窗口。5.2 可视化端如何消费它ValueRange不是被存储后就闲置的元数据查看器端会主动读取它。例如张量视图在构建可视化器时读取该组件见 crates/views/re_view_tensor/src/visualizer_system.rs体素网格与编码深度视频的可视化器同样引用它见 crates/views/re_view_spatial/src/visualizers/voxel_grid_map.rs 与 crates/views/re_view_spatial/src/visualizers/video/encoded_depth_image.rs组件 UI 层为它注册了专门的区间编辑器edit_view_range1d见 crates/viewer_support/re_component_ui/src/lib.rs用户在查看器中可直接以区间控件形式查看和编辑该值当组件缺失时由 fallback 逻辑补上默认值见 crates/viewer_support/re_component_fallbacks/src/component_fallbacks.rs与 Rust 侧Default的[0.0, 1.0]保持一致。六、在日志 API 中的实际用法实际开发中最常见的用法是不直接 log 这个组件而是通过 archetype 的命名参数/字段顺带写入。以 Python 为例import rerun as rr # 深度图通过 depth_range 传入期望区间 rr.log( world/camera/depth, rr.DepthImage( dataz_vals, # 深度数据 meter0.001, # 每单位对应毫米 depth_range[0.0, 10.0], # ValueRange[下界, 上界] ), ) # 张量通过 value_range 指定数值窗口 rr.log(sensor/tensor, rr.Tensor(datatensor_data, value_range[-1.0, 1.0])) # 体素网格同样使用 value_range rr.log( map/voxels, rr.VoxelGridMap(grid..., value_range[0.0, 1.0]), )从 Rust 实现value_range_ext.rs可知传入的列表会被严格映射为二元组[start, end]并在序列化时以两个非空f64写入FixedSizeList(2)。因此列表必须恰好包含两个数值下界、上界数值类型应为浮点整型会在语言层转换但底层始终以Float64存储空区间下界 上界或上下界颠倒在类型层面不会被拒绝——该组件只声明区间语义校验由具体可视化逻辑负责。七、与其他区间类型的区别Rerun 的类型体系中存在一组容易混淆的区间类型建议按用途区分类型层级含义ValueRange本文组件数据的期望/合法取值范围供张量、深度、体素等可视化使用Range1D编码datatype一维区间[start, end]的纯数据结构被ValueRange等复用Range2D编码二维区间同样以Range1D为基础扩展见 range1d.md 的 Used by简言之ValueRange是带语义的组件Range1D是无语义的容器。前者负责告诉查看器数据应该在哪个窗口内解释后者只负责把两个浮点数组织成 Arrow 定长列表。八、小结ValueRange是 Rerun 数据类型体系中的一个基础组件语义声明数据的期望/合法区间当前标记为 unstable编码包装Range1D[f64; 2]Arrow 存储为FixedSizeList(2 x non-null Float64)使用无需单独构造通常通过DepthImage.depth_range、Tensor.value_range、Volume3D.value_range、VoxelGridMap.value_range等 archetype 可选字段以[start, end]形式传入默认值[0.0, 1.0]RustDefault与组件 fallback 一致消费方张量视图、体素网格/编码深度可视化器、组件 UI 区间编辑器re_component_ui/src/lib.rs。掌握这个组件是正确控制深度图、张量与体素数据的数值窗口、让可视化结果贴合真实物理量纲的第一步。由于它仍处于 unstable 状态升级 Rerun 版本时请关注 CHANGELOG.md 中对类型系统的变更记录。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考