Rerun GeoPoints 地理空间点集：EPSG:4326 经纬度数据的可视化与查询指南

Rerun GeoPoints 地理空间点集：EPSG:4326 经纬度数据的可视化与查询指南

【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun

导读

GeoPoints是 Rerun 中用于表达地理空间点集（geospatial points）的核心 archetype，它用 EPSG:4326 搭配，把 GPS/UTM 轨迹、信标位置、传感器观测点直接叠加到 2D 地图底图上。读完本文，你将掌握GeoPoints的完整字段结构、Python / Rust / C++ 三种 SDK 的调用方式、底层LatLon组件与渲染管线实现，以及如何用 Blueprint 定制地图视图。

GeoPoints 是什么

根据 类型定义文档，GeoPoints的定义为：

Geospatial points with positions expressed in EPSG:4326 latitude and longitude (North/East-positive degrees), and optional colors and radii.

即：用 EPSG:4326 经纬度（北/东为正的度数）表示位置、并携带可选颜色与半径的地理空间点集合。它是 Rerun 类型体系中Geospatial（地理空间）分类下的一个 archetype，声明状态为stable，对应的内置可视化为GeoPoints，源码定义见 crates/build/re_type_definitions/rerun/archetypes/geo_points.def.rs：

#[rerun::rerun_type] #[docs(category = "Geospatial")] #[docs(view_types = "MapView")] #[rerun(state = "stable")] #[rerun(visualizer = "GeoPoints")] pub struct GeoPoints { /// The EPSG:4326 coordinates for the points (North/East-positive degrees). #[rerun(required)] pub positions: Vec<rerun::components::LatLon>, /// Optional radii for the points, effectively turning them into circles. #[rerun(recommended)] pub radii: Option<Vec<rerun::components::Radius>>, /// Optional colors for the points. #[rerun(recommended)] pub colors: Option<Vec<rerun::components::Color>>, /// Optional class Ids for the points. #[rerun(optional)] pub class_ids: Option<Vec<rerun::components::ClassId>>, }

字段与组件结构

GeoPoints共包含4 个组件（1 个必选、2 个推荐、1 个可选），生成代码中通过常量明确标注了这一点（见 crates/store/re_sdk_types/src/archetypes/geo_points.rs 中NUM_COMPONENTS: usize = 4usize）：

分类	字段	组件类型	说明
Required	positions	LatLon	EPSG:4326 经纬度坐标（北/东为正的度数），点集的核心数据
Recommended	radii	Radius	可选半径，使点变成圆；注意场景单位下的半径以米为单位
Recommended	colors	Color	可选颜色，按 sRGB gamma 空间下的 RGB/RGBA 解释
Optional	class_ids	ClassId	可选类别 ID，未显式指定颜色时由 ClassId 提供颜色

支持在哪些视图中展示

依据文档，GeoPoints可以在以下两种视图中展示：

• MapView：2D 地图视图，用于展示地理空间图元；
• DataframeView：数据表格视图，用于按行/列检查组件数据。

快速上手：三种 SDK 的完整示例

原文档给出的示例名为Log a geospatial point（记录一个地理空间点），对应的三个语言版本示例代码完整保存在仓库中，可直接复制运行。

Python

源码见 docs/snippets/all/archetypes/geo_points_simple.py：

"""Log some very simple geospatial point.""" import rerun as rr rr.init("rerun_example_geo_points", spawn=True) rr.log( "rerun_hq", rr.GeoPoints( lat_lon=[59.319221, 18.075631], radii=rr.Radius.ui_points(10.0), colors=[255, 0, 0], ), )

要点说明：

• rr.init("rerun_example_geo_points", spawn=True)初始化录制并自动拉起查看器进程；
• lat_lon接受[lat, lon]形式的经纬度列表，也可传入多个点组成的二维列表（见下文 MapView 示例）；
• rr.Radius.ui_points(10.0)表示以UI points（与缩放无关、随界面缩放）为单位指定半径；
• colors=[255, 0, 0]使用 0-255 整数表示 RGB 红色。

Rust

源码见 docs/snippets/all/archetypes/geo_points_simple.rs：

//! Log some very simple geospatial point. fn main() -> Result<(), Box<dyn std::error::Error>> { let rec = rerun::RecordingStreamBuilder::new("rerun_example_geo_points") .spawn()?; rec.log( "rerun_hq", &rerun::GeoPoints::from_lat_lon([(59.319221, 18.075631)]) .with_radii([rerun::Radius::new_ui_points(10.0)]) .with_colors([rerun::Color::from_rgb(255, 0, 0)]), )?; Ok(()) }

Rust 侧的关键 API：

• GeoPoints::from_lat_lon(...)是便捷构造函数，定义在扩展文件 crates/store/re_sdk_types/src/archetypes/geo_points_ext.rs 中，直接由一组LatLon创建点集；
• with_radii/with_colors/with_class_ids是链式 builder 方法（生成于 crates/store/re_sdk_types/src/archetypes/geo_points.rs），分别填充推荐与可选字段；
• 此外还有clear_fields()（清空全部字段）、update_fields()（仅更新部分字段）、以及columns()/columns_of_unit_batches()用于把数据分片为列，配合RecordingStream::send_columns做列式（columnar）发送。

C++

源码见 docs/snippets/all/archetypes/geo_points_simple.cpp：

// Log some very simple geospatial point. #include <rerun.hpp> int main(int argc, char* argv[]) { const auto rec = rerun::RecordingStream("rerun_example_geo_points"); rec.spawn().exit_on_failure(); rec.log( "rerun_hq", rerun::GeoPoints::from_lat_lon({{59.319221, 18.075631}}) .with_radii(rerun::Radius::ui_points(10.0f)) .with_colors(rerun::Color(255, 0, 0)) ); }

三个示例都向同一个实体路径"rerun_hq"记录了一个位于瑞典斯德哥尔摩（北纬 59.319221°、东经 18.075631°）附近的红色圆点。

深入 LatLon 组件：经纬度如何编码

positions字段的组件类型是 LatLon，其定义在 crates/store/re_sdk_types/src/components/lat_lon.rs 中：

#[repr(transparent)] pub struct LatLon(pub crate::encodings::DVec2D);

关键实现事实：

• Rerun 编码：DVec2D，即双精度（f64）二维向量，x存纬度、y存经度；
• Arrow 数据类型：FixedSizeList(2 x non-null Float64)，即两个非空 Float64 组成的定长列表，与 DVec2D 一一对应；
• 便捷方法（见 crates/store/re_sdk_types/src/components/lat_lon_ext.rs）：LatLon::new(lat, lon)构造、latitude()与longitude()分别读取纬度和经度；
• 纬度与经度均使用度数，方向约定为北为正（N+）、东为正（E+）。

半径与颜色的细节语义

Radius：场景单位与 UI points

根据 Radius 组件文档：

• 内部表示为一个Float32数值：正值表示场景单位，负值被解释为 UI points；
• UI points 与视图缩放无关，但对应用 UI 缩放敏感：100% UI 缩放下，1 UI point ≈ 1 像素；查看器默认跟随操作系统缩放（全高清屏约 100%，4K 屏约 200%）；
• 在GeoPoints场景中，以场景单位指定的半径被解释为米（这是.def.rs中radii字段注释明确标注的注意点，见 geo_points.def.rs）。

三种 SDK 对应的构造方式：Python 用rr.Radius.ui_points(10.0)，Rust 用rerun::Radius::new_ui_points(10.0)，C++ 用rerun::Radius::ui_points(10.0f)。

Color：sRGB gamma 空间下的 RGBA

根据 Color 组件文档：

• 语义为带未预乘（unmultiplied/separate）alpha 的 RGBA，处于 sRGB gamma 空间，alpha 为线性；
• 存储为 32 位整数，最高字节为 R、最低字节为 A，Arrow 数据类型为UInt32；
• Python 侧既可使用 0-1 浮点，也可使用 0-255 整数并带独立 alpha（见.def.rs中对colors的注释）。

源码级实现：从类型定义到地图渲染

GeoPoints的完整链路体现了 Rerun 代码生成驱动的架构：

1. 类型定义：crates/build/re_type_definitions/rerun/archetypes/geo_points.def.rs 是用re_types_builder解析的权威定义，负责生成 Rust / Python / C++ 三端绑定与文档；
2. 生成代码：crates/store/re_sdk_types/src/archetypes/geo_points.rs 中实现了Archetypetrait（required_components/recommended_components/optional_components的完整描述符列表）、Arrow 序列化/反序列化（from_arrow_components/as_serialized_batches）以及 builder 方法；
3. 渲染可视化：crates/views/re_view_map/src/visualizers/geo_points.rs 中的GeoPointsVisualizer负责把组件数据变成地图上的点。从源码可以观察到以下实现细节：
   • 它以LatLon为唯一必选组件建立查询（VisualizerQueryInfo::single_required_component::<LatLon>），并通过query_archetype_with_history::<GeoPoints>拉取带历史的数据；
   • 通过AnnotationMapCache建立标注上下文：class_ids未显式提供颜色时，用标注上下文为colors提供颜色回退（annotation_context_query()把GeoPoints:class_ids指向GeoPoints:colors的标注目标）；
   • 半径未提供时，通过typed_fallback_for获取回退半径，并且单实例半径缺失时复用最后一个半径值（instance clamping 语义）；
   • 位置经walkers::lat_lon(lat, lon)转为地图投影坐标，再由walkers::Projector投影为 UI 二维坐标，最终用re_renderer::PointCloudBuilder以点云形式绘制（radius_to_size负责把半径换算成屏幕尺寸）。

用 Blueprint 定制 MapView 地图视图

GeoPoints的典型呈现载体是 MapView——一个 2D 地图视图（注意：文档标注该视图类型目前为unstable，未来可能发生不向后兼容的变更）。MapView 的属性包括：

• zoom：配置地图视图的缩放级别；
• background：配置背景底图来源。

仓库中的完整示例见 docs/snippets/all/views/map.py，同时记录了多个地理点并下发自定义蓝图：

"""Use a blueprint to customize a map view.""" import rerun as rr import rerun.blueprint as rrb rr.init("rerun_example_map_view", spawn=True) rr.log( "points", rr.GeoPoints( lat_lon=[[47.6344, 19.1397], [47.6334, 19.1399]], radii=rr.Radius.ui_points(20.0), ), ) # Create a map view to display the chart. blueprint = rrb.Blueprint( rrb.MapView( origin="points", name="MapView", zoom=16.0, background=rrb.MapProvider.OpenStreetMap, ), collapse_panels=True, ) rr.send_blueprint(blueprint)

该示例同时演示了两个实践要点：

• lat_lon可以传入多个点组成的二维列表（这里记录了两个布达佩斯附近的点）；
• 通过rrb.MapView(origin="points", ...)让视图锚定到"points"实体，设置zoom=16.0缩放级别，并选择OpenStreetMap作为底图。

此外，MapView 文档（docs/content/reference/types/views/map_view.md）明确列出了它可视化的 archetype 列表：GeoLineStrings与GeoPoints——也就是说，你可以在同一地图视图中把点集与地理折线（如行驶轨迹）叠加展示。

已知限制与后续方向

从 geo_points.def.rs 源码中的 TODO 注释可以看出，GeoPoints未来计划补充的能力包括：

• Label与ShowLabels组件（点的文本标签与标签显隐控制）；
• Altitude组件（海拔信息，用于支持三维地理语义）。

当前版本中，若需要为点附加文本信息，可以结合 Rerun 的通用标签/文本组件另行记录；地图视图类型本身处于 unstable 状态，在升级 SDK 时需要注意其 API 与数据格式可能发生变更。

小结

GeoPoints是 Rerun 地理空间可视化体系的基础 archetype：以LatLon（EPSG:4326，北/东为正的度数）为唯一必选组件，配合Radius（场景单位下以米计）与Color两个推荐组件，以及可选的ClassId（经由标注上下文提供颜色回退），即可在 MapView 或 DataframeView 中呈现地理点数据。无论你使用 Python、Rust 还是 C++ SDK，都可以通过GeoPoints::from_lat_lon/rr.GeoPoints一行构造、链式with_radii/with_colors丰富视觉表达，再结合 Blueprint 的MapView(zoom=..., background=...)精确控制地图呈现，从而把机器人、自动驾驶等场景的经纬度数据直接落到地图上进行观察与调试。

【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun