简介这是一套基于WPF、Halcon与C#开发的仿EasyVision通用视觉框架软件全套源码面向机器视觉方向的中高级开发者、上位机工程师及希望深入理解视觉框架设计的学习者可用于快速搭建检测、定位、测量等工业视觉项目也适合作为二次开发的基础底座。压缩包共约2000个文件整体约187.77MB以700个cs源码文件、315个dll动态库、47个xaml界面文件及大量pdb调试符号、config配置、resources资源与csproj工程文件为主涵盖解决方案、界面布局、算法调用与插件配置等完整结构。框架内置50多个功能模块采用插件式开发代码开源需要新功能可自行扩展便于学习参考或略作修改后用于实际项目。目前已有2994人学习下载读者可从中掌握视觉框架的分层设计、模块组织与Halcon集成思路理解插件机制与工程目录结构为自建视觉平台或改造现有项目提供可复用的参考。1. 仿 easyvision 的通用视觉框架WPFHalconC# 这套组合到底能跑多远产线上新来一台 CCD 相机老板要求三天内出一个能标定、能找圆、能测距、能出报表的上位机界面。你打开 Visual Studio新建一个 WPF 项目NuGet 里把 HalconDotNet 拖进来然后开始纠结图像显示用 Image 控件还是 Halcon 的 HWindowControl相机回调线程怎么把 HObject 安全地丢给 UI标定参数存 XML 还是 JSON这套「通用视觉框架」要解决的就是把这类重复劳动一次性封装掉——它不是一个具体检测项目而是一套可复用的骨架相机管理、图像采集、算法算子编排、结果显示、参数持久化、日志追溯全部预置好新项目只写业务算子。WPF 负责界面与数据绑定Halcon 负责视觉算法C# 负责把两者粘起来源码开箱即用的意思是你拿到手就能编译、能连相机、能跑通一个找圆流程而不是从零搭 MVVM 和 Halcon 互操作。这套东西适合谁适合已经会 C# 基础语法、能看懂 Halcon 算子文档、但每次做新项目都要重新造轮子的视觉工程师也适合做 C# 上位机、想往视觉方向转的开发者。不适合完全没碰过 C# 和图像处理的新手直接啃因为框架里的抽象层会掩盖很多底层细节你得先知道底层在干什么才能改得动框架。2. 框架分层与选型为什么是 WPF 而不是 WinForm为什么是 Halcon 而不是 OpenCV2.1 界面层选 WPF 的硬理由数据绑定与多相机并发刷新WinForm 做视觉界面不是不行但一旦相机数量超过两台、每台都要实时刷新图像和结果控件重绘和线程同步就会变成玄学。WPF 的依赖属性与数据绑定机制让图像源、结果列表、状态灯这些 UI 元素可以绑定到 ViewModel 的属性上相机回调线程只负责更新 ViewModel 的属性值由 WPF 的 Dispatcher 自动调度 UI 刷新。这比 WinForm 里手动 Invoke 控件要干净得多。另一个硬理由是 WPF 对高 DPI 和复杂布局的支持更好视觉软件经常要在同一窗口里塞图像、参数面板、结果表格、日志区WPF 的 Grid 和 DockPanel 组合能撑住这种复杂度。但 WPF 也有代价HWindowControl 是 WinForm 控件要在 WPF 里用就得套 WindowsFormsHost。这个宿主控件在渲染叠加图形时会有空域问题——WPF 的透明层盖不住它。常见做法是图像显示用 HWindowControl结果叠加用 Halcon 的 disp_message 和 disp_circle 直接画在 HWindow 上而不是用 WPF 的 Canvas 去叠。这样虽然牺牲了一点 UI 灵活性但避免了空域冲突导致的图形闪烁。2.2 Halcon 的不可替代性找圆、测量、标定算子成熟度OpenCV 找圆用 HoughCircles参数调起来很痛苦边缘一断就丢圆。Halcon 的 find_circle 和 fit_circle_contour_xld 组合配合亚像素边缘提取在金属件、玻璃、PCB 标记点这些场景下稳定性明显高一个档次。测量方面Halcon 的 measure_pos 和 measure_pairs 直接给出一维边缘对的距离标定后的世界坐标转换也有现成的 vector_to_hom_mat2d 和 affine_trans_point_2d。这些算子不是 OpenCV 没有而是 Halcon 在工业现场的调参经验和文档积累更厚。代价是 license 成本以及 Halcon 版本与 .NET 运行时的兼容性——比如 Halcon 23.11 要求 .NET Framework 4.8 或 .NET 6老项目升级时要注意。选型结论如果项目预算允许、检测精度要求亚像素级、现场环境光照不稳定Halcon 是更稳的选择。如果只是做定位引导、精度要求不高、想省 license 费用OpenCVSharp 也能用但框架里的算子封装层要重写。2.3 框架核心模块划分与依赖关系一套能开箱即用的通用视觉框架至少要有这几个模块模块职责关键类/接口相机管理枚举相机、连接、采图、回调ICamera、CameraManager图像处理Halcon 算子封装、ROI 管理VisionTool、ToolResult流程编排多工具串联、条件分支FlowEngine、IToolNode参数持久化标定参数、工具参数存取ParamStorage、JsonSerializer结果显示图像渲染、结果叠加、报表DisplayManager、ReportBuilder日志与追溯操作日志、检测结果存档Logger、ResultRepository依赖关系是相机管理输出 HObject 给流程编排流程编排调用图像处理模块的算子算子结果通过结果显示模块画到 HWindowControl 上同时写入日志与追溯模块。参数持久化模块被所有模块依赖用来保存和加载配置。2.4 最小可运行框架的搭建步骤第一步新建 WPF 项目目标框架选 .NET Framework 4.8 或 .NET 6。第二步NuGet 安装 HalconDotNet注意版本要和本机安装的 Halcon 版本一致。第三步在 XAML 里放一个 WindowsFormsHost里面嵌 HWindowControl。第四步写一个 CameraManager 类用 Halcon 的 open_framegrabber 打开相机设置回调函数。第五步在回调里把图像 HObject 通过 Dispatcher.BeginInvoke 传给 UI 线程显示。// CameraManager.cs using HalconDotNet; public class CameraManager { private HTuple _acqHandle; private HWindow _hWindow; public void OpenCamera(HWindow hWindow) { _hWindow hWindow; // 打开第一个可用相机参数按实际相机型号调整 HOperatorSet.OpenFramegrabber(GigEVision2, 0, 0, 0, 0, 0, 0, progressive, -1, default, -1, false, default, cam1, 0, -1, out _acqHandle); // 设置回调异步采图 HOperatorSet.SetFramegrabberCallback(_acqHandle, async, new HTuple(), new HTuple(), OnImageGrabbed); } private void OnImageGrabbed(HTuple handle, HTuple context, HTuple userData) { HObject image; HOperatorSet.GrabImageAsync(out image, handle, -1); // 通过事件把图像传出去由 UI 层决定怎么显示 ImageGrabbed?.Invoke(this, new ImageEventArgs(image)); } public event EventHandlerImageEventArgs ImageGrabbed; }这段代码的关键点open_framegrabber 的参数顺序不能错接口名 GigEVision2 对应 GigE 相机如果是 USB3 相机要改成 USB3Vision。回调函数里用 GrabImageAsync 而不是 GrabImage避免阻塞采集线程。图像通过事件传出而不是直接在回调里操作 UI 控件这是 WPF 线程模型的基本要求。参数说明SetFramegrabberCallback 的第二个参数 async 表示异步回调模式如果相机不支持异步要改成同步采图加定时器轮询。实际项目中我一般会把相机参数曝光、增益、触发模式也封装成属性通过 SetFramegrabberParam 动态设置。3. Halcon 算子封装与流程编排把 find_circle 做成可配置工具节点3.1 工具节点的抽象设计输入 HObject输出 ToolResult通用视觉框架的核心价值在于「工具可配置、流程可编排」。每个视觉工具找圆、找边、测量、OCR都实现同一个接口public interface IVisionTool { string ToolName { get; } ToolResult Execute(HObject image, ToolParams parameters); void DisplayResult(HWindow window, ToolResult result); }ToolResult 里至少要有成功标志、耗时、输出数值圆心、半径、角度、输出轮廓用于显示、错误信息。ToolParams 是一个字典或强类型对象保存算子的所有可调参数。这样设计的好处是流程编排引擎不需要知道具体工具在干什么只需要按顺序调用 Execute把上一个工具的输出图像传给下一个工具。3.2 找圆工具的完整实现与参数说明以 find_circle 为例一个可配置的找圆工具需要这些参数ROI 区域圆心大致位置和搜索半径、边缘阈值、边缘极性、亚像素模式、拟合算法。实现代码如下public class FindCircleTool : IVisionTool { public string ToolName FindCircle; public ToolResult Execute(HObject image, ToolParams p) { var result new ToolResult(); var sw Stopwatch.StartNew(); // 1. 生成测量区域这里用圆环 ROI HObject circleRegion; HOperatorSet.GenAnnulus(p.CenterRow, p.CenterCol, p.InnerRadius, p.OuterRadius, out circleRegion); // 2. 提取亚像素边缘 HObject edges; HOperatorSet.EdgesSubPix(image, out edges, canny, p.Alpha, p.Low, p.High); // 3. 在 ROI 内筛选边缘并拟合圆 HObject contour; HOperatorSet.Intersection(edges, circleRegion, out contour); HTuple circleRow, circleCol, radius; HOperatorSet.FitCircleContourXld(contour, algebraic, -1, 2, 0, 3, 2, out circleRow, out circleCol, out radius); result.Success radius.Length 0; result.Values[CenterRow] circleRow; result.Values[CenterCol] circleCol; result.Values[Radius] radius; result.Contour contour; result.ElapsedMs sw.ElapsedMilliseconds; return result; } }逻辑说明GenAnnulus 生成一个圆环区域参数 CenterRow/CenterCol 是圆心的粗略位置InnerRadius/OuterRadius 是圆环的内外半径这两个值决定了搜索范围。EdgesSubPix 用 Canny 算子提取亚像素边缘Alpha 是平滑系数Low/High 是滞后阈值。Intersection 把边缘和 ROI 求交只保留 ROI 内的边缘点。FitCircleContourXld 用代数法拟合圆参数里的 2 表示迭代次数0 和 3 是离群点剔除的阈值。参数怎么调如果圆边缘对比度低把 Alpha 调小0.5~1.0Low/High 调低如果边缘毛刺多把 High 调高或者增大拟合的离群点剔除阈值。实际项目中我一般会先用手动 ROI 跑一遍看边缘提取效果再决定参数。3.3 流程编排引擎顺序、分支与循环流程编排引擎负责把多个工具节点串起来。最简单的实现是一个 List 按顺序执行。但实际项目需要条件分支比如找圆成功才执行测量失败就跳过去报警。这时候可以用一个简单的节点树public class FlowNode { public IVisionTool Tool { get; set; } public FlowNode Next { get; set; } public FlowNode OnSuccess { get; set; } public FlowNode OnFailure { get; set; } public ToolParams Params { get; set; } } public class FlowEngine { public void Run(FlowNode start, HObject image) { var current start; while (current ! null) { var result current.Tool.Execute(image, current.Params); current.Tool.DisplayResult(_displayWindow, result); if (result.Success) current current.OnSuccess ?? current.Next; else current current.OnFailure; } } }这个引擎很简陋但够用。更复杂的场景可以用状态机或者行为树但视觉检测流程通常不会太复杂顺序加条件分支就能覆盖 90% 的需求。3.4 参数持久化JSON 序列化与版本兼容工具参数要能保存和加载否则每次重启软件都要重新调参这是血泪经验。用 System.Text.Json 或 Newtonsoft.Json 把 ToolParams 序列化成 JSON 文件。注意两点一是 HObject 不能直接序列化只存参数不存图像二是参数结构变更时要做好版本兼容比如加一个 Version 字段加载旧版本参数时做迁移。public class ToolParams { public int Version { get; set; } 1; public double CenterRow { get; set; } public double CenterCol { get; set; } public double InnerRadius { get; set; } public double OuterRadius { get; set; } public double Alpha { get; set; } 1.0; public double Low { get; set; } 30; public double High { get; set; } 60; } // 保存 var json JsonSerializer.Serialize(toolParams, new JsonSerializerOptions { WriteIndented true }); File.WriteAllText(params.json, json); // 加载 var loaded JsonSerializer.DeserializeToolParams( File.ReadAllText(params.json)); if (loaded.Version 2) { /* 迁移逻辑 */ }参数说明Alpha 默认 1.0Low/High 默认 30/60 是 Canny 的常用起始值。实际调参时先用默认值跑看边缘图再微调。Version 字段是为了以后加参数时不至于让旧配置文件报错。4. 避坑与排查相机回调、Halcon 内存、WPF 线程这三座大山4.1 相机回调里直接操作 UI 导致界面卡死现象相机一采图界面就无响应鼠标点不动日志也不刷新。原因Halcon 的异步回调是在非 UI 线程上执行的如果在回调里直接调用 HWindowControl 的显示方法或者更新 WPF 控件属性就会跨线程访问 UI 元素WPF 会抛 InvalidOperationException 或者直接死锁。解决回调里只做数据拷贝把 HObject 和结果封装成事件参数通过 Dispatcher.BeginInvoke 抛到 UI 线程再显示。注意 BeginInvoke 是异步的不要用 Invoke否则回调线程会等 UI 线程相机采集频率高的时候会堆积。4.2 Halcon 对象未释放导致内存暴涨现象软件跑几个小时内存从 200MB 涨到 2GB最后 OutOfMemory。原因Halcon 的 HObject 和 HTuple 是非托管资源虽然实现了 IDisposable但很多人忘了 Dispose或者用 using 包了但对象在 using 外还被引用。解决每个 HObject 用完就 Dispose尤其是在循环里。可以用 Halcon 的 SetSystem 参数 garbage_collect 开自动回收但不要完全依赖它。我一般会在工具节点的 Execute 方法里用 try-finally 确保释放中间图像。4.3 HWindowControl 在 WPF 里的空域问题现象用 WPF 的 Canvas 在 HWindowControl 上面画结果框结果框不显示或者闪烁。原因WindowsFormsHost 是空域控件WPF 的渲染层盖不住它。解决所有叠加图形都用 Halcon 的 disp_obj 和 disp_message 直接画在 HWindow 上不要用 WPF 的 Shape。如果一定要用 WPF 控件叠加考虑用 D3DImage 或者把 HWindowControl 换成 Halcon 的 HSmartWindowControl如果版本支持。4.4 标定参数与图像坐标系搞反现象标定后测量值总是差一个符号或者差 90 度。原因Halcon 的图像坐标系是 Row 向下、Column 向右而很多机械臂或运动控制用的是 X 向右、Y 向上。标定矩阵的方向搞反了。解决在标定的时候用 vector_to_hom_mat2d 得到矩阵后先用几个已知点验证一下变换结果确认方向正确再写入参数文件。我一般会做一个「标定验证」按钮点一下显示几个验证点的理论值和实际值。4.5 Halcon license 在发布后失效现象开发机上跑得好好的拷到现场机器上提示 license 错误。原因Halcon 的 license 是绑定网卡 MAC 或加密狗的现场机器没有对应的 license。解决发布前确认目标机器有 license或者用 Halcon 的运行时 license价格低一些但功能受限。如果用的是和谐版注意版本要和 HalconDotNet 的版本严格对应否则会报找不到入口点。5. 进阶技巧用脚本引擎把算子配置热更新不改代码就能调参框架做到上面那一步已经能跑通基本流程了。但实际产线上调参是常态今天光照变了要改阈值明天换了批次要改 ROI。如果每次都要改代码、重新编译、重新部署效率太低。我一般会在框架里加一个轻量脚本引擎把工具参数和流程逻辑用 JSON 或简单 DSL 描述运行时加载。这样现场工程师只需要改配置文件重启软件就能生效。具体做法定义一个 JSON 格式的流程描述文件里面列出每个工具的类型、参数、下一步节点。框架启动时读取这个文件用反射创建对应的 IVisionTool 实例填充参数构建 FlowNode 树。改参数就是改 JSON 里的数值改流程就是调整节点顺序。{ version: 1, nodes: [ { id: find_circle_1, tool: FindCircleTool, params: { centerRow: 512, centerCol: 640, innerRadius: 80, outerRadius: 120, alpha: 0.8, low: 25, high: 50 }, next: measure_1, onFailure: alarm_1 }, { id: measure_1, tool: MeasureDistanceTool, params: { row1: 400, col1: 600, row2: 700, col2: 600 }, next: null, onFailure: alarm_1 } ] }加载逻辑用反射根据 tool 字段的类名从程序集里找到对应的 TypeActivator.CreateInstance 创建实例然后用 JsonSerializer 把 params 反序列化成 ToolParams 对象。这样新增工具只需要写一个新的 IVisionTool 实现不需要改引擎代码。验证方法改完 JSON 后不重启软件加一个「重新加载流程」按钮点一下重新读取文件并重建 FlowNode 树。跑一遍测试图像看结果是否按新参数输出。如果报错检查 JSON 格式和参数名是否匹配。这个技巧的边界JSON 不适合描述复杂逻辑比如循环、嵌套条件。如果流程真的很复杂还是得用代码。但对于 80% 的视觉检测项目顺序加简单分支就够了。我自己的习惯是框架里永远留一个「脚本模式」的开关简单项目用 JSON复杂项目用代码两者可以混用。最后说一个我踩过的坑JSON 里的参数名要和 C# 属性名大小写一致System.Text.Json 默认是区分大小写的。如果现场工程师写错了大小写反序列化会得到默认值而不是报错导致调参调了半天没效果。后来我在加载后加了一个校验检查关键参数是否在合理范围内超出范围就弹窗提示。这个后悔药希望你别再吃一遍。希望帮到你。本文还有配套的精品资源点击获取