Halcon 模板匹配忽好忽坏？create_shape_model 七个参数的整定实录（C# 联合编程）

上个月接手一条 3C 装配线的视觉工位：手机中框上的镭雕 Logo 定位，Halcon 形状模板匹配（shape-based matching），C# 联合编程。程序是外包团队交付的，验收时跑得好好的，量产第三天产线叫停——换了一批来料，定位分数从稳定的 0.9 掉到 0.3 上下，偶尔干脆"未找到"；更烦的是偶尔误检到 20mm 外一个形状相似的丝印孔，机械手跟着抓偏，直接撞定位销。

打开外包留下的代码，模板创建就一句CreateShapeModel全默认参数，查找一句FindShapeModel，问就是"当时调过"。没办法，只能把两边的参数逐个过一遍。这篇文章记录整个整定过程：哪个参数管什么、动了之后现象怎么变、最后定在什么值，给同样被"忽好忽坏"折磨的人一份参照。代码都是 C# + HOperatorSet 风格，可以直接抄。

一、先对着现象找嫌疑参数

匹配问题无非三类现象，嫌疑参数完全不同，先定位再动手，别乱试：

我们这条线三种现象全占了——典型的"模板没裁干净 + 参数全默认"。

二、模板创建：先把模板图裁干净

整定时第一个要改的不是任何参数，而是模板图本身。外包直接拿整幅工位图建的模板：背景里带着夹具边缘和流水线护罩，来料批次一换、光照一变，背景特征先崩，分数跟着崩。

正确做法是从首件良品图上圈 ROI，只保留稳定的目标特征再建模板：

// 1. 首件良品图上圈住 Logo 的 ROI（行、列坐标按实际标定）HOperatorSet.GenRectangle1(outHObjectroi,512,640,920,1180);HOperatorSet.ReduceDomain(goodImage,roi,outHObjecttplImg);// 2. 先"体检"再建模板：看金字塔每层的轮廓还剩多少HOperatorSet.InspectShapeModel(tplImg,outHObjectlvlImgs,outHObjectlvlRegions,newHTuple(4),newHTuple(30));// 4 层、对比度 30，结果在 HDevelop 里看图像// 3. 建模板：角度只给实际会出现的 ±15°（弧度！）HOperatorSet.CreateShapeModel(tplImg,newHTuple(4),// NumLevels：inspect 确认第 4 层轮廓仍完整newHTuple(-0.2618),newHTuple(0.5236),// 起点 -15°，跨度 30°newHTuple("auto"),// AngleStep 自动newHTuple("auto"),// Optimization 自动newHTuple("use_polarity"),// Metric：反光/镀膜件换 ignore_global_polaritynewHTuple(30),// Contrast：低于 30 的灰度变化不进模板newHTuple(10),// MinContrast：搜索阶段的最小对比度outHTuplemodelID);

1. NumLevels：别迷信 auto

金字塔层数决定"先粗后细"的粗到什么程度。auto经常给到 8~10 层，而我们的 Logo 宽度只有 60 个像素，顶层图像被缩到只剩几个像素，轮廓早就磨没了——匹配自然不稳。用InspectShapeModel把每层的轮廓图调出来看，从上往下找到"轮廓仍然完整可辨"的最高一层，就用它。我们这里 4 层是上限。

2. 角度范围：AngleStart/Extent 是"起点+跨度"，不是起止角

这个签名坑我亲眼见过两次。AngleStart=-0.26, AngleExtent=0.52的含义是-15° 起转 30°（即 -15°~+15°），不是 -15°~+30°。当初想当然按"起止角"理解，范围悄悄多出了 15°，正好把旁边那个丝印孔的旋转姿态包了进来，误检就是它贡献的。

另外，范围能小就小。全角度（0~6.28）意味着模板要为每个姿态都建索引，库大、搜索慢，还放大误检概率。我们有机械定位，工件只可能 ±15° 漂移，30° 跨度足够。

3. Contrast / MinContrast：一个管建模板，一个管搜索

• Contrast：建模板时的轮廓筛选阈值。默认 auto 在我们这张图上取到了 18，把镜头脏污和背景纹理全圈进了模板。提到 30 之后模板只剩 Logo 本体。
• MinContrast：查找阶段允许的最小对比度。必须小于产线最低光照条件下目标与背景的实际对比度。我们实测最暗工况对比度约 20，取 10 留余量。这个值给太高，灯稍微暗一点就"未找到"；给太低（比如 5），噪声进搜索、速度还变慢。

4. Metric：反光件考虑 ignore_global_polarity

use_polarity要求目标和模板明暗极性一致。我们的件是阳极氧化铝，偶尔反光让 Logo 局部极性翻转，分数就抖。如果整件反光严重，换ignore_global_polarity，速度会慢一点但稳得多。

三、查找阶段：宽进严出

整定完模板，查找侧的原则就一句话：MinScore 放宽保证找得到，质量判断放到业务层。别指望把 MinScore 调到 0.8 来"提质"——那是在用搜索参数做质检，会把临界良品直接判死。

HOperatorSet.FindShapeModel(searchImage,modelID,newHTuple(-0.35),newHTuple(0.70),// 比建模板略放宽，留机构漂移余量newHTuple(0.55),// MinScore：宽进newHTuple(1),// NumMatches：单目标就给 1newHTuple(0.5),// MaxOverlapnewHTuple("least_squares"),// SubPixel 亚像素插值newHTuple(0),// NumLevels=0：用模板自身层数newHTuple(0.75),// Greediness：0.9 以上会丢低对比目标outHTuplerows,outHTuplecols,outHTupleangles,outHTuplescores);// 严出：分数阈值放业务层判doublescore=(scores.Length==0)?-1:scores[0].D;if(score<0.62)thrownewLocateFailException($"定位失败：score={score:F3}");// 用完释放，别让 modelID 泄漏HOperatorSet.ClearShapeModel(modelID);

四、最终参数表（可直接抄）

整定后连续跑了一周：分数稳定在 0.88~0.94，未复现误检，单次匹配耗时从 42ms 降到 19ms（角度范围收窄 + 层数减少的红利）。

五、踩坑清单

1. 模板带背景建模板：最大元凶。来料/光照一变，先崩的就是背景特征。
2. 把 AngleExtent 当成终止角：范围悄悄多出一段，误检从这来。记住是"起点+跨度"。
3. Greediness 拉满求速度：0.9 以上是"跳跃搜索"，低对比目标直接被跳过，表现为偶发找不到，最难查。
4. MinContrast 高于实际对比度：实验室灯箱下调好的参数，到车间顶光下就找不到。整定必须用产线最暗工况的图。
5. 忘了 ClearShapeModel：换型重建模板的工位，不释放 modelID，内存一天涨几百 M，最后报的不是泄漏是崩溃。
6. 拿整图找多目标时 NumMatches 给太小：我们是单目标所以给 1；多目标场景这个值必须 ≥ 目标数，否则每次只回最像的那个。

六、结论

模板匹配"忽好忽坏"，九成不是算法不行，是模板质量和参数整定问题。整定顺序建议固定成：裁干净 ROI → InspectShapeModel 定层数 → 按机械约束收窄角度 → 用产线极限工况图定 Contrast/MinContrast → 最后才动查找侧的 MinScore/Greediness。宽进严出，把质量判断留在业务层。这套流程走完，参数表贴在工位文档里，下次换型照抄就行。