简介面向C#开发者和机器视觉入门者的一套C#与HALCON视觉检测项目案例围绕位置设定界面与显示操作演示如何借助HALCON的.NET接口将图像抓取、特征提取、模板匹配、几何测量等能力集成到WPF桌面应用中。项目从相机连接与实时取像到控件布局、参数输入、事件驱动流程、数据绑定、多线程界面刷新和异常调试基本覆盖了视觉检测操作界面的完整开发链路。压缩包共73个文件包含cs源码、bmp图像资源、resx与resources资源配置、xml与dat数据文件、exe和dll可执行及运行库、sln工程与配置文件整体约3.92MB目录结构清晰便于按模块对照研读。已有546人学习下载尤其适合正在构建视觉定位/显示界面、希望上手C#与HALCON联动开发的读者。从界面设计到HALCON算子调用均有源码级参考可帮助理解高级编程语言与专业视觉库在实际项目中的结合方式。1. C# 与 Halcon 的视觉检测项目位置设定界面和显示操作要先于算法落地车间里换产品型号时操作工每天按得最多的不是算法参数页而是位置设定界面。视觉检测上位机项目里算法能不能检出来要跑完整个流程才知道但操作工换产品时拉一拉检测框、对准一下基准点、看一眼图像上叠加的 ROI 和结果这个动作每调一次就要发生一次。标题里的两个词落到工程上就是用 C# 把 Halcon 窗口嵌进上位机给人提供“在图像上示教位置、存配方、实时看结果”的能力。位置设定界面解决的是“换产品怎么快速改”矩形 ROI 拉一拉、基准十字叉移一移、世界坐标自动换算、配方一键保存。显示操作解决的是“改了怎么看得见”图像缩放平移、检测结果叠加、OK/NG 反馈让窗口里的画面和产线现场对得上。两者合在一起是 C# 上位机视觉项目的骨架后面的标定、手眼映射、halcon 测量、缺陷检测全都挂在这套骨架上跑。这篇按做视觉集成最常见的落地路径来写适合正在用 C# winform/wpf 搭上位机、准备把 Halcon 集成进来的开发也适合要设计示教流程的调试工程师。2. 位置设定的数据模型Halcon 像素坐标、世界坐标与配方序列化2.1 Halcon 的 (Row, Col) 坐标系和界面上习惯的 (X, Y) 差在哪接触 Halcon 的 C# 开发几乎都会在同一个地方栽跟头Halcon 图像坐标系里第一个坐标是 Row行从上往下第二个是 Column列从左往右原点在左上角。而界面和机器人领域习惯的是 X 向右、Y 向上的笛卡尔坐标。把 Halcon 返回的 row 当成 Y、col 当成 X方向是反的想恢复成日常习惯还要再把 Y 取负。位置设定界面如果在这个换算上出错后续标定和手眼映射会全部跟着偏。另外要区分“控件坐标”和“图像坐标”。HSmartWindowControl 的鼠标事件给的是控件像素位置一旦图像被缩放或平移过两个坐标系就不是等比例关系。显示操作里任何“鼠标点哪里图像对应哪里”的需求都要先走一次坐标系换算// 把控件上的鼠标位置换算成当前图像上的 (row, col) HOperatorSet.ConvertCoordinates( hSmartWindowControl.HalconWindow, new HTuple(e.Y), new HTuple(e.X), window, out HTuple imgRow, out HTuple imgCol, image); // 状态栏给操作员看的坐标转成笛卡尔习惯 // X 取 colY 取 row注意 Halcon 里 Y 轴向下 string tip $X {imgCol.D:F1}, Y {imgRow.D:F1};这段代码的逻辑ConvertCoordinates 接受窗口坐标from 写 window、to 写 image算子内部会结合当前 ImagePart 完成缩放和平移的反算输入顺序永远先 row 后 col。参数里 e.Y、e.X 是 HMouseEventArgs 的控件坐标window 和 image 是最常用的一组坐标系枚举也可以换成 display 看显示缓冲区的坐标。换算结果和鼠标位置差一截时优先检查 ImagePart 是否还是旧尺寸。2.2 一个“位置”记录应该存哪些字段位置设定界面里的一条记录绝不是一对坐标这么简单。以平面定位加区域检测的常见场景为例一条位置要同时回答三个问题检测目标在哪块区域、基准点在哪、机械手要去哪。因此数据结构按三组职责设计直接对照采集、标定、显示三个阶段的数据流public class VisionPosition { public string Name { get; set; } // 位置名如 Pos_A、吸嘴1 public string RecipeName { get; set; } // 所属配方/产品型号 // 图像坐标Halcon 习惯 row 在前 public double Row { get; set; } public double Column { get; set; } // 世界坐标平面标定后的物理坐标单位 mm public double WorldX { get; set; } public double WorldY { get; set; } public double Angle { get; set; } // 弧度系统内统一用弧度 // ROI 几何矩形用两角点圆用中心半径 public double RoiRow1 { get; set; } public double RoiCol1 { get; set; } public double RoiRow2 { get; set; } public double RoiCol2 { get; set; } public double RoiRadius { get; set; } public bool Enabled { get; set; } true; }字段拆开的理由是图像坐标负责“算法在哪找”世界坐标负责“机器往哪动”ROI 负责“界面上画什么形状”。三者经常联动变化例如产品整体转了 30 度ROI 跟着转但基准点相对治具的世界坐标不变把三类字段放在同一个类里后续做表格绑定、配方切换、显示高亮都会顺手很多。2.2.1 为什么显示层还要一份 Rectangle2显示操作里常用 DispRectangle2 画带角度的框它接收的是中心行、中心列、角度、半高、半宽和 RoiRow1 这种两角点表达不一样。工程上的常见做法是存储一律用两角点示教最直观渲染时用中心点和半高半宽重新生成 Rectangle2 参数。两套表达之间换算很简单但必须在数据边界上统一成一种存储格式避免界面上同时存在“存的是一套、画的是另一套”的情况。2.3 配方文件的序列化方案JSON 为主Halcon 对象单独落盘位置参数就是产品配方的核心。保存格式的选择直接影响产线换型效率下面是三种常见方案的对比方案可读性版本兼容中文支持适用场景JSON好可直接手改好缺字段给默认值好UTF-8推荐主方案winform/wpf 直接解析XML中标签多好好客户或 MES 指定接口Halcon 的 .tup / .mat差全是数值一般差只放标定矩阵、模板句柄推荐组合是配方主体用 JSONHalcon 特有的数据HomMat2D 标定矩阵、测量模板单独导成 .mat 或 .tup 文件配方里只存路径。HRegion、HImage、HMeasure 这类 Halcon 对象不能直接 JSON 序列化边界上要转成几何数值或 HTuple这正是上一节把 VisionPosition 设计成纯数值类的原因。// 配方保存把位置列表整份写成 UTF-8 的 JSON public static void SavePositions(string path, ListVisionPosition list) { var opt new JsonSerializerOptions { WriteIndented true }; string json JsonSerializer.Serialize(list, opt); File.WriteAllText(path, json, Encoding.UTF8); } // 配方加载文件不存在或解析失败都返回空列表 public static ListVisionPosition LoadPositions(string path) { if (!File.Exists(path)) return new ListVisionPosition(); try { string json File.ReadAllText(path, Encoding.UTF8); return JsonSerializer.DeserializeListVisionPosition(json) ?? new ListVisionPosition(); } catch (JsonException) { return new ListVisionPosition(); } }这两段代码的逻辑WriteIndented 让配方文件可以直接交给非技术同事肉眼比对显式传 Encoding.UTF8 避免 Windows 默认代码页把中文位置名读成乱码反序列化失败返回空列表而不是往上抛异常是“界面不能因为一个坏配方就起不来”的防御习惯。参数说明JsonSerializerOptions 来自 System.Text.JsonWriteIndented 控制是否格式化缩进catch JsonException 只接解析错误File.Exists 挡掉文件缺失分支。3. 在 C# 工程里集成 Halcon 窗口从 HSmartWindowControl 到显示操作3.1 控件选型HWindowControl 和 HSmartWindowControl 怎么选Halcon 的 .NET 接口里有两个常用窗口控件。HWindowControl 是老牌的 WinForms 控件缩放、平移、重绘全部要自己接管HSmartWindowControl 是面向交互场景设计的控件内置滚轮缩放、左键平移和自适应显示还提供 HMouseDown、HMouseMove、HMouseWheel 这一整套事件。WPF 工程对应使用 HSmartWindowControlWPF事件模型和 WinForms 版保持一致。能力HWindowControlHSmartWindowControl滚轮缩放手写内置图像平移手写内置鼠标事件有需自换算有坐标换算配套绘图调用Draw* 阻塞式Draw* 阻塞式可配合事件自绘显示自适应手写 SetPartSetFullImagePart 一步到位新项目直接选 HSmartWindowControl只有老项目迁移才需要继续维护 HWindowControl。理由很直接视觉检测调试时放大看缺陷边缘、平移看 ROI 与工件相对位置是高频操作滚轮以鼠标为中心缩放自己写有一定的 ImagePart 换算量不值得重复造。3.2 最小可运行加载图片并用 HSmartWindowControl 显示把 halcondotnet.dll 加到工程引用、工具箱里拖入 HSmartWindowControl 之后加载一张本地图片显示出来的代码只需四行private void btnLoadImage_Click(object sender, EventArgs e) { if (openFileDialog1.ShowDialog() ! DialogResult.OK) return; _currentImage?.Dispose(); _currentImage new HImage(openFileDialog1.FileName); // 读入图像 // 把 ImagePart 设为整幅图窗口按控件尺寸自适应缩放 hSmartWindowControl.SetFullImagePart(_currentImage); hSmartWindowControl.HalconWindow.DispObj(_currentImage); RedrawOverlays(); // 把已有的 ROI、十字线重新叠加上去 }SetFullImagePart 的作用是让窗口一次性看到整幅图像随后滚轮缩放、拖拽平移都以这幅图像为基准DispObj 把 HImage 内部持有的 HObject 画到窗口上。如果是相机取流把这四行里的 new HImage 换成相机 Grab 返回值即可。老版本 Halcon 没有 SetFullImagePart 时等价写法是手动 SetPart(0, 0, height-1, width-1)。3.2.1 ImagePart 是什么ImagePart 是 Halcon 窗口当前可见的图像区域本质是四个边界值 (row1, col1, row2, col2)。缩放和平移改变的就是这个区域显示操作里的坐标换算也以它为基准。HSmartWindowControl 把这块封装掉了但理解 ImagePart 仍然重要凡是“图像上画框、鼠标点击命中、窗口里截图”这三类需求最终都要回到 ImagePart 的数值上。3.3 显示操作里高频出现的设置项颜色、线宽、十字线、文字位置设定界面上除了底图还要画 ROI、中心点、匹配框、OK/NG 文字。这些东西全部走同一套模式先用设置算子定义样式再调用 Disp 系列算子画上去HWindow hWin hSmartWindowControl.HalconWindow; // 画一个矩形 ROI绿色边框、线宽 2、只描边不填充 hWin.SetColor(green); hWin.SetLineWidth(2); hWin.SetDraw(margin); // margin 描边fill 填充 hWin.DispRectangle2(pos.Row, pos.Column, pos.Angle, 60, 40); // 在基准位置画十字线 hWin.SetColor(red); hWin.SetLineWidth(1); hWin.DispCross(pos.Row, pos.Column, 25, pos.Angle);DispRectangle2 的参数顺序是中心行、中心列、角度、半高、半宽角度为 0 时退化为普通矩形DispCross 的第 4 个参数是十字线偏角与位置角度保持一致画出来的十字才跟着产品方向转。这里的 pos 就是第 2 章 VisionPosition 的一条记录。执行顺序上必须先 DispObj 底图、再画叠加内容后画的图形始终盖在图像上方位置设定界面才能保证 ROI 永远清晰可见。中文文字是显示操作里最典型的坑。Halcon 自带的默认字体不包含中文字形直接用 DispText 输出“检测结果: OK”会变成方框。常见做法是用 SetTfont 把字体指到系统已安装的中文字体XLFD 是固定 14 段的字体描述串// 让 DispText 支持中文指定系统中文字体字段用 * 通配 hWin.SetTfont(-*-Microsoft YaHei-Medium-R-Normal--14-*-*-*-*-*-*-*); hWin.DispText(检测结果: OK, window, 15, 15, black, lime, box);提示DispText 的坐标系统参数有两档window 是相对窗口定位缩放时文字不动image 是相对图像定位文字跟随图像移动。位置设定界面的结果文字一般用 window。如果 SetTfont 的 XLFD 串在你们版本上一直报 invalid font最省事的替代方案是Halcon 窗口内只显示 OK、NG、数值这类 ASCII 内容中文标题放到窗体自身的 Label 或状态栏里。很多量产项目的界面就是这么分的。3.4 窗体 Resize 后的重绘顺序HSmartWindowControl 在窗体尺寸变化时会自动调整显示区域但窗口缓冲区的重建会把上次画上去的叠加图形冲掉表现为“缩放窗口后 ROI 不见了”。处理方法是在 SizeChanged 里按固定顺序重画private void hSmartWindowControl_SizeChanged(object sender, EventArgs e) { if (_currentImage null) return; hSmartWindowControl.HalconWindow.DispObj(_currentImage); // 先底图 RedrawOverlays(); // 后叠加 }顺序和 3.3 里说的完全一致。RedrawOverlays 内部遍历位置列表逐个画 ROI这个函数在位置列表增删、选中项切换、检测完成三个时机都要调用是整个显示操作里复用率最高的入口值得单独抽出来维护。4. 位置设定界面的交互实现画 ROI、位置列表联动与测量喂参4.1 画 ROI 的两种实现DrawRectangle1 阻塞式与鼠标事件自绘示教 ROI 是位置设定界面的核心动作。Halcon 提供了 Draw 系列算子DrawRectangle1、DrawCircle、DrawPoint 都能在窗口上交互取数也有基于鼠标事件的自绘方案。两者对比如下方式代码量实时预览与缩放兼容适用场景DrawRectangle1 阻塞式少无窗口自动处理点按钮后拉一个框的简单示教鼠标事件自绘多可做需自己换坐标拖动过程要看测量值/尺寸阻塞式是入门最快的写法鼠标十字光标由 Halcon 窗口自己处理用户拖完矩形松手算子才返回private void btnTeachRoi_Click(object sender, EventArgs e) { HWindow hWin hSmartWindowControl.HalconWindow; HTuple r1, c1, r2, c2; // 在当前显示的图像上拖一个矩形松手后返回两角点 hWin.DrawRectangle1(out r1, out c1, out r2, out c2); var pos _positions[_currentIndex]; pos.RoiRow1 r1.D; pos.RoiCol1 c1.D; pos.RoiRow2 r2.D; pos.RoiCol2 c2.D; RedrawOverlays(); }注意DrawRectangle1 这类 Draw 算子是阻塞调用期间窗体其他控件不可用。不要把它放到采集线程里执行否则窗口停在等待鼠标状态取流直接卡死。缺点是绘制期间窗体其他按钮全部不可用也没法在拖动过程中实时看到测量结果。需要实时反馈的产品用鼠标事件自绘private bool _drawing; private double _sRow, _sCol; // 拖动起点图像坐标 private double _eRow, _eCol; // 拖动终点图像坐标 private void hSmart_HMouseDown(object sender, HMouseEventArgs e) { if (_editMode ! EditMode.DrawRoi) return; _drawing true; // 窗口坐标必须换成图像坐标否则缩放后画歪 ConvertWindowToImage(e.X, e.Y, out _sRow, out _sCol); _eRow _sRow; _eCol _sCol; } private void hSmart_HMouseMove(object sender, HMouseEventArgs e) { if (!_drawing) return; HWindow hWin hSmartWindowControl.HalconWindow; // 第一步用白色粗线把上一次的框“擦掉” hWin.SetColor(white); hWin.SetLineWidth(5); hWin.DispRectangle1(_sRow, _sCol, _eRow, _eCol); // 第二步按最新鼠标位置画红色新框 ConvertWindowToImage(e.X, e.Y, out _eRow, out _eCol); hWin.SetColor(red); hWin.SetLineWidth(2); hWin.DispRectangle1(_sRow, _sCol, _eRow, _eCol); } private void ConvertWindowToImage(int winX, int winY, out double imgRow, out double imgCol) { // Halcon 窗口坐标行 Y列 X HOperatorSet.ConvertCoordinates(hSmartWindowControl.HalconWindow, new HTuple(winY), new HTuple(winX), window, out HTuple ir, out HTuple ic, image); imgRow ir.D; imgCol ic.D; }自绘方案的逻辑是“先擦后画”Halcon 窗口没有 XOR 模式用白色粗线重画一次旧矩形把它盖掉再画新矩形鼠标移动时视觉上就是跟手拖拽。参数说明_editMode 是自定义枚举用来区分当前是窗口平移模式还是画框模式避免和 HSmartWindowControl 自带的左键平移手势冲突进入画框模式时把平移禁止掉退出时恢复这是工程上的常见约定。4.2 位置列表和图像联动选中一条记录就高亮对应框光能画框还不够位置设定界面要有“位置清单”。用 DataGridView 绑定位置列表选中行变化时触发重绘把选中位置的框变成高亮红色其余位置保持绿色private void dgvPositions_SelectionChanged(object sender, EventArgs e) { if (dgvPositions.CurrentRow?.DataBoundItem is not VisionPosition sel) return; RedrawOverlays(sel); } private void RedrawOverlays(VisionPosition highlight null) { HWindow hWin hSmartWindowControl.HalconWindow; if (_currentImage ! null) hWin.DispObj(_currentImage); // 先重画底图 foreach (var p in _positions) { bool isSel (p highlight); hWin.SetColor(isSel ? red : green); // 选中红色高亮 hWin.SetLineWidth(isSel ? 3 : 1); hWin.DispRectangle2(p.Row, p.Column, p.Angle, 60, 40); hWin.DispCross(p.Row, p.Column, 25, p.Angle); } }这段代码的逻辑SelectionChanged 里先从 CurrentRow 的 DataBoundItem 解出位置对象解不出就返回重绘函数每次都先刷底图再遍历全部位置选中项用红色粗线、其他用绿色细线。注意 RedrawOverlays 是 3.4 里说的那个重绘入口这里的 highlight 参数让同一函数同时服务列表联动和检测完成刷新。4.2.1 数据源用 BindingList 而不是 ListDataGridView 的 DataSource 直接绑 List 时新增、删除、修改字段后表格不会自动刷新还要手动 ResetBindings。常见做法是绑 BindingListVisionPosition集合变化会自动通知表格刷新而 VisionPosition 里的属性通知则用 INotifyPropertyChanged 实现。位置设定界面里的“新增一条、改个角度、删一条”这些操作都建立在可感知的集合上。4.3 位置设定之后的下游把坐标喂给测量算子和缺陷检测位置设定不是终点设定好的坐标要喂给 Halcon 的检测算子。最典型的是把位置的角度和范围交给一维测量工具测边缘对的距离这也是 c# 上位机视觉项目里“位置”最有价值的用法// 用位置记录里的中心点和角度创建测量对象 HMeasure mm new HMeasure(pos.Row, pos.Column, pos.Angle, 1.0, 30, all, all); HTuple rowEdge, colEdge, amp, dist; mm.MeasurePos(_currentImage, 1.0, true, all, all, out rowEdge, out colEdge, out amp, out dist); // 在界面上把测量到的边缘点用十字画出来操作员肉眼核对 HWindow hWin hSmartWindowControl.HalconWindow; for (int i 0; i rowEdge.Length; i) { hWin.SetColor(orange); hWin.DispCross(rowEdge.DArr[i], colEdge.DArr[i], 15, pos.Angle); }HMeasure 构造参数依次是中心行、中心列、角度、平滑系数、边缘阈值、边缘选取方式和过渡方向测量矩形沿 pos.Angle 方向张开。MeasurePos 返回的 rowEdge、colEdge 是找到的边缘点amp 是边缘幅度dist 是边缘对距离把边缘点以十字线形式画回图像是显示操作里最直观的验证手段。同理缺陷检测里把 ROI 区域传给 Blob 分析或深度学习分类器之前区域的位置和角度同样来自这里。这套“示教位置 - 存配方 - 启动时载入 - 喂给算子 - 结果显示”的闭环就是位置设定界面的完整职责。5. 循环数据采集下 UI 刷新卡顿排查与 Halcon 窗口内容自检5.1 循环数据采集下 UI 刷新卡顿限流 BeginInvoke 组合相机连续取流时在采集线程里直接调 DispObj 是界面卡顿的最常见原因。Halcon 窗口只能在 UI 线程绘制跨线程调用轻则掉帧、重则报错而每次都 BeginInvoke 不做限流高频取流会把 UI 消息队列塞满表现为鼠标拖不动、数据表格假死。标准做法是采集线程只管取帧UI 刷新单独限流private readonly Stopwatch _uiClock new Stopwatch(); private bool _running; private HImage _latest; private void AcquisitionLoop() { _uiClock.Restart(); while (_running) { _latest _camera.GrabImage(); // 采集线程取帧 // 界面刷新限流40ms 一帧约 25fps if (_uiClock.ElapsedMilliseconds 40) { _uiClock.Restart(); BeginInvoke((Action)(() DisplayFrame(_latest))); } // 检测算法也放这个线程和 UI 隔离 } } private void DisplayFrame(HImage frame) { hSmartWindowControl.HalconWindow.DispObj(frame); RedrawOverlays(); }BeginInvoke 是异步投递采集线程不会因为界面绘制慢而停顿限流让界面刷新频率固定不受采集帧率波动影响。40ms 这个值适合大多数产线节拍需要看高速运动的物体时改为 16ms再快就没有意义了人眼在 25fps 以上基本感知不到提升。还卡就查 RedrawOverlays 是不是每次都在 DispObj 整幅底图这一步是显示开销的大头。5.2 把 Halcon 窗口内容导出 PNG远程定位显示问题现场反馈“界面显示不对”时截图往往比口头描述可靠。Halcon 的 DumpWindowImage 能把窗口当前内容连叠加图形一起导出成图片这个能力在远程调试工位尤其有用// 把 Halcon 窗口当前显示内容含所有叠加导出为 PNG HOperatorSet.DumpWindowImage(out HImage dump, hSmartWindowControl.HalconWindow); dump.WriteImage(png, 0, D:\debug\window_snapshot.png); dump.Dispose();DumpWindowImage 导出的分辨率等于 ImagePart 对应的图像尺寸而不是控件像素尺寸如果导出的图片和现场肉眼看的不一样先确认是不是 ImagePart 与控件尺寸不一致导致。把导出功能绑到快捷键或右键菜单上让操作员就地生成现场画面远程调试能少一半来回确认。最后给一个低成本的自检流程新位置设定界面做完可以照这个顺序验收加载一张带明显角点的测试图新增三个不同角度的位置并逐个画 ROI按第 2 章的格式保存配方重启程序再加载确认所有框的位置、角度、十字线和高亮色都和保存前一致。这个流程同时覆盖了坐标换算、序列化、重绘三条链路视觉项目里最容易出问题的三个环节一次验完。本文还有配套的精品资源点击获取