Kornia 文档交互化改造实战:Playground「Try in browser」徽章、nms2d/nms3d 单位窗口语义修正与 Plasma 增强确定性重放
Kornia 文档交互化改造实战:Playground「Try in browser」徽章、nms2d/nms3d 单位窗口语义修正与 Plasma 增强确定性重放
本文基于 Kornia 仓库 changelog.d 中保留的 +migration-009 系列变更记录(对应 PR #4333、#4242、#4462),完整拆解三条对开发者有直接影响的改动:API 参考文档新增「Try in browser」交互徽章及其快照维护机制、nms2d/nms3d 单位窗口(unit window)行为从伪影与异常走向明确定义、RandomPlasmaBrightness/RandomPlasmaContrast/RandomPlasmaShadow 三个增强算子获得可确定性重放能力。读者读完既能理解每条变更背后的设计动机与迁移影响,也能掌握文档徽章体系的生成、注入与刷新全流程。
一、变更背景:changelog.d 碎片化发布机制与 +migration-* 保留文件
在深入三条变更之前,先说明它们的载体。Kornia 采用 Towncrier 目录,文件名遵循 <PR>.<type>.md 约定,类型分为 added(新特性)、fixed(缺陷修复)、breaking(破坏性变更,需同时描述新旧行为),详见 changelog.d/README.md。
其中 +migration-* 是一批特殊保留文件:它们保存了该工作流引入前已处于 Unreleased 章节的历史条目,使用 Towncrier 的孤儿前缀 + 以避免在发布时生成重复的 PR 链接,且仅在首次迁移后的那次发布中被消费。本文讨论的 +migration-009.added.md、+migration-009.breaking.md、+migration-009.fixed.md 正是同一发布周期内、由三个不同 PR 提交的同批次三条用户可见变更。这与仓库根目录 CHANGELOG.md 最终合并后的章节一一对应。
二、新增:API 参考文档的「Try in browser」交互徽章(PR #4333)
2.1 功能动机:让 API 文档"可运行"
+migration-009.added.md 描述了这次新增功能的核心:
API reference entries now carry a Try in browser badge that links a function, its
nn.Modulecounterpart or a browser model to its interactive page on the kornia.org playground, so readers can run the operator on a sample image without installing anything.
也就是说,从本次发布开始,Kornia 的 API 参考文档(Sphinx 自动生成)中,凡是 playground 上存在对应交互页面的条目,都会在摘要行之后出现一个「Try in browser」徽章。点击后读者直接在浏览器中对该算子施加于示例图片,观察输出结果,完全不需要本地安装 Kornia、不需要 Python 环境、不需要 GPU。这对于快速验证算子行为、比较不同参数效果、以及在撰写文档或 issue 时复现问题,都提供了零成本的入口。
徽章的覆盖对象有三类:
- 函数式 API(function),例如
kornia.filters.sobel; - 对应的
nn.Module封装(module counterpart),例如kornia.filters.Sobel——它与函数共享同一个交互页面; - 浏览器端模型(browser model),例如
kornia.feature.LoFTR、kornia.models.tiny_vit.TinyViT等可在浏览器直接推理的模型。
2.2 快照文件:docs/source/_playground_links.json
徽章链接集合并非文档构建时动态请求网络获取,而是维护为一份静态快照:docs/source/_playground_links.json。该文件是一个从「全限定 API 名」到「playground 页面 URL」的映射。对当前仓库快照的统计显示,它共包含 245 个条目,按顶层模块分布如下:
| 模块 | 条目数 | 代表性条目 |
|---|---|---|
kornia.augmentation |
68 | RandomAffine、RandomCrop、RandomMosaic、RandomPlasmaBrightness |
kornia.color |
43 | rgb_to_lab、RgbToHsv、apply_colormap |
kornia.enhance |
40 | adjust_gamma、JPEGCodecDifferentiable、equalize_clahe |
kornia.filters |
37 | gaussian_blur2d、Canny、MedianBlur、fft_conv |
kornia.geometry |
35 | nms2d、warp_perspective3d、center_crop |
kornia.morphology |
7 | dilation、erosion、top_hat |
kornia.feature |
7 | LoFTR、XFeat、KeyNet+HardNet、harris_response |
kornia.contrib |
5 | connected_components、FaceDetector、EdgeDetectorBuilder |
kornia.models |
3 | TinyViT、SmallSRNetWrapper、DepthAnythingONNXBuilder |
观察条目可以确认几个设计细节:函数与其 nn.Module 版本(如 kornia.color.rgb_to_lab 与 kornia.color.RgbToLab)映射到同一个页面 URL;模型类(如 kornia.feature.LoFTR)使用 /playground/models/<slug>/ 路径,与算子使用的 /playground/ops/<slug>/ 路径区分。
2.3 快照生成脚本:docs/generate_playground_links.py
快照由 docs/generate_playground_links.py 生成。其数据源是 kornia.org playground 发布的两个 JSON 文件:
playground/registry.json:算子注册表,每个算子携带全限定名称(id)、页面slug、status以及可选的module_name(nn.Module对应类名);playground/models/index.json:浏览器模型索引,每个模型同样携带id与slug。
脚本核心逻辑 build_map() 值得逐段理解:
- 遍历注册表中每个算子,仅保留
status属于RUNNABLE_STATUS = {"live", "frames"}且非alias_of(别名)的条目——注释说明,页面只记录了"不可导出"状态的算子没有可运行内容,因此不生成徽章; - 为算子生成
https://kornia.org/playground/ops/<slug>/链接,并同时登记其id与module_name(两者共享同一页面); - 遍历模型索引,生成
https://kornia.org/playground/models/<slug>/链接; - 最后
dict(sorted(...))排序后写入docs/source/_playground_links.json,保证输出稳定、可 diff。
数据加载支持两种模式(_load 函数):
# 模式一:从本地 kornia.github.io 检出目录读取(离线、可复现)
KORNIA_SITE=~/git/kornia.github.io python docs/generate_playground_links.py
# 模式二:直接从已发布站点抓取
python docs/generate_playground_links.py
若最终生成的映射为空,脚本会以 sys.exit("no playground links were produced; check KORNIA_SITE or the network") 明确报错,防止误写入空快照。如文档头注释所述,将快照捆绑进仓库(而非构建期联网拉取)是为了"让文档构建保持离线且可复现;刷新它是一次刻意、可审查的变更,而不是构建期的网络调用"。
2.4 徽章注入机制:docs/source/conf.py 中的 autodoc 钩子
快照文件只有在文档构建时被消费才有意义。消费逻辑位于 docs/source/conf.py:
- 模块加载时读取
_playground_links.json,用try/except (OSError, json.JSONDecodeError)包裹——即使快照缺失,文档也必须能正常构建(此时_PLAYGROUND_LINKS = {},只是没有徽章); _inject_playground_link(app, what, name, obj, options, lines)挂接在 Sphinx 的autodoc-process-docstring事件上。它只对what in ("function", "class")生效,在映射表中查到name后,构造一段 reST 徽章:
badge = ["", ".. container:: kornia-try", "", f" `Try in browser <{url}>`__", ""]
cut = next((i for i, line in enumerate(lines) if line.strip() == ""), len(lines))
lines[cut:cut] = badge
关键在于 cut 的定位:徽章被插入到 docstring 的第一段空白行之后,即首个摘要段落的下方。注释说明这是为了保证"摘要保持为第一行(autosummary 依赖它)",徽章只追加其后而不破坏摘要提取。
2.5 徽章视觉样式:docs/source/_static/css/playground.css
徽章外观由 docs/source/_static/css/playground.css 定义,并通过 html_css_files = <a href="https://link.gitcode.com/i/0754b59d5a3022b5bb44a246ff7fc419" target="_blank">"css/pydata.css", "css/blueprint.css", "css/playground.css"]([conf.py)引入。样式要点:
.kornia-try容器右对齐,位于内容列右侧边缘;- 链接呈现为胶囊(
border-radius: 999px)、琥珀色描边#f5b301、浅琥珀色半透明背景; - 悬停时背景填充为
#f5b301、文字反转为深色,形成明显的可交互反馈; - 同时提供
html[data-theme="dark"]与@media (prefers-color-scheme: dark)两套暗色适配。
除自动注入的徽章外,docs/source/models/index.rst 中的模型清单表格也手工放置了等价的「Try in browser」链接(如 RT-DETR、YuNet、TinyViT、LoFTR、HardNet、DexiNed),首页 docs/source/index.rst 亦以按钮链接指向 playground。
2.6 维护建议:何时需要刷新快照
结合脚本注释与 conf.py 注释,快照的刷新时机可以总结为:
- playground 新增或移除算子/模型时——例如新算子加入
registry.json且状态为live或frames; - 算子状态发生变化(例如从不可导出变为可运行);
- 刷新的动作应作为独立、可审查的提交合入,而非在 CI 构建期动态拉取。
三、破坏性变更:nms2d/nms3d 单位窗口语义修正(PR #4242)
3.1 旧行为的问题
+migration-009.breaking.md 记录了一条需要用户感知的行为修正:
nms2d(x, (1, 1))andnms3d(x, (1, 1, 1))returnxunchanged. A unit window has no neighbours, so nothing can be suppressed; the old 2-D result was an artifact of the zeroed centre tap of the convolution kernel summing to0.0, while the old 3-D path raised because of #4241.
nms2d 与 nms3d 是 Kornia 子像素模块(kornia.geometry.subpix)中的非极大值抑制算子,接口定义见 docs/source/geometry.subpix.rst 的 "Non-Maxima Suppression" 一节,签名分别为 nms2d(input, kernel_size, mask_only=False) 与 nms3d(input, kernel_size, mask_only=False)。它们把密集的角点/关键点响应图稀疏化为局部极大值候选位置,是 kornia/geometry/subpix/nms.py 中 NonMaximaSuppression2d / NonMaximaSuppression3d 模块的函数式入口。
当窗口参数取单位窗口 (1, 1)(2D)或 (1, 1, 1)(3D)时,窗口内除了中心点本身没有任何邻居,因此"抑制"无从谈起,正确语义就是原样返回。然而旧实现的行为是错的:
- 2D 路径:旧实现基于卷积核对响应图做局部求和比较,其中卷积核的中心 tap 被置零。当窗口为
(1, 1)时核内仅剩中心一个元素且为 0,整个求和结果恒为0.0,导致输出全部归零——这是一个数值伪影,而非有意义的 NMS 结果; - 3D 路径:旧实现直接抛出异常,问题追踪自 #4241。
3.2 新行为与源码实现
修复后的语义在 nms.py 中明确落地。NonMaximaSuppression2d.forward 的开头分支(L162-L163):
if self.kernel_size == (1, 1):
mask = torch.ones(B, CH, H, W, device=x.device, dtype=torch.bool)
单位窗口直接生成全 True 的布尔掩码:每个位置都是"局部极大值",因此 mask_only=False 时返回的 x 保持逐元素不变。NonMaximaSuppression3d 同样在 self.kernel_size == (1, 1, 1) 处走等价的全 True 掩码分支(nms.py)。
值得注意的是,当前实现为常见窗口尺寸提供了显式逐元素比较路径,例如 3×3 窗口的 8 次严格大于比较(L164-L180)、5×5 的 24 次比较等,注释说明这是"为 3×3 邻域显式比较路径:不再为卷积核占用额外内存"。这在性能上优于通用卷积方案,同时也让边界行为更直观。
3.3 边界语义与迁移建议
修复后的契约可以完整表述为:
nms2d(x, (1, 1))/nms3d(x, (1, 1, 1)):单位窗口无邻居,任何元素都不会被抑制,输出与输入恒等;- 一般窗口下,每个空间位置只与窗口内邻居比较,必须严格大于(strictly larger than)才保留;
- 距离边缘
(k - 1) // 2以内的位置永远不可能是极大值——因为其窗口无法完整放入输入,比较无法进行(见 nms.py 的 docstring 说明)。
对调用方的影响:如果你曾在 2D 场景用 kernel_size=(1, 1) 且依赖旧的"全零输出"(例如作为占位或恒零掩码),现在会得到原始输入,需要改用显式方式表达意图;3D 场景则从"报错"变为"合法调用",nms3d(x, (1, 1, 1)) 现在可安全使用。对于绝大多数正常使用((3, 3) / (3, 3, 3) 及以上窗口)的行为没有任何变化。
四、修复:Plasma 增强算子的确定性重放(PR #4462)
4.1 变更内容
+migration-009.fixed.md 记录:
Fixed
RandomPlasmaBrightness,RandomPlasmaContrast, andRandomPlasmaShadowto replay deterministically from storedparams=.
RandomPlasmaBrightness、RandomPlasmaContrast、RandomPlasmaShadow 是 Kornia 增强模块中基于等离子体(plasma)噪声模拟光照变化的三个随机增强算子,均可在 playground 上交互体验(快照 docs/source/_playground_links.json 中包含三者对应的 /playground/ops/ 页面条目)。
4.2 修复的意义:可复现性与离线增强
Kornia 的增强模块(kornia.augmentation)与纯随机采样不同,其设计哲学是"参数可记录、可重放":每次随机变换产生的参数(几何变换矩阵、亮度/对比度因子、plasma 噪声的随机种子等)都会被序列化进 params 字典,并在 forward 时既可用于当前批次,也能在后续阶段(如对同一数据流施加不同处理、或在训练与推理间保持一致性)被显式传入以确定性重放同一变换。
本次修复让三个 Plasma 算子归入这一体系:从存储的 params= 重放时,生成的 plasma 噪声与亮度/对比度/阴影调制结果与原始执行严格一致,不再因内部随机源未被纳入参数化而出现重放漂移。这直接服务于需要可复现的数据增强流水线(例如对比实验、日志审计、多 worker 数据加载与离线增强缓存场景)。
4.3 使用建议
在实践中,若你的流水线依赖这些算子的重放能力,可以按以下方式使用:
import torch
from kornia.augmentation import RandomPlasmaBrightness
aug = RandomPlasmaBrightness(p=1.0)
x = torch.rand(2, 3, 64, 64)
out_1 = aug(x) # 首次执行,随机生成参数
params = aug._params # 记录本次参数(含等离子噪声种子)
out_2 = aug(x, params=params) # 重放:结果与 out_1 一致
注意:
_params是内部属性,跨版本可能存在命名调整;生产代码建议在单次流水线生命周期内使用,跨进程持久化参数请参考官方文档对应版本的 API 说明。三条变更涉及的具体参数与 API 细节,以 kornia/augmentation/_2d 目录下对应算子的当前实现与测试为准。
五、总结:一次发布的三面观照
+migration-009 的三条记录恰好展现了 Kornia 一个发布周期内的三种典型变更形态:
- 新增(#4333):把文档从"静态说明"升级为"可交互体验"——通过快照 JSON、生成脚本、autodoc 钩子与 CSS 四层配合,构建出一套离线可复现、增量可审查的「Try in browser」徽章体系,同时让缺失快照的文档构建依然健壮;
- 破坏性变更(#4242):把
nms2d/nms3d单位窗口从"数值伪影 + 异常"收敛为"无邻居、无抑制、恒等返回"的明确契约,并在源码中以全True掩码直接实现,附带清晰的边界语义文档; - 修复(#4462):让三个 Plasma 随机增强算子回归 Kornia"参数化 + 可重放"的设计主线,保证从
params=重放的确定性。
对于升级到包含本批变更版本的读者:文档徽章是无感知增强;nms2d/nms3d 的 (1, 1)/(1, 1, 1) 调用需按新契约审视;Plasma 算子则获得了更可靠的重放保证。相关实现与测试可直接在仓库中继续追踪:docs/generate_playground_links.py、docs/source/conf.py、kornia/geometry/subpix/nms.py 与 kornia/augmentation 目录。