Rerun StateTimelineView 视图详解:用水平状态泳道可视化机器人状态机与模式切换
Rerun StateTimelineView 视图详解:用水平状态泳道可视化机器人状态机与模式切换
本篇技术指南以 Rerun 官方类型参考文档 state_timeline_view.md 为主体,结合本仓库中该视图的 Rust 实现(re_view_state_timeline crate)、SDK 类型定义与 Python 示例,系统讲解 StateTimelineView 的功能定位、time_ranges 配置、配套的 StateChange / StateConfiguration 数据模型,以及完整可运行的 Blueprint 代码。读完本文,你将能够:为任意离散状态(门开关、机械臂位姿阶段、任务执行模式、机器人行为状态)生成随时间推进的彩色泳道图,并掌握其底层数据查询与渲染原理。
视图概览:什么是 StateTimelineView
StateTimelineView 是 Rerun 提供的一种用于展示随时间发生的状态切换(state transitions)的视图,它以“水平彩色泳道(horizontal colored lanes)叠加在时间轴上”的形式呈现数据,专门服务于 archetypes.StateChange 这类状态变更数据。在 re_view_state_timeline/README.md 中,该视图被一句话概括为:“A view that shows state transitions as horizontal lanes over time.”(一种以水平泳道形式展示随时间变化的状态切换的视图)。
从类型定义看,state_timeline.def.rs 中声明了该视图的元信息:
#[rerun::rerun_type]
#[rerun(view_identifier = "StateTimeline")]
#[rerun(state = "unstable")]
pub struct StateTimelineView {
pub time_ranges: rerun::blueprint::archetypes::VisibleTimeRanges,
}
这里有两个关键信息:
- 视图类标识符(view_identifier)为
"StateTimeline",与 state_timeline_view.rs 中ViewClass::identifier()返回的"StateTimeline"一致,是注册到 Viewer 的正式视图类名。 - 该类型当前标记为
unstable(不稳定)。官方文档明确提示:“⚠️ This type is unstable and may change significantly in a way that the data won't be backwards compatible.”——即该类型可能在后续版本中发生显著变化,且变化方式可能导致数据不再向后兼容。在依赖它构建 Blueprint 或持久化数据时,需要做好版本兼容性预案。
在 view_class.rs 中,该视图的 display_name() 返回 "State timeline",并带有独立的图标 VIEW_STATE_TIMELINE,其推荐瓦片宽高比为 2.5、布局优先级为 Low,这意味着它默认让位给时序图等高优先级视图,但在检测到状态数据时会主动建议创建。
核心配置属性:time_ranges
StateTimelineView 只有一个公开配置属性 time_ranges,其类型为 VisibleTimeRanges(可见时间范围)。官方文档对该属性的说明如下:
time_ranges:配置该视图在每条时间轴(timeline)上展示的时间范围(除非在具体实体上被另行指定)。- 如果未指定,默认展示整条时间轴。
- 如果同一条时间轴被指定了多次,以第一次出现的条目为准。
也就是说,time_ranges 允许你为视图限定可见的时间窗口(例如只观察 step 从 100 到 200 的状态变迁),而默认行为是展示录制数据的全部时间范围。从 Rust 实现看,StateTimelineView 对 VisibleTimeRanges 实现了 From、Borrow 与 Deref 转换,因此你可以直接传入一个 VisibleTimeRanges 值来构造视图。
提示:
time_ranges控制的是“绘制哪些状态”的窗口。从源码看,视图的时间轴范围(数据区间的 min/max 与“时间轴结束”锯齿带的位置)刻意独立于可见时间范围——限制可见范围只会决定画哪些状态,而不会让时间轴在用户修改配置时发生跳动,这一设计意图体现在 view_class.rs 的data_time_range注释中。
数据模型:用 StateChange 记录状态切换
StateTimelineView 的数据来源是 StateChange archetype。在 state_change.rs 中,其定义与语义如下:
- 一次
StateChange记录代表实体在某时刻进入一个新状态,适合表达离散状态机、模式切换或随时间变化的状态; - 每次
log一个StateChange就标记了给定时间点上的一个新状态; - 一个
null状态会重置当前状态,在 StateTimelineView 中表现为一个间隙(gap); - 状态数组中的每个实例(instance)在视图中各占一条泳道。
关于重置语义,源码注释给出了更细的规则:
一个 reset 会结束前一个状态,并在视图上显示一段间隙,直到下一个状态出现。空字符串、null 数组元素、以及空状态数组(例如清空字段产生的)都会被当作 reset。 状态数组的长度不应随时间变化。
StateChange 的完整组件结构为:1 个必需组件(state,类型为 rerun.components.Text)、0 个推荐组件、0 个可选组件,可见其模型极其精简。
Rust 示例:记录门的开合状态
来自 state_change.rs 的官方 Rust 示例:
let rec = rerun::RecordingStreamBuilder::new("rerun_example_state_change")
.spawn()?;
rec.set_time_sequence("step", 0);
rec.log("door", &rerun::StateChange::single("open"))?;
rec.set_time_sequence("step", 1);
rec.log("door", &rerun::StateChange::single("closed"))?;
rec.set_time_sequence("step", 2);
rec.log("door", &rerun::StateChange::single("open"))?;
每个状态只携带“起始时间”,当前状态一直延续到下一个状态开始为止(最后一个状态是开区间、无限延伸),这正是泳道图的视觉语义:每一条有色段表示一个状态相位(phase)。
样式定制:StateConfiguration 并行数组映射
为了控制每个状态值的显示样式,StateTimelineView 配套了 StateConfiguration archetype。在 state_configuration.rs 中定义了 4 个可选组件,它们构成按索引配对的并行数组:
| 字段 | 组件类型 | 语义 | 默认行为 |
|---|---|---|---|
values |
Text |
该配置所应用的原始状态值 | 每个条目定义一个已知状态值,顺序决定与其余数组的映射 |
labels |
Text |
每个状态值的显示标签 | 未提供或短于 values 时,直接用原始值作为标签 |
colors |
Color |
每个状态值的颜色 | 未提供时,从内置调色板自动分配颜色 |
visible |
Visible |
每个状态值的可见性 | 未提供时所有状态值均可见 |
官方文档特别强调:
values、labels、colors和visible是并行数组:索引i处的条目共同描述同一个状态值,只有按索引配对才有意义。四个数组应长度一致;任何短于values的辅助数组(labels、colors、visible),缺失的条目将回退到默认值。 通常推荐以 static 方式记录该类型(即整段录制期间全局生效),并且底层数据需要记录在与StateChange相同的实体路径上。
完整示例:自定义样式的状态流
来自 state_configuration.rs 的 Rust 示例展示了颜色与标签的定制:
let rec = rerun::RecordingStreamBuilder::new("rerun_example_state_configuration")
.spawn()?;
// 配置每个原始状态值的显示方式(标签、颜色、可见性)
rec.log_static(
"door",
&rerun::StateConfiguration::new()
.with_values(["open", "closed"])
.with_labels(["Open", "Closed"])
.with_colors([0x4CAF50FFu32, 0xEF5350FFu32]),
)?;
rec.set_time_sequence("step", 0);
rec.log("door", &rerun::StateChange::single("open"))?;
rec.set_time_sequence("step", 1);
rec.log("door", &rerun::StateChange::single("closed"))?;
rec.set_time_sequence("step", 2);
rec.log("door", &rerun::StateChange::single("open"))?;
Python 端同样提供了等价能力,见 docs/snippets/all/howto/state_timeline.py,其中 /door 实体使用自定义配置,而 /window 实体则使用默认样式(原始值作为标签、哈希派生颜色),直观地展示了两种风格共存的效果:
import rerun as rr
import rerun.blueprint as rrb
rr.init("rerun_example_howto_state_timeline", spawn=True)
# 定制每个状态值的显示方式(标签、颜色、可见性)
rr.log(
"door",
rr.StateConfiguration(
values=["open", "closed"],
labels=["Open", "Closed"],
colors=[0x4CAF50FF, 0xEF5350FF],
),
static=True,
)
# 记录两个实体的状态切换,每次调用标记新状态的开始
rr.set_time("step", sequence=0)
rr.log("door", rr.StateChange(state="open"))
rr.log("window", rr.StateChange(state="closed"))
rr.set_time("step", sequence=1)
rr.log("door", rr.StateChange(state="closed"))
rr.set_time("step", sequence=3)
rr.log("window", rr.StateChange(state="open"))
rr.set_time("step", sequence=4)
rr.log("door", rr.StateChange(state="open"))
# 在根节点放置一个状态时间线视图
blueprint = rrb.Blueprint(
rrb.StateTimelineView(origin="/", name="Doors and windows"),
)
rr.send_blueprint(blueprint)
实战:用 Blueprint 展示 StateTimelineView
原文档引用了一个名为 views/state_timeline 的官方示例片段,即 docs/snippets/all/views/state_timeline.py。该示例完整演示了“记录状态 + 创建视图”的完整链路,是可以直接复制运行的最小可复现方案:
import rerun as rr
import rerun.blueprint as rrb
rr.init("rerun_example_state_timeline", spawn=True)
rr.set_time("step", sequence=0)
rr.log("door", rr.StateChange(state="open"))
rr.set_time("step", sequence=1)
rr.log("door", rr.StateChange(state="closed"))
rr.set_time("step", sequence=2)
rr.log("door", rr.StateChange(state="open"))
# 创建一个状态时间线视图来展示状态切换
blueprint = rrb.Blueprint(
rrb.StateTimelineView(
origin="/",
name="State Transitions",
),
collapse_panels=True,
)
rr.send_blueprint(blueprint)
要点说明:
rr.StateChange(state=...)在 Python 端对应StateChange.state文本数组,每条log在该step时刻把实体切换到新状态;rrb.StateTimelineView(origin="/", name="...")以根实体为原点、指定显示名称创建一个状态时间线视图;collapse_panels=True用于折叠侧边面板以获得更沉浸的展示效果;- 该示例同样存在于 Rust 与 C++ 示例目录中(见 examples/rust/state_timeline、examples/python/state_timeline),多语言 API 结构一致。
需要说明的是:即使不显式发送 Blueprint,Viewer 在检测到 StateChange 数据时也会自动创建该视图。查看 view_class.rs 中的 spawn_heuristics 逻辑可以发现,只要存在携带 StateChange 的实体,视图类就会返回 ViewSpawnHeuristics::root(),即“默认把所有状态变更流放进同一个视图”。显式使用 Blueprint 的价值在于:你可以精确控制视图的原点、名称、布局,以及后续讨论的 time_ranges 等配置。
交互与空状态:视图的使用体验
view_class.rs 中通过 Help 组件定义了完整的交互方式,整理如下:
| 操作 | 交互方式 |
|---|---|
| 移动时间游标 | 在视图中任意位置右键点击 |
| 平移(Pan) | 左键或中键拖拽;触控板双指横向滚动 |
| 缩放(Zoom) | Cmd/Ctrl + 滚轮(以指针位置为中心) |
| 重置视图 | 双击视图区域(不重置全局时间游标) |
渲染与布局细节(均来自 view_class.rs 的常量):
- 时间标尺(time ruler)绘制在视图顶部(高度 20px),其下为泳道区域;
- 每条泳道带高度 22px、标签行高 14px、泳道间距 4px,多实例分组的内部子泳道间距 1px;
- 视图顶部还会绘制与时间面板风格一致的锯齿状“时间轴结束”带(zig-zag band),最后一个开放状态的色段会略微延伸到该带之下,使其齿形切入色段而非留下背景缺口;
- 当某个状态相位在屏幕上窄于 4px(
MERGE_PHASE_THRESHOLD_PIXEL)时,会把连续且相邻的窄相位**合并成一个区域(Merged region)**渲染,避免出现无法辨认的细碎色条;用户主动隐藏的状态不会被打包进合并区域,而是保持为间隙; - 悬停某个泳道相位时,该相位的时间范围会以半透明色带高亮,并通过
HighlightRange时间命令广播给其他视图联动高亮(TimeRangeHighlightKind::StateTimeline)。
当视图中没有任何状态数据时,会显示引导文案:“No state data. Drag a state entity or a string component from the streams tree into this view or add a new visualizer.”(无状态数据。可从流树中把状态实体或字符串组件拖入本视图,或添加新的 visualizer。)
此外,该视图支持拖拽交互:
- 拖入实体:只有记录了
StateChange的实体才被接受,其他 archetype 会被拒绝(提示“NoStateChangedata on this entity, try dropping a component instead”); - 拖入组件:拖入任意组件时,会为其新建一个
StateVisualizer,把StateChange.state从该组件重映射出来,从而实现“把任意字符串/数值/布尔组件可视化为状态泳道”的通用能力。
原理纵深:从数据到泳道的完整流水线
该视图的核心实现位于 re_view_state_timeline/src,其中 visualizer.rs 的文件头注释给出了从数据到画面的完整数据流,概述如下:
- 查询窗口:以“蓝图中的可见时间范围 ∩ 视图状态中的平移/缩放窗口”为查询区间;
- 双重查询:对窗口做范围查询(range query,并扩展边界以便最后一个相位知道其终点),同时在窗口起点做 latest-at 查询(“bootstrap”:获取窗口打开时已经处于激活状态的状态,避免窗口前移时泳道出现空白断层);
- 多态类型收敛:通过组件类型转换表(
COMPONENT_CAST_MAP),把可接受的所有源类型折叠为字符串、f64或布尔三种类型——Utf8/LargeUtf8保持为字符串,Boolean保持为布尔,所有整数与浮点类型统一转为Float64,对应StateValueKind的String、Scalar、Bool三类泳道; - 相位构建(build_lane_phases):同一时间点上 row id 较新的记录胜出;相邻的相同状态自动折叠合并;reset 打开一个间隙;
- 样式应用:
StateConfiguration的labels/colors/visible按索引应用到对应状态值——被隐藏的值变为间隙,未配置的值使用哈希派生的颜色; - 逐层聚合:
StateLanePhase→StateLane(状态数组的每个实例一条泳道)→StateLaneGroup(每个 visualizer 指令一组,组内泳道共享标签与配置)→StateLanesOutput; - 最终渲染:
view_class::ui负责平移、缩放、绘制色带与时间游标。
关于时间轴联动,time_axis_link 读取蓝图中 TimeAxis 的 link 组件:当为 LinkToGlobal 时,平移/缩放窗口与其他绘图类视图(如时序图)通过全局蓝图视图共享;当为 Independent 时,每个时间轴各自持有独立的窗口(保存在 StateTimelineViewState.windows 中)。在选中该视图时,右侧面板也只会暴露联动模式这一可编辑项——视图范围本身由平移/缩放操作驱动,这与设计注释“Only the link mode is editable per-view. The view range is driven by pan/zoom.”完全吻合。
小结
StateTimelineView 为 Rerun 生态补充了一种专注于离散状态随时间演化的可视化视角:通过 StateChange 记录状态切换(配合 null / 空值实现 reset 间隙语义),通过 StateConfiguration 并行数组定制标签、颜色与可见性,通过 time_ranges 控制每个时间轴的可见范围,并以水平彩色泳道 + 时间标尺的形态直观呈现。底层实现则以“范围查询 + latest-at 引导 + 多态类型收敛 + 相位合并”的流水线保证了大数据量下的稳定渲染与流畅交互。
由于该类型目前仍标记为 unstable,建议在正式项目中将其视为实验性能力,关注后续版本的类型变更公告。若希望深入源码,可依次阅读 state_timeline.def.rs(类型定义源)、state_timeline_view.rs(SDK 生成代码)、view_class.rs(视图渲染与交互)以及 visualizer.rs(数据查询与泳道构建流水线)。