kornia `distance_transform` 数值下溢修复：从静默返回错误结果到显式报错（4152）

计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载kornia.contrib.distance_transform是 Kornia 中基于级联卷积近似欧氏距离变换Euclidean distance transform的实现其核心是形如exp(-dist/h)的卷积核。当h相对kernel_size过小、或工作精度不足时核边缘的某个 tap 会下溢为精确的 0旧版本会静默丢掉该 tap返回一份看起来合理实则错误的距离场甚至全零结果。本篇文章基于 changelog.d/migration-099.fixed.md 中记录的 #4152 修复结合 kornia/contrib/distance_transform.py 的源码与 tests/contrib/test_conv_distance_transformer.py 的回归测试深入讲解该问题的根因、两处修复手段半精度升档 显式范围校验、跨后端一致性问题以及排错与参数选型建议。读完你将清楚什么参数组合会触发异常、为什么这样设计以及如何在 2D/3D 场景中安全使用该算子。背景级联卷积实现的distance_transform功能与 APIdistance_transform计算图像/体数据中每个像素或体素到最近非零元素的距离逐通道独立处理支持 2D(B, C, H, W)与 3D(B, C, D, H, W)输入。该方法源自pham2021dtlayer可微距离变换层通过级联的卷积与软最小soft-min操作逐步逼近精确欧氏距离因此全程可微可嵌入深度学习管线反向传播。函数式接口与模块式接口同时提供两者导出自 kornia/contrib/init.py文档入口见 docs/source/contrib.rst# 函数式 from kornia.contrib import distance_transform tensor torch.zeros(1, 1, 5, 5) tensor[:, :, 1, 2] 1.0 dt distance_transform(tensor) # 默认 kernel_size3, h0.35 # 模块式多通道输入会被折叠进 batch 维独立处理再还原布局 from kornia.contrib import DistanceTransform dt_module DistanceTransform(kernel_size7, h0.35) volume torch.zeros(1, 1, 5, 5, 5) volume[:, :, 2, 2, 2] 1.0 dt3d dt_module(volume)参数见 distance_transform 源码参数默认值约束与含义image必填浮点张量形状(B,C,H,W)或(B,C,D,H,W)非浮点/非法维度直接报错kernel_size3卷积核尺寸必须为不小于 3 的奇数KORNIA_CHECK强制h0.35控制对 min 函数近似的平滑度级联核 tap 为exp(-dist/h)h越小近似越尖锐但越容易下溢级联算法与核的构造2D 实现_distance_transform_2d_implkornia/contrib/distance_transform.py的流程是用create_meshgrid(kernel_size, kernel_size)生成以核中心为原点的偏移网格减去k_half kernel_size // 2得到相对距离计算距离dist sqrt(x² y²)构造核kernel exp(-dist / h)中心 tap 精确等于1.0由 test_kernel_geometry 验证迭代n_iters ceil(max(H, W) / k_half)次每轮对当前边界图做filter2d(..., border_typereplicate)再用-h * log(...)与阈值掩码提取正响应并累加距离偏移offset i * k_half循环次数固定、无数据相关早退使算子可被torch.compile完整图编译源码注释明确说明test_dynamo亦覆盖。一个细节2D 核的距离计算使用torch.sqrt(x**2 y**2)而非torch.hypot3D 使用torch.norm(..., p2)这是因为hypot没有 ONNX lowering——该改动记录在 changelog.d/migration-021.added.md#4182保证算子可经torch.onnx.export(..., dynamoTrue)导出。问题根因轴对齐 tap 的数值下溢为什么轴对齐 tap是判据而非角落 tapexp(-dist/h)核的 tap 随距离指数衰减但不同位置的 tap 重要性完全不同角落 tap距离sqrt(dims) * k_half衰减极快即使下溢丢失其对软最小soft-min的贡献也微乎其微丢失它无伤大雅轴对齐 tap沿单一坐标轴距离k_half处的 tap是真正参与传播最近距离信息的 tap丢失它才会实质性地破坏结果。因此_check_h_range的判据选取的是轴对齐 tapsmallest_tap exp(-k_half / h)而不是角落 tap见 kornia/contrib/distance_transform.py 的注释。触发场景默认参数在 float16 下的静默错误修复前float16/bfloat16输入直接在半精度下跑完整级联。半精度的最小正规数finfo(tiny) 6.10e-5即2^-14而默认h0.35时kernel_size 15 → k_half 7 → tap exp(-7/0.35) exp(-20) ≈ 2.06e-9 6.10e-5该 tap 在半精度下精确下溢为 0reachable from the documented defaulth0.35atkernel_size 15infloat16changelog 原文。卷积静默地丢掉这个 tap 后返回的是看起来合理但错误的距离场例如峰值距离本应约 13.5实际却回到约 15.7见测试注释若h再小一些则直接返回全零结果——没有任何报错排错极其困难。修复一半精度输入在 float32 下计算结果再转回第一个修复是升档计算。_compute_dtypekornia/contrib/distance_transform.py将float16/bfloat16输入的计算精度提升到float32级联结束后再cast回原 dtypedef _compute_dtype(dtype: torch.dtype) - torch.dtype: if dtype in (torch.float16, torch.bfloat16): return torch.float32 return dtype这一做法与 Kornia 其他模块对半精度输入的既有策略一致源码注释点名的PatchAffineShapeEstimator、extract_patches_from_pyramid均采用同类 upcast默认h0.35的场景仅靠这一条就能修复float32 的finfo.tiny ≈ 1.18e-38exp(-20) ≈ 2e-9落在其正常表示范围内与原生 float32 的工作区间对齐由于前向全程可微升档计算让半精度输入在精度与梯度行为上都与 float32 对齐。回归测试 test_half_precision_matches_float64_reference 固定了这一行为对kernel_size15的输入无论float16/bfloat16输入输出峰值都应跟踪独立的 CPU float64 参考值rtol/atol1e-2——修复前该用例会得到约 15.7 的错误峰值。修复二仍会下溢的组合改为显式报错升档解决了默认参数但某些h/kernel_size/dtype 组合即便在 float32 下轴对齐 tap 依然下溢。此时旧版本会继续猜测一个错误答案新版本改为直接抛错——这正是_check_h_rangekornia/contrib/distance_transform.py的作用k_half kernel_size // 2 smallest_tap math.exp(-k_half / h) KORNIA_CHECK( smallest_tap torch.finfo(dtype).tiny, fh{h} is too small for kernel_size{kernel_size} at working precision {dtype}: ..., )为什么阈值选finfo.tiny最小正规数而非次正规数一个关键的设计决策判据使用的是torch.finfo(dtype).tiny——最小的正正规数而不是设备相关的真正最小次正规数。原因在于跨后端一致性CPU 保留次正规数exp(-100) ≈ 3.7e-44在 float32 中虽低于最小正规数1.18e-38但仍大于真正的次正规下界CPU 能正确携带它参与计算MPS 将次正规数刷为 0同样的数值在 Apple MPS 上被 flush 成 0。于是同一个调用在 CPU 与 MPS 上会静默地得到不同结果。changelog 给出了一个具体案例h0.01、kernel_size3、float32 时tap exp(-1/0.01) exp(-100)CPU 上该调用并非数值错误距离场跟踪解析参考值到约2e-4精度全程经次正规范围携带但 MPS 上结果不同。这种取决于调用者碰巧跑在哪个后端的隐性分歧无法容忍因此新版本对这类组合统一报错把分歧从源头排除而不是信任某一端的意外行为。修复后的判定边界float32 工作精度以finfo(float32).tiny ≈ 1.18e-38、判据exp(-(kernel_size//2)/h) tiny推算与 changelog 表述一致场景轴对齐 tap修复前修复后h0.35kernel_size 63float32exp(-31/0.35) ≈ 5.5e-39 tinyCPU 返回可用样子的答案MPS 静默返回别的东西抛错h0.01kernel_size3float32或半精度升档后exp(-100) ≈ 3.7e-44次正规CPU 数值正确~2e-4MPS 刷零两端不一致抛错任意h在任意工作精度下 tap 下溢如h1e-30任何精度含 float64都下溢静默返回错误/全零抛错h0.35kernel_size 61float32exp(-30/0.35) ≈ 2e-38 tiny正常正常float16/bfloat16 经升档同样正常对应的异常信息会同时给出原因与解法建议Increase h or decrease kernel_size。跨后端一致性与相关修复的联动本次修复并非distance_transform唯一的健壮性改动它与仓库中另外两条变更记录形成完整的数值安全闭环NaN 梯度修复#4232见 changelog.d/migration-064.fixed.md当级联卷积恰为全零稀疏掩码、全零输入时-h*log(0)会产生 NaN 梯度修复后前向输出不变但梯度保持有限。测试 test_zero_convolution_has_finite_gradients 验证了全零输入输出全零且梯度全有限。ONNX 导出适配#4182见 changelog.d/migration-021.added.md核距离计算避免hypot使算子可被 Dynamo ONNX 导出覆盖。三者的共同主题是消除静默行为要么让错误结果不可能出现显式报错要么让结果与参考一致升档计算、有限梯度、导出等价。回归测试新行为被牢固固定tests/contrib/test_conv_distance_transformer.py 中与 #4152 直接相关的用例构成了一张防护网测试固定行为test_half_precision_matches_float64_reference半精度float16/bfloat16输入在kernel_size15、默认h0.35下跟踪 float64 参考test_h_too_small_raisesh1e-30在任何工作精度下抛BaseError匹配 too small for kernel_sizetest_h_too_small_raises_float32_regressionh0.01、kernel_size3在float32下必须抛错float64 因finfo.tiny更小而不触发恰好验证了阈值与精度相关test_offset_parenthesis_fix将原先h0.01的用例改为h0.1继续锁定 offset 累加的括号正确性错写offset cdt * mask会使该用例失败同时避开新的下溢守卫test_dynamo/test_gradcheck/test_value_2d/test_value_3d编译等价性、可微性gradcheck、2D/3D 数值正确性值得注意测试文件中删除了一个原先用于固定修复前静默错误行为的 xfail 用例test_convention_small_h_keeps_nonzero_distances_4152因为修复后该组合改为抛BaseError与 xfail 锁定的AssertionError类型不符——这从侧面印证了行为变更的刻意性与彻底性。实践建议优先使用默认参数h0.35与kernel_size3的组合在 float32 及半精度升档后下都安全需要更大感受野时float32 下kernel_size 61均可配合h0.35使用。调整参数时先算判据牢记exp(-(kernel_size // 2) / h) torch.finfo(工作精度).tiny。h减半会平方级放大指数衰减增大kernel_size则线性放大k_half——两者都会迅速逼近下溢边界。不要依赖没报错报错是刻意设计的安全网。若收到h... is too small for kernel_size...异常按提示增大h或减小kernel_size而不是用try/except吞掉。跨后端部署注意涉及次正规数范围的组合如h0.01、kernel_size3的 float32在 CPU 上能用但在 MPS 上结果不同新版本直接拒绝这类组合若要保留小h的尖锐近似请显式改用 float64 工作精度并自行评估后端一致性。保持可微与可导出distance_transform全程可微见test_gradcheck且支持torch.compiletest_dynamo与 Dynamo ONNX 导出在多通道输入时使用DistanceTransform模块即可自动按通道独立处理并还原布局kornia/contrib/distance_transform.py。总而言之#4152 的修复把distance_transform从在特定精度/参数组合下静默产出错误结果的隐患中解放出来半精度升档扩大了安全区间显式校验则把所有仍可能下溢的组合挡在报错之外配合跨后端一致性考量让这个可微距离变换算子在任何 dtype、任何后端上都行为可预期。赞分享计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载相关推荐告别逐帧手K用 BoneAnimCopy 三步完成 Blender 骨骼动画重定向告别逐帧手K用 BoneAnimCopy 三步完成 Blender 骨骼动画重定向 凌晨一点半你把 Mixamo 上下载的跑步动画套到自己的角色骨架上播放开发工具代码质量静态分析揭秘mqttclient核心架构跨平台设计与mbedtls加密无缝集成的实现原理揭秘mqttclient核心架构跨平台设计与mbedtls加密无缝集成的实现原理 MQTTClient是一个高性能、高稳定性、跨平台的MQTT客户端库它基于物联网嵌入式通信TypeGraphQL查询错误恢复部分结果返回策略TypeGraphQL查询错误恢复部分结果返回策略 在GraphQL API开发中单一字段错误导致整个查询失败是常见痛点。本文将系统介绍TypeGraphQ后端GraphQLAPI设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考