简介本资源是一套2022年工业级C#与Halcon联合开发的完整机器视觉项目实战案例面向具备基础C#编程能力及初步图像处理认知的工程师与高校高年级学生旨在解决视觉系统工程化落地中架构混乱、代码耦合度高、难以维护升级等典型问题。压缩包共228个文件含71个核心C#源码.cs、6个Visual Studio解决方案与项目文件.sln/.csproj、29个Halcon运行时依赖DLL、35幅实采检测图像.bmp及配套配置、日志与资源文件整体41.16MB结构清晰体现标准三层架构——表现层WinForm界面、业务逻辑层Halcon算法封装与流程调度、数据访问层结果存储与设备通信。已有6279人学习下载读者可直接复用模块化视觉处理类、掌握Halcon.NET API在产线场景下的稳定调用方式并通过真实图像样本与完整项目结构深入理解工业视觉系统的分层设计思想与工程规范。 2022年接过一个视觉项目任务不复杂但细节是真的多用C#写上位机Halcon 20.11跑图像算法软件整体采用三层架构目标是在一条半自动产线上做金属零件的尺寸测量和表面缺陷检测。项目前后做了三个月踩了不少坑也沉淀了一套可以复用的套路。这篇文章就把这套完整案例拆开讲讲从架构设计到Halcon集成从像素标定到部署排错尽量把关键代码和排查思路都还原出来。如果你正在做C#上位机正准备把Halcon塞进项目里或者对一个工业视觉项目该用什么结构完全没有概念这篇文章应该能帮你少走不少弯路。1. 这个视觉案例的业务背景和方案选型逻辑1.1 项目要解决的实际问题是什么产线那边的需求并不复杂。一个金属零件在进入下一个工位之前需要自动检测两件事关键尺寸是否在公差范围内表面有没有明显的划痕和脏污。检测节拍要求3秒一件结果要通过IO或者网口告诉PLC如果是NG件还要在界面上留下记录方便后续追溯。检测平台用的是普通工控机相机是600万像素的黑白GigE工业相机镜头是35mm定焦的C口镜头没有用视觉控制器所有图像处理都交给上位机软件处理。这个配置在小型视觉项目里很常见不买专用设备用现有PC跑算法控制和显示都放在同一个程序里。按照这个需求软件并不是一个纯粹的“图像算法工具”它更像一个完整的上位机系统要管相机、管通信、管界面、管参数配置还要管检测结果和历史记录。这也是为什么我当时坚持用三层架构来组织项目——因为如果只是写一个Halcon脚本丢给产线后期任何一个小改动都会变成一场灾难。1.2 为什么选C#和Halcon而不是OpenCV或者纯C很多接触机器视觉不久的朋友会问直接用Halcon的HDevelop写脚本不行吗为什么还要用C#包一层HDevelop确实是Halcon的便利工具但它的定位是算法开发环境不是产品交付环境。产线上的操作工不会去打开HDevelop看检测界面他们需要一个稳定的、好看的、能显示零件图片和OK/NG状态的Windows程序。这个程序必须不容易被误操作能够记录日志能够保存检测结果。这些能力用C#做非常顺手尤其是WinForm和WPF的界面开发效率比纯C高太多。Halcon和OpenCV的对比也是老话题了。OpenCV免费、社区大但工业场景里常用的标定、卡尺测量、形状模板匹配、亚像素边缘提取OpenCV不是没有而是需要自己去组合和调参稳定性和Halcon还是差一截。Halcon的算子成熟文档和案例丰富尤其是找标定板、测量像素位置映射到物理尺寸这类功能省掉了大量底层开发时间。对项目交付来说直接选择Halcon是性价比最高的方案。1.3 三层架构在这种项目里解决了什么真实问题“三层架构”这个词在培训机构里已经被说烂了搞得上位机项目好像不用三层架构就不好意思叫工程。但我在这个项目里体会特别深的是三层架构解决的是需求变更带来的连锁修改问题。比如项目运行两周后客户提了一个需求同一个零件有A/B两种型号需要一键切换检测模板。如果检测逻辑、界面显示、参数存储全部揉在同一个窗体类里这个需求会让开发人员把界面代码、算法代码、配置文件代码全部翻一遍很容易改出回归问题。而按三层架构拆分之后界面只需要加一个下拉框业务层根据型号加载对应的模板参数数据访问层负责按型号保存标定数据改动范围一下子就被限制住了。再比如产线换了一台不同品牌的相机采集代码变了。如果采集逻辑分散在界面里得全局搜索“new HFramegrabber”去找所有相关位置如果采图入口集中在业务层的CameraService里替换一个类就够了界面完全不用动。所以我的结论是哪怕只是一个单机版、单相机、三五个界面的视觉项目也一定要把UI、业务、数据访问分开。它不是过度设计它是给未来留的退路。2. 三层架构在视觉项目里的落地方案每层该放什么2.1 UI层只做展示和交互不碰算子在这个项目里UI层是WinForm做的主要界面有三个主检测界面实时图像显示、启动/停止检测按钮、OK/NG指示灯、当前零件信息、计数统计。参数设置界面相机参数、检测公差、模板选择、保存路径。历史记录界面按时间查询检测记录查看当时的图像和测量结果。UI层的一个核心原则是界面代码里不允许直接出现new HFramegrabber、call Halcon这类操作。所有视觉动作都通过业务层提供的接口发起。界面只负责把用户的点击转换成调用把结果显示出来。public interface IVisionService { void StartCamera(); void StopCamera(); TaskVisonResult ExecuteInspectionAsync(int productTypeId); event EventHandlerImageReadyEventArgs ImageReady; event EventHandlerResultReadyEventArgs ResultReady; }窗体拿到的永远是这个接口的实例它不需要关心内部是Halcon还是其他算法库。这方便我后续在公司内部把算法替换成其他方案也方便写单元测试当然工业项目的单元测试优先级不高但至少架构上留了口子。界面刷新还用到了一个细节Halcon的图像对象不能直接跨线程丢给UI线程去显示。我会把图像先转成Bitmap再通过事件抛给界面。这样UI线程不直接和Halcon的句柄打交道避免很多莫名其妙的崩溃。2.2 业务层视觉流程编排和多线程管理业务层是整个项目的核心我把它拆成几个服务类每一个类只负责一块明确的工作CameraService负责相机初始化、连接、连续采集、软触发/硬触发对外提供最新一帧图像。VisionService负责调用Halcon算子执行模板匹配、测量、缺陷检测返回结果对象。ResultService负责把结果写入数据库、生成报表、统计产量。PlcService负责和PLC通信告知OK/NG。这里最需要设计好的是采集和检测的协作方式。刚开始做第一个版本时我是在相机采集回调里直接做检测看起来没问题但实际跑起来界面卡顿严重而且只要检测算子耗时稍微长一点相机缓冲区就会大量积压导致报警和丢帧。后来改成生产者消费者模式采集线程负责不断把新图像塞进一个队列检测线程从队列里取图像执行算法。这样即使某个瞬间检测比采集慢也不会阻塞相机采集图像队列最多积压几帧丢掉旧的、保留最新的。代码骨架大概是这个意思private BlockingCollectionHObject _imageQueue new BlockingCollectionHObject(boundedCapacity: 3); private Task _inspectTask; private void CaptureLoop() { while (_capturing) { HObject image _cameraService.GrabImage(); if (!_imageQueue.TryAdd(image, 100)) { image.Dispose(); // 队列满了丢弃旧帧 } } } private void InspectLoop() { foreach (HObject image in _imageQueue.GetConsumingEnumerable()) { VisonResult result _visionService.Inspect(image); _resultService.Save(result); ResultReady?.Invoke(this, new ResultReadyEventArgs(result)); image.Dispose(); } }这个设计在项目里非常稳。需要强调一点HObject是托管包装类内部持有非托管句柄不用的图像一定要及时Dispose()。这个项目跑到后面内存泄露问题几乎都出在忘了释放图像对象上。2.3 数据访问层参数、标定数据和检测记录怎么管数据访问层看起来不起眼但它决定了项目后期好不好维护。我在这层做了三件事第一标定参数和检测公差按产品型号保存。格式用了JSON每个型号一个配置节点包含模板路径、像素当量、尺寸公差上下限、缺陷面积阈值等。这样换产品时只需要在界面上选择型号业务层自动加载对应配置。{ productTypeId: 1, modelName: A001, shapeModelFile: ./models/A001.shm, pixelCalibration: 0.0125, nominalLength: 25.40, toleranceMin: 24.90, toleranceMax: 25.90, defectAreaLimit: 0.35 }第二检测记录存SQLite。每次检测生成一行记录包含检测时间、产品型号、测量值、判定结果、图像路径。SQLite是单文件数据库不需要在工控机装数据库服务产线环境也能接受很省心。第三日志单独走一套文件Logger。我用的是NLog按天切分日志里记录每次Halcon报错的堆栈和当前参数。后面要提到的#5322采图超时等错误就是靠日志定位出来的。没有日志工业现场的问题排查基本等于大海捞针。3. Halcon和C#集成的细节DLL、调用方式、图像转换3.1 引用DLL和“无法加载一个或多个请求的类型”用C#集成Halcon第一步是引用Halcon提供的.NET组件。安装Halcon后在bin\dotnet目录下能找到halcondotnet.dll和hdevengine.dll新版本里还有hdevenginedotnet.dll。在Visual Studio里添加引用后代码中可以直接using HalconDotNet;。但这里有一个特别常见的坑程序一启动就报“System.IO.FileNotFoundException: 无法加载一个或多个请求的类型”。排查思路如下确认引用的是正确的目标平台版本。Halcon的.NET DLL区分x86和x64而Visual Studio项目本身也有目标平台两者不一致肯定报错。现代工控机基本都是64位统一使用x64。确认所有依赖DLL都复制到了输出目录。引用添加后DLL会被复制到bin目录但有时候因为版本更新halcon.dll原生C库没有同步复制。最简单粗暴的办法是手动把这些DLL复制到发布目录。确认没有版本混用。比如项目编译时用的Halcon 20.11的DLL发布的机器上只装了Halcon 18.11的Runtime运行时会因为版本不匹配报错。尽量让开发环境和部署环境保持一致或者直接带上目标机器的全部Runtime。3.2 两种调用方式HOperatorSet和HDevEngineHalcon在C#里主要有两种调用方式。第一种是HOperatorSet静态类直接调用每个算子。这种方式的优点是编译期就能检查语法执行效率高可以直接用HDevelop里导出C#代码的功能把算法脚本转出来。项目里最终部署的检测算法基本都是这种方式。第二种是HDevEngine可以在C#边运行边加载.hdvp脚本或.hdev文件。它的好处是算法工程师在HDevelop里改完算法不需要重新编译C#程序重启软件就能用新脚本。缺点是脚本语言在运行时才解析调试起来不如C#方便而且跨线程使用HDevEngine的实例时需要每个线程单独创建一个HDevEngine对象否则会有严重的线程安全问题。对比项HOperatorSetHDevEngine开发方式HDevelop导出C#代码编译集成运行时加载.hdvp脚本运行时调试较难依赖C#调试可以直接改算法脚本执行性能高略低线程安全需要自己管理句柄每个线程独立引擎适合场景最终交付、稳定版本算法调优、现场可调参我这个项目采取的是混合方案产品A、B的核心检测算法用HOperatorSet硬编码进程序保证稳定和性能参数设置界面保留了一个加载脚本入口如果算法工程师有应急调整可以临时走HDevEngine跑一个脚本。上线半年多这个应急入口只用过两次但都是救命的场景。3.3 HObject和Bitmap互转跨界必须掌握的代码Halcon的图像对象是HObjectC#原生界面和外部系统不认。这个项目至少要处理两个场景把图像显示在WinForm的PictureBox里以及把检测异常的图像保存成JPG文件给追溯系统用。把Bitmap转成HObject的常见代码public static HObject BitmapToHImage(Bitmap bitmap) { Rectangle rect new Rectangle(0, 0, bitmap.Width, bitmap.Height); BitmapData bmpData bitmap.LockBits(rect, ImageLockMode.ReadOnly, PixelFormat.Format8bppIndexed); try { HOperatorSet.GenImage1(out HObject image, byte, bitmap.Width, bitmap.Height, bmpData.Scan0); return image; } finally { bitmap.UnlockBits(bmpData); } }把HObject转成Bitmap的常用代码public static Bitmap HObjectToBitmap(HObject image) { HOperatorSet.GetImagePointer1(image, out IntPtr pointer, out string type, out int width, out int height); Bitmap bitmap new Bitmap(width, height, PixelFormat.Format8bppIndexed); BitmapData bmpData bitmap.LockBits(new Rectangle(0, 0, width, height), ImageLockMode.WriteOnly, PixelFormat.Format8bppIndexed); byte[] buffer new byte[width * height]; System.Runtime.InteropServices.Marshal.Copy(pointer, buffer, 0, buffer.Length); System.Runtime.InteropServices.Marshal.Copy(buffer, 0, bmpData.Scan0, buffer.Length); bitmap.UnlockBits(bmpData); return bitmap; }黑白工业相机的图像是8位灰度图转Bitmap时用Format8bppIndexed需要给调色板赋值否则显示出来是黑乎乎一片或颜色错乱。如果是彩色相机用GenImageInterleaved或逐通道转换会更方便项目里用的黑白相机所以这里没涉及。3.4 不用Halcon控件显示图像的替代方案热搜词里有一条是WPF 显示halcon格式图片方案 不使用halcon控件看到这个说明不是只有我遇到过这个问题。Halcon自带的HWindowControl在WinForm里挺好用但到了WPF里就很别扭因为WPF的渲染线程和HWindowControl的句柄机制容易冲突尤其是频繁刷新实时画面时会出现闪烁甚至断线的现象。我的做法是绕开Halcon控件在业务层用图像转换扩展方法把HObject转成Bitmap再在WPF端转成BitmapSource绑定给Image控件。public BitmapSource ToBitmapSource(Bitmap bitmap) { IntPtr hBitmap bitmap.GetHbitmap(); try { return Imaging.CreateBitmapSourceFromHBitmap( p a hrefhttps://download.csdn.net/download/weixin_46931877/80098038 stylecolor:#ec7500;font-size:14px; 本文还有配套的精品资源点击获取 /a img altmenu-r.4af5f7ec.gif srchttps://csdnimg.cn/release/wenkucmsfe/public/img/menu-r.4af5f7ec.gif stylewidth:16px;margin-left:4px;vertical-align:text-bottom;cursor:text; /p