夜雨聆风学习资料网

ARTICLE · 1363686

C#封装HALCON匹配算子:使用模板训练与金字塔搜索实现统一接口调用

C#封装HALCON匹配算子:使用模板训练与金字塔搜索实现统一接口调用

四个项目用了三套匹配代码,封装完终于不用复制粘贴了

之前手上同时维护着几个视觉项目,连接器定位用的find_shape_model,字符识别用的find_ncc_model,还有一套老的用的是find_scaled_shape_model。每套代码的模板创建、参数设置、结果解析都不一样,改一个bug要改三个地方。

有次客户反馈匹配在某个角度区间总是失败,我查了半天,发现是三个项目里角度步长的设置逻辑不一致,其中一个项目的步长设太大了。要是代码是同一套封装,这种问题根本不会出现。

后来花了几天,把HALCON的匹配算子封装成了一个统一的接口。CreateModel、FindModel、ReleaseModel三个方法,内部根据模板类型分发到不同的HALCON算子。项目切换的时候,换一下模板文件就行,代码不用动。

这篇把封装的设计、模板训练流程、金字塔参数调优,以及踩过的坑整理一下。

一、HALCON的匹配算子有几种

HALCON的模板匹配不是单一算子,是一组:

**create_shape_model / find_shape_model**:基于边缘的模板匹配。对光照变化不敏感,适合有清晰轮廓的工件。工业定位用得最多。

**create_ncc_model / find_ncc_model**:基于灰度相关性的匹配。对纹理敏感,适合没有清晰边缘但灰度分布有特征的场景。

**create_scaled_shape_model / find_scaled_shape_model**:带尺度搜索的形状匹配。工件大小有变化时用。

**create_local_deformable_model / find_local_deformable_model**:局部可变形匹配。适合柔性材料或者有局部形变的工件。

几种算子的调用流程一样——建模板、找模板、释放模板。但参数集合、结果结构、坐标系转换都不一样。封装的目的是把这层差异藏起来。

二、封装的接口设计

using System;using System.Collections.Generic;using HalconDotNet;///<summary>/// 模板类型///</summary>publicenum TemplateType{    Shape,          // 基于边缘的形状匹配    Ncc,            // 基于灰度相关性的匹配    ScaledShape,    // 带尺度搜索的形状匹配    LocalDeformable // 局部可变形匹配}///<summary>/// 模板参数///</summary>publicclassTemplateParams{public TemplateType Type { get; set; } = TemplateType.Shape;// 金字塔层数publicint NumLevels { get; set; } = 0;  // 0=自动// 角度搜索范围(弧度)publicdouble AngleStart { get; set; } = -0.39;   // -22.5°publicdouble AngleExtent { get; set; } = 0.79;   // +22.5°// 尺度范围(仅ScaledShape有效)publicdouble ScaleMin { get; set; } = 0.9;publicdouble ScaleMax { get; set; } = 1.1;// 最小匹配分数publicdouble MinScore { get; set; } = 0.7;// 贪婪度(0-1,越大越快,可能漏检)publicdouble Greediness { get; set; } = 0.9;// 最大匹配数量publicint NumMatches { get; set; } = 1;// 重叠度(多个匹配之间的最小重叠)publicdouble MaxOverlap { get; set; } = 0.5;// 搜索的极性publicstring Polarity { get; set; } = "use_polarity";}///<summary>/// 匹配结果///</summary>publicclassMatchResult{publicdouble Row { get; set; }       // 中心行坐标publicdouble Column { get; set; }    // 中心列坐标publicdouble Angle { get; set; }     // 旋转角度(弧度)publicdouble Scale { get; set; }     // 尺度publicdouble Score { get; set; }     // 匹配分数publicdouble AngleDeg => Angle * 180.0 / Math.PI;}///<summary>/// HALCON匹配算子统一封装///</summary>publicclassHalconMatcher : IDisposable{private HTuple _modelId;private TemplateParams _params;private TemplateType _currentType;privatebool _modelCreated;///<summary>/// 从图像创建模板///</summary>publicboolCreateModel(HImage templateImage, TemplateParams parameters)    {try        {            ReleaseModel();            _params = parameters;            _currentType = parameters.Type;switch (parameters.Type)            {case TemplateType.Shape:                    CreateShapeModel(templateImage, parameters);break;case TemplateType.Ncc:                    CreateNccModel(templateImage, parameters);break;case TemplateType.ScaledShape:                    CreateScaledShapeModel(templateImage, parameters);break;case TemplateType.LocalDeformable:                    CreateLocalDeformableModel(templateImage, parameters);break;default:thrownew ArgumentException("未知模板类型");            }            _modelCreated = true;            Console.WriteLine($"模板创建成功: {parameters.Type}, " +$"角度范围 ±{parameters.AngleExtent * 180 / Math.PI:F1}°");returntrue;        }catch (HalconException ex)        {            Console.WriteLine($"模板创建失败: {ex.Message}");returnfalse;        }    }privatevoidCreateShapeModel(HImage template, TemplateParams p)    {// 提取模板区域:用户传入的是裁剪好的模板图,整个区域作为模板        HOperatorSet.GetDomain(template, out HRegion domain);        HOperatorSet.CreateShapeModel(            template,            p.NumLevels,            p.AngleStart,            p.AngleExtent,"auto","auto",            p.Polarity,            p.MinScore < 0.5 ? "auto" : "auto","auto",out _modelId);    }privatevoidCreateNccModel(HImage template, TemplateParams p)    {        HOperatorSet.CreateNccModel(            template,            p.NumLevels,            p.AngleStart,            p.AngleExtent,"auto",            p.Polarity,out _modelId);    }privatevoidCreateScaledShapeModel(HImage template, TemplateParams p)    {        HOperatorSet.CreateScaledShapeModel(            template,            p.NumLevels,            p.AngleStart,            p.AngleExtent,"auto",            p.ScaleMin,            p.ScaleMax,"auto","auto",            p.Polarity,"auto","auto",out _modelId);    }privatevoidCreateLocalDeformableModel(HImage template, TemplateParams p)    {        HOperatorSet.CreateLocalDeformableModel(            template,            p.NumLevels,            p.AngleStart,            p.AngleExtent,"auto",            p.ScaleMin,            p.ScaleMax,"auto","auto",            p.Polarity,"auto","auto",out _modelId);    }///<summary>/// 在图像中查找模板///</summary>public List<MatchResult> FindModel(HImage searchImage)    {if (!_modelCreated)thrownew InvalidOperationException("模板未创建");var results = new List<MatchResult>();try        {            HTuple row, col, angle, scale, score;switch (_currentType)            {case TemplateType.Shape:                    HOperatorSet.FindShapeModel(                        searchImage, _modelId,                        _params.AngleStart, _params.AngleExtent,                        _params.MinScore, _params.NumMatches,                        _params.MaxOverlap,"least_squares", 0, _params.Greediness,out row, out col, out angle, out score);break;case TemplateType.Ncc:                    HOperatorSet.FindNccModel(                        searchImage, _modelId,                        _params.AngleStart, _params.AngleExtent,                        _params.MinScore, _params.NumMatches,                        _params.MaxOverlap,"true", 0,out row, out col, out angle, out score);break;case TemplateType.ScaledShape:                    HOperatorSet.FindScaledShapeModel(                        searchImage, _modelId,                        _params.AngleStart, _params.AngleExtent,                        _params.ScaleMin, _params.ScaleMax,                        _params.MinScore, _params.NumMatches,                        _params.MaxOverlap,"least_squares", 0, _params.Greediness,out row, out col, out angle, out scale, out score);break;case TemplateType.LocalDeformable:                    HTuple vec;                    HOperatorSet.FindLocalDeformableModel(                        searchImage, out vec, _modelId,                        _params.AngleStart, _params.AngleExtent,                        _params.ScaleMin, _params.ScaleMax,                        _params.MinScore, _params.NumMatches,                        _params.MaxOverlap,"least_squares", 0, _params.Greediness,out row, out col, out angle, out scale, out score);break;default:thrownew InvalidOperationException("未知模板类型");            }int count = row?.Length ?? 0;for (int i = 0; i < count; i++)            {                results.Add(new MatchResult                {                    Row = row[i].D,                    Column = col[i].D,                    Angle = angle[i].D,                    Scale = _currentType == TemplateType.Shape ||                             _currentType == TemplateType.Ncc                             ? 1.0 : (scale?.Length > i ? scale[i].D : 1.0),                    Score = score[i].D                });            }        }catch (HalconException ex)        {            Console.WriteLine($"匹配失败: {ex.Message}");        }return results;    }///<summary>/// 从文件加载模板///</summary>publicboolLoadModel(string path)    {try        {            ReleaseModel();string ext = System.IO.Path.GetExtension(path).ToLower();switch (ext)            {case".shm":                    HOperatorSet.ReadShapeModel(path, out _modelId);                    _currentType = TemplateType.Shape;break;case".ncm":                    HOperatorSet.ReadNccModel(path, out _modelId);                    _currentType = TemplateType.Ncc;break;case".sm":                    HOperatorSet.ReadScaledShapeModel(path, out _modelId);                    _currentType = TemplateType.ScaledShape;break;case".dm":                    HOperatorSet.ReadLocalDeformableModel(path, out _modelId);                    _currentType = TemplateType.LocalDeformable;break;default:                    Console.WriteLine($"不支持的模板格式: {ext}");returnfalse;            }            _modelCreated = true;            Console.WriteLine($"模板加载成功: {path}");returntrue;        }catch (HalconException ex)        {            Console.WriteLine($"模板加载失败: {ex.Message}");returnfalse;        }    }///<summary>/// 保存模板///</summary>publicvoidSaveModel(string path)    {if (!_modelCreated) thrownew InvalidOperationException("模板未创建");switch (_currentType)        {case TemplateType.Shape:                HOperatorSet.WriteShapeModel(_modelId, path);break;case TemplateType.Ncc:                HOperatorSet.WriteNccModel(_modelId, path);break;case TemplateType.ScaledShape:                HOperatorSet.WriteScaledShapeModel(_modelId, path);break;case TemplateType.LocalDeformable:                HOperatorSet.WriteLocalDeformableModel(_modelId, path);break;        }        Console.WriteLine($"模板已保存: {path}");    }///<summary>/// 释放模板///</summary>publicvoidReleaseModel()    {if (_modelCreated && _modelId != null)        {switch (_currentType)            {case TemplateType.Shape:                    HOperatorSet.ClearShapeModel(_modelId);break;case TemplateType.Ncc:                    HOperatorSet.ClearNccModel(_modelId);break;case TemplateType.ScaledShape:                    HOperatorSet.ClearScaledShapeModel(_modelId);break;case TemplateType.LocalDeformable:                    HOperatorSet.ClearLocalDeformableModel(_modelId);break;            }            _modelId = null;            _modelCreated = false;        }    }publicvoidDispose()    {        ReleaseModel();    }}

三、模板训练的几个关键参数

模板创建之后,有几个参数直接决定匹配的效果和速度。

金字塔层数(NumLevels)。0表示自动,HALCON会根据模板大小自动选。自动的选择通常合适,但有时需要手动干预:

模板大、目标大,层数多一些(4-6层),搜索速度快;模板小、目标小,层数少一些(2-3层),避免高层信息丢失太多。

有个经验规则:最高层的模板尺寸不小于16×16像素。模板128×128,最多4层金字塔(最高层8×8,太小了,所以3层合适)。

角度步长。create_shape_model的角度步长参数设"auto",HALCON根据角度范围和金字塔层数自动算。手动设的话,角度步长 = 角度范围 / 金字塔层数的一个经验比例。设太大,角度稍偏就匹配不上;设太小,模板创建慢、匹配也慢。

贪婪度(Greediness)。0-1之间,越大越快,但可能漏检。0.9是默认值,大多数场景够用。对漏检零容忍的场景(比如安全件检测),降到0.7-0.8。

最小分数(MinScore)。0-1之间,低于这个分数的匹配结果被过滤。0.7是起点。实际项目中根据误检率和漏检率调整——误检多就提高,漏检多就降低。

四、使用示例

classProgram{staticvoidMain()    {// 1. 从模板图创建模板        HImage templateImage = new HImage("template.png");usingvar matcher = new HalconMatcher();var param = new TemplateParams        {            Type = TemplateType.Shape,            NumLevels = 0,            AngleStart = -0.39,      // -22.5°            AngleExtent = 0.79,      // 45°搜索范围            MinScore = 0.7,            Greediness = 0.9,            NumMatches = 3        };if (!matcher.CreateModel(templateImage, param))return;// 2. 保存模板,后续直接加载        matcher.SaveModel("connector.shm");// 3. 在搜索图中查找        HImage searchImage = new HImage("frame.png");var results = matcher.FindModel(searchImage);foreach (var r in results)        {            Console.WriteLine($"位置: ({r.Row:F2}, {r.Column:F2}), " +$"角度: {r.AngleDeg:F2}°, 分数: {r.Score:F3}");        }    }}

五、实测数据

连接器定位,模板96×96,搜索图2448×2048,Intel i7-11800H:

参数配置
匹配耗时
匹配成功率
金字塔自动(4层),贪婪度0.9
8ms
96%
金字塔2层,贪婪度0.9
22ms
97%
金字塔6层,贪婪度0.9
6ms
91%
金字塔自动,贪婪度0.7
12ms
99%

金字塔层数越多越快,但层数太多最高层信息丢失,成功率下降。自动层数(4层)在速度和成功率之间平衡得最好。贪婪度从0.9降到0.7,速度慢了一半,但成功率从96%提到了99%——对漏检敏感的场景值得。

六、几个容易踩的坑

坑一:模板区域没约束好

create_shape_model的输入图像,整个图像区域都会被当成模板。如果模板图里有背景、有其他物体,模板会包含这些无关信息,匹配时被干扰。创建模板前先把目标区域抠出来,用reduce_domain或者直接传裁剪好的图。

坑二:角度范围设太大

角度范围±180°,模板创建要遍历所有角度,创建慢、匹配也慢。工件实际摆放角度就±15°,范围设±20°就够。角度范围越小,模板创建越快,匹配也越准。

坑三:金字塔层数太多

模板64×64,金字塔设了5层,最高层2×2,信息全丢了,匹配成功率暴跌。最高层至少保证16×16,层数 = log2(min(模板宽, 模板高) / 16)。

坑四:MinScore设太高

0.9的MinScore,稍微有点遮挡或者光照变化就匹配不上。0.7是起点,看误检情况再调。

坑五:忘了释放模板

ClearShapeModel不调,模板占的内存一直不释放。长时间运行的程序,反复创建模板不释放,内存持续增长。封装里用IDisposable保证释放。

坑六:模板文件的路径和坐标系

从文件加载模板,模板的参考坐标系是创建时定的。换了一台相机、换了一个工作距离,同一个模板文件可能匹配不准。模板文件要跟标定参数一起管理,换了光学条件重新创建。

坑七:NCC模板对光照敏感

create_ncc_model基于灰度,光源亮度变化直接影响匹配分数。用NCC的时候,光源要稳定,或者做归一化处理。形状匹配对光照变化鲁棒得多,能用形状匹配就别用NCC。

七、什么时候用哪种模板

场景
推荐模板类型
工件有清晰轮廓
Shape
轮廓模糊、靠灰度纹理区分
Ncc
工件大小有变化
ScaledShape
柔性材料、局部形变
LocalDeformable
光照变化大
Shape(比NCC鲁棒)
高速定位、精度要求高
Shape + 合适金字塔层数

八、总结

HALCON匹配算子封装的核心就这三件事:

  1. 统一接口——CreateModel、FindModel、LoadModel、SaveModel,内部按模板类型分发到不同算子
  2. 模板训练参数——金字塔层数保证最高层≥16×16,角度范围按实际摆放,贪婪度和MinScore按误检/漏检要求调
  3. 资源管理——模板用IDisposable封装,释放时调对应的Clear算子

那套封装用了大半年,四个项目共用一套代码,改bug只改一处。模板文件按项目分别存,换项目换模板文件就行,代码不动。

小提示:第一次建模板,先把金字塔层数设自动、角度范围按实际摆放角度、MinScore设0.7、贪婪度0.9,跑一批样本图看匹配率和速度。匹配率不够就降MinScore或降贪婪度,速度不够就加金字塔层数或缩小角度范围。模板区域一定要干净,背景和无关物体不要包含进去。模板文件跟标定参数一起版本管理,换了光学条件重新创建。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料