2. HALCON模板匹配核心概念

在HALCON模板匹配工程中，几乎所有定位问题最终都归结为六个核心概念：模板（Template）、ROI（感兴趣区域）、金字塔（Pyramid）、相似度（Similarity）、匹配分数（Score）和位姿参数（Pose）。它们不是彼此独立的术语，而是一条从“准备数据”到“输出定位结果”的完整链路：模板决定匹配什么，ROI决定在哪里找，金字塔决定以什么速度与鲁棒性去找，相似度决定如何度量“像不像”，匹配分数决定“像到什么程度可以接受”，位姿参数则给出最终可用的位置与姿态。理解这条链路，是后续所有参数调优与工程落地的基础。

模板：匹配的“标准答案”

模板是匹配算法在图像中寻找的目标参考。在HALCON中，模板通常由 create_shape_model、create_ncc_model 或 create_scaled_shape_model 等算子从一幅参考图像中生成，生成时并不是简单保存一块像素，而是提取目标的边缘、梯度方向、对比度等特征，形成模型描述。模板的工程意义在于：它定义了“什么算目标”。模板质量直接决定匹配上限——如果模板本身包含大量背景、反光或形变，后续再调参数也难以稳定。

模板的选取应遵循几个原则：目标轮廓清晰、对比度稳定、包含足够的方向性特征（避免旋转对称导致角度歧义）、尽量排除背景干扰。例如定位一个金属齿轮，应让模板覆盖齿形轮廓而非中心孔，因为齿形提供了明确的旋转方向信息。

ROI：把搜索范围收窄到“该找的地方”

ROI（Region of Interest）是搜索区域，它告诉匹配算法“只在图像的这一部分找模板”。ROI的工程价值体现在两方面：一是速度，搜索面积越小，金字塔各层需要计算的候选位置越少；二是抗干扰，把无关区域排除在外，可以显著降低误匹配概率。

ROI的设定通常有两种方式：一是用 gen_rectangle1 等算子手工框选；二是通过上一级定位结果动态生成，例如先粗定位大区域，再在局部小ROI内做精匹配。在流水线检测中，ROI往往随产品位置浮动，因此常与 reduce_domain 配合使用，把搜索限制在合理范围内。

金字塔：多尺度搜索的速度与鲁棒性来源

金字塔是模板匹配的核心加速机制。算法把图像和模板逐层降采样，形成由粗到细的层级结构。搜索时先在最高层（最小分辨率）快速找到候选位置，再逐层向下细化，最终在原图分辨率上得到精确位姿。金字塔层数由 NumLevels 控制，层数越多，速度越快，但过高会导致小目标或弱边缘在高层丢失。

金字塔的工程意义在于它同时影响速度与鲁棒性：高层负责“大致在哪”，低层负责“精确到哪”。如果目标在图像中尺度变化较大，还需要配合 create_scaled_shape_model 设置角度与尺度搜索范围。金字塔层数不是越多越好，通常以最高层仍能保留目标主要轮廓为原则。

相似度：如何度量“像不像”

相似度是匹配算法用来衡量模板与图像局部区域“像不像”的数学度量。HALCON中常用的相似度包括基于边缘方向的形状相似度（shape-based）和基于灰度归一化互相关的NCC相似度。形状相似度对光照变化不敏感，适合边缘清晰的目标；NCC对纹理丰富、灰度变化明显的目标更有效。

相似度的工程意义在于它决定了匹配的“敏感方向”。例如，形状相似度主要看边缘方向是否一致，因此对局部遮挡有一定容忍；而NCC看灰度分布，对光照变化更敏感。选择哪种相似度，本质上是在选择“目标在什么条件下仍然算像”。

匹配分数：从“像”到“可用”的阈值判断

匹配分数是相似度经过归一化后的数值，通常范围在0到1之间，越接近1表示越像。HALCON中通过 find_shape_model 的 MinScore 参数设定接受阈值。分数低于阈值的候选会被丢弃，高于阈值的才作为有效匹配输出。

匹配分数的工程意义在于它是质量门限。阈值设得太低，误匹配增多；设得太高，漏检增多。实际工程中，通常先观察一批合格样本的分数分布，再取一个略低于最低合格分数的值作为 MinScore。例如合格样本分数在0.85～0.95之间，可将阈值设为0.80，留出一定余量。

位姿参数：定位结果的最终表达

位姿参数是匹配输出的最终结果，通常包括Row、Column、Angle、Scale以及对应的Score。Row和Column给出目标在图像中的平移位置，Angle给出旋转角度，Scale给出缩放比例，Score给出该结果的置信度。在HALCON中，这些参数通过 find_shape_model 的 Row、Column、Angle、Scale、Score 输出，并可直接用于后续的测量、抓取或对齐。

位姿参数的工程意义在于它是下游任务的输入。例如机器人抓取需要把Row、Column转换为机械手坐标；测量任务需要根据Angle把测量ROI旋转到与目标一致的方向；对齐任务需要根据Scale判断产品是否在允许的尺寸范围内。因此，位姿参数的精度和稳定性直接决定整个定位系统的可用性。

六个概念的工程关系小结