简介C#联合Halcon通用快速开发框架是一套基于Halcon17.12的工业机器视觉项目完整源码资源面向具备一定C#与Halcon基础、需要快速搭建视觉检测上位机的开发者。框架支持按项目实际需求自由配置窗口数量和排列方式每个窗口可独立选择Halcon脚本并实时查看、编译与修改脚本同时可设置CCD相机参数调用海康网口SDK完成相机调试、模板创建并实现与三菱FX5U以太网通讯覆盖相机触发、图像处理、结果输出与设备联动等常见环节。框架还提供历史检测数据查询、产量履历记录与历史图像保存功能便于生产追溯适配质检、定位、测量等典型视觉场景。资源共347个文件压缩包约165.76MB主要包含C#源码、Halcon脚本hdvp/hdev、DLL依赖库、可执行程序、工程文件与配置文件等并附有演示视频。所有源码开放没有封装黑盒便于深入学习与定制。已有3656人学习浏览适合作为视觉项目架构参考可直接改造或二次开发。1. 为什么做框架机器视觉项目里时间和稳定才是真成本做过两个以上Halcon视觉项目的人基本都体会过同一种窘境算法验证时HDevelop里跑得又快又准一到C#工程里就变了个样子。图像采集线程稍一抖动UI卡顿、相机丢帧、定位结果偶尔跳几个像素——问题不在于Halcon本身而在于没有人把图像采集、算法执行、结果显示、参数管理这些公共能力沉淀下来。每个项目从零搭一遍重复造轮子的成本远比算法开发本身高。这个“C#联合Halcon通用快速开发框架”本质就是解决两件事让Halcon算法工程师和C#应用工程师在同一套结构下协作让图像处理逻辑和应用逻辑解耦到可以独立替换、独立调试的程度。对于做上位机、视觉检测设备、定位引导项目的团队这套框架能把一个常规视觉项目的联调周期从三周压到一周以内。下面我按自己搭这类框架的经验从分层设计、执行引擎、参数封装一直讲到RT调试和运行期性能检查。2. 框架的架构分层把Halcon代码隔离到一个不会污染C#业务的边界里2.1 为什么不能直接把HOperatorSet调用散落在窗体代码里常见做法是把Halcon的HImage、HRegion直接塞进WinForms或WPF的按钮事件里这么做在几十行代码时没问题一旦流程超过五个步骤——采集、预处理、找边、测量、结果显示——代码结构会迅速腐化。更本质的问题是Halcon的HDebug模式下部分对象是非托管资源靠GC回收并不可靠长期运行的项目会看到内存曲线缓慢爬升。另一个现实原因是Halcon的算法代码迭代非常频繁。今天用threshold明天可能要换成dyn_threshold或者深度学习分割。如果算法逻辑散落在窗体的各个事件里每一次算法调整都要重新编译整个UI层。所以框架第一件事是把“视觉处理”和“应用外壳”彻底分开。2.2 分层模型采集层、处理层、应用层三板斧我习惯把框架分成三层。采集层负责跟相机硬件打交道不管是用Halcon自己的接口还是厂商SDK对外只暴露一个统一的ImageAcquired事件事件参数里携带HImage或图像字节数组。处理层是核心它接收图像执行Halcon算子序列最终输出测量结果、定位坐标或者OK/NG判别。应用层负责UI刷新、数据存储、流程控制、与PLC或机器人通信。这三层之间用接口连接处理层完全不知道UI长什么样。这样做的直接收益是算法调试时可以不启动相机用文件夹里的图片回放UI调优时可以不跑算法用模拟数据源。联合调试只在最后阶段做时间和人力都省下来了。2.3 在C#工程里组织Halcon引用与命名空间的约定实现上建议单独建一个类库项目起名如Vision.Core专门放Halcon相关的引用。Halcon的.NET接口在安装目录下有hlib目录引用三个核心程序集halcondotnet.dll基础类型和算子封装、hdevenginedotnet.dllHDevEngine用于执行外部过程文件、hdevenginedotnet.dll对应的CX和CXX版本不强求。引用后注意在csproj里把CopyLocal设为true避免部署时漏DLL。命名空间上要跟业务代码拉开距离我用的是Vision.Core.Halcon和Vision.Core.Interface两层。前者放Halcon类型包装后者放抽象接口。业务代码只允许引用后者。这样做的好处是未来如果要把Halcon换成OpenCV或者自定义算法库业务层代码几乎不用动。3. 可复现的框架骨架用C#写一个能直接跑的Halcon处理流程3.1 处理流程的抽象从“写死算子”到“流水线步骤”框架中间最核心的一个类叫做VisionFlow它把图像处理过程建模成一个步骤列表。每个步骤继承自一个抽象基类VisionStep基类定义两个方法Execute(HImage input, out HImage output)和参数读写接口。这样每个算法步骤就变成一个可独立配置、独立调试的单元。下面给出一个最小可运行的框架骨架这段代码可以直接建一个控制台工程跑通。public abstract class VisionStep { public string Name { get; set; } public abstract bool Execute(HImage input, out HImage output); } public class ThresholdStep : VisionStep { public double MinGray { get; set; } 128; public double MaxGray { get; set; } 255; public override bool Execute(HImage input, out HImage output) { HRegion region input.Threshold(MinGray, MaxGray); output input.ReduceDomain(region); return true; } } public class VisionFlow { private ListVisionStep _steps new ListVisionStep(); public void AddStep(VisionStep step) _steps.Add(step); public HImage Execute(HImage input) { HImage current input; foreach (var step in _steps) { if (!step.Execute(current, out current)) throw new Exception($步骤 {step.Name} 执行失败); } return current; } }这段代码的逻辑说明每个步骤接受一张HImage输出一张处理后的HImage下一个步骤消费上一个的输出。ThresholdStep演示了Halcon里最常用的阈值分割操作ReducedDomain的作用是把图像裁剪到区域范围内减少后续处理的像素量。参数说明MinGray和MaxGray对应Halcon中threshold算子的两个阈值参数单位为灰度值0到255。实际项目中这两个参数不应该硬编码在代码里而是从配置文件或界面上读取后面第4章会专门讲参数封装。这个骨架的精髓在于每个步骤只关心自己的输入输出不关心前后步骤是什么这为并行和组合提供了基础。3.2 相机采集成帧触发与回调解决UI刷新卡顿的关键写法C#上位机里最常见的性能杀手是直接在相机回调线程里刷新UI控件。Halcon的HImage本质是一个比较重的对象如果在UI线程里反复构造和析构GC会频繁触发卡顿随之而来。正确做法是在回调线程里只做采图和入队UI刷新交给Dispatcher或BeginInvoke。public class CameraService { private HTuple _acqHandle; private BlockingCollectionHImage _queue new BlockingCollectionHImage(new ConcurrentQueueHImage(), 5); public void Start() { HOperatorSet.OpenFramegrabber(GigEVision2, 0, 0, 0, 0, 0, 0, default, -1, default, -1, false, default, cam1, 0, -1, out _acqHandle); Task.Run(GrabLoop); } private void GrabLoop() { while (true) { HImage image new HImage(); image.GrabImageAsync(_acqHandle, -1); if (!_queue.TryAdd(image, 50)) Console.WriteLine(队列已满丢弃当前帧); } } }逻辑说明OpenFramegrabber是Halcon打开采集设备的统一入口参数很长其中GigEVision2表示使用GigE Vision协议cam1是相机名称。GrabImageAsync是异步抓图-1表示无限等待。BlockingCollection的容量设为5消费速度跟不上时主动丢帧这比让内存无限堆积要安全得多。参数说明队列容量5并不是拍脑袋定的它取决于处理一帧的时间。如果一帧处理需要30毫秒相机帧率是30fps那么队列容量至少是2才能保证不丢帧。要调优时用性能计数器记录消费速度和生产速度按二者差值设定容量。UI刷新不要在GrabLoop里做用事件通知UI线程自行取图。3.3 窗口显示与ROI交互以HSmartWindowControl为核心的组件封装Halcon的.NET接口里显示图像最常见的坑是在WinForms下用HWindowControl但想要缩放、平移、画ROI这类交互能力一定要用HSmartWindowControl。HWindowControl的交互能力很弱而HSmartWindowControl内置了鼠标拖拽平移和滚轮缩放还能通过SetInteractiveMode控制划线行为。public class HalconDisplay : IDisposable { private HSmartWindowControl _control; public void DisplayImage(HImage image) { _control.HalconWindow.DispObj(image); _control.HalconWindow.SetPart(0, 0, image.Height - 1, image.Width - 1); } public HRegion DrawRoi() { _control.SetInteractiveMode(HSmartWindowControl.InteractiveMode.ROI); HRegion roi _control.GetROI(); return roi; } }逻辑说明DispObj是最基础的图像显示调用SetPart决定了当前显示的图像区域这里设置成整幅图像。DrawRoi里开启交互模式用户用鼠标在控件上画矩形区域GetROI返回画好的区域。在实际项目里先显示图像、再让用户画ROI、然后用ROI裁剪图像输入给处理流程是定位类项目最常见的交互形态。注意HSmartWindowControl在WPF和WinForms下的命名空间不同WPF版本是HalconDotNet.HSmartWindowControlWPFWinForms版本不需要WPF后缀。绘图操作必须在UI线程执行否则会导致显示异常。这一条几乎踩过的人都有印象联调时莫名其妙的白屏多半就是后台线程调用DispObj导致的。4. 参数封装与调试效率把Halcon调试参数写到界面的正确姿势4.1 参数表的定义与序列化让算法参数具备持久化能力Halcon算子参数多类型杂HTuple是万金油但直接暴露给界面并不友好。实际项目里我习惯把参数抽成强类型对象每个VisionStep对应一个Parameter类。比如查找圆心的步骤参数包括最小灰度、最大灰度、边缘阈值、半径范围、极性等。这样界面上绑定的就是具体属性而不是字典里的一堆字符串键。序列化选择用JSON还是XML取决于团队习惯。如果客户要求可配置性高、能在现场直接改参数而不重新编译JSON更合适。下面的代码展示了一个参数JSON文件的加载与保存过程{ threshold: { minGray: 80, maxGray: 200, minArea: 50 }, findCircle: { radiusMin: 50, radiusMax: 100, edgeThreshold: 30, polarity: positive } }public class VisionParameters { public ThresholdParam threshold { get; set; } public FindCircleParam findCircle { get; set; } public static VisionParameters LoadFromFile(string path) { string json File.ReadAllText(path); return JsonConvert.DeserializeObjectVisionParameters(json); } public void SaveToFile(string path) { string json JsonConvert.SerializeObject(this, Formatting.Indented); File.WriteAllText(path, json); } }逻辑说明LoadFromFile在相机启动前调用把参数一次性读入内存。这里要注意文件读取失败的兜底——参数加载失败时应该用默认值启动并弹出日志或提示而不是让程序崩溃。SaveToFile用于调试时把当前界面调整好的参数写回文件下次直接使用。参数说明JSON框架选择Newtonsoft.Json是较稳妥的路径因为微软自带的System.Text.Json在写Canvas或自定义Converter时会有一些不够顺手的地方。SaveToFile里要注意编码问题中文路径和中文参数值建议统一UTF-8编码避免现场工控机上出现乱码。4.2 参数调试的界面范式先显示中间结果再调参数Halcon调试效率低原因往往不是算子本身而是参数调整后看不到中间结果。框架里应该专门做一个小窗口左侧放原始图右侧放当前步骤的中间结果图。拖动参数滑块时右侧实时更新。这个功能在Halcon的.HDevelop里很容易做到但在C#里需要重新实现因为它对框架的依赖关系是逆向的。具体做法是VisionFlow的当前执行状态里保存每个步骤的output图界面通过事件订阅方式获取。下面是实现中值得注意的点public event ActionHImage, string OnIntermediateResult; public HImage Execute(HImage input) { HImage current input; foreach (var step in _steps) { step.Execute(current, out current); OnIntermediateResult?.Invoke(current, step.Name); } return current; }这段代码的核心在于每个步骤执行完就触发一次事件界面上把结果存进字典key是步骤名。这样用户在下拉框里切换步骤时可以直接把对应的中间结果显示出来。相比在界面里对每个步骤单独写绑定这种做法只需要一套通用代码新增算法步骤时不需要改界面代码。注意这里不要直接在事件参数里处理UI逻辑事件回调发生在算法线程界面拿到的是HImage引用显示前需要复制或者确保不再被后续步骤修改。一种稳妥方案是在事件里立即调用BeginInvoke刷新显示不要攒批量。4.3 Halcon license 相关问题与运行时检查开发机上装好Halcon后遇到“Halcon can not find feature in license”这类错误通常是license文件中不包含正在使用的算子授权。实际影响是某些高级算子比如深度学习推理或特定测量算子在试用版或基础版license下无法运行。在框架层面应该对关键算子调用做一次启动自检避免运行到一半才报错。public static class HalconLicenseChecker { public static void CheckRequiredFeatures() { try { HOperatorSet.OpenWindow(0, 0, 1, 1, 0, visible, , out HTuple window); HOperatorSet.CloseWindow(window); } catch (HalconException ex) { throw new InvalidOperationException(Halcon许可证初始化失败: ex.Message); } } }逻辑说明通过尝试打开一个1像素的最小窗口来验证License是否有效这个方法虽然简单但很实用。窗口参数里的第一个0是窗口编号后面两个1是宽高visible表示可见但1像素的窗口在屏幕上根本看不出来所以不会干扰用户。失败时抛出的异常应该在框架启动早期被捕获弹窗提示检查许可。5. 高级流程控制触发事件、并行处理与外部过程文件的执行5.1 扫码枪串口触发与视觉采集的联动设计实际产线上常见的触发来源除了PLC硬触发之外就是扫码枪串口触发。扫码枪读到条码后通过串口发送字符串视觉系统收到字符串后开始抓图处理。这个需求看起来简单但在C#里涉及串口事件、图像采集、算法执行三者的时序协调。public class SerialTriggerService { private SerialPort _serialPort; public event Actionstring OnTriggerReceived; public void Start(string portName, int baudRate) { _serialPort new SerialPort(portName, baudRate, Parity.None, 8, StopBits.One); _serialPort.DataReceived (s, e) { string data _serialPort.ReadExisting(); OnTriggerReceived?.Invoke(data.Trim()); }; _serialPort.Open(); } }逻辑说明串口DataReceived事件在后台线程触发这里直接把原始字符串抛出去。上层接到触发后应该调用相机采图服务的异步抓图方法并把条码字符串和图像一起打包成一个任务交给处理队列。注意不要在事件处理里直接做图像处理否则串口缓冲区会在处理期间堆积数据导致下一次触发丢失。参数说明波特率一般用9600或115200取决于扫码枪配置。ReadExisting在触发时可能只读到半个条码稳妥方案是加一个简单的缓冲区等到收到换行符或回车符才认为一次触发完整。这个细节在调试时容易踩扫码枪一次性发来的数据在串口上可能被拆成多段。5.2 并行执行多个Halcon流程用Task代替线程的考量一台设备上可能有多个相机、多个工位每个相机独立跑一套流程。C#上位机里用Thread还是Task业界默认是Task加async/await。Halcon的算子内部通常不阻塞UI线程所以在Task里跑Halcon是安全的关键是处理好任务取消和结果回调。private async Taskint RunProcessAsync(HImage image, CancellationToken token) { return await Task.Run(() { token.ThrowIfCancellationRequested(); // 执行Halcon测量算子 HMeasure measure new HMeasure(); measure.SetHandle(image, new HTuple(), new HTuple()); HTuple result measure.MeasurePos(image, 1, 30, all, all, out _, out _, out _); return result.Length; }, token); }逻辑说明Task.Run保证Halcon算子在线程池线程上执行。外层用await等待结果UI不会卡死。CancellationToken是取消机制的关键——如果用户点击停止按钮token被置为取消状态线程池里的运行任务会在下一次检查时主动退出。注意Halcon算子的执行不一定能被立即中断这里只能保证在算子边界处响应取消。如果你运行在多相机环境里注意Halcon运行时是否开启了HALCON_THREAD_POOL环境变量。默认情况下每个Halcon调用内部的线程池是独立的但多相机并行时需要评估CPU核心数是否能撑住。四核以下机器不建议开超过两个并行流程。5.3 用HDevEngine执行外部HDVP脚本实现算法与程序分离算法工程师在HDevelop里写完流程并导出为hdvp文件后C#工程师可以用HDevEngine直接在应用程序里加载执行这个脚本。这样算法迭代时不需要重新编译C#工程只需要替换脚本文件这是“快速开发”的另一种重要落地方式。public class HDevEngineRunner { private HDevEngine _engine; private HDevProcedure _procedure; public void Load(string hdvpPath) { _engine new HDevEngine(); _engine.SetProcedurePath(Path.GetDirectoryName(hdvpPath)); _procedure new HDevProcedure(hdvpPath); } public HTuple Execute(HImage image, HTuple inputParams) { HDevProcedureCall call _procedure.CreateCall(); call.SetInputIconicParamObject(Image, image); call.SetInputCtrlParamTuple(InputParam, inputParams); call.Execute(); return call.GetOutputCtrlParamTuple(Result); } }逻辑说明Load方法在程序启动时调用把外部hdvp文件编译为内部过程。Execute时创建一次调用传入图像和控制参数执行后取回结果。整个过程中C#代码对算法内容完全无感知算法里的算子怎么组合、用了多少个步骤对C#层是黑盒。参数说明SetInputIconicParamObject用于传入图像这类图标型参数SetInputCtrlParamTuple用于传入数值、字符串等控制型参数二者的名字必须与HDevelop里的参数名对应。GetOutputCtrlParamTuple返回输出结果如果需要返回区域或图像需要相应调用GetOutputIconicParamObject方法。6. 框架落地的最后一步用性能计时和结果复现确认框架能上线一个框架搭得再好如果性能没有量化指标到了客户现场就会出现修不完的“慢”和“不稳”。我的习惯是在框架内置两个轻量级的诊断工具一个是处理流程的分段计时器一个是图像与结果的存档日志。计时器记录每个VisionStep消耗多少毫秒数值写到一个环形缓冲区里存档日志则是把有代表性的原始图和对应结果异步写入本地磁盘方便离线复现问题。public class StepTimer { private Dictionarystring, Stopwatch _timers new(); private Dictionarystring, double _lastElapsedMs new(); public void Start(string stepName) _timers[stepName] Stopwatch.StartNew(); public void Stop(string stepName) { _timers[stepName].Stop(); _lastElapsedMs[stepName] _timers[stepName].Elapsed.TotalMilliseconds; } public void DumpToLog() { foreach (var kv in _lastElapsedMs) Trace.WriteLine(${kv.Key}: {kv.Value:F1} ms); } }使用时要保证Start和Stop成对出现放在每个VisionStep的Execute方法入口和出口处。若某个步骤耗时异常攀升对比最近几次Dump结果就能定位到是哪个阶段变得不稳定。现场排查时最常用的命令就是看这个控制台输出。图像存档功能要控制频率。连续运行时每帧都存IO压力很大建议只存NG图和每第N帧的样本图配合条码或时间戳命名。这一步做完后整个框架才算是真正从“能跑”进入“能上线”的状态。本文还有配套的精品资源点击获取