Kornia 中 SOLD² 线段检测与匹配实战:从预训练模型调用到源码级原理

原创2026-09-23 21:09:581,406 阅读
文章标签:计算机视觉图像处理人工智能深度学习机器学习图形学科学计算

Kornia 中 SOLD² 线段检测与匹配实战:从预训练模型调用到源码级原理

SOLD²(Self-supervised Occlusion-aware Line Detection and Description)是 CVPR 2021 提出的首个在单一深度网络内联合完成线段检测与描述的方法,Kornia 将其以 PyTorch 模块的形式完整复现并附带了在 Wireframe 数据集上预训练的权重。本文以 docs/source/models/sold2.rst 为骨架,完整讲解 SOLD2 与 SOLD2_detector 的调用方式、输出格式、配置参数,并深入到 kornia/feature/sold2/ 的源码与 tests/feature/test_sold2.py 测试,让读者既能直接跑通"检测 + 匹配"流程,也能理解线段检测、描述子提取与基于 Needleman-Wunsch 的线段匹配的底层原理。

SOLD² 线段检测与匹配效果:左右两图为各自检测到的线段(绿色),右图以同色绘制匹配对

SOLD² 是什么:像关键点一样匹配线段

与特征点检测和描述相比,线段检测与描述面临更多挑战,但线段由图像梯度定义清晰、在低纹理区域也频繁出现,并能提供稳健的结构线索。SOLD² 的核心思想是:在一个网络中同时完成线段的检测和描述,从而让线段能够像关键点一样跨视角匹配。得益于自监督训练,该方法不需要任何人工标注的线段标签,因此可以泛化到任意数据集。

在 Kornia 中这一能力由两个类提供(导出自 kornia/feature/init.py):

  • SOLD2:完整管线,返回每张图像的线段(line_segments)以及稠密描述子图(dense_desc),并提供 match 方法配对两张图像的线段;
  • SOLD2_detector:仅检测器,只输出线段和热力图,不计算描述子,也无法匹配。

两者的模型权重均基于 Wireframe 数据集训练,协议为 MIT。

快速上手:一行配置跑通检测与匹配

官方文档给出了一个可直接复制运行的示例。假设手头有两张同一场景的照片 church_1.png 与 church_2.png(位于当前工作目录):

import torch
from kornia.color import rgb_to_grayscale
from kornia.feature import SOLD2
from kornia.io import load_image

img1 = load_image("church_1.png")[None]  # (1, 3, H, W) float in [0, 1]
img2 = load_image("church_2.png")[None]
gray = rgb_to_grayscale(torch.cat([img1, img2]))  # (2, 1, H, W)

sold2 = SOLD2(pretrained=True).eval()
with torch.no_grad():
    out = sold2(gray)
    lines1, lines2 = out["line_segments"]  # list of (N, 2, 2) endpoints in (y, x) pixels, one per image
    desc = out["dense_desc"]  # (2, 128, H/4, W/4)
    matches = sold2.match(lines1, lines2, desc[0:1], desc[1:2])  # (N1,) index into lines2, -1 = no match

matched1, matched2 = lines1[matches != -1], lines2[matches[matches != -1]]

几个关键点:

  • 输入是灰度批次:load_image 返回 (1, 3, H, W) 的 float 图像(值域 <a href="https://link.gitcode.com/i/3510ad24ea9502c300440bd26c237e42" target="_blank">0, 1]),通过 rgb_to_grayscale 转成单通道。SOLD2.forward 内部通过 KORNIA_CHECK_SHAPE(img, ["B", "1", "H", "W"]) 强制校验输入形状(见 [kornia/feature/sold2/sold2.py),因此必须保证 (B, 1, H, W)。
  • 端点坐标约定:line_segments 中的每条线段是 (N, 2, 2),即两个端点的 (y, x) 像素坐标(ij 坐标约定)。
  • 匹配结果约定:matches 长度为 N1(第一张图像的线段数),每个元素是第二张图像中匹配线段的索引,-1 表示未匹配上。代码最后的切片即可筛出匹配对。
  • 示例中的 match 使用的是批量描述子 desc[0:1] 和 desc[1:2],形状为 (1, 128, H/4, W/4)。

除了上述字段,out 中还携带原始热力图 junction_heatmap 与 line_heatmap,形状均为 (B, H, W)。检测与匹配的阈值全部通过 SOLD2 的 config 参数控制(详见下文"配置参数"一节)。

输出解析:一次前向返回什么

SOLD2.forward(kornia/feature/sold2/sold2.py)返回一个字典,包含四个键:

键 形状 含义
line_segments List[(N, 2, 2)],每张图像一个 N 条线段的两个端点,(y, x) 像素坐标
junction_heatmap (B, H, W) 原始角点(junction)热力图
line_heatmap (B, H, W) 原始线段热力图
dense_desc (B, 128, H/4, W/4) 半稠密描述子图(空间分辨率是输入的 1/4,通道数 128)

从源码看,前向过程分为两段(对应 kornia/feature/sold2/sold2.py):

  1. CNN 骨干前向:SOLD2Net 一次性输出角点热力图、线段热力图和描述子(SOLD2 构造时会把 use_descriptor 强制置为 True,见 kornia/feature/sold2/sold2.py);
  2. 检测后处理:对每张图像的角点概率图调用 prob_to_junctions 提取角点,再交给 LineSegmentDetectionModule.detect 生成连通关系图 line_map,最后用 line_map_to_segments 转成 (N, 2, 2) 端点列表(实现在 kornia/feature/sold2/sold2_detector.py)。

而 SOLD2_detector 的前向(kornia/feature/sold2/sold2_detector.py)只输出 line_segments、junction_heatmap、line_heatmap 三项,不计算描述子。测试 tests/feature/test_sold2.py 也印证了这一约定:对 (B, 1, 64, 64) 的输入,两个热力图形状均为 (B, 64, 64);SOLD2 的描述子输出则为 (B, 128, 16, 16)(tests/feature/test_sold2.py)。

配置参数:检测与匹配的每个阈值

文档明确指出:检测和匹配阈值通过 SOLD2 的 config 参数设置。源码中的 config 类型为 DetectorCfg 数据类(定义在 kornia/feature/sold2/structures.py),默认参数针对 400~800 像素的图像调优。SOLD2 同时兼容 dict 形式的旧配置——传入 dict 时通过 dict_to_dataclass 自动转换,但源码中的弃用警告(kornia/feature/sold2/sold2_detector.py)明确建议改用 DetectorCfg 数据类以保证类型安全。

顶层 DetectorCfg

字段 默认值 说明
backbone_cfg BackboneCfg() 骨干网络配置(输入通道 1、深度 4、堆叠 2 个沙漏模块、每个残差块 1 层、5 个输出类)
use_descriptor False SOLD2_detector 保持 False;SOLD2 构造时会强制置为 True
grid_size 8 角点解码器的上采样倍数,热力图相对输入的空间缩放
keep_border_valid True 是否保留边界角点
detection_thresh 0.0153846(即 1/65) 角点检测阈值,对应 SuperPoint 式 65 通道 softmax 输出的单格概率
max_num_junctions 500 每张图像最多保留的角点数
line_detector_cfg LineDetectorCfg() 线段检测后处理配置
line_matcher_cfg LineMatcherCfg() 线段匹配配置(仅 SOLD2 使用)

线段检测 LineDetectorCfg

SOLD2 中的角点只是候选,真正的线段由 LineSegmentDetectionModule 从角点连通性和线段热力图推断而来(kornia/feature/sold2/sold2_detector.py)。其配置默认值如下:

字段 默认值 说明
detect_thresh 0.5 线段判定的平均激活概率阈值(0~1)
num_samples 64 沿每条候选线段采样的位置数(torch.linspace(0, 1, 64))
inlier_thresh 0.99 满足阈值采样点的最小内点比例(0~1,0 表示不启用)
use_candidate_suppression True 是否抑制长线段的重叠候选(将长线段拆分为子段)
nms_dist_tolerance 3.0 NMS 距离容差,决定某角点是否算"落在线上"
heatmap_low_thresh 0.15 角点恢复中视为候选像素的最低阈值
heatmap_high_thresh 0.2 角点恢复中 NMS 的高阈值
max_local_patch_radius 3.0 局部最大值搜索的最大邻域半径
lambda_radius 2.0 局部最大值搜索线性公式中的 λ 因子
use_heatmap_refinement True 是否启用热力图细化
heatmap_refine_cfg HeatMapRefineCfg() 热力图细化参数(见下)
use_junction_refinement True 是否启用角点(端点)细化
junction_refine_cfg JunctionRefineCfg() 端点细化参数(num_perturbs=9 个扰动候选、perturb_interval=0.25 像素间隔)

热力图细化支持 global 与 local 两种模式(默认 mode="local",num_blocks=20 分块、overlap_ratio=0.5 重叠、ratio=0.2 取前 20% 高值、valid_thresh=0.001),实现细节见 kornia/feature/sold2/sold2_detector.py。LineSegmentDetectionModule.detect 的整体流程为:热力图细化 → 构建角点候选连通矩阵(上三角)→ 候选抑制 → 沿候选线段采样并做局部最大值搜索 → 平均激活阈值 + 内点比例双重判定 → 端点扰动细化(类似 LSD 的做法)。

线段匹配 LineMatcherCfg

匹配由 WunschLineMatcher 实现(kornia/feature/sold2/sold2.py),其配置默认值为:

字段 默认值 说明
cross_check True 是否启用双向最近邻(互检)过滤,过滤后非互匹配置为 -1
num_samples 5 每条线段上采样 5 个点用于描述子比对
min_dist_pts 8 采样点之间的最小像素距离,短线段据此自动减少采样数(下限 2)
top_k_candidates 10 预筛选阶段每根线段保留的候选线段数
grid_size 4 描述子图相对原图的空间缩放(与检测器的 grid_size=8 不同)
line_score False 是否计算线段显著性得分(默认关闭)

匹配原理:采样、双线性提取与 Needleman-Wunsch

SOLD2.match 并不直接比较整根线段,而是把线段"变成"若干点的描述子再做序列级对齐。源码中的实现链条(kornia/feature/sold2/sold2.py)如下:

  1. 沿线采样:sample_line_points 以 min_dist_pts 为最小间距,在每条线段上均匀取 num_samples 个点,短线段自动截断并用掩码标记无效点(kornia/feature/sold2/sold2.py);
  2. 描述子提取:keypoints_to_grid 把 (y, x) 像素坐标按 xy * 2 / img_size - 1 归一化为 <a href="https://link.gitcode.com/i/8d546990d0bb80106257bbfefa03592e" target="_blank">-1, 1]² 网格,配合 F.grid_sample(..., align_corners=False) 从半稠密描述子图上做双线性采样,再对 128 维描述子做 L2 归一化([kornia/feature/sold2/sold2.py)。这一归一化公式特意与参考实现(cvg/SOLD2)保持一致——注释与测试都指出,换用其他像素归一化约定会使采样在远边缘产生漂移,破坏与预训练权重的兼容性(tests/feature/test_sold2.py);
  3. 相似度矩阵:两图所有采样点描述子做内积得到得分矩阵,无效采样点置为 -1;
  4. 候选预筛:filter_and_match_lines 先按均值得分保留每根线段的前 top_k_candidates 个候选,并同时考虑线段的两种方向(正反翻转拼接),再用批量实现的 Needleman-Wunsch 动态规划算法计算每条候选对的序列对齐得分(gap 罚分 0.1),取最高分对应的候选为匹配(kornia/feature/sold2/sold2.py);
  5. 互检过滤:若 cross_check=True,反向再做一次匹配,只有双向一致的配对才保留,否则置为 -1。

边界情况在源码中也有处理:第一张图无线段时返回空张量,第二张图无线段时返回全 -1(kornia/feature/sold2/sold2.py)。

网络结构:检测、描述如何在一个网络中共存

SOLD2Net(kornia/feature/sold2/backbones.py)把三条子任务分支挂在一个共享骨干上:

  • 骨干:HourglassBackbone,来自 LCNN 的沙漏网络结构(堆叠 2 个、深度 4),输入单通道灰度图,输出 (B, 256, H/4, W/4) 特征(kornia/feature/sold2/backbones.py);
  • 角点解码器:SuperpointDecoder,SuperPoint 式结构——256 通道特征经 3×3 步长 2 卷积降到 65 通道,softmax 后取前 64 个非空通道做 pixel_shuffle 上采样 grid_size 倍,得到原分辨率的角点概率热力图(kornia/feature/sold2/backbones.py);
  • 线段热力图解码器:PixelShuffleDecoder,两轮 3×3 卷积 + nn.PixelShuffle(2) 逐步上采样,输出 2 通道后 softmax 取第二通道作为线段概率图(kornia/feature/sold2/backbones.py);
  • 描述子解码器:SuperpointDescriptor,256→256→128 通道卷积,输出 (B, 128, H/4, W/4) 的半稠密描述子图,不额外上采样(kornia/feature/sold2/backbones.py)。

三个头共享同一个沙漏骨干特征,因此"检测 + 描述"是真正意义上的单网络联合学习,这正是 SOLD² 相比"检测器 + 描述器级联"方案的关键差异。

预训练权重与运行注意事项

  • pretrained=True(默认)会从远端下载 Wireframe 预训练权重(SOLD2 使用 Hugging Face 镜像 + CVUT 备用源,见 kornia/feature/sold2/sold2.py;SOLD2_detector 使用 ETH CVG 数据源,见 kornia/feature/sold2/sold2_detector.py),加载后自动置为 eval() 模式;若网络受限,可传 pretrained=False 自行加载权重。
  • 模型默认参数针对 400~800 像素的图像调优;输入过大或过小建议先做缩放。
  • 测试用例中以 pretrained=False 构建模型做形状断言与 JIT 脚本化验证,其中 gradcheck 与 JIT 测试因沙漏结构的递归定义和耗时问题被标记为跳过(tests/feature/test_sold2.py),这是仓库内已知的边界情况。
  • load_image 返回的即是 <a href="https://link.gitcode.com/i/c0f7c8a35b46f3377beff9c86ff47a1b" target="_blank">0, 1] 浮点张量([kornia/io/io.py),可直接接入 rgb_to_grayscale 与 SOLD2,无需额外归一化。

小结

SOLD² 在 Kornia 中是一个开箱即用的线段级特征管线:SOLD2(pretrained=True) 一行即可对灰度图批次完成线段检测与描述,match 方法借助沿线采样描述子与 Needleman-Wunsch 序列对齐实现跨视角匹配;SOLD2_detector 则专注检测。所有关键阈值(角点检测、线段判定、内点比例、匹配互检与候选数)都集中在 DetectorCfg / LineDetectorCfg / LineMatcherCfg 三个数据类中,默认参数面向 400~800 像素图像调优,实际使用时应结合自身图像尺寸与场景调整。进一步的源码细节可继续阅读 kornia/feature/sold2/ 目录及对应的 tests/feature/test_sold2.py,其模型页入口见 docs/source/models/index.rst。

登录后查看全文
kornia