Rerun Points2D 原型深度解析：2D 点云的数据字段、半径语义与可视化实战

Rerun Points2D 原型深度解析2D 点云的数据字段、半径语义与可视化实战【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文围绕 Rerun 数据模型中的Points2D原型Archetype展开完整覆盖它的必填/推荐/可选字段、Radius组件正值为场景单位、负值为 UI 点数的底层编码语义以及 Spatial2DView 等视图的承载方式并配合仓库内 Rust/Python 三种语言的官方示例带你掌握从记录 2D 点云到设置视图边界的完整实战流程。读完本文你将能够正确构造带颜色、半径、标签、分类信息的 2D 点云数据并理解每个字段在 Rerun 存储与渲染管线中的实际作用。一、Points2D 是什么一个面向 2D 点云的数据原型在 Rerun 的数据模型中Archetype原型是结构化数据的模板它把若干Component组件按必填 / 推荐 / 可选三个层级组织起来每个字段对应一个强类型的 Arrow 数组列。Points2D的原型定义是A 2D point cloud with positions and optional colors, radii, labels, etc.一个带有位置以及可选颜色、半径、标签等属性的 2D 点云。它适用于任何平面上的点集合场景2D 图像上的关键点检测结果、2D 标注、轨迹点、检测框中心点等。Rust 侧的实现由 Points2D 原型定义 承载该文件由crates/build/re_types_builder基于crates/build/re_type_definitions/rerun/archetypes/points2d.def.rs自动代码生成其组件注册信息ComponentDescriptor会把它标识为rerun.archetypes.Points2D每个字段都携带形如Points2D:positions的组件描述符与对应的组件类型如rerun.components.Position2D。1.1 字段总览层级字段组件类型语义RequiredpositionsPosition2D点云中每个点所在的 2D 坐标x, y是唯一必填字段RecommendedradiiRadius每个点的半径使点变成圆RecommendedcolorsColor每个点的颜色OptionallabelsText每个点的文本标签Optionalshow_labelsShowLabels是否显示文本标签Optionaldraw_orderDrawOrder2D 绘制顺序值越大越靠上默认30.0Optionalclass_idsClassId类别 ID未显式指定颜色/标签时可由它回退提供Optionalkeypoint_idsKeypointId关键点 ID用于在同一个类别内部进一步区分点从 原型源码 的结构看Points2D的 8 个字段全部是OptionSerializedComponentBatch—— 即每个字段都是一段可选的 Arrow 序列化批次字段间长度通常保持一致每个点一行数据NUM_COMPONENTS常量标注为81 必填 2 推荐 5 可选。new()构造函数只接受positions其余字段通过with_radii、with_colors、with_labels、with_show_labels、with_draw_order、with_class_ids、with_keypoint_ids等链式方法按需填充此外还提供update_fields()构造一个空批次用于局部更新与clear_fields()用各组件的空 Arrow 数组清空全部字段这类增量记录辅助方法。几个值得注意的字段语义细节labels如果该实体上只有一个标签它会被放在实体中心否则每个实例点各带一个标签。show_labels如果不显式设置标签会在实体上恰好只有一个标签、或实例数低于某个阈值时自动显示。class_ids/keypoint_ids的组合这是关键点检测的典型用法——例如类别是Person而keypoint_id指代该骨架上的各个关节。如果只传了keypoint_ids而没有class_idsClassId会默认取 0。1.2 支持的视图Points2D可以在以下视图中展示Spatial2DView2D 空间视图主要展示位置Spatial3DView仅在日志记录在某个投影projection如 pinhole 相机之下时2D 点会被反投影回 3D 场景显示DataframeView以表格形式查看底层列数据。这个同一份数据、多种视图的能力正体现了 Rerun 原型系统的价值数据侧只记录一次强类型列数据展示侧由蓝图Blueprint决定以何种视图消费它。二、半径的双重语义场景单位与 UI 点数Points2D的radii字段看似只是一个浮点数但它承载了 Rerun 2D 视图中一个很有意义的语义同一个Radius值既可以用世界/场景单位表达也可以用屏幕 UI 点数表达。这一机制的完整定义见 Radius 组件源码/// **Component**: The radius of something, e.g. a point. /// /// Internally, positive values indicate scene units, whereas negative values /// are interpreted as UI points. /// /// UI points are independent of zooming in Views, but are sensitive to the application UI scaling. /// at 100% UI scaling, UI points are equal to pixels #[repr(transparent)] pub struct Radius(pub crate::encodings::Float32);从源码注释看可以确认以下规则正数→ 解释为场景单位scene units即与positions同一坐标系中的世界空间单位。这是默认行为直接传[0.1, 0.3]即可。负数→ 解释为UI 点数UI points。UI 点数不随视图缩放zoom in/out变化但会随应用 UI 缩放比例变化在 100% UI 缩放下UI 点数等于像素数。视图的 UI 缩放默认跟随操作系统缩放通常 Full HD 屏为 100%、4K 屏为 200%。Radius本身是#[repr(transparent)]包装单个Float32的类型因此符号即语义这一约定零成本地嵌入在编码里。各语言 SDK 为此提供了便利构造器Python 中用rr.Radius.ui_points([40.0, 60.0])Rust 中用rerun::Radius::new_ui_points(40.0)它们负责生成对应的负值编码。下面第三节示例会实际用到。三、示例一最简 2D 点 设置视图边界参考 points2d_simple.py同目录另有 points2d_simple.rs 与 points2d_simple.cpp 版本Log some very simple points. import rerun as rr import rerun.blueprint as rrb rr.init(rerun_example_points2d, spawnTrue) rr.log(points, rr.Points2D([[0, 0], [1, 1]])) # Set view bounds: rr.send_blueprint( rrb.Spatial2DView( visual_boundsrrb.VisualBounds2D(x_range[-1, 2], y_range[-1, 2]) ) )要点解析rr.init(rerun_example_points2d, spawnTrue)以应用名rerun_example_points2d初始化记录流并自动拉起查看器spawn viewer。rr.log(points, rr.Points2D([[0, 0], [1, 1]]))在实体路径points下记录两个点。注意这里只提供了必填字段positions——这正是Points2D构造器的最小入参。rr.send_blueprint(...)通过发送一条蓝图把视图切换为Spatial2DView并显式设定VisualBounds2D的显示范围x_range[-1, 2],y_range[-1, 2]。在记录端固定视图边界能保证截图/分享链接呈现一致的画面这在 CI 截图对比与文档生成中很常见Rust 侧对应示例中留了TODO(#5521): log VisualBounds2D说明该蓝图写法仍在持续演进。四、示例二带随机颜色与半径的批量点云参考 points2d_random.py 与 Rust 版 points2d_random.rsLog some random points with color and radii. from numpy.random import default_rng import rerun as rr import rerun.blueprint as rrb rr.init(rerun_example_points2d_random, spawnTrue) rng default_rng(12345) positions rng.uniform(-3, 3, size[10, 2]) colors rng.uniform(0, 255, size[10, 4]) radii rng.uniform(0, 1, size[10]) rr.log(random, rr.Points2D(positions, colorscolors, radiiradii)) # Set view bounds: rr.send_blueprint( rrb.Spatial2DView( visual_boundsrrb.VisualBounds2D(x_range[-4, 4], y_range[-4, 4]) ) )Rust 版本则展示了new()with_*链式构造的惯用法//! Log some random points with color and radii. use rand::prelude::*; fn main() - Result(), Boxdyn std::error::Error { let rec rerun::RecordingStreamBuilder::new(rerun_example_points2d_random) .spawn()?; let mut rng rand::rngs::SmallRng::seed_from_u64(42); let dist rand::distr::Uniform::new(-3., 3.)?; rec.log( random, rerun::Points2D::new( (0..10).map(|_| (rng.sample(dist), rng.sample(dist))), ) .with_colors((0..10).map(|_| { rerun::Color::from_rgb(rng.random(), rng.random(), rng.random()) })) .with_radii((0..10).map(|_| rng.random::f32())), )?; // TODO(#5521): log VisualBounds2D Ok(()) }这个示例同时把positions10×2、colors10×4 的 RGBA、radii10 个标量三类字段一次性传入正好覆盖必填 两个推荐字段组。注意几个细节列式批量的自然契合Positions2D的三个数组长度一致各 10 行记录端把它们序列化为三个 Arrow 数组批次这正对应源码中as_serialized_batches()把各字段的SerializedComponentBatch平铺收集的实现见 as_serialized_batches。颜色广播单个Color如rerun::Color::from_rgb(0, 0, 255)可应用到整批点这与示例三中两个点共用一个颜色的写法一致而随机示例展示了逐点独立取色。半径默认走场景单位rng.uniform(0, 1)产生的是非负浮点数按第二节规则将被解释为世界空间单位点的大小会随视图缩放而变化。五、示例三混用场景单位与 UI 点数半径参考 points2d_ui_radius.py 与 Rust 版 points2d_ui_radius.rs这个示例是理解Radius双语义的最佳教材Log some points with ui points scene unit radii. import rerun as rr import rerun.blueprint as rrb rr.init(rerun_example_points2d_ui_radius, spawnTrue) # Two blue points with scene unit radii of 0.1 and 0.3. rr.log( scene_units, rr.Points2D( [[0, 0], [0, 1]], # By default, radii are interpreted as world-space units. radii[0.1, 0.3], colors[0, 0, 255], ), ) # Two red points with ui point radii of 40 and 60. # UI points are independent of zooming in Views, but are sensitive to the # application UI scaling. # For 100% ui scaling, UI points are equal to pixels. rr.log( ui_points, rr.Points2D( [[1, 0], [1, 1]], # rr.Radius.ui_points produces radii that the viewer interprets # as given in ui points. radiirr.Radius.ui_points([40.0, 60.0]), colors[255, 0, 0], ), ) # Set view bounds: rr.send_blueprint( rrb.Spatial2DView( visual_boundsrrb.VisualBounds2D(x_range[-1, 2], y_range[-1, 2]) ) )Rust 侧等价写法// Two blue points with scene unit radii of 0.1 and 0.3. rec.log( scene_units, rerun::Points2D::new([(0.0, 0.0), (0.0, 1.0)]) // By default, radii are interpreted as world-space units. .with_radii([0.1, 0.3]) .with_colors([rerun::Color::from_rgb(0, 0, 255)]), )?; // Two red points with ui point radii of 40 and 60. rec.log( ui_points, rerun::Points2D::new([(1.0, 0.0), (1.0, 1.0)]) // rerun::Radius::new_ui_points produces a radius that the viewer interprets as given in ui points. .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)]), )?;对比两条日志即可看出设计意图scene_units实体中半径 0.1/0.3 是场景里的小圆缩放视图时圆会跟着放大缩小ui_points实体中 40/60 的 UI 点数则始终占据固定屏幕尺寸适合标注、HUD 式叠加层这类不希望随缩放变形的可视化需求。六、实现内幕从 Archetype 到 Arrow 批次结合 Points2D Rust 实现可以梳理出Points2D在 Rerun 管线中的关键机制类型即契约Points2D实现re_types_core::Archetype与AsComponents两个核心 trait。required_components()/recommended_components()/optional_components()返回的是ComponentDescriptor静态切片REQUIRED_COMPONENTS仅含positionsRECOMMENDED_COMPONENTS含radii与colorsOPTIONAL_COMPONENTS含其余 5 项这套元数据既用于文档生成也用于存储端校验与反序列化。构造与序列化new()只填充positions所有with_*方法都调用try_serialize_field(描述符, 迭代器)把 Rust/Python/C 侧的任意可迭代数据统一转成带组件描述符的 Arrow 批次。因此 SDK 层字段 列与查看器 DataframeView 中看到的列一一对应。反序列化路径from_arrow_components()接收(ComponentDescriptor, ArrayRef)对按描述符把 Arrow 数组回填到各字段——这意味着Points2D可以从持久化的.rrd文件或网络流无损重建。列式分区columns(lengths)把一个批次的各字段按指定长度切分成多个SerializedComponentColumn可配合RecordingStream::send_columns直接以列式方式发送columns_of_unit_batches()则是把批次按每行一个子批次自动切分的便捷入口。对于流式、增量写入大量 2D 点如逐帧关键点检测输出的场景这条路径能避免整体重发。可视化注册VisualizableArchetype实现返回Visualizer::new(Points2D).with_overrides(self)把原型与查看器的 Points2D 可视化器绑定字段中的可选覆盖值如draw_order会随可视化配置一起下发。七、多语言 API 对照与延伸阅读Points2D在三端 SDK 中同名同构均为代码生成产物字段语义一致语言入口类型半径 UI 点数构造器Pythonrr.Points2D(positions, colors..., radii...)rr.Radius.ui_points([...])Rustrerun::Points2D::new(positions).with_radii(...)rerun::Radius::new_ui_points(f32)Crerun::archetypes::Points2D见 Radius 组件文档仓库内对应的多语言示例源码均位于 docs/snippets/all/archetypes/ 目录下points2d_simple.{py,rs,cpp}、points2d_random.{py,rs,cpp}、points2d_ui_radius.{py,rs,cpp}可通过 snippets 索引 查看其注册信息。围绕Points2D以下文档可作延伸阅读组件参考Position2D、Radius、Color、Text、ShowLabels、DrawOrder、ClassId、KeypointId视图参考Spatial2DView、Spatial3DView、DataframeView相邻原型points3d.md3D 点云、line_strips2d.md2D 折线、pinhole.md相机投影决定 2D 点能否在 3D 视图中展示小结Points2D用必填 positions 推荐 radii/colors 五个可选字段的轻量结构覆盖了 2D 点云可视化与检测标注的主要需求Radius通过符号位区分场景单位与 UI 点数是 2D 视图中平衡物理一致与屏幕恒定的关键设计而从try_serialize_field的列式序列化到columns()的分区发送其实现为大规模、流式的 2D 数据记录提供了清晰可扩展的路径。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考