模板匹配定位
找目标角度位置最稳定
VM / VPP 对照
| VM / VPP 操作 | Halcon 算子链 | 核心区别 |
|---|---|---|
| 拖模板匹配工具 → 画 ROI → 点击学习 → 调匹配分数 → 完成 | create_shape_model → find_shape_model → vector_angle_to_rigid |
halcon训练（create）和查找（find）分开写，找到后还要自己做坐标变换vm |
css
* ========== 训练阶段（只跑一次，离线完成）==========
* 步骤1: 读取模板图像
read_image (TemplateImage, 'template.png')
* 步骤2: 转灰度
rgb1_to_gray (TemplateImage, GrayTemplate)
* 步骤3: 创建ROI矩形
gen_rectangle1 (ROI, 100, 100, 200, 200)
* 步骤4: 裁剪ROI区域
reduce_domain (GrayTemplate, ROI, TemplateReduced)
* 步骤5: 创建形状模板
create_shape_model (TemplateReduced, 'auto', rad(-180), rad(360), 'auto', 'auto', 'use_polarity', 'auto', 'auto', ModelID)
* ========== 运行阶段（每次来新图都跑，在线检测）==========
* 步骤6: 读取待检测图像
read_image (SearchImage, 'search_image.png')
* 步骤7: 转灰度
rgb1_to_gray (SearchImage, GraySearch)
* 步骤8: 形状模板匹配
find_shape_model (GraySearch, ModelID, rad(-180), rad(360), 0.5, 1, 0.5, 'least_squares', 0, 0.9, Row, Column, Angle, Score)
* 步骤9: 匹配结果判定
if (|Score| > 0)
* 步骤10: 计算刚性变换矩阵
vector_angle_to_rigid (0, 0, 0, Row, Column, Angle, HomMat2D)
* 步骤11: 图像仿射变换
affine_trans_image (GraySearch, ImageAligned, HomMat2D)
endif🔬 算子参数详解与原理
核心思路： 模板匹配分为离线训练和在线检测两个阶段。训练阶段将标准模板的边缘轮廓提取并多层金字塔化，生成可复用的模型句柄(ModelID)；运行阶段则在待检测图像的多层金字塔上逐层搜索，通过相似度度量找到最佳匹配位姿(位置+角度)。VM/VPP 将这两阶段封装为模板匹配工具，Halcon 则提供细粒度控制。
| 阶段 | 算子 | VM / VPP 对应操作 | 核心作用 |
|---|---|---|---|
| 训练阶段 (离线) | read_image |
图像源 → 加载模板图像 | 读入标准、无缺陷的模板原图 |
rgb1_to_gray |
图像转换 → 彩色转灰度 | 统一为单通道，消除颜色干扰 | |
gen_rectangle1 |
ROI工具 → 矩形ROI | 在模板上框选需要学习的特征区域 | |
reduce_domain |
ROI裁剪 / 掩膜 | 将ROI外的像素屏蔽，只保留特征区域 | |
create_shape_model |
模板匹配 → 训练模板 | 基于边缘轮廓创建形状模型，输出ModelID | |
| 运行阶段 (在线) | read_image |
图像源 → 加载检测图像 | 读入待检测的实时图像 |
rgb1_to_gray |
图像转换 → 彩色转灰度 | 与训练阶段保持一致的预处理 | |
find_shape_model |
模板匹配 → 搜索/匹配 | 在检测图中搜索模板，返回位姿和分数 | |
vector_angle_to_rigid |
位置修正 / 仿射变换 | 根据匹配结果计算刚性变换矩阵 | |
affine_trans_image |
图像对齐 / 仿射变换 | 将检测图变换到模板坐标系，实现ROI跟随 |
训练阶段 ① gen_rectangle1 --- 创建矩形ROI
scss
gen_rectangle1 (ROI, 100, 100, 200, 200)参数说明：
ROI(输出): 生成的矩形区域变量。100(Row1): 矩形左上角行坐标（Y1）。100(Column1): 矩形左上角列坐标（X1）。200(Row2): 矩形右下角行坐标（Y2）。200(Column2): 矩形右下角列坐标（X2）。
工作原理： 在图像坐标系中生成一个与坐标轴对齐的矩形区域。坐标系原点在图像左上角，Row向下递增，Column向右递增。
工程建议： ROI应尽可能紧凑，只包含目标的稳定特征（如边缘轮廓丰富的区域），避免包含背景、反光或易变区域，否则会导致匹配不稳定或误检。
训练阶段 ② reduce_domain --- 裁剪ROI区域
scss
reduce_domain (GrayTemplate, ROI, TemplateReduced)参数说明：
GrayTemplate(输入): 输入的灰度图像。ROI(输入): 需要保留的区域（由gen_rectangle1生成）。TemplateReduced(输出): 裁剪后的图像。ROI外的像素被设为"未定义"，不参与后续计算。
工作原理： Halcon中图像(Image)与区域(Region)是分离的数据结构。reduce_domain 将 Region 作为Domain（定义域）附加到 Image 上，告诉后续算子"只处理这个范围内的像素"。这相当于数学中的"限制定义域"操作。注意：它不会真正删除像素，只是标记为无效，因此内存占用不变，但计算时会跳过这些像素。
训练阶段 ③ create_shape_model --- 创建形状模板（核心）
less
create_shape_model (TemplateReduced, 'auto', rad(-180), rad(360), 'auto', 'auto', 'use_polarity', 'auto', 'auto', ModelID)参数说明（共10个参数，非常重要）：
-
TemplateReduced(输入): 裁剪后的模板图像。必须是灰度图，且包含清晰的边缘轮廓。 -
'auto'(NumLevels): 金字塔层数。'auto'表示 Halcon 自动根据图像尺寸选择最优层数（通常3 ~ 5层）。金字塔层数越多，搜索越快，但对细小特征的敏感度降低。可手动设为 3 ~ 7 的整数。 -
rad(-180)(AngleStart): 角度搜索起始值，单位为弧度。rad(-180) = -π，表示逆时针180度。 -
rad(360)(AngleExtent): 角度搜索范围。从 -180° 到 +180°，共覆盖360°，即全角度搜索。若目标无旋转，可设为0，大幅提升速度。 -
'auto'(AngleStep): 角度步长。'auto'自动计算，平衡精度与速度。步长越小，角度精度越高，但模型越大、搜索越慢。通常自动值在 0.5°~2° 之间。 -
'auto'(Optimization): 优化方法。'auto'自动选择；可选'none'（不优化，精度最高）、'point_reduction_high'（减少边缘点，提速）等。 -
'use_polarity'(Metric): 匹配度量方式。
'use_polarity': 极性匹配。模板边缘的明暗方向必须与检测图一致（如黑到白 vs 白到黑）。精度最高，适用于光照稳定场景。'ignore_global_polarity': 忽略全局极性。允许整体明暗反转（如模板白底黑字，检测图黑底白字）。'ignore_local_polarity': 忽略局部极性。适用于表面反光不均匀或材质变化场景，但误检率略高。
-
'auto'(Contrast): 对比度阈值。'auto'自动根据模板边缘强度确定。可手动设为整数（如30），表示边缘点梯度幅度必须 ≥30 才被纳入模型。 -
'auto'(MinContrast): 最小对比度。'auto'自动确定。用于抑制低对比度噪声边缘。 -
ModelID(输出): 模型句柄。本质是一个内存指针/ID，后续 find_shape_model 通过它调用模型数据。程序结束前必须用clear_shape_model(ModelID)释放内存，否则造成内存泄漏。
工作原理： create_shape_model 执行以下步骤：
① 边缘提取： 对模板图像进行边缘检测（如Sobel、Canny），提取亚像素级边缘轮廓点。
② 金字塔分层： 将边缘图像逐层降采样（如1/2、1/4、1/8...），构建多层金字塔。顶层用于快速粗定位，底层用于精修位姿。
③ 方向量化： 将每个边缘点的主梯度方向离散化为若干角度级别，存储为方向直方图特征。
④ 模型编码： 将所有边缘点的坐标、方向信息编码为紧凑的数据结构，绑定到 ModelID。
与VM的区别： VM的训练通常只需框选ROI点按钮，Halcon则需要显式指定角度范围、度量方式、对比度等，适合专业调优。
运行阶段 ① find_shape_model --- 形状模板匹配（核心）
less
find_shape_model (GraySearch, ModelID, rad(-180), rad(360), 0.5, 1, 0.5, 'least_squares', 0, 0.9, Row, Column, Angle, Score)参数说明（共13个参数）：
-
GraySearch(输入): 待检测的灰度图像。 -
ModelID(输入): create_shape_model 生成的模型句柄。 -
rad(-180)(AngleStart): 角度搜索起始值。必须与训练时一致或范围更小。 若训练时是 -180~+180，运行时设为 -90~+90 可提速。 -
rad(360)(AngleExtent): 角度搜索范围。 -
0.5(MinScore): 最小匹配分数阈值，范围 0, 1。0.5 表示至少50%的模型边缘点要在检测图中找到对应点。值越高越严格，漏检风险增加；值越低越宽松，误检风险增加。通常设 0.3 ~ 0.7。 -
1(NumMatches): 最多返回的匹配数量。设为1表示只找最佳匹配；设为0或更大值可返回多个候选（如多目标场景）。 -
0.5(MaxOverlap): 最大重叠比例。当多个匹配结果的空间重叠度（IOU）超过此值时，只保留分数最高的一个。0.5 表示重叠50%以上视为同一目标。设为0允许完全重叠（不推荐），设为1禁止任何重叠。 -
'least_squares'(SubPixel): 亚像素优化算法。
'none': 无亚像素优化，精度约1像素，速度最快。'least_squares': 最小二乘拟合，精度约 0.1 ~ 0.3 像素，推荐常用。'least_squares_high': 高精度最小二乘，精度约 0.01 ~ 0.1 像素，速度较慢。'max_deformation': 允许模型有轻微形变（如柔性物体）。
-
0(NumLevels): 金字塔搜索层数。0 表示使用模型创建时的所有层数；设为1 ~ 5可限制层数，用精度换速度。 -
0.9(Greediness): 贪婪度，范围 0, 1。值越高，搜索时越早放弃低分区域，速度越快，但可能漏检低对比度目标。0.9 是高速推荐值；若目标模糊或低对比，应降至 0.3 ~ 0.5。
11 Row: 匹配中心点的行坐标（浮点数，亚像素级）。
12.Column: 匹配中心点的列坐标（浮点数，亚像素级）。
13.Angle: 匹配到的旋转角度（弧度）。
14.Score: 匹配分数 0, 1，越接近1表示越相似。
工作原理（分层搜索）：
① 顶层粗搜： 在金字塔最顶层（分辨率最低）用模型边缘点的方向特征进行快速匹配，筛选出候选位置。
② 逐层精修： 将候选位置映射到下一层更高分辨率的图像，局部细化位姿，剔除误匹配。
③ 底层精定位： 在原始分辨率层进行亚像素级优化（如最小二乘），输出最终的 Row/Column/Angle。
④ 分数计算： Score = (成功匹配的边缘点数) / (模型总边缘点数)。边缘点匹配需满足：位置接近 + 方向一致 + 极性符合（取决于Metric设置）。
性能调优口诀： 角度范围能小则小，金字塔层数能多则多，贪婪度先高后低，分数阈值看现场。
运行阶段 ② vector_angle_to_rigid --- 计算刚性变换矩阵
sql
vector_angle_to_rigid (0, 0, 0, Row, Column, Angle, HomMat2D)参数说明：
- 前3个参数 (Row1, Column1, Angle1): 模板参考位姿。通常设为 (0, 0, 0)，表示模板在"原点、无旋转"的坐标系中定义。
- 中3个参数 (Row2, Column2, Angle2): 检测到的实际位姿，即 find_shape_model 的输出。
HomMat2D(输出): 2D齐次变换矩阵 (3×3)。包含旋转和平移，形式为：
sql
[ cos(Angle) -sin(Angle) Column ]
[ sin(Angle) cos(Angle) Row ]
[ 0 0 1 ]工作原理： 刚性变换(Rigid Transformation)保持物体的形状和尺寸不变，只允许旋转和平移（不允许缩放和剪切）。该算子通过两组对应点+角度，求解最优的旋转平移矩阵。后续可用此矩阵对图像、区域或XLD轮廓进行对齐变换，实现"ROI跟随"------即使目标旋转平移，检测区域也能自动对准。
运行阶段 ③ affine_trans_image --- 图像仿射对齐
scss
affine_trans_image (GraySearch, ImageAligned, HomMat2D)参数说明：
GraySearch(输入): 待对齐的原始检测图像。ImageAligned(输出): 对齐后的输出图像。该图像中目标的位置和角度与模板图像一致。HomMat2D(输入): vector_angle_to_rigid 计算的变换矩阵。
工作原理： 对输入图像的每个像素坐标 (x, y)，用逆变换矩阵映射到原始图像中的对应位置，通过双线性或双三次插值获取灰度值。对齐后，可以在固定位置（模板坐标系下的固定ROI）进行后续测量（如1D测量、Blob分析），无需每次重新定位ROI，大幅提高检测稳定性和开发效率。
应用场景： PCB焊盘检测、芯片引脚测量、装配定位等。先模板匹配定位整体位姿，再对齐图像，最后用固定ROI做局部检测------这是工业视觉的经典粗定位+精检测流程。