OpenCV 特征匹配 + 单应性矩阵：用 cv.findHomography 在复杂场景中定位已知物体（Python 实战）

本文围绕 OpenCV Python 官方教程 py_feature_homography.markdown 展开，讲解如何把上一章节的 SIFT/FLANN 特征匹配结果与 cv.findHomography() 透视变换估计结合起来，在杂乱背景图中精确框出已知物体的位置。读完本篇，你将掌握从“特征点匹配”走到“目标几何定位”的完整流水线：RANSAC 内点掩码的用法、3x3 单应性矩阵如何变换查询图像四个角点，以及 cv.drawMatches() 的绘图参数细节，并能对照 OpenCV 仓库源码与自带测试用例理解每一步的实现依据。

1. 问题背景：从“找到物体局部”到“框出整个物体”

教程的前置章节已经解决了一个问题：给定一张查询图像（queryImage，物体特写）和一张训练图像（trainImage，包含物体的杂乱场景），用 SIFT 检测关键点、用 FLANN 匹配器做 knn 匹配、再用 Lowe 比率测试筛选优质匹配。也就是说，我们已经在杂乱场景中找到了物体上若干部分的对应位置。

这些信息已经足够把整个物体“框”出来。做法是调用 cv.findHomography()（传统上属于 calib3d 模块，在 OpenCV 5.x 仓库中该函数族的声明已迁移到 geometry 模块头文件，Python 侧仍统一写作 cv.findHomography()）：把两幅图像中匹配点的坐标集合作为输入，求出描述该平面物体透视关系的 3x3 变换矩阵；再用 cv.perspectiveTransform() 把查询图像的四个角点投影到场景图中，即可得到物体的四边形轮廓。

从 API 声明可以看到该函数的完整签名与默认参数：

CV_EXPORTS_W Mat findHomography( InputArray srcPoints, InputArray dstPoints,
                                 int method = 0, double ransacReprojThreshold = 3,
                                 OutputArray mask=noArray(), const int maxIters = 2000,
                                 const double confidence = 0.995);

• method = 0：默认方法，即不带鲁棒估计的线性解法；
• ransacReprojThreshold = 3：RANSAC 重投影误差阈值（像素）；
• maxIters = 2000：RANSAC 最大迭代次数；
• confidence = 0.995：结果置信度。

注意单应性矩阵只确定到任意尺度，若 h_33 非零，实现会将其归一化为 1；当矩阵无法估计时返回空矩阵。

为什么必须有鲁棒估计

特征匹配必然存在误匹配，几个错点对足以毁掉整个透视变换。因此算法采用 RANSAC 或 LEAST_MEDIAN（由 method 标志决定）做鲁棒估计：能支撑正确估计的匹配点称为 inliers（内点），其余为 outliers（外点）。cv.findHomography() 返回一个掩码 mask 指明每个点是内点还是外点。源码层面，fundam.cpp 中的实现 在 method 落在 USAC 区间时直接分派给 usac::findHomography，否则走经典 RANSAC/LMEDS 流程。

估计方法枚举值定义在 3d.hpp：

enum { LMEDS  = 4,        //!< 最小中值平方算法
       RANSAC = 8,        //!< RANSAC 算法
       RHO    = 16,       //!< RHO 算法
       USAC_DEFAULT  = 32, //!< USAC 系列（默认/并行/快速/精确…）
       USAC_PARALLEL = 33,
       USAC_FAST     = 35,
       USAC_ACCURATE = 36,
       USAC_PROSAC   = 37,
       USAC_MAGSAC   = 38 };

教程示例中使用 cv.RANSAC，即枚举值 8。单应性估计的单元测试可参考 test_homography.cpp（例如 L700 附近同时用 RANSAC 与 RHO 方法估计并比较内点掩码，L732 验证点数不足时抛出异常）。

2. 第一步：SIFT 特征 + FLANN 匹配 + 比率测试

首先按惯例在两张图中检测 SIFT 特征，并用比率测试（Lowe's ratio test）挑选优质匹配。示例图像使用仓库自带资源 box.png（查询图）和 box_in_scene.png（场景图）：

import numpy as np
import cv2 as cv
from matplotlib import pyplot as plt

MIN_MATCH_COUNT = 10  # 至少 10 个匹配点才有足够信息估计单应性并定位物体

img1 = cv.imread('box.png', cv.IMREAD_GRAYSCALE)          # queryImage：物体特写
img2 = cv.imread('box_in_scene.png', cv.IMREAD_GRAYSCALE) # trainImage：杂乱场景

# 初始化 SIFT 检测器
sift = cv.SIFT_create()

# 检测关键点与描述子
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)

# FLANN 匹配器：KD 树索引
FLANN_INDEX_KDTREE = 1
index_params = dict(algorithm=FLANN_INDEX_KDTREE, trees=5)   # 建 5 棵 KD 树
search_params = dict(checks=50)                              # 每个查询做 50 次最近邻检查

flann = cv.FlannBasedMatcher(index_params, search_params)
matches = flann.knnMatch(des1, des2, k=2)  # 每个描述子取 2 个最近邻

# 按 Lowe 比率测试存储优质匹配：最近邻距离须小于次近邻的 0.7 倍
good = []
for m, n in matches:
    if m.distance < 0.7 * n.distance:
        good.append(m)

要点说明：

• knnMatch(des1, des2, k=2) 为 queryImage 的每个描述子在 trainImage 中找 2 个最近邻，返回形如 [(m, n), ...] 的匹配列表；
• 比率阈值 0.7 来自 Lowe 的经典实验结论，比率越小匹配越可靠；
• MIN_MATCH_COUNT = 10 是人为设定的“可定位门槛”，下文会用它判断匹配数量是否足够。

3. 第二步：findHomography + perspectiveTransform 定位物体

如果优质匹配数达到阈值，就提取两侧匹配关键点的坐标，交给 cv.findHomography() 求透视变换；拿到 3x3 矩阵后，用它变换查询图像的四个角点，得到物体在场景图中的四边形位置并画出。

if len(good) > MIN_MATCH_COUNT:
    # 分别取出 query/train 两图中匹配关键点坐标，整形为 (N,1,2) float32
    src_pts = np.float32([kp1[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)
    dst_pts = np.float32([kp2[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)

    # RANSAC 鲁棒估计，重投影阈值 5.0 像素；mask 标出内点
    M, mask = cv.findHomography(src_pts, dst_pts, cv.RANSAC, 5.0)
    matchesMask = mask.ravel().tolist()  # 转成 drawMatches 所需的 0/1 列表

    h, w = img1.shape
    # 查询图像的四个角点：左上、左下、右下、右上
    pts = np.float32([[0, 0], [0, h-1], [w-1, h-1], [w-1, 0]]).reshape(-1, 1, 2)
    dst = cv.perspectiveTransform(pts, M)   # 角点经单应性变换到场景图坐标

    # 在场景图上画出白色四边形（LINE_AA 抗锯齿）
    img2 = cv.polylines(img2, [np.int32(dst)], True, 255, 3, cv.LINE_AA)

else:
    print("Not enough matches are found - {}/{}".format(len(good), MIN_MATCH_COUNT))
    matchesMask = None

几个关键细节：

1. 坐标提取：m.queryIdx / m.trainIdx 分别是匹配点在 queryImage 与 trainImage 关键点列表中的下标，kp1[m.queryIdx].pt 得到该点坐标。reshape(-1, 1, 2) 是 findHomography 与 perspectiveTransform 期望的矩阵形状；
2. cv.findHomography(src_pts, dst_pts, cv.RANSAC, 5.0)：第三个参数指定鲁棒方法，第四个是 ransacReprojThreshold（教程取 5.0，比源码默认值 3 更宽松，容忍更大的匹配噪声）。返回的 mask 形状为 (N,1) 的 8U 矩阵，ravel().tolist() 之后正好是 cv.drawMatches() 的 matchesMask 参数格式；
3. 角点变换：h, w = img1.shape 中 h-1、w-1 是因为像素坐标从 0 开始；把查询图像边界四个角点整体透视变换过去，就得到物体在场景图中的四边形；
4. 绘制：cv.polylines(img2, [np.int32(dst)], True, 255, 3, cv.LINE_AA) 中 True 表示闭合多边形，255 是白线，线宽 3。

4. 第三步：用 drawMatches 绘制匹配结果

最后用 cv.drawMatches() 可视化：如果成功定位，只画内点匹配；如果失败（matchesMask = None），则画全部匹配。

draw_params = dict(matchColor=(0, 255, 0),      # 匹配线段画成绿色
                   singlePointColor=None,       # 关键点本身不着色
                   matchesMask=matchesMask,     # 为 None 时画全部，否则只画内点
                   flags=2)

img3 = cv.drawMatches(img1, kp1, img2, kp2, good, None, **draw_params)
plt.imshow(img3, 'gray'), plt.show()

运行后可看到效果：杂乱场景图中被定位的物体以白色四边形标出，左侧面板中绿色线段只连接通过 RANSAC 验证的内点匹配对——这正是 mask 掩码最直观的用途。

5. 参数速查表

参数 / 变量	位置	教程取值	源码默认值	说明
MIN_MATCH_COUNT	示例代码	10	—	少于该数量的匹配即放弃定位，避免点数不足导致估计退化
trees	FLANN 建索引	5	—	KD 树棵数，越多越精确、越慢
checks	FLANN 搜索	50	—	每个查询描述子的近似最近邻检查次数
比率测试阈值	示例代码	0.7	—	m.distance < 0.7*n.distance 才保留匹配
method	cv.findHomography	cv.RANSAC（=8）	0	鲁棒估计方法，可选 LMEDS(4)、RANSAC(8)、RHO(16) 及 USAC 系列(32~38)
ransacReprojThreshold	cv.findHomography	5.0	3	重投影误差阈值（像素），决定内点判定松紧
maxIters / confidence	cv.findHomography	未传	2000 / 0.995	RANSAC 最大迭代次数与置信度
matchColor	drawMatches	(0,255,0)	—	匹配线段颜色（BGR）
matchesMask	drawMatches	RANSAC 掩码	None	只画内点；None 时画全部匹配

6. 仓库测试用例中的工程化写法

OpenCV 自带的 Python 测试 test_feature_homography.py 展示了同一思路在“视频序列目标跟踪”场景下的完整工程实现，值得对照学习：

• 该测试基于 graf1.png 与 box.png 渲染合成带噪声、带运动的目标序列（noise = 0.5, speed = 0.5），要求 100 帧内每帧跟踪四边形的交并比大于 0.6；
• PlaneTracker 类用 cv.ORB_create(nfeatures=1000) 替代 SIFT（免专利费的快速特征），用 FLANN LSH 索引（FLANN_INDEX_LSH = 6）做批量匹配，比率阈值取 0.75；
• 核心跟踪逻辑与教程一致，但更严格地利用了 RANSAC 掩码：

H, status = cv.findHomography(p0, p1, cv.RANSAC, 3.0)
status = status.ravel() != 0
if status.sum() < MIN_MATCH_COUNT:
    continue
p0, p1 = p0[status], p1[status]   # 只用内点参与后续计算

quad = np.float32([[x0, y0], [x1, y0], [x1, y1], [x0, y1]])
quad = cv.perspectiveTransform(quad.reshape(1, -1, 2), H).reshape(-1, 2)

对比可见两处经验：一是阈值回落到源码默认的 3.0；二是内点掩码不仅用于绘图，还用于过滤点集后再做角点变换与后续跟踪——把 mask.ravel() != 0 作为布尔索引筛点，是把教程“定位一个物体”扩展成“多目标持续跟踪”的关键一步。

7. 小结

本教程的核心链路可以概括为：

1. SIFT + FLANN knnMatch + 0.7 比率测试 得到高质量匹配对；
2. 匹配数 ≥ 10 才进入估计环节，否则报“匹配不足”；
3. cv.findHomography(..., cv.RANSAC, 5.0) 输出 3x3 单应性矩阵与内点掩码，掩码既用于 drawMatches 可视化，也可用于点集清洗；
4. cv.perspectiveTransform() 把查询图像四角变换到场景图，cv.polylines() 画出闭合四边形。

这套“特征匹配 + 单应性”的组合是平面目标检测、图像配准和简单 AR 定位的基础工具；若场景中的物体发生非平面形变或需要亚像素精度，可进一步结合 test_homography.cpp 中 RANSAC 与 RHO 两种方法的对比用例，或 geometry 模块 提供的 USAC 系列估计器做鲁棒性调优。