Rerun 内置视图（View）完全指南：Viewport 面板体系与蓝图配置详解

Rerun 的视口（Viewport）是查看器（Viewer）的核心交互区域，而视图（View）则是视口中用于检查与可视化已记录数据的各类面板。本指南以 Rerun 仓库中 Views 参考文档 为骨架，系统讲解全部 11 种内置视图的功能定位、可配置属性（Properties）、可可视化的 archetype（原语）列表，并结合 re_sdk_types 中的 Rust 源码说明其底层实现。读完本文，你将掌握每种视图适合呈现什么类型的数据、如何通过蓝图（Blueprint）定制视图外观与行为，以及如何为机器人多模态数据选择最合适的可视化面板。

视图在 Rerun 架构中的角色

在 Rerun 的数据模型中，日志侧通过 archetype（如 Points3D、Scalars、Image）记录多模态数据，而展示侧则由 Blueprint 决定"用什么视图、在什么位置、以什么配置"来呈现这些数据。视图即视口中显示的面板，是检查与可视化已记录数据的主要手段。

从源码结构看，视图类型定义位于 crates/store/re_sdk_types/src/blueprint/views，每个视图对应一个 Rust struct，并实现 re_types_core::View trait，通过 identifier() 返回唯一的 ViewClassIdentifier。例如 Spatial2DView 的标识符为 "2D"（见 spatial2d_view.rs），TimeSeriesView 的标识符为 "TimeSeries"（见 time_series_view.rs）。这些 struct 的字段即视图的可配置属性，全部由 re_types_builder 从定义文件（如 blueprint/views/spatial2d.def.rs）自动生成，与文档保持严格一致。

⚠️ 注意：当前文档中所有视图类型均标注为 unstable，即未来可能发生不向后兼容的重大变更。

内置视图总览

Rerun 目前内置 11 种视图，主文档 views.md 的完整清单如下：

视图	用途
BarChartView	柱状图视图
DataframeView	以表格形式展示任意数据
GraphView	随时间变化的（有向/无向）图可视化
MapView	展示地理空间原语的 2D 地图
Spatial2DView	查看空间 2D 数据
Spatial3DView	查看空间 3D 数据
StateTimelineView	展示随时间变化的状态迁移，配合 StateChange archetype
TensorView	展示任意维度的张量
TextDocumentView	展示单个文本文档，配合 TextDocument archetype
TextLogView	展示文本日志，配合 TextLog archetype
TimeSeriesView	标量随时间变化的时间序列图，配合 Scalars archetype

下面按数据形态分组逐一深入。

空间类视图：Spatial2DView 与 Spatial3DView

空间视图是机器人、自动驾驶等场景最常用的面板，分别用于查看 2D 与 3D 空间数据。

Spatial2DView

定位为"查看空间 2D 数据"。其可配置属性（见 spatial2d_view.md）包括：

• background：视图背景配置。
  • kind：背景类型；
  • color：纯色背景使用的颜色。
• visual_bounds：场景可见区域（位于场景坐标系中）。边界内的内容保证可见，边界外由于 letterboxing（信箱式留边）也可能部分可见。
• spatial_information：视图中空间信息显示的配置。
  • target_frame：所有变换的目标参考坐标系；
  • show_bounding_box：是否显示包围盒；
  • show_axes：是否在原点显示坐标轴；
  • axes：控制 3D 视图中坐标轴的方向，在 2D 视图中无效果。
• time_ranges：配置该视图在每条时间线上显示的时间范围（除非对单个实体另行指定）。未指定时默认显示每个组件的最新状态；同一时间线被指定多次时，以第一条为准。

其对应 Rust 结构体定义在 spatial2d_view.rs，四个字段 background、visual_bounds、spatial_information、time_ranges 与文档属性一一对应，类型分别指向 Background、VisualBounds2D、SpatialInformation、VisibleTimeRanges 等蓝图 archetype。

Spatial2DView 可可视化的 archetype 非常丰富，包括：AnnotationContext、Arrows2D、AssetVideo、Boxes2D、Clear、CoordinateFrame、DepthImage、Ellipses2D、EncodedDepthImage、EncodedImage、GridMap、Image、LineStrips2D、Pinhole、Points2D、SegmentationImage、VideoFrameReference、VideoStream；此外，若 3D 数据被记录在激活投影（projection）之上，以下 3D archetype 也可显示：Arrows3D、Asset3D、Boxes3D、Capsules3D、Cylinders3D、Ellipsoids3D、InstancePoses3D、LineStrips3D、Mesh3D、Points3D、Transform3D。各 archetype 的详细文档见 archetypes 目录。

Spatial3DView

定位为"查看空间 3D 数据"。其属性（见 spatial3d_view.md）除 2D 视图已有的 background、spatial_information、time_ranges 外，还包括：

• line_grid：3D 线网格配置。
  • visible：网格是否可见；
  • spacing：相邻网格线间距（以场景单位计）；
  • plane：网格绘制所在的平面；
  • stroke_width：线宽（以 UI 单位计）；
  • color：网格颜色。
• eye_controls：3D 眼睛（相机）配置。
  • kind：3D 视图的相机类型；
  • position：相机当前位置；
  • look_target：相机当前注视的位置；
  • eye_up：眼睛自身的上轴（世界坐标系）；
  • speed：使用 WASDQE 键在 3D 场景中移动时的平移速度；
  • tracking_entity：当前跟踪的实体；
  • spin_speed：相机绕眼睛上轴自旋的速度（非零即启用自旋）。

Spatial3DView 的原生可视化 archetype 包括：AnnotationContext、Arrows3D、Asset3D、Boxes3D、Capsules3D、Clear、CoordinateFrame、Cylinders3D、Ellipsoids3D、GaussianSplats3D、GridMap、InstancePoses3D、LineStrips3D、Mesh3D、Pinhole、Points3D、Transform3D、TransformAxes3D、ViewCoordinates、Volume3D、VoxelGridMap；同时，若 2D 数据被记录在投影之下，也可显示 Arrows2D、AssetVideo、Boxes2D、DepthImage、Ellipses2D、EncodedDepthImage、EncodedImage、Image、LineStrips2D、Points2D、SegmentationImage、VideoFrameReference、VideoStream 等 2D archetype。这体现了 Rerun 支持将 2D 图像/相机数据"挂在"3D 场景投影平面上的典型机器人可视化工作流。

标量与时间序列视图：TimeSeriesView 与 BarChartView

TimeSeriesView

用于展示标量随时间变化的曲线，配合 Scalars archetype 使用。其属性（见 time_series_view.md）包括：

• axis_x：横轴（时间轴）配置。
  • link：多个图之间横轴如何联动；
  • view_range：横轴显示范围；
  • zoom_lock：启用后，缩放时 X 轴范围锁定在指定区间。
• axis_y：纵轴配置。
  • range：纵轴范围；
  • zoom_lock：启用后，缩放时 Y 轴范围锁定。
• plot_legend：图例配置。
  • corner：图例对齐的角落；
  • visible：图例是否显示。
• background：绘图背景配置（color 背景色、show_grid 是否绘制网格）。
• interaction：悬停提示与数据点标记行为。
  • tooltip_mode：悬停时提示框的行为；
  • points_display：线序列上数据点标记的显示时机。
• time_ranges：各时间线显示范围，未指定时默认显示整条时间线。

对应源码 time_series_view.rs 中六个字段分别对应 TimeAxis、ScalarAxis、PlotLegend、PlotBackground、PlotInteraction、VisibleTimeRanges。可可视化的 archetype 为：Clear、Measurements、Scalars、SeriesLines、SeriesPoints，其中 SeriesLines/SeriesPoints 用于配置线条样式与数据点样式。

BarChartView

柱状图视图，适合展示离散分布（如直方图）。属性（见 bar_chart_view.md）：

• plot_legend：图例配置（corner 对齐角落、visible 是否显示）。
• background：绘图背景（color 背景色、show_grid 是否绘制网格）。

可可视化 archetype 为 BarChart 以及 1D 的 Tensor，即一维张量可直接以柱状图形式呈现。

表格与日志视图：DataframeView、TextLogView、TextDocumentView

DataframeView

以表格形式展示 store 中的任意数据，支持灵活、可用户配置的查询（query）。其查询模型参见 dataframe-queries 概念文档。属性（见 dataframe_view.md）：

• query：数据帧查询配置。
  • timeline：查询使用的时间线；
  • filter_by_range：若提供，仅显示时间戳在该范围内的行；
  • filter_is_not_null：若提供，仅显示对指定组件记录过事件的行；
  • apply_latest_at：是否用 latest-at 查询填充空单元格；
  • select：选中的列。若未设置，默认选中活动时间线与全部组件列；
  • entity_order：实体路径列分组顺序，未设置时使用默认顺序；
  • auto_scroll：是否自动滚动以跟随时间游标。

该视图不限于特定 archetype——任何数据都可以显示，这使它成为排查数据、检查原始记录内容的利器。

TextLogView

文本日志视图，配合 TextLog archetype。属性（见 text_log_view.md）：

• columns：视图中显示的列（timeline_columns 显示哪些时间线列、text_log_columns 全部要显示的列）。
• rows：行显示过滤器。
• format_options：格式化选项。

可可视化 archetype 为 TextLog。

TextDocumentView

单个文本文档视图，配合 TextDocument archetype。属性（见 text_document_view.md）：

• format_options：文档格式化选项。
  • monospace：文档正文是否使用等宽字体；
  • word_wrap：长行是否自动换行。

可可视化 archetype 为 TextDocument。

图与地理空间视图：GraphView 与 MapView

GraphView

用于展示随时间变化的（有向或无向）图，例如机器人任务中的状态机、拓扑关系。属性（见 graph_view.md）基于力导向（force-directed）布局模型：

• background：图的背景配置。
• visual_bounds：边界内的内容保证可见，边界外因 letterboxing 可能部分可见。
• force_link：控制由边连接的两个节点间的相互作用。
  • enabled：是否启用链接力；
  • distance：两节点间的目标距离；
  • iterations：每次迭代应用该力的次数。
• force_many_body：类似电荷的、每对节点之间的作用力。
  • enabled：是否启用；
  • strength：力的强度。
• force_position：类似重力，将节点拉向指定位置。
  • enabled：是否启用；
  • strength：强度；
  • position：节点被拉向的位置。
• force_collision_radius：根据节点半径解析包围球之间的碰撞。
  • enabled：是否启用；
  • strength：强度；
  • iterations：每次迭代应用次数。
• force_center：将图的质心拉向原点。
  • enabled：是否启用；
  • strength：强度。

可可视化 archetype 为 GraphEdges 与 GraphNodes。

MapView

用于展示地理空间原语的 2D 地图视图。属性（见 map_view.md）较为精简：

• zoom：地图视图的缩放级别。
• background：地图底图（背景地图）的配置。

可可视化 archetype 为 GeoLineStrings 与 GeoPoints，适合 GPS/经纬度轨迹等机器人室外导航数据。

张量与状态视图：TensorView 与 StateTimelineView

TensorView

展示任意维度的张量，配合 Tensor archetype。属性（见 tensor_view.md）：

• slice_selection：选择要展示的张量切片。
  • width：映射到宽度的维度；
  • height：映射到高度的维度；
  • indices：其余所有维度选中的索引；
  • slider：列出的维度会提供索引滑条。
• scalar_mapping：标量到颜色的映射。
  • mag_filter：放大张量时使用的过滤方式；
  • colormap：标量值如何映射到颜色；
  • gamma：在映射到颜色之前，应用于归一化值的伽马指数。
• view_fit：选中的切片如何适应视图。

可可视化 archetype 为 Tensor。从源码看，张量视图对应的蓝图组件还涉及 TensorViewFit 等（见 tensor_view_fit.rs）。

StateTimelineView

展示随时间变化的状态迁移，配合 StateChange archetype。属性（见 state_timeline_view.md）仅一项：

• time_ranges：各时间线显示范围，未指定时默认显示整条时间线；同一时间线多次指定时以第一条为准。

可可视化 archetype 为 StateChange 与 StateConfiguration，适合展示机器人行为状态机等离散状态切换场景。

视图与蓝图的组合使用

以上所有视图属性都不是写死的，而是通过 Blueprint（蓝图）声明式地配置。在 Python SDK 中，每种视图都有对应的蓝图类（如 rerun.blueprint.views.Spatial3DView），你可以用类似下面的方式创建并定制视图（示意，具体以 SDK 文档为准）：

import rerun.blueprint as rrb

viewport = rrb.Viewport(
    root=rrb.Horizontal(
        rrb.Spatial3DView(origin="/world"),
        rrb.TimeSeriesView(origin="/metrics", axis_y=rrb.ScalarAxis(range=[0.0, 1.0])),
    )
)
rrb.blueprint(viewport)

视图与数据通过 origin（实体路径前缀）关联：视图只展示其 origin 及其子路径下记录的 archetype 数据。例如，将相机图像记录在 /world/camera 之下，Spatial3DView 配合 Pinhole 投影即可将图像纹理化地显示在 3D 场景中。

总结与选型建议

结合 Rerun 面向多模态机器人数据的定位，视图选型可以遵循以下思路：

• 点云、网格、位姿、3D 框、相机投影 → Spatial3DView（可嵌套 2D 图像）；
• 图像、分割图、深度图、2D 框、视频帧 → Spatial2DView；
• 里程计、温度、电量等标量曲线 → TimeSeriesView；
• 分布统计（直方图） → BarChartView；
• 高维数组、特征向量 → TensorView；
• 节点/边关系、拓扑 → GraphView；
• GPS 经纬度轨迹 → MapView；
• 状态机、阶段迁移 → StateTimelineView；
• 原始日志、结构化文本 → TextLogView / TextDocumentView；
• 排查 store 中任意数据 → DataframeView。

所有视图类型定义（含属性与默认行为）的权威来源是 docs/content/reference/types/views 目录，其自动生成的 Rust 实现位于 crates/store/re_sdk_types/src/blueprint/views，Python 侧则通过 rerun.blueprint.views 暴露同名类。由于当前所有视图类型均处于 unstable 状态，升级 SDK 时应留意属性字段可能发生的变更。