Rerun Radius 组件深度解析场景单位Scene Units与 UI Points 双模式尺寸语义【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunRadius 是 Rerun 数据类型体系中负责表达尺寸的核心组件用于描述点、线、箭头、包围盒、圆柱体、胶囊体、椭球体等图元的半径。它最独特的设计在于同一个Float32标量通过符号位同时编码场景单位与UI Points两套度量体系让开发者既能绘制随视角缩放的真实尺寸物体也能绘制恒定屏幕大小的标记。本文将以 radius.md 为主线结合仓库内的类型定义、自动生成的 SDK 绑定与官方示例完整讲解 Radius 的编码原理、边界值语义、跨语言 API 用法及其在 16 个 Archetype 中的实际应用。Radius 组件的定位与定义Radius 的官方定义只有一句话The radius of something, e.g. a point.某物体的半径例如一个点的半径。它属于rerun.components.Radius状态为stable稳定意味着其语义与序列化格式已固化可放心在长期项目中依赖。该组件的规范源头位于类型定义文件 radius.def.rs#[rerun::rerun_type] #[python(aliases float)] #[python(array_aliases float | npt.ArrayLike)] #[rust(derive(Copy, PartialEq, PartialOrd, bytemuck::Pod, bytemuck::Zeroable))] #[rust(repr transparent)] #[rerun(state stable)] pub struct Radius { pub value: rerun::encodings::Float32, }这份.def.rs是 Rerun 代码生成管线的单一事实来源由re_types_builder解析Rust、Python、C 三端 SDK 的Radius类型都由它统一生成从而保证三端语义完全一致。值得注意的是#[rust(repr transparent)]与bytemuck::Pod / Zeroable意味着 Radius 在内存中与Float32布局完全一致可零拷贝地与 Arrow 数组互转#[python(aliases float)]允许 Python 侧直接传普通float字面量#[python(array_aliases float | npt.ArrayLike)]允许传 NumPy 数组批量指定半径。双单位编码一个Float32表达两种度量体系Radius 最重要的设计决策是用值的符号区分单位这是理解该组件的关键内部存储中正值表示场景单位scene units负值被解释为 UI Points。这意味着 Radius 根本不需要额外的判别字段tag/discriminator序列化时就是一个裸Float32紧凑且高效。Rust 侧的手写扩展实现位于 radius_ext.rs通过两个构造函数和两个访问器完成符号语义的封装/// Creates a new radius in scene units. /// Values passed must be finite positive. pub fn new_scene_units(radius_in_scene_units: f32) - Self { debug_assert!(0.0 radius_in_scene_units, Bad radius: {radius_in_scene_units}); Self(Float32(radius_in_scene_units)) } /// Creates a new radius in ui points. /// Values passed must be finite positive. pub fn new_ui_points(radius_in_ui_points: f32) - Self { debug_assert!(0.0 radius_in_ui_points, Bad radius: {radius_in_ui_points}); Self(Float32(-radius_in_ui_points)) } pub fn scene_units(self) - Optionf32 { self.0.is_sign_positive().then_some(*self.0) } pub fn ui_points(self) - Optionf32 { self.0.is_sign_negative().then_some(-*self.0) }两种度量的物理含义截然不同对应两种典型的使用诉求度量体系存储值行为特征典型用途场景单位Scene Units正值与视图缩放联动随相机拉近拉远而等比放大缩小是真实世界尺寸机器人的点云、路标点、包围盒、圆柱半径等需要表达真实几何尺寸的对象UI Points负值与视图缩放无关恒定屏幕尺寸但对应用 UI 缩放敏感交互标记、关键点、类别标签的锚点等需要始终清晰可见的 UI 元素关于 UI Points 的缩放行为官方文档明确给出了换算基准100% UI 缩放时1 UI Point 1 像素Viewer 的 UI 缩放默认跟随操作系统缩放例如全高清Full HD屏幕通常为 100%4K 屏幕通常为 200%。因此同一个半径值在 4K 高分屏上会被自动放大一倍以像素计从而在不同 DPI 的屏幕上保持一致的视觉尺寸——这正是UI Points相对裸像素的优势。边界值与特殊值符号语义的严谨落地由于 Radius 用符号位承载语义零值0.0与负零-0.0就成了必须明确区分的边界情况。实现中特意使用is_sign_positive()/is_sign_negative()而非 0/ 0比较正是为了把 IEEE 754 中的-0.0正确归类为 UI Points负零是有效的负号值。这一细节由 radius_ext.rs 中的单元测试scene_point_distinction完整覆盖let radius Radius(Float32(1.0)); // scene_units() Some(1.0), ui_points() None let radius Radius(Float32(-1.0)); // scene_units() None, ui_points() Some(1.0) let radius Radius(Float32(f32::INFINITY)); // scene_units() Some(inf) let radius Radius(Float32(f32::NEG_INFINITY)); // ui_points() Some(inf) let radius Radius(Float32(0.0)); // scene_units() Some(0.0) let radius Radius(Float32(-0.0)); // scene_units() None, ui_points() Some(0.0)可以看到正负无穷也被符号位正确分流。此外radius_ext.rs还提供了两个常用常量和默认值pub const ZERO: Self Self(Float32(0.0)); // 零半径场景单位 pub const ONE_UI_POINTS: Self Self(Float32(-1.0)); // 1 个 UI Point 的半径 impl Default for Radius { fn default() - Self { Self::new_ui_points(1.5) } }默认半径为 1.5 个 UI Points当用户未显式指定半径时图元会以约 1.5 像素100% 缩放下的屏幕尺寸绘制保证开了点但没给半径也能立即看见。两个构造函数内部都用debug_assert!校验入参必须为非负防止把负值误解为反向半径造成歧义。数据编码与 Arrow 表示Radius 的序列化链路非常直接Rerun 编码encodingFloat32Arrow 数据类型datatypeFloat32即在数据帧Dataframe与磁盘存储中一个 Radius 就是 4 字节单精度浮点数无任何额外开销。自动生成的 Rust 绑定见 radius.rs其核心结构为#[repr(transparent)] pub struct Radius(pub crate::encodings::Float32); impl ::re_types_core::WrapperComponent for Radius { type Encoding crate::encodings::Float32; fn name() - ComponentType { rerun.components.Radius.into() } }它实现了Deref / DerefMut、FromT: IntoFloat32、Copy / PartialEq / PartialOrd等 trait因此在实际使用中 Radius 与普通f32几乎可以互换任何能转成Float32的类型都能直接IntoRadius配合with_radii这类批量写入接口使用非常顺滑。跨语言 API 使用指南Radius 在 Rust、Python、C 三端均有对称的 API下面是三端对照表以官方示例 points3d_ui_radius 为参照语义RustPythonC场景单位Radius::new_scene_units(0.3)或直接传0.3f32rr.Radius.scene_units(0.3)或直接传0.3rerun::Radius::scene_units(0.3f)UI PointsRadius::new_ui_points(40.0)rr.Radius.ui_points(40.0)rerun::Radius::ui_points(40.0f)常量1 UI PointRadius::ONE_UI_POINTS——注Python 与 C 的构造器名为ui_points/scene_units见 geo_points_simple.py、line_strips3d_ui_radius.rs 等示例Rust 端则为new_ui_points/new_scene_units命名略有差异但语义一致。Rust 示例同帧混合两种单位fn main() - Result(), Boxdyn std::error::Error { let rec rerun::RecordingStreamBuilder::new(rerun_example_points3d_ui_radius).spawn()?; // 两个蓝色点场景单位半径 0.1 与 0.3随视角缩放 rec.log( scene_units, rerun::Points3D::new([(0.0, 1.0, 0.0), (1.0, 1.0, 1.0)]) .with_radii([0.1, 0.3]) // 默认即场景单位 .with_colors([rerun::Color::from_rgb(0, 0, 255)]), )?; // 两个红色点UI Points 半径 40 与 60恒定屏幕尺寸 rec.log( ui_points, rerun::Points3D::new([(0.0, 0.0, 0.0), (1.0, 0.0, 1.0)]) .with_radii([ rerun::Radius::new_ui_points(40.0), rerun::Radius::new_ui_points(60.0), ]) .with_colors([rerun::Color::from_rgb(255, 0, 0)]), )?; Ok(()) }Python 示例完全等价的写法import rerun as rr rr.init(rerun_example_points3d_ui_radius, spawnTrue) # 场景单位默认行为 rr.log( scene_units, rr.Points3D([[0, 1, 0], [1, 1, 1]], radii[0.1, 0.3], colors[0, 0, 255]), ) # UI Points通过 rr.Radius.ui_points 显式声明 rr.log( ui_points, rr.Points3D( [[0, 0, 0], [1, 0, 1]], radiirr.Radius.ui_points([40.0, 60.0]), # 批量传入数组 colors[255, 0, 0], ), )Python 侧由于array_aliases的存在rr.Radius.ui_points(...)既能接收单个float也能接收npt.ArrayLike数组与radii[...]逐点对齐。底层写入机制在 Archetype 层面radii字段通过with_radii统一写入。以 Points3D 为例其实现位于 points3d.rs/// Optional radii for the points, effectively turning them into circles. pub fn with_radii( mut self, radii: impl IntoIteratorItem impl Intocrate::components::Radius, ) - Self { self.radii try_serialize_field(Self::descriptor_radii(), radii); self }注意impl IntoRadius的泛型约束传入的每个元素都会被自动转换为Radius因此直接传f32字面量时默认按场景单位解释只有显式调用new_ui_points/ui_points才会编码为 UI Points。在 Points3D 的字段体系中radii属于Recommended推荐字段与colors同级——这意味着绘图时给出半径是常见的最佳实践但并非强制。使用 Radius 的 Archetype 全景根据组件参考文档Radius被 16 个 Archetype 引用覆盖了 Rerun 几乎所有的几何图元。按用途可归纳为五类1. 点与轨迹类Points2D、Points3D半径把点变成可见圆斑LineStrips2D、LineStrips3D折线的线宽GraphNodes图结构中的节点大小。2. 箭头与刚体类Arrows2D、Arrows3D箭头杆身的粗细Capsules3D、Cylinders3D胶囊体与圆柱的截面半径。3. 包围盒与曲面类Boxes2D、Boxes3D圆角包围盒的圆角半径Ellipses2D、Ellipsoids3D椭圆/椭球体的轴半径。4. 地理空间类GeoPoints、GeoLineStrings地图上的点位与路径宽度官方示例中即用Radius::ui_points指定恒定屏幕尺寸见 geo_points_simple.py。5. 相机模型类Pinhole针孔相机模型相关的半径描述。实践建议与易错点综合官方文档与源码实现使用 Radius 时有几个关键经验值得记录单位混用是最大陷阱with_radii([0.1, 0.3])直接传字面量 场景单位要固定屏幕尺寸必须显式用ui_points系构造器。若在一个批次中混入两种语义务必逐元素确认符号。零半径与负零0.0是场景单位下的零-0.0则是0 个 UI Points。Rust 实现用is_sign_negative()精确区分二者序列化往返不会丢失该语义。默认值兜底未指定半径时使用new_ui_points(1.5)1.5 个 UI Points保证图元始终可见因此忘设半径不会导致画面空无一物。UI 缩放联动UI Points 不随视图缩放但会随应用 UI 缩放等比变化100% 缩放时 1 UI Point 1 像素。若你的场景需要无论 1080p 还是 4K 屏幕都保持相同屏幕尺寸UI Points 是正确的选择反之需要真实世界尺寸感如机器人导航中的障碍物半径请使用场景单位。通过本文对 radius.md、radius.def.rs、radius_ext.rs 及官方示例的交叉解读可以看出 Radius 是 Rerun 中小类型、深设计的典型代表一个 4 字节浮点数以符号位承载双单位语义再经由代码生成管线在 Rust/Python/C 三端提供一致的构造器、常量与默认值最终支撑起从点云到地图、从包围盒到相机模型的整套可视化体系。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考