C#+HALCON视觉检测系统源码拆解：配置化工位与采集检测链路

简介：这是一套面向机器视觉开发者与学习者的 C# 结合 HALCON 完整检测软件源代码，围绕工件表面质量检测展开，可用于理解工业视觉系统从图像采集到结果判定的实现路径，也适合作为课程设计、项目原型与二次开发的基础参考。压缩包共245个文件、约45.48MB，以80个cs源码为核心，配合35张bmp样本图、29个dll依赖库及pdb调试文件，另有resx/resources界面资源、csproj工程文件、配置与数据文件，工程结构和运行素材相对齐全。已有7066人学习下载，说明该案例在同类视觉项目中具有较高参考热度。源码覆盖图像采集、预处理、特征提取、决策反馈和图形化界面等环节，读者可对照HALCON算子调用、C#工程组织、检测流程串联与缺陷判定逻辑，理解模块职责、复现调试过程并积累定制开发与排错思路，适合希望系统掌握机器视觉软件构建的中高级读者。

1. 产线上的视觉工位

产线换型最怕的不是新工件，是上位机里那堆写死的坐标。前阵子拆了一个 C# + HALCON 做的视觉检测完整系统源代码包，它的路子是把每个工位的检测逻辑切成可配置的步骤，换产品只改一份 JSON，不动代码。这类系统干的活儿很集中：相机取图、模板匹配定位、Blob 找缺陷、亚像素测量尺寸、标定换算成毫米，最后把 OK/NG 和测量值丢给 PLC。适合两类人：一是被要求两周内交出一套检测上位机的自动化工程师，二是想从 OpenCV 转到 HALCON 商业视觉栈的 C# 开发者。它不适合只想跑个 demo 的人——里面有一半代码在处理相机断线重连、结果缓存、日志回溯这些不漂亮的活。

2. 骨架与编译：解开压缩包后先看清分层，再让它跑起来

2.1 解开压缩包先看目录：六个工程各管一摊

很多人拿到这种完整系统的源代码，第一反应是双击 .sln 然后 F5，结果一堆红色波浪线直接劝退。我的习惯是先看目录树，搞清楚哪个工程是入口、哪些是类库、依赖往哪个方向走，再决定先编译谁。这个包的结构大致是这样：

VisionSystem/ ├─ VisionSystem.sln ├─ src/ │ ├─ VisionSystem.UI/ 上位机主界面，WinForms，只管显示和操作 │ ├─ VisionSystem.Core/ 流程引擎、工位调度、结果模型、状态机 │ ├─ VisionSystem.Halcon/ HALCON 算子封装、图像工具、标定工具 │ ├─ VisionSystem.Camera/ 相机抽象接口与各家 SDK 适配器 │ ├─ VisionSystem.Comm/ PLC / 上位机通讯，TCP、Modbus │ └─ VisionSystem.Config/ 配置模型与 JSON 序列化 ├─ models/ .shm 形状模板、.cam 相机参数、.tup 标定矩阵 ├─ config/ station_*.json，一个工位一份 ├─ logs/ 按天滚动的运行日志 └─ tools/ 离线调参小工具，单独编译

这个划分里最关键的一条是：VisionSystem.UI不直接引用halcondotnet.dll。所有跟 HALCON 打交道的代码被关在VisionSystem.Halcon里，UI 只拿得到纯数据的StepResult。好处很实际——换视觉库、升级 HALCON 版本、给某个工位做单元测试，都不用动界面代码。我自己做项目时也会这么切，哪怕一开始只有一个工位，也要先把这堵墙砌起来，否则三个月后界面里全是HOperatorSet.开头的调用，想改都改不动。

models/目录值得单独说。里面的.shm是形状模板，.cam是相机内参，.tup是像素到毫米的变换矩阵，这三个文件必须跟着源代码一起走，缺一个就会出现「代码编译过了但检测全 NG」的玄学。有些包会把这些文件放在bin/Debug下面，那份是运行时产物，不是源头，别搞混。

2.2 三层依赖：UI 不认识 HObject

把依赖方向理清楚之后，就能看懂为什么它要用接口来切步骤。核心抽象长这样：

// Core/IDetectionStep.cs —— 一个检测步骤的最小契约 public interface IDetectionStep { string Name { get; } // 步骤名，写进日志和结果表 string Unit { get; } // 主测量值单位，mm / px / count // ctx 里带当前帧图像、上一级定位结果、标定矩阵 // 返回纯数据，不返回任何 HObject，UI 层才敢直接用 StepResult Execute(ImageContext ctx, StepConfig cfg); } // Core/StepResult.cs —— 不引用视觉库，方便脱离相机做单测 public class StepResult { public string StepName { get; set; } public bool IsOk { get; set; } public double Value { get; set; } // 主值，比如间距 12.48 public double Score { get; set; } // 匹配得分，追溯用 public long ElapsedMs{ get; set; } // 单步耗时，性能瓶颈全靠它 public string Message { get; set; } // NG 原因，直接显示在界面上 }

ImageContext是唯一一个跨层传递的「重」对象，它持有当前帧的HObject、定位得到的OriginRow / OriginCol / OriginAngle，以及标定矩阵。后面所有测量步骤都以这个原点为基准做相对坐标，工件在视野里平移旋转都不影响结果。

StepResult里的ElapsedMs看着不起眼，实际是调优的抓手。一条产线节拍 800ms，五个步骤里只要有一个吃掉 400ms，整条线就得降速。我在自己项目里会把这个值打到日志里按天统计 P95，超过预算的步骤单独拎出来优化，比凭感觉猜准得多。

这套设计的取舍也很明显：接口化意味着每个步骤都得写一个类、注册一次、配一份 JSON，前期啰嗦；但换型时你只需要改配置，不用重新编译发给客户，这个账在产线场景下怎么算都划算。

2.3 第一次编译：先把相机摘掉再跑

环境这块，实际踩下来最省事的组合是 VS2022 + .NET Framework 4.8（老版本 HALCON 的 .NET 程序集对 .NET Core 支持一般，4.8 最稳），然后确认三件事：halcondotnet.dll的位数跟工程平台一致、许可证能被找到、相机 SDK 装没装。

# 1. 找本机的 halcondotnet.dll，确认是 x64 还是 x86 Get-ChildItem "C:\Program Files" -Filter "halcondotnet.dll" -Recurse -ErrorAction SilentlyContinue | Select-Object FullName, Length # 2. 看许可证环境变量有没有配，没配就跑不起来 [Environment]::GetEnvironmentVariable("HALCONLICENSEFILE", "Machine") # 3. 引用加好后编译，先编 Halcon 工程，再编 UI dotnet build src\VisionSystem.Halcon\VisionSystem.Halcon.csproj -c Debug

第一次运行千万别接相机。包里VisionSystem.Camera有一个FolderCamera适配器，把配置里的图像源改成文件夹，就能用本地样本图把整条链路跑通：

{ "station": "ST01", "source": { "type": "Folder", "path": "D:/samples/st01", "loop": true, "intervalMs": 200 }, "steps": [ { "type": "Locate", "name": "定位", "model": "models/chip_01.shm", "minScore": 0.7 }, { "type": "Measure", "name": "引脚间距", "roi": [120, 80, 400, 300], "nominal": 12.5, "tolerance": 0.15 } ] }

type决定实例化哪个步骤类，source.type切到Folder后intervalMs控制出图节奏，模拟相机帧率。这一步跑通的意义在于：把「相机问题」和「算法问题」彻底分开。后面检测结果不对，你就知道不是采集层的锅。

提示：FolderCamera出图速度比真相机快得多，测试时故意把intervalMs调到 50 以下，容易把并发问题提前暴露出来，比在产线上复现省事。

3. 采集层拆解：一帧图像从相机 SDK 回调到 HObject 的完整链路

3.1 ICamera 抽象：回调里只做一件事

相机品牌换一换，SDK 的接口就全变，所以这一层必须抽象掉。包里所有相机适配器都实现同一个接口：

public interface ICamera : IDisposable { string Name { get; } bool Open(); // 打开设备，失败要能拿到错误码 bool Start(); // 开始采集 bool Stop(); event Action<HObject, long> FrameArrived; // HObject + 时间戳 }

关键是FrameArrived这个事件的处理方式。新手最容易犯的错是在回调里直接跑算子：相机 SDK 的回调线程通常是驱动层给的，你在里面跑 200ms 的模板匹配，SDK 的缓冲队列立刻溢出，表现就是「跑着跑着丢帧，然后相机报超时」。

正确的做法是回调里只做转换和入队，检测另起一个线程消费：

private readonly BlockingCollection<Frame> _queue = new BlockingCollection<Frame>(3); // 相机 SDK 的原始回调线程，这里绝对不能跑算子 private void OnSdkFrame(IntPtr data, int width, int height) { // GenImage1 直接把非托管内存"包"成 HObject，不做全图拷贝，快 HOperatorSet.GenImage1(out HObject img, "byte", width, height, data); // 队列只留 3 帧，满了就丢最旧的：宁可丢图，也不能让产线卡住 if (_queue.Count >= 3) _queue.TryTake(out _); _queue.Add(new Frame { Image = img, Timestamp = _sw.ElapsedMilliseconds }); }

GenImage1的四个参数分别是像素类型（"byte"对应 8 位灰度）、宽、高、数据首地址。这里有个隐藏的坑：它不拷贝内存，只是持有了那个指针。如果 SDK 在下一帧复用了同一块缓冲区，你手上这张图就会变成花屏，而且是偶发的、极难复现的那种。稳妥的写法是在入队前补一次HOperatorSet.CopyImage(img, out HObject safe)，多一次拷贝换一个确定性，在 500 万像素以内开销可以接受。

队列长度设 3 也是有讲究的。设 1 会让采集和检测强耦合，检测慢一帧采集就阻塞；设 20 则意味着最坏情况下你处理的是 20 帧之前的图，节拍全乱。3 帧刚好覆盖一次抖动。

3.2 HObject 的生命周期：它不是普通对象

HObject是个句柄，底层指向 HALCON 的 iconic 变量区，这部分内存不在 .NET 托管堆上。也就是说，GC 根本不知道它有多大，只有 finalizer 兜底释放。长时间跑下来，你会看到进程内存一路涨到 2G 然后界面卡死——这就是没手动释放的典型症状。

包里的Frame是这么写的：

public sealed class Frame : IDisposable { public HObject Image { get; set; } public long Timestamp { get; set; } public void Dispose() { Image?.Dispose(); // HObject 实现了 IDisposable，别只置 null Image = null; } }

消费端必须用using包住，保证每一帧处理完立刻归还：

// 检测线程主循环 foreach (var frame in _queue.GetConsumingEnumerable(_cts.Token)) { using (frame) // 出了这个块，图像内存立刻释放 { var results = _engine.Run(frame.Image); _results.Enqueue(results); // 只把纯数据丢给 UI } }

除了Frame，还有一类更容易漏的地方：算子产生的中间对象。Threshold出来的 region、Connection出来的 connected regions、FindShapeModel内部产生的轮廓，全都是 iconic 变量。在一个每帧调用十几次算子的流程里，漏掉两三个就是每秒几十个句柄的泄漏。我的做法是在VisionSystem.Halcon里封一层using友好的工具方法，或者干脆每个Execute方法内部统一用try/finally集中释放。

注意：调试期别用任务管理器看内存，HALCON 的 iconic 区和 .NET 堆是两块，任务管理器只给你一个总和，看不出是谁涨的。用 HALCON 自带的变量窗口或者定时打印get_system('allocated_size')更准。

3.3 UI 刷新：别让 Invoke 把消息泵打满

检测线程拿到结果后要更新界面，最直觉的写法是Invoke。问题是每帧调一次、每次刷新一整张表格，界面线程光顾着重绘，按钮都点不动。包里用的是「生产者-消费者 + 定时拉取」：

// 检测线程：只压队列，绝不碰控件 _results.Enqueue(result); // UI 线程：30ms 定时消费，一次处理完积压的结果 private void timerUi_Tick(object sender, EventArgs e) { while (_results.TryDequeue(out var r)) { dgvResults.Rows.Insert(0, r.StepName, r.Value.ToString("F3"), r.IsOk ? "OK" : "NG", r.ElapsedMs); if (dgvResults.Rows.Count > 200) dgvResults.Rows.RemoveAt(dgvResults.Rows.Count - 1); // 表格不能无限长 } }

定时器周期 30ms 大约对应 33fps 的界面刷新，人眼已经看不出延迟，但消息泵的压力比每帧Invoke低了不止一个数量级。表格限制 200 行同样是血泪经验：有人跑了一整夜，第二天界面卡死，原因就是 DataGridView 里堆了三十万行。

实时预览图走另一条路。HObject没法直接喂给PictureBox，中间要转Bitmap，这一步开销不小（一次全图转换大概几毫秒），所以预览只在「调试模式」下开，正式跑的时候关掉，把这几毫秒省给检测。

4. 检测层拆解：模板匹配、Blob 与标定换算的算子级实现

4.1 流程配置化：一份 JSON 描述一个工位

检测逻辑不写死在代码里，这是整套系统最值钱的部分。一个 step 对应一个类，配置只描述参数：

{ "type": "Locate", "name": "定位", "model": "models/chip_01.shm", "angleRange": 0.78, "minScore": 0.7, "numMatches": 1 }

angleRange单位是弧度，0.78 约等于 ±45 度，覆盖工件任意摆放。minScore是接受线，低于它就判 NG。numMatches设 1 表示只找最佳匹配，多工件场景才往上调。

工厂里换型时，工艺员拿着新产品的模板文件，改这三四个数字就能上线，不需要开发介入。这也是为什么配置文件要放config/而不是编译进程序集——现场根本没条件重新编译。

4.2 模板匹配：读一次，别每帧读

形状模板的读取是磁盘 IO 加模型解析，耗时几十毫秒，绝对不能放在每帧的执行路径里。包里把modelId缓存在步骤实例上，第一次执行时才加载：

public StepResult Locate(ImageContext ctx, LocateConfig cfg) { var sw = Stopwatch.StartNew(); // 模板只读一次，缓存在实例字段里；工位切换时才重新加载 if (_modelId == null) HOperatorSet.ReadShapeModel(cfg.ModelPath, out _modelId); HOperatorSet.FindShapeModel( ctx.Image, _modelId, -cfg.AngleRange, cfg.AngleRange * 2, // 起始角 + 角度范围，都是弧度 cfg.MinScore, // 最低分，低于它不返回 cfg.NumMatches, // 最多匹配个数 0.5, // 最大重叠，多目标时防重复 "least_squares", // 亚像素模式，精度最高也最慢 0, // 金字塔层数，0 = 自动 0.9, // 贪心度，越大越快越可能漏 out HTuple rows, out HTuple cols, out HTuple angles, out HTuple scores); if (scores.Length == 0) return StepResult.Ng(cfg.Name, "模板未匹配"); // 定位结果写回 ctx，后续步骤全部基于这个原点做相对坐标 ctx.OriginRow = rows.D[0]; ctx.OriginCol = cols.D[0]; ctx.OriginAngle = angles.D[0]; return new StepResult { StepName = cfg.Name, IsOk = true, Score = scores.D[0], ElapsedMs = sw.ElapsedMilliseconds }; }

几个参数值得抠一下。"least_squares"是最慢但精度最高的亚像素模式，如果节拍紧张可以降到"interpolation"，实测在 500 万像素图上能快 30% 左右，代价是重复精度从 0.02 像素掉到 0.1 像素。Greediness设 0.9 是速度和召回率的折中，设 1.0 可能漏检，设 0.7 又慢得离谱；如果发现偶发漏匹配，先降到 0.8 试试，比重新做模板有效。

定位拿到之后，后续所有 ROI 都不写绝对坐标，而是写成相对原点的偏移。工件在视野里挪了 20 像素，整套测量跟着挪，不用改配置。

4.3 Blob 与尺寸测量：阈值之后一定要筛形状

外观缺陷判定用 Blob 分析，标准套路是「二值化 → 连通域 → 按面积筛」：

// 1. 彩色图先转灰度，Threshold 只吃单通道 HOperatorSet.Rgb1ToGray(ctx.Image, out HObject gray); // 2. 双阈值分割，MinGray/MaxGray 来自配置，不同产品差异很大 HOperatorSet.Threshold(gray, out HObject region, cfg.MinGray, cfg.MaxGray); // 3. 连通域拆分，每个脏点变成独立 region HOperatorSet.Connection(region, out HObject connected); // 4. 按面积筛，把噪点和真实缺陷分开 HOperatorSet.SelectShape(connected, out HObject defects, "area", "and", cfg.MinArea, 999999); HOperatorSet.CountObj(defects, out HTuple count);

SelectShape的五个参数是：输入区域、输出区域、特征名（"area"面积、"circularity"圆度、"rect2_len1"外接矩形长边）、逻辑关系（"and"/"or"）、下限、上限。只用面积筛很容易把长条状的划痕漏掉——面积不够但长度够。实际项目里我一般叠两个条件：面积大于阈值，或者外接矩形长边大于阈值，用两次SelectShape再Union2合并。

尺寸测量走的是另一条路：在 ROI 里提取边缘点，再拟合成直线或圆，最后算距离。这里最容易忽略的是「用哪个边缘」。一条边有明到暗和暗到明两个梯度方向，edges_sub_pix的"positive"/"negative"参数选错了，量出来的值会稳定偏一个边缘宽度，看着像标定不准，其实是选错边。

4.4 标定换算：像素到毫米只差一个矩阵

所有以像素为单位的测量值，最终都要换成毫米才能交给工艺。包里用的是一个 2D 仿射矩阵，存在.tup文件里：

// 标定产物在启动时加载一次，别在检测循环里读文件 HOperatorSet.ReadTuple("models/hom_01.tup", out HTuple homMat2D); // 像素坐标 → 世界坐标（毫米） HOperatorSet.AffineTransPoint2d(homMat2D, row, col, out HTuple x, out HTuple y); // 两点距离，x/y 已经是毫米 double dx = x[1].D - x[0].D; double dy = y[1].D - y[0].D; double distance = Math.Sqrt(dx * dx + dy * dy);

这个矩阵把旋转、平移、缩放打包在一起，所以工件转了角度也不影响距离计算——距离在欧氏空间里是旋转不变的，这算是用仿射矩阵而不是纯比例系数的一个隐性好处。

脆弱的地方在于前提条件：标定板平面必须和被测物表面共面。差个 2mm，在 0.05mm 的重复精度要求下就是灾难。我见过一个工位，样件放在载具上标定，量产时工件直接放皮带上，高度差了 3mm，测量值系统性偏大 0.08mm，查了两天才定位到。这类问题的表现特别有迷惑性——重复性很好，偏差很稳定，看着像「标定系数错了」，改系数又能把值拉回来，于是就这么错着用了半年。

5. 踩坑与排查：跑不起来、跑不稳、量不准的三类现场问题

5.1 编译通过但运行时报 DllNotFoundException

现象：解决方案全部编译成功，F5 一运行就抛DllNotFoundException: halcondotnet或BadImageFormatException，换台机器有时候又能跑。

原因：位数不匹配。工程平台设的 Any CPU 或 x86，引用的却是 x64 的halcondotnet.dll；或者 dll 拷到了输出目录，但它依赖的 native 库（halcon.dll）没跟着拷。

解决：把工程平台统一改成 x64，检查引用的halcondotnet.dll路径指向安装目录下的 x64 版本，并在 csproj 里加一段拷贝 native 库的 post-build。别用「手动复制到 bin 目录」这种办法，下次清理重建又没了。

5.2 跑两三个小时界面卡死，内存涨到 2G

现象：刚启动一切正常，跑半天之后界面越来越卡，任务管理器里进程内存持续上涨，重启就好。

原因：HObject没释放。这类对象的内存不在托管堆上，GC 感知不到压力，finalizer 又要等真正内存紧张才跑，于是就一路涨。

解决：给每个HObject找到明确的释放点。图像帧用using包住，算子中间结果在Execute方法里try/finally统一释放，UI 表格限制行数。改完跑 8 小时内存曲线应该是平的，不是缓慢上升。

5.3 相机断线之后上位机僵住十几秒

现象：网线拔一下再插上，界面卡住十几秒，恢复后有几帧旧图混在新图里被检测。

原因：采集线程和检测线程共用一个锁，检测在跑算子时持锁，采集回调拿不到锁就阻塞；重连逻辑又写在同一个线程里，整个链路串死。

解决：采集和检测彻底解耦，用有界队列传帧，回调只入队。断线检测单独起一个心跳线程，重连成功之后清空队列再恢复，避免旧帧污染。丢几帧比卡十几秒强得多。

5.4 同一批产品，匹配分数忽高忽低

现象：同一套模板、同一批工件，分数在 0.85 和 0.55 之间跳，偶尔直接掉到阈值以下判 NG。

原因：八成是光照。环形光源老化、环境光从侧面漏进来、工件表面有油，都会让对比度变化，形状模板对边缘梯度敏感，对比度一掉分数就掉。另一个可能是模板本身是在另一台设备上做的，镜头和光源都不一样。

解决：先固定光照，把环境光遮掉再测一轮，如果分数稳定了就是光的问题。模板必须在现场、用实际光源、拿合格品重新做一次，做完之后跑 200 件看分数分布，把minScore定在分布下沿再往下留 0.1 的余量，不要照着第一次的 0.9 就写死。

5.5 标定完测量值系统性偏大或偏小

现象：重复性很好，标准差 0.01mm，但实测值和三次元对不上，差 0.05~0.1mm，而且是稳定的偏。

原因：标定面与被测面不共面（高度差），或者镜头畸变没校正就用了线性比例系数。

解决：标定板和工件必须放在同一高度、同一姿态下标定；有畸变的镜头必须走完整标定流程拿到相机内参，用AffineTransPoint2d而不是简单的「像素数乘一个系数」。改完之后拿标准件复测，偏差应该收敛到 0.02mm 以内。

6. 二次开发：给系统加一个新工位并验证它不闯祸

需求来的时候通常很急：「这条线再加一个字符识别的工位，明天要看到效果」。按这套架构，改动其实只有四处，理清楚就不会乱：

步骤类本身很短，重点在资源管理和参数校验：

public class OcrStep : IDetectionStep { public string Name => "字符识别"; public string Unit => "count"; private HTuple _modelId; // OCR 分类器只加载一次 public StepResult Execute(ImageContext ctx, StepConfig cfg) { var sw = Stopwatch.StartNew(); _modelId ??= LoadOcrModel(cfg.GetString("model")); // ROI 一律用相对定位原点的偏移，工件移动不影响 HOperatorSet.GenRectangle1(out HObject roi, ctx.OriginRow + cfg.GetDouble("dy", -40), ctx.OriginCol + cfg.GetDouble("dx", -80), ctx.OriginRow + cfg.GetDouble("dy", 40), ctx.OriginCol + cfg.GetDouble("dx", 80)); try { HOperatorSet.ReduceDomain(ctx.Image, roi, out HObject reduced); HOperatorSet.BinaryThreshold(reduced, out HObject chars, "max_separability", "dark", out _); HOperatorSet.Connection(chars, out HObject conn); HOperatorSet.SelectShape(conn, out HObject valid, "area", "and", 80, 5000); HOperatorSet.DoOcrMultiClass(valid, _modelId, out HTuple result); string text = string.Join("", result.Select(t => t.S)); return new StepResult { StepName = Name, IsOk = text.Length == cfg.GetInt("expectLen", 8), Value = text.Length, Message = text, ElapsedMs = sw.ElapsedMilliseconds }; } finally { // 中间产物显式释放，这里最容易漏 roi.Dispose(); } } }

验证分两步走，缺一不可。第一步离线：准备 50 张现场图放D:/samples/st02，把source.type设成Folder跑一遍，看 OK/NG 分布和单帧耗时，耗时超过节拍预算的 40% 就得回头优化算子参数。第二步在线：接真相机跑 200 件，同时把每件的Score、ElapsedMs、Message打进日志，跑完统计一次 P95 耗时和误判率。只做第一步就上线的，基本都会在产线上被光照和节拍教育一遍。

还有个容易被忽略的验证点：新步骤加进去之后，原有 ST01 的结果有没有变。共享的ImageContext是会传下去的，新步骤如果手贱改了OriginRow，后面所有工位全歪。我一般会在Execute开头断言一次ctx.OriginRow有没有被动物理，或者在调试模式下把关键字段打快照对比。

从那以后我每次加新工位，都会强制走一遍「离线 50 张 + 在线 200 件 + 对比旧工位结果」这三步，哪怕需求再急也不跳——跳过一次，排查一整天的滋味不好受。希望帮到你。

本文还有配套的精品资源，点击获取