基于 Rerun Blueprint 构建股票时间序列多视图面板：blueprint

基于 Rerun Blueprint 构建股票时间序列多视图面板：blueprint_stocks 示例深度解析

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

导读

blueprint_stocks是 Rerun 官方 Python 示例中聚焦 Blueprint（蓝图）机制的代表性案例：它从 Yahoo Finance 抓取多只股票最近 5 个交易日的行情数据，用同一份数据在 Rerun Viewer 中渲染出单图、图文混排、去除峰值、双股对比、全量网格等多种截然不同的界面形态。读完本文，你将掌握rrb.Blueprint中视图（View）、容器（Container）、面板（Panel）三大核心构件，以及origin、contents查询表达式、布局份额等关键参数的实际用法，并能用同一套思路为自己的数据构建可复用、可切换的展示布局。

示例概览：一份数据，六种蓝图

本文对应的文档为 examples/python/blueprint_stocks/README.md，完整可运行源码位于 examples/python/blueprint_stocks/blueprint_stocks.py，工程配置见 examples/python/blueprint_stocks/pyproject.toml。

该示例的核心思想用一句话概括：数据记录一次，展示形态任意切换。脚本从 Yahoo Finance 抓取 AAPL、AMZN、GOOGL、META、MSFT 五只股票最近 5 个交易日、以 5 分钟为间隔的高频行情，并按下面的实体层级写入数据存储：

stocks/{symbol}/{day} # 某股票某天的价格时间序列 stocks/{symbol}/peaks/{day} # 当天最高价（峰值）标注 stocks/{symbol}/info # 该股票的 Markdown 信息文档

随后通过--blueprint命令行参数选择不同的蓝图，让同一份stocks/数据呈现出不同的界面：

auto：重置为 Viewer 的自动布局；
one-stock：用过滤器只展示单只股票的单张图表；
one-stock-with-info：用容器把图表与其信息文档垂直排布；
one-stock-no-peaks：用过滤器额外剔除图表中的峰值数据；
compare-two：把多路数据源加入同一张图表；
grid：以网格布局展示全部图表。

安装与运行

示例通过独立的 Python 包分发，依赖信息在 examples/python/blueprint_stocks/pyproject.toml 中声明：运行时依赖rerun-sdk、yfinance与humanize，并要求 Python 版本不低于 3.10。项目还注册了blueprint_stocks = "blueprint_stocks:main"的控制台入口。

pip install -e examples/python/blueprint_stocks python -m blueprint_stocks

安装后也可以直接用注册好的命令入口运行：

blueprint_stocks

默认情况下（--blueprint缺省值为grid），运行后会在 Rerun Viewer 中看到按股票分组的网格布局。不同蓝图可通过--blueprint参数切换，例如：

python -m blueprint_stocks --blueprint=one-stock

命令行参数全表

从 blueprint_stocks.py 的argparse定义可以整理出完整参数表：

参数	取值 / 类型	默认值	说明
`--blueprint`	`auto`、`one-stock`、`one-stock-with-info`、`compare-two`、`one-stock-no-peaks`、`grid`	`grid`	选择要使用的蓝图
`--show_panels`	布尔开关（`store_true`）	`False`	是否显示时间面板与选择面板，缺省时二者被折叠
`rr.script_add_args(parser)`注入的参数	`--serve`、`--connect`、`--save`、`--stdout`、`--web-viewer`等	—	Rerun SDK 的标准脚本参数，控制数据送往本地 Viewer、Rerun Server 或保存为`.rrd`文件

--show_panels的逻辑在main()中体现：当蓝图不是auto且未指定--show_panels时，视图区会被hide_panels(viewport)包裹，将时间面板与选择面板折叠。

五种自定义蓝图逐层拆解

主脚本 blueprint_stocks.py 中每个函数对应一种蓝图，全部返回rrb.ContainerLike（即Container或View），由main()在解析命令行参数后统一通过rr.send_blueprint(blueprint)发送给 Viewer。下面逐个拆解其实现细节。

auto：回到 Viewer 的自动布局

def auto_blueprint() -> rrb.BlueprintLike: return rrb.Blueprint(auto_views=True, auto_layout=True)

auto蓝图没有显式声明任何视图，而是把auto_views与auto_layout同时置为True，等价于 Viewer 的默认行为：根据数据存储中的内容自动创建视图并自动排布。从 api.py 的Blueprint.__init__源码看，这两个参数默认在“未提供任何容器/视图”时自动为True；若想创建完全空白的蓝图，则必须显式置为False。

one-stock：最小化单视图蓝图

def one_stock(symbol: str) -> rrb.ContainerLike: return rrb.TimeSeriesView(name=f"{symbol}", origin=f"/stocks/{symbol}")

这是最简单的自定义视图：只声明一个TimeSeriesView，用origin把视图原点锚定到/stocks/{symbol}。origin是视图的最关键参数之一——从 time_series_view.py 的构造函数签名可以看到，其默认值为/，contents默认值为$origin/**，即“以视图原点为根，递归包含其下所有实体”。因此这里只需指定origin，该股票各交易日的全部标量曲线就会自动出现在同一张图表中。

one-stock-with-info：Vertical 容器与布局份额

def one_stock_with_info(symbol: str) -> rrb.ContainerLike: return rrb.Vertical( rrb.TextDocumentView(name=f"{symbol}", origin=f"/stocks/{symbol}/info"), rrb.TimeSeriesView(name=f"{symbol}", origin=f"/stocks/{symbol}"), row_shares=[1, 4], )

这个蓝图展示了**容器（Container）**的用法：rrb.Vertical把两个视图垂直堆叠——上方是TextDocumentView，origin 指向/stocks/{symbol}/info，用于渲染股票的基本面 Markdown 文档；下方是价格时序图。

关键在于row_shares=[1, 4]。根据 containers.py 中Vertical的定义，row_shares决定每个子视图占用的纵向空间比例：第i个视图占shares[i] / total_shares。这里意味着文档区与图表区按 1:4 分配高度，图表占大头。同理，Horizontal容器支持column_shares按比例分配列宽，Grid容器则同时支持两者并可用grid_columns指定列数。

one-stock-no-peaks：contents 排除表达式

def one_stock_no_peaks(symbol: str) -> rrb.ContainerLike: return rrb.TimeSeriesView( name=f"{symbol}", origin=f"/stocks/{symbol}", contents=[ "+ $origin/**", "- $origin/peaks/**", ], )

该蓝图展示了contents查询表达式的威力。contents接受字符串或字符串列表，每条表达式的+/-前缀分别表示“包含”与“排除”，$origin是相对视图原点展开的变量。因此：

+ $origin/**：包含原点下所有实体（整只股票的全部价格曲线）；
- $origin/peaks/**：排除peaks/子目录下的峰值标注。

两条规则叠加的效果就是“显示全部价格，但剔除峰值”。这与数据侧的记录方式严格对应：脚本把峰值单独记录在stocks/{symbol}/peaks/{day}路径下（见 blueprint_stocks.py），从而可以用路径通配在视图层做细粒度的数据裁剪。这种“数据完整入库、视图按需过滤”的模式，正是 Rerun Blueprint 的典型最佳实践。

compare-two：多数据源汇入单图

def compare_two(symbol1: str, symbol2: str, day: Any) -> rrb.ContainerLike: return rrb.TimeSeriesView( name=f"{symbol1} vs {symbol2} ({day})", contents=[ f"+ /stocks/{symbol1}/{day}", f"+ /stocks/{symbol2}/{day}", ], )

与前面用origin+ 通配不同，这个蓝图完全不设 origin（保持默认/），而是用两条绝对实体路径把两路数据显式加入同一张TimeSeriesView：+ /stocks/META/{day}与+ /stocks/MSFT/{day}。当调用compare_two("META", "MSFT", dates[-1])时，即对比两只股票最近一个交易日（dates[-1]）的分时走势。这是多源数据对比的标准写法——路径即过滤器，多个+条目即可把任意实体汇入同一视图。

grid：嵌套容器构建网格看板

def stock_grid(symbols: list[str], dates: list[Any]) -> rrb.ContainerLike: return rrb.Vertical( contents=[ rrb.Horizontal( contents=[rrb.TextDocumentView(name=f"{symbol}", origin=f"/stocks/{symbol}/info")] + [rrb.TimeSeriesView(name=f"{day}", origin=f"/stocks/{symbol}/{day}") for day in dates], name=symbol, ) for symbol in symbols ], )

grid是默认蓝图，也是嵌套容器用法的完整示范：外层Vertical按股票逐行堆叠；每一行是一个Horizontal，列内容为“信息文档 + 该股票每一天的独立TimeSeriesView”。通过列表推导式，为 5 只股票、5 个交易日自动生成 5 行、每行 6 个视图的看板。注意这里每个视图的 origin 精确到/stocks/{symbol}/{day}，所以每个日期各占一张独立小图，与one-stock中“整只股票一张图”形成鲜明对比——同样的数据，视图划分粒度完全由蓝图决定。

面板控制：hide_panels 与 --show_panels

def hide_panels(viewport: rrb.ContainerLike) -> rrb.BlueprintLike: return rrb.Blueprint( viewport, rrb.TimePanel(state="collapsed"), rrb.SelectionPanel(state="collapsed"), )

hide_panels展示了Blueprint的“视图区 + 面板”组合能力：第一个位置参数是根容器（定义 viewport），随后可以传入任意面板部件。TimePanel(state="collapsed")与SelectionPanel(state="collapsed")分别把时间面板和选择面板折叠，营造沉浸式的图表看板效果。从 api.py 的Panel基类源码看，面板支持expanded（已废弃）与state两种写法，state可取expanded/collapsed/hidden，且每个面板类型（TopPanel、BlueprintPanel、SelectionPanel、TimePanel）在同一个Blueprint中最多出现一次。TimePanel还额外支持timeline、playback_speed、fps、play_state、loop_mode、time_selection等播放控制参数。

蓝图底层机制：View、Container、Panel 如何变成界面

理解示例中各种rrb.*对象的本质，需要回到蓝图 API 的源码。在 rerun_py/rerun_sdk/rerun/blueprint/api.py 中：

View（视图）：界面中一个具体的视图单元（如TimeSeriesView、TextDocumentView）。构造时携带class_identifier（如"TimeSeries"）、origin、contents、name，以及若干属性 archetype（如TimeAxis、ScalarAxis、PlotLegend、PlotBackground、PlotInteraction、VisibleTimeRanges）。内部_log_to_stream会把视图以view/{uuid}的蓝图实体路径写入流。
Container（容器）：用于排版的组织节点，Vertical/Horizontal/Grid/Tabs均为其子类，通过ContainerKind区分布局方向，通过row_shares/column_shares/grid_columns/active_tab控制空间分配。容器内部以container/{uuid}为路径递归记录其子节点。
Panel（面板）：控制 Viewer 顶部、蓝图、选择、时间四个面板的显隐与状态。
Blueprint：顶层容器，内部有一个根容器定义 viewport，再叠加若干面板。_log_to_stream最后会把根容器 id 写入viewport实体，并把面板状态写入各自路径。

最终，rr.send_blueprint(blueprint)把整棵“蓝图树”作为普通数据发送给 Viewer。值得一提的是Blueprint还提供save()（保存为.rbl蓝图文件）与connect_grpc()/spawn()（连接或拉起远程 Viewer）等方法，示例中未使用但值得了解。另外TimeSeriesView本身还支持axis_x、axis_y、plot_legend、background、interaction、time_ranges等属性（见 time_series_view.py 中的 docstring 示例），可用于设置 Y 轴范围、开关图例、隐藏网格、配置悬浮提示等，是扩展本示例图表细节的下一步入口。

数据侧实现：抓取、样式与实体路径约定

蓝图负责“怎么显示”，数据侧负责“显示什么”。数据部分同样在 blueprint_stocks.py 中完成，可分为三个层次：

1. 静态元数据与样式（static=True记录）。主循环首先为每只股票、每个交易日记录两组静态数据（第 174-178 行）：

rr.log(f"stocks/{symbol}/{day}", style_plot(symbol), static=True) rr.log(f"stocks/{symbol}/peaks/{day}", style_peak(symbol), static=True)

style_plot与style_peak分别构造rr.SeriesLines与rr.SeriesPoints，为曲线与峰值点指定品牌色、图例名与点标记（如markers="up"表示向上三角标记，峰值统一使用红色0xFF0000FF）。品牌色表（第 99-105 行）为每只股票定义了唯一颜色，使得同一视图中的多曲线天然可区分。

2. Markdown 信息文档。使用yf.Ticker(symbol)拉取shortName、industry、marketCap、totalRevenue，经humanize.intword格式化为可读文本后，以rr.TextDocument(info_md, media_type=rr.MediaType.MARKDOWN)记录到stocks/{symbol}/info——这正是one-stock-with-info与grid中TextDocumentView的数据来源。

3. 日内行情时间序列。对每个交易日取美东时间 09:30 开盘到 16:00 收盘、间隔 5 分钟的历史数据，将索引归一化为相对开盘时间的datetime.timedelta，随后：

rr.set_time("time", duration=row.Index) rr.log(f"stocks/{symbol}/{day}", rr.Scalars(row.High)) if row.Index == peak: rr.log(f"stocks/{symbol}/peaks/{day}", rr.Scalars(row.High))

即在time时间轴上按“距开盘的时长”推进时间游标，把每根 K 线的高价作为标量逐帧记录；同时找出当日最高点（hist.High.idxmax()）单独记录到peaks/子路径，供one-stock-no-peaks的排除表达式使用。注意交易日集合通过x.weekday() < 5过滤掉周末，保证只拉取真实交易日数据。

运行效果与自定义扩展建议

运行python -m blueprint_stocks（默认grid）即可看到 5 行 × 6 列的股票看板；依次尝试--blueprint=one-stock、one-stock-with-info、one-stock-no-peaks、compare-two可以直观对比“同一份数据在不同蓝图下的呈现差异”，这是理解 Rerun “数据与视图解耦”理念最快的路径。

在此基础上可以做以下扩展练习：

仿照compare_two增加compare-all蓝图，把五只股票同一日期的数据全部+进一张图；
在TimeSeriesView上追加axis_y=rrb.ScalarAxis(range=(0.0, 1000.0), zoom_lock=True)等属性，固定纵轴范围（属性细节见 time_series_view.py 的 docstring 示例）；
在Blueprint中组合rrb.TopPanel、rrb.BlueprintPanel，或把state从"collapsed"改为"hidden"体验更强的沉浸式布局；
用Blueprint.save()把满意的布局导出为.rbl蓝图文件，供其他程序或 Viewer 直接加载。

小结

blueprint_stocks用一组真实可运行的金融数据，把 Rerun Blueprint 的核心 API 全部串了起来：origin划定视图的数据范围，contents的+/-表达式实现包含与排除，Vertical/Horizontal容器配合row_shares/column_shares完成排版，TimePanel/SelectionPanel控制界面沉浸度，而auto_views/auto_layout则保留随时回归自动布局的能力。理解了这份示例，你就掌握了在 Rerun 中“一份数据、任意形态”的通用方法论——它同样适用于机器人多模态数据、传感器时序数据等其他以时间为主轴的场景。

企业官网建设流程全解析