Kornia 文档交互化改造实战:Playground「Try in browser」徽章、nms2d/nms3d 单位窗口语义修正与 Plasma 增强确定性重放

原创2026-09-22 17:25:071,616 阅读
文章标签:计算机视觉图像处理人工智能深度学习机器学习图形学科学计算

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.Module counterpart 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() 值得逐段理解:

  1. 遍历注册表中每个算子,仅保留 status 属于 RUNNABLE_STATUS = {"live", "frames"} 且非 alias_of(别名)的条目——注释说明,页面只记录了"不可导出"状态的算子没有可运行内容,因此不生成徽章;
  2. 为算子生成 https://kornia.org/playground/ops/<slug>/ 链接,并同时登记其 id 与 module_name(两者共享同一页面);
  3. 遍历模型索引,生成 https://kornia.org/playground/models/<slug>/ 链接;
  4. 最后 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)) and nms3d(x, (1, 1, 1)) return x unchanged. 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 to 0.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, and RandomPlasmaShadow to replay deterministically from stored params=.

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 一个发布周期内的三种典型变更形态:

  1. 新增(#4333):把文档从"静态说明"升级为"可交互体验"——通过快照 JSON、生成脚本、autodoc 钩子与 CSS 四层配合,构建出一套离线可复现、增量可审查的「Try in browser」徽章体系,同时让缺失快照的文档构建依然健壮;
  2. 破坏性变更(#4242):把 nms2d/nms3d 单位窗口从"数值伪影 + 异常"收敛为"无邻居、无抑制、恒等返回"的明确契约,并在源码中以全 True 掩码直接实现,附带清晰的边界语义文档;
  3. 修复(#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 目录。

登录后查看全文
kornia