OpenCV 模板匹配实战：matchTemplate 原理、掩码与 6 种匹配方法详解（C++ / Python / Java 完整示例）

模板匹配（Template Matching）是 OpenCV 图像处理中最经典的定位技术之一：给定一张"模板小图"，在整幅源图像中滑动比对，找出与模板最相似的区域。本文以 官方教程 template_matching.markdown 为核心骨架，完整讲解 matchTemplate() 与 minMaxLoc() 的用法、掩码（Mask）匹配机制、6 种匹配方法的数学定义与适用场景，并结合本仓库的 C++、Python、Java 三份示例逐段拆解实现。读完本文，你将能够独立完成一次"模板匹配定位 + 最优区域标框"的完整实战，并理解背后的源码级原理与工程约束。

适用版本：OpenCV >= 3.0，示例与本文说明均针对当前仓库源码。

一、本教程的目标

通过本教程你将掌握两个核心技能：

• 使用 OpenCV 的 matchTemplate() 函数，在一张输入图像中搜索与某个图像块（patch / 模板）最匹配的区域；
• 使用 minMaxLoc() 函数，在结果矩阵中定位最大值与最小值及其坐标，从而确定最佳匹配位置。

配套的可交互演示程序还实现了：加载源图像与模板、通过滑块（Trackbar）实时切换 6 种匹配方法、对结果做归一化显示、把最高匹配区域用矩形框标出。

二、模板匹配的基本原理

2.1 什么是模板匹配

模板匹配是一种在图像中寻找与模板图像（patch）相似区域的技术。它逐点"扫描"整幅源图像，本质上是一个穷举式滑窗搜索：把模板放在源图像的每一个可能位置上，计算两者之间的相似度（或差异度）。

一个重要的前提是：模板必须是一个矩形区域。如果矩形内并非所有像素都与目标物体相关（例如矩形边缘混入了背景），此时可以借助掩码（Mask） 把真正需要参与匹配的像素隔离出来。

模板匹配涉及两个主要输入：

1. 源图像 I（Source image）：期望在其中找到与模板匹配区域的图像；
2. 模板图像 T（Template image）：用来与源图像各区域做比较的小图。

我们的目标就是找到源图像中匹配度最高的区域。

2.2 匹配过程：滑动、度量、结果矩阵

模板匹配通过"滑动"实现比对，具体流程如下：

• 滑动：把模板从源图像的左上角开始，每次向右（或向下）移动 1 个像素，从左到右、从上到下逐像素扫过整个源图像；
• 在每个位置计算一个度量值：该值表示"这个位置的模板与源图像对应区域有多相似（或不相似）"；
• 把每个位置的度量值写入结果矩阵 R：结果矩阵 R 中的坐标 $(x,y)$ 对应的数值，正是模板左上角位于源图像 $(x,y)$ 处时算出的匹配度量。

滑动过程与"度量值存储到结果矩阵"的示意如下：

以下图的原理总览为例，可以直观理解"源图像 + 模板 → 定位最高匹配区域"的完整流程：

结果矩阵 R 的直观呈现：如果使用 TM_CCORR_NORMED 方法，矩阵中最亮的位置代表匹配度最高。在下图的示意里，红圈标记处几乎肯定是值最大的位置，因此以该点为左上角、宽高与模板相同的矩形区域即为最终匹配结果。

实践要点：在实际代码中，我们并不直接"看"结果矩阵的明暗，而是调用 minMaxLoc() 在 R 中找到全局最大值（或最小值，取决于匹配方法）及其坐标，这一步对所有方法都是通用的。

三、带掩码（Mask）的模板匹配

当模板矩形内部混入无关内容、或者你只关心模板中的某个图案（如字符、Logo、特定纹理）时，掩码可以显著提升匹配质量。

3.1 掩码匹配需要三个输入

• 源图像 I：待搜索图像；
• 模板图像 T：待匹配的 patch；
• 掩码图像 M：一个用于"遮罩模板"的灰度图，指明模板中哪些像素真正参与匹配。

3.2 掩码的硬性约束

结合 imgproc.hpp 中 matchTemplate 的官方注释 与教程文档，掩码必须满足以下规则：

约束项	要求
支持的匹配方法	目前只有 TM_SQDIFF 与 TM_CCORR_NORMED 两种方法接受掩码
尺寸	掩码必须与模板同尺寸（mask.size() == templ.size()）
深度	必须是 CV_8U 或 CV_32F（源码断言还兼容 CV_Bool）
通道数	与模板通道数相同，或只有 1 个通道（此时单通道掩码会被复制应用到所有通道）
CV_8U 掩码语义	按二值处理：0 表示不参与匹配，非 0 表示参与（权重视为 1）
CV_32F 掩码语义	掩码值作为权重，取值范围应在 [0, 1] 内，模板像素会乘上对应掩码像素值

3.3 掩码在源码中如何被处理

从 templmatch.cpp 的 matchTemplateMask() 实现 可以看到掩码分支的细节：

1. 入口即通过 CV_Assert 校验掩码深度（CV_8U / CV_32F）、通道数（等于模板通道数或为 1）与尺寸（必须等于模板尺寸），并要求源图像不小于模板；
2. 为统一计算，CV_8U 的源图像与模板先被 convertTo 转成 CV_32F；
3. CV_8U 掩码会先经 threshold(..., 0, 1.0, THRESH_BINARY) 二值化为 0/1，再转成 CV_32F 权重；
4. 若掩码只有 1 个通道而模板是多通道，则通过 merge 把掩码复制到每个通道。

这些处理对应了教程中"示例输入为 CV_8UC3，因此掩码也按彩色图读取"的说明。

四、OpenCV 支持的 6 种匹配方法

matchTemplate() 通过 method 参数选择比较算法，method 取值为 TemplateMatchModes 枚举。以下按 Trackbar 上的顺序列出全部 6 种方法（$x',y'$ 在模板范围内求和，即 $x'=0\ldots w-1,\ y'=0\ldots h-1$）：

① TM_SQDIFF = 0（平方差）

$$R(x,y)=\sum_{x',y'}\bigl(T(x',y')-I(x+x',y+y')\bigr)^2$$

差值越小越相似，因此值越小表示匹配越好。它是"像素直接相减再平方"的朴素度量，对光照差异较敏感。

② TM_SQDIFF_NORMED = 1（归一化平方差）

$$R(x,y)=\frac{\sum_{x',y'}\bigl(T(x',y')-I(x+x',y+y')\bigr)^2}{\sqrt{\sum_{x',y'}T(x',y')^2\cdot\sum_{x',y'}I(x+x',y+y')^2}}$$

同样值越小匹配越好，但因为引入了模板与图像块的"能量"作归一化，对整体亮度变化有更强的鲁棒性。

③ TM_CCORR = 2（相关）

$$R(x,y)=\sum_{x',y'}T(x',y')\cdot I(x+x',y+y')$$

即简单的互相关（内积）。值越大匹配越好，但它对亮度、能量高度敏感，容易在过亮区域产生"伪高匹配"。

④ TM_CCORR_NORMED = 3（归一化相关）

$$R(x,y)=\frac{\sum_{x',y'}T(x',y')\cdot I(x+x',y+y')}{\sqrt{\sum_{x',y'}T(x',y')^2\cdot\sum_{x',y'}I(x+x',y+y')^2}}$$

值越大匹配越好。在教程示例中，未归一化的 CCORR 给出的最佳匹配是错的，而归一化版本则能正确命中——这正是归一化对亮度差异抑制作用的体现。

⑤ TM_CCOEFF = 4（相关系数）

$$R(x,y)=\sum_{x',y'}T'(x',y')\cdot I'(x+x',y+y')$$

其中 $T'$、$I'$ 是减去自身窗口均值后的零均值化版本：

$$T'(x',y')=T(x',y')-\frac{1}{w\cdot h}\sum_{x'',y''}T(x'',y''),\qquad I'(x+x',y+y')=I(x+x',y+y')-\frac{1}{w\cdot h}\sum_{x'',y''}I(x+x'',y+y'')$$

值越大匹配越好。通过去均值实现了对"亮度偏移"的不变（相当于度量两者波动形态的相关程度）。

⑥ TM_CCOEFF_NORMED = 5（归一化相关系数）

$$R(x,y)=\frac{\sum_{x',y'}T'(x',y')\cdot I'(x+x',y+y')}{\sqrt{\sum_{x',y'}T'(x',y')^2\cdot\sum_{x',y'}I'(x+x',y+y')^2}}$$

值越大匹配越好。它是实践中最常推荐使用的度量：对线性光照变化具有较好不变性，且输出可解释为 $[-1,1]$ 区间内的相似程度。

6 种方法在示例中的取值（Trackbar 0~5）正好一一对应上述编号。判断"最优"的方向可以归纳为：TM_SQDIFF / TM_SQDIFF_NORMED 取最小值，其余 4 种取最大值。

4.1 速查表

编号	方法常量	中文含义	最优匹配	接受掩码
0	TM_SQDIFF	平方差	最小值	✅
1	TM_SQDIFF_NORMED	归一化平方差	最小值	❌
2	TM_CCORR	互相关	最大值	❌
3	TM_CCORR_NORMED	归一化互相关	最大值	✅
4	TM_CCOEFF	相关系数（去均值）	最大值	❌
5	TM_CCOEFF_NORMED	归一化相关系数	最大值	❌

五、核心 API 与工程约束

5.1 matchTemplate

matchTemplate 在 imgproc.hpp 中的声明为：

void matchTemplate(InputArray image, InputArray templ,
                   OutputArray result, int method, InputArray mask = noArray());

结合 API 注释可以提取出如下关键约束与行为：

• image：执行搜索的图像，必须是 8 位或 32 位浮点类型；
• templ：被搜索的模板，尺寸不能大于源图像，且数据类型必须与源图像一致；
• result：比对结果矩阵，必须是单通道 32 位浮点（CV_32FC1）。若源图像尺寸为 $W\times H$、模板尺寸为 $w\times h$，则结果矩阵尺寸为 $(W-w+1)\times(H-h+1)$；
• method：比较方法，即上文 6 种 TemplateMatchModes；
• mask：可选掩码，规则见第三节；
• 多通道行为：当输入为彩色图时，分子与分母中的各求和会跨所有通道累计，且每个通道使用各自的均值；彩色模板+彩色源图像也可以匹配，结果仍是便于分析的单通道图。

5.2 minMaxLoc

minMaxLoc() 用于在一个数组中找出最小/最大值及其位置，声明于 core 模块：返回全局最小值 minVal、最大值 maxVal，以及各自坐标 minLoc、maxLoc（可额外传入掩码只统计指定区域）。在模板匹配流水线里，它是"从结果矩阵 R 中定位最佳匹配"的收尾工具。

5.3 一个重要前提：多峰与唯一性

minMaxLoc() 只报告全局唯一的最值。教程在结果部分特别指出：CCORR 与 CCOEFF（未归一化）在该示例中给出了错误的"最佳匹配"，而归一化版本却正确——原因在于我们只考虑了"全局最高匹配"这一个峰，忽略了其余可能的高匹配区。这意味着：模板匹配定位单个实例是可靠的；若场景中存在多个同类目标、旋转/缩放或强光照变化，需要配合阈值筛选局部峰值或改用特征点匹配等方案。

六、完整示例代码与运行

示例程序会：加载源图像、模板（以及可选的掩码）→ 用所选匹配方法执行 matchTemplate() → 对结果归一化 → 用 minMaxLoc() 定位最优匹配 → 在原图与结果矩阵上画出矩形框。

6.1 C++ 示例

完整源码：samples/cpp/tutorial_code/Histograms_Matching/MatchTemplate_Demo.cpp

/**
 * @file MatchTemplate_Demo.cpp
 * @brief Sample code to use the function MatchTemplate
 * @author OpenCV team
 */

#include "opencv2/imgcodecs.hpp"
#include "opencv2/highgui.hpp"
#include "opencv2/imgproc.hpp"
#include <iostream>

using namespace std;
using namespace cv;

/// Global Variables
bool use_mask;
Mat img; Mat templ; Mat mask; Mat result;
const char* image_window = "Source Image";
const char* result_window = "Result window";

int match_method;
int max_Trackbar = 5;

/// Function Headers
void MatchingMethod( int, void* );

const char* keys =
"{ help  h| | Print help message. }"
"{ @input1 | Template_Matching_Original_Image.jpg | image_name }"
"{ @input2 | Template_Matching_Template_Image.jpg | template_name }"
"{ @input3 |  | mask_name }";

int main( int argc, char** argv )
{
  CommandLineParser parser( argc, argv, keys );
  samples::addSamplesDataSearchSubDirectory( "doc/tutorials/imgproc/histograms/template_matching/images" );

  /// Load image and template
  img = imread( samples::findFile( parser.get<String>("@input1") ) );
  templ = imread( samples::findFile( parser.get<String>("@input2") ), IMREAD_COLOR );

  if(argc > 3) {
    use_mask = true;
    mask = imread(samples::findFile( parser.get<String>("@input3") ), IMREAD_COLOR );
  }

  if(img.empty() || templ.empty() || (use_mask && mask.empty()))
  {
    cout << "Can't read one of the images" << endl;
    return EXIT_FAILURE;
  }

  /// Create windows
  namedWindow( image_window, WINDOW_AUTOSIZE );
  namedWindow( result_window, WINDOW_AUTOSIZE );

  /// Create Trackbar
  const char* trackbar_label = "Method: \n 0: SQDIFF \n 1: SQDIFF NORMED \n 2: TM CCORR \n 3: TM CCORR NORMED \n 4: TM COEFF \n 5: TM COEFF NORMED";
  createTrackbar( trackbar_label, image_window, &match_method, max_Trackbar, MatchingMethod );

  MatchingMethod( 0, 0 );

  waitKey(0);
  return EXIT_SUCCESS;
}

void MatchingMethod( int, void* )
{
  /// Source image to display
  Mat img_display;
  img.copyTo( img_display );

  /// Create the result matrix
  int result_cols = img.cols - templ.cols + 1;
  int result_rows = img.rows - templ.rows + 1;

  result.create( result_rows, result_cols, CV_32FC1 );

  /// Do the Matching and Normalize
  bool method_accepts_mask = (TM_SQDIFF == match_method || match_method == TM_CCORR_NORMED);
  if (use_mask && method_accepts_mask)
    { matchTemplate( img, templ, result, match_method, mask); }
  else
    { matchTemplate( img, templ, result, match_method); }

  normalize( result, result, 0, 1, NORM_MINMAX, -1, Mat() );

  /// Localizing the best match with minMaxLoc
  double minVal; double maxVal; Point minLoc; Point maxLoc;
  Point matchLoc;

  minMaxLoc( result, &minVal, &maxVal, &minLoc, &maxLoc, Mat() );

  /// For SQDIFF and SQDIFF_NORMED, the best matches are lower values.
  /// For all the other methods, the higher the better
  if( match_method  == TM_SQDIFF || match_method == TM_SQDIFF_NORMED )
    { matchLoc = minLoc; }
  else
    { matchLoc = maxLoc; }

  /// Show me what you got
  rectangle( img_display, matchLoc, Point( matchLoc.x + templ.cols , matchLoc.y + templ.rows ), Scalar::all(0), 2, 8, 0 );
  rectangle( result, matchLoc, Point( matchLoc.x + templ.cols , matchLoc.y + templ.rows ), Scalar::all(0), 2, 8, 0 );

  imshow( image_window, img_display );
  imshow( result_window, result );

  return;
}

C++ 运行方式（不带参数时，默认使用教程 images 目录下的两张样例图）：

g++ MatchTemplate_Demo.cpp -o MatchTemplate_Demo $(pkg-config --cflags --libs opencv4)
./MatchTemplate_Demo <源图像> <模板图像> [掩码图像]

6.2 Python 示例

完整源码：samples/python/tutorial_code/imgProc/match_template/match_template.py

from __future__ import print_function
import sys
import cv2 as cv

use_mask = False
img = None
templ = None
mask = None
image_window = "Source Image"
result_window = "Result window"

match_method = 0
max_Trackbar = 5

def main(argv):

    if (len(sys.argv) < 3):
        print('Not enough parameters')
        print('Usage:\nmatch_template_demo.py <image_name> <template_name> [<mask_name>]')
        return -1

    global img
    global templ
    img = cv.imread(sys.argv[1], cv.IMREAD_COLOR)
    templ = cv.imread(sys.argv[2], cv.IMREAD_COLOR)

    if (len(sys.argv) > 3):
        global use_mask
        use_mask = True
        global mask
        mask = cv.imread( sys.argv[3], cv.IMREAD_COLOR )

    if ((img is None) or (templ is None) or (use_mask and (mask is None))):
        print('Can\'t read one of the images')
        return -1

    cv.namedWindow( image_window, cv.WINDOW_AUTOSIZE )
    cv.namedWindow( result_window, cv.WINDOW_AUTOSIZE )

    trackbar_label = 'Method: \n 0: SQDIFF \n 1: SQDIFF NORMED \n 2: TM CCORR \n 3: TM CCORR NORMED \n 4: TM COEFF \n 5: TM COEFF NORMED'
    cv.createTrackbar( trackbar_label, image_window, match_method, max_Trackbar, MatchingMethod )

    MatchingMethod(match_method)

    cv.waitKey(0)
    return 0

def MatchingMethod(param):

    global match_method
    match_method = param

    img_display = img.copy()

    method_accepts_mask = (cv.TM_SQDIFF == match_method or match_method == cv.TM_CCORR_NORMED)
    if (use_mask and method_accepts_mask):
        result = cv.matchTemplate(img, templ, match_method, None, mask)
    else:
        result = cv.matchTemplate(img, templ, match_method)

    cv.normalize( result, result, 0, 1, cv.NORM_MINMAX, -1 )

    _minVal, _maxVal, minLoc, maxLoc = cv.minMaxLoc(result, None)

    if (match_method == cv.TM_SQDIFF or match_method == cv.TM_SQDIFF_NORMED):
        matchLoc = minLoc
    else:
        matchLoc = maxLoc

    cv.rectangle(img_display, matchLoc, (matchLoc[0] + templ.shape[1], matchLoc[1] + templ.shape[0]), (0,0,0), 2, 8, 0 )
    cv.rectangle(result, matchLoc, (matchLoc[0] + templ.shape[1], matchLoc[1] + templ.shape[0]), (0,0,0), 2, 8, 0 )
    cv.imshow(image_window, img_display)
    cv.imshow(result_window, result)
    pass

if __name__ == "__main__":
    main(sys.argv[1:])

Python 运行方式（示例图位于 doc/tutorials/imgproc/histograms/template_matching/images/）：

python3 match_template.py Template_Matching_Original_Image.jpg Template_Matching_Template_Image.jpg
# 可选：追加掩码图作为第三个参数

6.3 Java 示例

完整源码：samples/java/tutorial_code/ImgProc/tutorial_template_matching/MatchTemplateDemo.java。Java 版核心逻辑与 C++/Python 完全一致，仅 UI 不同：用 Swing 的 JSlider（取值 0~5）替代 HighGUI 的 Trackbar 来切换匹配方法。核心代码如下：

// 加载源图像与模板；若提供第三个参数则加载掩码
img = Imgcodecs.imread(args[0], Imgcodecs.IMREAD_COLOR);
templ = Imgcodecs.imread(args[1], Imgcodecs.IMREAD_COLOR);
if (args.length > 2) {
    use_mask = true;
    mask = Imgcodecs.imread(args[2], Imgcodecs.IMREAD_COLOR);
}

// 创建结果矩阵: CV_32FC1
int result_cols = img.cols() - templ.cols() + 1;
int result_rows = img.rows() - templ.rows() + 1;
result.create(result_rows, result_cols, CvType.CV_32FC1);

// 仅 TM_SQDIFF / TM_CCORR_NORMED 支持掩码
Boolean method_accepts_mask =
    (Imgproc.TM_SQDIFF == match_method || match_method == Imgproc.TM_CCORR_NORMED);
if (use_mask && method_accepts_mask)
    Imgproc.matchTemplate(img, templ, result, match_method, mask);
else
    Imgproc.matchTemplate(img, templ, result, match_method);

// 归一化 + 定位最佳匹配
Core.normalize(result, result, 0, 1, Core.NORM_MINMAX, -1, new Mat());
Core.MinMaxLocResult mmr = Core.minMaxLoc(result);
if (match_method == Imgproc.TM_SQDIFF || match_method == Imgproc.TM_SQDIFF_NORMED)
    matchLoc = mmr.minLoc;   // SQDIFF 系列取最小值
else
    matchLoc = mmr.maxLoc;   // 其余方法取最大值

// 画框并显示
Imgproc.rectangle(img_display, matchLoc,
    new Point(matchLoc.x + templ.cols(), matchLoc.y + templ.rows()),
    new Scalar(0, 0, 0), 2, 8, 0);
result.convertTo(result, CvType.CV_8UC1, 255.0);

Java 运行方式：程序参数为 <源图像> <模板图像> [掩码图像]，入口类 MatchTemplateDemo 会先 System.loadLibrary(Core.NATIVE_LIBRARY_NAME) 再执行业务。

七、代码逐段解析

7.1 全局变量声明

C++ 版声明了四张关键矩阵/图像——img（源图像）、templ（模板）、mask（可选掩码）、result（结果矩阵），外加当前匹配方法 match_method 与滑块上限 max_Trackbar = 5，以及两个窗口名常量。Python / Java 版与之对应。

7.2 加载源图像、模板与掩码

三个版本都先按 IMREAD_COLOR 读入源图像与模板；只有命令行提供了第三个参数（掩码路径）时才置 use_mask = true 并读入掩码，随后做空指针/空 Mat 检查。C++ 版利用 samples::findFile() 与 addSamplesDataSearchSubDirectory() 实现了"默认样例图也能直接找到"的体验。

7.3 创建方法选择控件

C++/Python 通过 createTrackbar(label, window, &match_method, max_Trackbar, callback) 创建 0~5 的滑块；Java 用 JSlider(VERTICAL, 0, 5, ...) 实现，并给每个刻度配上方法名标签（0 - SQDIFF、5 - TM COEFF NORMED 等）。滑块变化即触发回调 MatchingMethod，实现"实时重算并刷新匹配结果"。

7.4 回调中的核心流程（MatchingMethod）

1. 复制源图用于显示：img.copyTo(img_display)，避免在原始图上直接叠加矩形框；
2. 创建结果矩阵：尺寸为 (源图宽 - 模板宽 + 1) × (源图高 - 模板高 + 1)，类型固定为 CV_32FC1；
3. 执行匹配：判断 method_accepts_mask（仅当 TM_SQDIFF 或 TM_CCORR_NORMED 且确实提供了掩码时）才把掩码作为第 5 个参数传入，否则走无掩码重载；
4. 归一化：normalize(result, result, 0, 1, NORM_MINMAX) 把结果矩阵线性映射到 [0, 1]，方便以灰度图直接观察明暗差异（这一步只影响可视化，不影响取最值后的定位结果）；
5. 定位最优位置：minMaxLoc(result, &minVal, &maxVal, &minLoc, &maxLoc)；
6. 按方法方向取 matchLoc：SQDIFF / SQDIFF_NORMED 用 minLoc，其余方法用 maxLoc；
7. 画框与显示：以 matchLoc 为左上角、matchLoc + 模板宽高 为右下角，在原图副本与结果矩阵上各画一个黑色矩形，并分别显示在两个窗口中。

八、运行结果解读

用教程提供的输入图像测试——源图像是一张包含两位人物的照片：

模板图像是其中一人脸部的裁剪特写：

依次切换 6 种方法会得到相应的结果矩阵灰度图（第一行为 SQDIFF、CCORR、CCOEFF，第二行为各自的归一化版本）。判读规则与第三节的公式方向一致：

• 第一列（SQDIFF / SQDIFF_NORMED）：矩阵中越暗代表匹配越好（值越小越好）；
• 第二、三列（CCORR、CCOEFF 及其归一化版）：越亮代表匹配越好（值越大越好）。

这些结果矩阵原图保存在 images 目录（Template_Matching_Correl_Result_0.jpg 至 Result_5.jpg）中，逐一对照可以直观看到各方法响应峰值的差异。

最终的正确匹配结果如图所示——源图像中右侧人物（戴帽者）的脸部被黑色矩形框标出：

需要特别留意的是：示例中 CCORR 与 CCOEFF（未归一化）给出了错误的最佳匹配，而其归一化版本都定位正确。正如本教程指出的，这大概率源于"只取全局最高峰"的简单策略——未归一化的相关类方法会被图像中亮度过高或能量过大的区域干扰。这一现象再次说明：

1. 实践中优先选用归一化方法（特别是 TM_CCOEFF_NORMED）；
2. 若场景复杂，应考虑对结果矩阵做多峰筛选 + 阈值（例如配合 threshold 或局部极大值检测），而不是只取 minMaxLoc 的全局最值。

九、源码级原理：进入实现内部

matchTemplate 的 C++ 实现位于 modules/imgproc/src/templmatch.cpp，公开入口在 templmatch.cpp 第 989 行。从源码结构可以看到几个关键事实：

• 入口参数校验：函数先断言 method 落在 TM_SQDIFF..TM_CCOEFF_NORMED 范围内，源图像深度必须是 CV_8U 或 CV_32F，且 image 与 templ 类型必须一致、image 维度不超过 2；
• 掩码分支优先：一旦传入非空掩码，整个计算转向专用的 matchTemplateMask()（templmatch.cpp#L735）。该分支内部先把 8U 输入转成 CV_32F，对 8U 掩码做 threshold(0, 1.0) 二值化得到 0/1 权重，再将单通道掩码按模板通道数 merge 复制，最后在浮点域执行带掩码的求和计算；
• 设备/加速派发：无掩码路径上，若结果矩阵是 UMat 且满足条件，会优先走 OpenCL 的 ocl_matchTemplate()（templmatch.cpp#L503）实现 GPU 加速；
• HAL 与公共后处理：CPU 路径会先尝试 cv_hal_matchTemplate（HAL 硬件抽象层），对需要归一化或去均值收尾的方法（如 TM_SQDIFF_NORMED、TM_CCOEFF、TM_CCOEFF_NORMED）还会调用 common_matchTemplate()（templmatch.cpp#L859）补齐后续处理，最终得到符合公式定义的结果矩阵。

测试方面，本仓库为模板匹配提供了专门的单元测试覆盖：test_templmatch.cpp（常规方法与基准结果校验）、test_templmatchmask.cpp（掩码匹配的尺寸/深度/通道约束与数值正确性），以及 ocl/test_match_template.cpp（OpenCL 路径与 CPU 结果的一致性）。如果读者想深入理解匹配算法的数值细节或自行扩展（例如新的 method 类型），以上实现与测试文件是最直接的参考入口。

十、使用限制与工程建议

综合文档与源码，在使用模板匹配时需要牢记以下边界条件：

• 匹配前提：模板与源图像必须同为 8U 或 32F 深度；模板尺寸不能大于源图像；结果矩阵自动为 (W-w+1)×(H-h+1) 的单通道 32F；
• 掩码限制：只有 TM_SQDIFF 与 TM_CCORR_NORMED 两个方法接受掩码，且掩码尺寸须等于模板尺寸、深度为 8U/32F、通道数与模板一致或为 1；
• 方法选择：优先使用 TM_CCOEFF_NORMED（对线性光照稳健、输出可解释）；若只是要求速度快、对光照要求不高，TM_SQDIFF_NORMED 也是稳妥选择；
• 算法本性：模板匹配不具旋转、尺度不变性，也不具备多实例统计决策能力，它是"在已知目标外观大致与模板一致"前提下的高效穷举搜索；对旋转/缩放/复杂遮挡场景，应转向特征点匹配（如 SIFT/ORB + 描述子）或基于深度学习的检测方案；
• 可视化注意：示例中 normalize(..., NORM_MINMAX) 把矩阵拉伸到 [0,1] 仅为便于观察，真正的定位仍以 minMaxLoc 返回的原始坐标为唯一依据。

至此，从理论公式、掩码机制、6 种方法的差异，到三种语言的完整可运行示例，再到 matchTemplate 的源码实现细节，你已经拥有了把"模板匹配"落地到具体项目所需的全部要素。以本仓库的 MatchTemplate_Demo.cpp 为起点替换为自己的源图/模板图，即可快速开始你的第一次匹配定位实战。