使用OpenCV matchTemplate函数触发断言失败错误的技术咨询

这个错误我之前帮不少开发者排查过，本质是cv2.matchTemplate对输入参数有三个严格的校验规则，咱们结合你给出的错误信息一条条拆解解决：

错误核心断言解析 #

首先看你遇到的错误提示：

OpenCV Error: Assertion failed ((depth == 0 || depth == 5) && type == _templ.type() && _img.dims() <= 2) in cv::matchTemplate, file C:\projects\opencv-python\opencv\modules\imgproc\src\templmatch.cpp, line 1102

这条断言包含三个必须满足的条件，任意一个不达标都会触发错误：

1. 图像深度（depth）必须是8位无符号整数或32位浮点数 #

• 解释：depth == 0对应CV_8U（8位0-255的无符号整数），depth ==5对应CV_32F（32位浮点数）。如果你的图像是16位、64位或者其他深度，就会触发这个校验失败。
• 解决方法：
  • 转成8位无符号整数：用cv2.convertScaleAbs(img)自动归一化并转格式
  • 转成32位浮点数：用img.astype(np.float32)直接转换（注意如果是彩色图要确保通道数一致）

2. 主图像与模板的类型（type）必须完全匹配 #

• 解释：这里的type是深度+通道数的组合，比如都是单通道灰度图（CV_8UC1），或者都是3通道彩色图（CV_8UC3）。哪怕一个是灰度一个是彩色，或者一个是8位一个是32位，都会报错。
• 解决方法：统一两者的格式，最常用的是都转成灰度图（模板匹配用灰度效果更稳定）：

  # 把主图像转灰度
  img_gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
  # 把模板转灰度
  template_gray = cv2.cvtColor(template, cv2.COLOR_BGR2GRAY)
  

  如果模板本身就是灰度图，直接用即可，但要确认主图像也是相同的单通道8位格式。

3. 图像维度不能超过2维 #

• 解释：matchTemplate只接受2D（单通道灰度图，shape为(H,W)）或3D（彩色图，shape为(H,W,C)）的数组。如果你的图像带了额外维度（比如批量处理的(B,H,W,C)，或者不小心加了空维度），就会触发这个错误。
• 解决方法：检查图像的shape，用np.squeeze()去掉多余的维度，比如：

  # 去掉所有尺寸为1的维度
  img = np.squeeze(img)
  template = np.squeeze(template)
  

完整可运行示例代码 #

这里给你一个经过参数校验的完整模板匹配代码，能避免大部分常见坑：

import cv2
import numpy as np

# 读取主图像和模板（注意路径要正确）
img = cv2.imread('main_image.jpg')
template = cv2.imread('template_image.jpg')

# 先检查图像是否读取成功
if img is None or template is None:
    print("错误：无法读取图像，请检查文件路径！")
else:
    # 统一转成灰度图
    img_gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    template_gray = cv2.cvtColor(template, cv2.COLOR_BGR2GRAY)

    # 额外校验：模板尺寸不能大于主图像（这个也是常见坑，虽然不在当前错误里，但提前预防）
    h, w = template_gray.shape
    if h > img_gray.shape[0] or w > img_gray.shape[1]:
        print("错误：模板尺寸不能大于主图像！")
    else:
        # 执行模板匹配
        res = cv2.matchTemplate(img_gray, template_gray, cv2.TM_CCOEFF_NORMED)
        print(f"匹配成功！匹配结果的形状为：{res.shape}")

内容的提问来源于stack exchange，提问作者Ensar Eray