Vega 层次边捆绑(Hierarchical Edge Bundling)实战:用 tree 变换与 bundle 插值绘制软件依赖关系图
Vega 层次边捆绑(Hierarchical Edge Bundling)实战:用 tree 变换与 bundle 插值绘制软件依赖关系图
层次边捆绑(Hierarchical Edge Bundling,HEB)是一种基于树形层次结构来减少网络图视觉混乱的经典技术:所有依赖边不再从源节点直接连向目标节点,而是沿着它们在层次树中的共同祖先路径“捆绑”成平滑曲线。本文以 Vega 官方示例 edge-bundling 为骨架,完整拆解该示例如何在软件类层次结构中可视化类之间的依赖关系——从 stratify/tree 变换构建放射状布局,到 treePath 表达式计算路径、line 标记的 bundle 插值绘制曲线,再到信号驱动的交互高亮。读完后你将能够独立复刻一个可交互的层次边捆绑图,并理解其背后 Vega 运行时与源码级的实现原理。
一、示例总览:一条边如何“捆绑”出来
原始示例文档 edge-bundling.md 用一句话概括了它的全部要点:
Visualizes dependencies between classes in a software class hierarchy using hierarchical edge bundling. Dependency curves are routed along the tree path between source and targets nodes in the package hierarchy. This example uses Vega's tree transform to layout the nodes, and a line mark with
bundleinterpolation to draw dependencies.
提炼出三个核心技术支柱,它们分别对应规范中的不同部分:
- 层次布局:用 tree 变换 把包/类层次树排布成放射状(角度 × 半径);
- 路径路由:用
treePath表达式计算依赖两端的树路径,作为曲线的骨架; - 曲线绘制:用 line 标记 的
bundle插值与tension参数控制捆绑曲率。
而“悬停节点高亮关联连线”的交互,则靠信号(signals)、indata 测试表达式与分组标记的 parent 引用协作完成。下文将按规范文件的顺序逐段展开。
二、视图与信号:交互参数从哪里来
示例的画布为 720×720 的方形视图,autosize: "none" 表示不做自动缩放,由布局坐标自行决定内容范围:
"padding": 5,
"width": 720,
"height": 720,
"autosize": "none"
signals 定义了全部用户可调参数与交互状态。前六个信号都绑定了输入控件(bind),这意味着渲染页面会生成对应的 UI 控件,读者可以实时调节:
| 信号 | 默认值 | 控件 | 作用 |
|---|---|---|---|
tension |
0.85 | range [0, 1],步长 0.01 | 捆绑曲线的张力(曲率),直接传给 line 标记的 tension 编码 |
radius |
280 | range [20, 400] | 放射布局的半径,控制整张图的大小 |
extent |
360 | range [0, 360] | 布局覆盖的扇区角度,360 即整圆,小于 360 会变成扇形图 |
rotate |
0 | range [0, 360] | 整体旋转角度,用于调整首节点起始方位 |
textSize |
8 | range [2, 20] | 叶节点标签字号 |
textOffset |
2 | range [0, 10] | 标签与圆环之间的间距 |
layout |
cluster | radio: tidy / cluster | 树布局方法:tidy(紧致、节点按深度分层)或 cluster(经典系统树图/树状图风格) |
colorIn |
firebrick | — | “被依赖”方向连线的颜色(入边) |
colorOut |
forestgreen | — | “依赖他人”方向连线的颜色(出边) |
active |
null | — | 当前悬停节点的 id,交互核心状态 |
其中 originX、originY 用表达式 width / 2、height / 2 动态计算为视图中心,保证图始终居中。active 信号通过事件更新驱动悬停交互:
{
"name": "active", "value": null,
"on": [
{ "events": "text:pointerover", "update": "datum.id" },
{ "events": "pointerover[!event.item]", "update": "null" }
]
}
text:pointerover:鼠标进入某个文本标签时,把该标签数据项的id写入active;pointerover[!event.item]:鼠标离开所有标记(事件目标不是任何 item)时,把active重置为null。
colorIn/colorOut 虽未绑定控件,但在规范末尾被一个 ordinal 序数比例尺 color 引用:
{
"name": "color",
"type": "ordinal",
"domain": ["depends on", "imported by"],
"range": [{"signal": "colorIn"}, {"signal": "colorOut"}]
}
比例尺的 range 直接引用信号值,说明 Vega 中比例尺也可以与信号联动;随后这个比例尺被 legends 用来生成“Dependencies”图例(symbolType: "stroke" 表示图例符号以描边线段展示)。
三、数据流水线:从层次树到放射坐标
3.1 tree 数据集:分层 + 布局 + 极坐标换算
tree 数据集的 URL 指向 data/flare.json(Flare 可视化库的类层次结构,约 1481 行 JSON),先后经过四个变换:
第一步 stratify:把扁平的父子表转成层次树对象。flare.json 中每条记录形如 {"id": 1, "name": "flare", "parent": null},通过 key: "id"、parentKey: "parent" 建立节点间的父子关系。该变换生成的是 Vega 的专用树节点对象,原始数据可通过节点的 data 字段访问(这一点在 tree 变换文档 中有明确说明)。
第二步 tree:计算节点链接布局。method 由信号动态指定({"signal": "layout"}),可在 tidy/cluster 间切换;size: [1, 1] 表示在归一化的 [0,1]² 空间里布局;输出字段通过 as: ["alpha", "beta", "depth", "children"] 重命名——这里把默认的 x、y 改名为 alpha(角度参数)、beta(半径参数),从而把直角坐标布局“解释”为极坐标参数,这正是 tree 变换文档 强调的“layout 坐标是任意坐标系,可把 x 当角度、y 当半径”的用法。
第三步/第四步 formula:把 alpha/beta 换算成真正的屏幕坐标,同时计算每个叶子是否位于圆盘左半边:
{ "type": "formula", "expr": "(rotate + extent * datum.alpha + 270) % 360", "as": "angle" },
{ "type": "formula", "expr": "inrange(datum.angle, [90, 270])", "as": "leftside" },
{ "type": "formula",
"expr": "originX + radius * datum.beta * cos(PI * datum.angle / 180)", "as": "x" },
{ "type": "formula",
"expr": "originY + radius * datum.beta * sin(PI * datum.angle / 180)", "as": "y" }
angle:把归一化角度alpha展开到extent扇区,再加上rotate和 270° 的基准偏移,最后取模 360 落在 [0, 360);leftside:判断角度是否在 [90°, 270°](左半圆),决定标签的朝向与对齐方式;x/y:标准的极坐标→直角坐标公式,beta充当半径比例因子,radius是最大半径。
3.2 leaves 数据集:只保留叶子节点
{
"name": "leaves",
"source": "tree",
"transform": [
{ "type": "filter", "expr": "!datum.children" }
]
}
tree 变换输出的每个节点带有 children 字段(在 as 中指定)。用 !datum.children 过滤掉所有内部节点,只留下叶子(即具体类),它们将作为文本标签和交互的入口。
3.3 dependencies 数据集:计算树路径
依赖边数据来自 data/flare-dependencies.json,每条记录含 source 与 target(均为叶子节点的 id)。核心是 formula 变换:
{
"type": "formula",
"expr": "treePath('tree', datum.source, datum.target)",
"as": "treepath",
"initonly": true
}
treePath 是 Vega 提供的内置表达式函数,实现在 packages/vega-functions/src/functions/tree.js:
export function treePath(name, source, target) {
const nodes = treeNodes(name, this),
s = nodes[source],
t = nodes[target];
return s && t ? s.path(t).map(datum) : undefined;
}
它从数据流中取出名为 tree 的数据集,利用其 root.lookup 索引按 id 找到源/目标树节点,调用 d3-hierarchy 的 path(t) 方法返回“从源节点上升到共同祖先、再下降到目标节点”的节点序列,最后 .map(datum) 把每个树节点映射回原始数据对象。因此 treepath 是一个有序的数据对象数组——这就是后续分组(facet)绘图的基础。initonly: true 表示该表达式只在初始化时计算一次,不随信号更新重算(路径本身不依赖任何交互状态,属于一次性派生数据)。
3.4 selected 数据集:驱动高亮
{
"name": "selected",
"source": "dependencies",
"transform": [
{ "type": "filter",
"expr": "datum.source === active || datum.target === active" }
]
}
当 active 信号变化时,selected 自动重算,仅保留与当前悬停节点相关的依赖边(源或目标等于 active)。这个数据集随后被文本标记的 indata('selected', ...) 测试使用,实现标签加粗与着色。
四、标记(marks):标签、曲线与交互
4.1 文本标记:放射状标签
{
"type": "text",
"from": {"data": "leaves"},
"encode": {
"enter": { "text": {"field": "name"}, "baseline": {"value": "middle"} },
"update": {
"x": {"field": "x"}, "y": {"field": "y"},
"dx": {"signal": "textOffset * (datum.leftside ? -1 : 1)"},
"angle": {"signal": "datum.leftside ? datum.angle - 180 : datum.angle"},
"align": {"signal": "datum.leftside ? 'right' : 'left'"},
"fontSize": {"signal": "textSize"},
"fontWeight": [
{"test": "indata('selected', 'source', datum.id)", "value": "bold"},
{"test": "indata('selected', 'target', datum.id)", "value": "bold"},
{"value": null}
],
"fill": [
{"test": "datum.id === active", "value": "black"},
{"test": "indata('selected', 'source', datum.id)", "signal": "colorIn"},
{"test": "indata('selected', 'target', datum.id)", "signal": "colorOut"},
{"value": "black"}
]
}
}
}
关键编码逻辑:
- 方位自适应:左半圆(
leftside为真)的标签dx为负(向左偏移)、align: 'right'、文字旋转angle - 180;右半圆则相反。这样标签永远“面朝外”且不互相挤压; - 高亮规则:
fontWeight与fill都使用测试数组(test-value 规则),优先级从上到下:- 当前悬停节点本身 → 黑色加粗;
- 是某条被选依赖边的
source→ 用colorIn(firebrick 红); - 是某条被选依赖边的
target→ 用colorOut(forestgreen 绿); - 其余 → 黑色、常规字重。
indata('selected', 'source', datum.id) 是 Vega 的集合测试表达式,判断 selected 数据集中是否存在 source 字段等于当前 id 的记录——比手写 filter + lookup 高效得多。
4.2 分组标记:把每条路径画成一条 bundle 曲线
这是全例的精华。外部是一个 group 标记,用 facet 按 treepath 字段对依赖边分组——每条依赖边生成一个子组,组内数据即该边的树路径节点数组:
{
"type": "group",
"from": {
"facet": {
"name": "path",
"data": "dependencies",
"field": "treepath"
}
},
"marks": [
{
"type": "line",
"interactive": false,
"from": {"data": "path"},
"encode": {
"enter": { "interpolate": {"value": "bundle"}, "strokeWidth": {"value": 1.5} },
"update": {
"stroke": [
{"test": "parent.source === active", "signal": "colorOut"},
{"test": "parent.target === active", "signal": "colorIn"},
{"value": "steelblue"}
],
"strokeOpacity": [
{"test": "parent.source === active || parent.target === active", "value": 1},
{"value": 0.2}
],
"tension": {"signal": "tension"},
"x": {"field": "x"}, "y": {"field": "y"}
}
}
}
]
}
要点:
interpolate: "bundle"告诉 line 标记使用 D3 的 bundle 曲线(贝塞尔样条),使路径呈现平滑的“丝带”感;tension信号直接绑定到编码属性,范围 0, 1],值越大曲线越“绷直”、越小越松垂。它在 [line 标记文档 中的默认值为 0.8,本示例的默认 0.85 略高于默认值;- 组内 line 通过
parent访问分组外层的数据(即依赖边记录),因此可以用parent.source === active、parent.target === active判断该曲线是否应高亮;非高亮曲线strokeOpacity: 0.2淡出,高亮曲线不透明; - 颜色语义与文本标记呼应:当前悬停节点作为
source的边用colorOut(绿色,表示“向外依赖”),作为target的边用colorIn(红色,表示“被依赖”)。interactive: false让曲线本身不响应鼠标事件,避免干扰标签上的悬停交互。
五、源码级原理:bundle 插值与 treePath 的底层实现
5.1 bundle 插值如何工作
Vega 的 line 标记把 interpolate 字符串映射到具体的 D3 曲线构造器,映射表位于 packages/vega-scenegraph/src/path/curves.js。bundle 条目为:
'bundle': {
curve: curveBundle,
tension: 'beta',
value: 0.85
}
curves(type, orientation, tension) 函数取出对应曲线后,若该曲线支持张力参数,还会调用 curveentry.tension 把编码层的 tension 值注入曲线(见 curves.js)。也就是说:tension 在这里被当作 D3 curveBundle.beta(tension) 的 β 参数,直接控制捆绑曲线的“贴紧程度”。支持张力参数的还有 cardinal(默认 0)与 catmull-rom(默认 0.5),而 linear、basis、natural、step 等则忽略张力。
5.2 treePath 的节点查找与路径构造
treePath 位于 packages/vega-functions/src/functions/tree.js,依赖树数据集的 root.lookup 索引。它等价于 d3-hierarchy 中 node.path(target) 的语义:从源节点沿 parent 链上溯到最近共同祖先,再下溯到目标节点,返回的数组恰好构成一条可绘制的连续折线路径。treePath 返回的是原始数据对象数组(.map(datum) 剥离树节点包装),这正是 facet 按字段分组所要求的普通数据行。若源或目标在树中不存在,函数返回 undefined,对应的边会被安全地忽略而不报错。
5.3 数据流触发关系
initonly: true 使 treepath 只在数据初始化时计算一次,避免每次滑动 tension 滑块都重算全部路径。与之相对,selected 数据集没有 initonly,因此每次 active 信号变化都会重新 filter——这正是悬停高亮实时响应的机制。整张图的依赖链可以概括为:
flare.json --stratify--> 树对象 --tree--> 极坐标参数 --formula--> 屏幕坐标
flare-dependencies.json --treePath--> treepath 数组 --facet--> 分组 line 标记
signals(active) --> selected 数据集 --> 文本标记 indata 测试 / 分组 parent 测试
六、运行与调整建议
查看与运行:本示例作为 Vega 官方示例集的一部分,规范文件为 edge-bundling.vg.json,数据文件为 flare.json 与 flare-dependencies.json,示例说明见 edge-bundling.md。在浏览器环境中通过 vega.parse(spec) 解析规范、new vega.View(parser).initialize(container).runAsync() 即可渲染;页面会自动生成 tension、radius、extent、rotate、textSize、textOffset、layout 对应的交互控件,无需额外代码。
可复制性与局限性说明:treePath 是 Vega 表达式环境的内置函数(导出自 packages/vega-functions/index.js),在使用自定义表达式函数或 vega-interpreter 时需要确认其可用性;tension/bundle 行为依赖 vega-scenegraph 对 d3-shape 曲线的封装,在 Node.js 服务端渲染与浏览器渲染中表现一致。
动手改造建议:
- 换数据:把
flare.json/flare-dependencies.json换成你自己的层次结构(节点必须有唯一id与parent字段),依赖数据保持source/target指向叶子 id 即可; - 调布局:把
extent从 360 调小(如 270),即得到扇形(半圆)捆绑图;把layout从cluster切到tidy,观察两种树布局对曲线形态的影响; - 改配色:直接修改
colorIn/colorOut信号默认值即可全局换色,因为文本标记、分组曲线与图例三处都引用这两个信号; - 裁剪交互:若不需要悬停高亮,删掉
active信号的on事件与selected数据集,同时移除文本/曲线编码里的测试规则即可,initonly的路径计算不受影响。
七、小结
层次边捆绑之所以适合依赖类网络,是因为它把“边”从几何直线升级为“沿层次树路径的曲线”,让同层、同父的依赖自然聚拢,视觉上形成清晰的束流结构。本示例用 Vega 的声明式规范完整实现了这一算法链:stratify 建树、tree 布局、formula 极坐标换算、treePath 路由、bundle 插值绘制,以及信号驱动的悬停高亮。掌握这套组合拳后,你不仅能复刻该示例,还能把同样的思路迁移到任意“网络 + 层次”叠加的数据场景中。
