1. 从一张漏读的现场照片说起第一次在产线上部署二维码识别十个工程师里有八个会经历同一个场景实验室里跑得飞快识别率 100%一上产线就掉到 85%还都是随机漏读——同一张图重新跑一遍有时又能读出来。当时我把问题归结为Halcon 不行后来才发现绝大多数所谓识别不准根子在模型参数和图像质量这两件事上跟算法本身关系不大。Halcon 这套东西有意思的地方在于它把所有视觉能力都封装成了算子Operator——你可以把算子简单理解成一个已经调好内部逻辑的黑盒函数输入图像或者句柄输出结果。threshold是算子find_data_code_2d也是算子连create_data_code_2d_model这种只是创建个句柄的东西也是算子。所有的算子拼起来构成算子链算子链就是你的视觉程序。这跟 OpenCV 那种自己拿函数拼流程的思路不太一样Halcon 更倾向于让你站在已有的算法模块上做组合和调参而不是从数学原理开始推。二维码识别是这条链上使用频率极高的一个场景因为它牵扯到的下游动作特别多扫码定位、字符解析、与 PLC 通讯、跟 MES 对单、写入数据库。它不是一个孤立的图像处理任务而是整条产线数据链的入口。这篇文章我想把单码识别和多码识别这两件事拆开讲透包括create_data_code_2d_model里每个参数到底在控制什么、find_data_code_2d内部大致做了什么、多码场景下三种路线的取舍以及一些我在现场被坑过之后才明白的细节。适合已经能跑通 Demo 但识别率上不去的人也适合刚接触 Halcon 想少走弯路的同行。2. create_data_code_2d_model参数设错后面全白搭2.1 SymbolType 决定了整条识别链的走向create_data_code_2d_model是二维码识别的起点它的原型是create_data_code_2d_model(SymbolType, GenParamName, GenParamValue, DataCodeHandle)第一个参数SymbolType决定了后面所有的内部逻辑。Halcon 支持的常用类型包括QR Code、Micro QR Code、Data Matrix ECC 200、PDF417、Aztec Code以及带 GS1 语义的GS1 DataMatrix、GS1 QR Code等变体。这里最容易踩的坑是把QR Code和Micro QR Code混用。Micro QR 只有 11×11 到 17×17 模块只有一个定位图形而标准 QR 有三个。如果你建了标准 QR 的模型去读 Micro QRHalcon 会一直找不到符合结构的候选区表现就是全图扫了一遍什么都没返回连失败的提示都没有——因为对它来说压根就没有找到候选符号。反过来也一样。所以拿到一个新项目第一件事是确认码制别默认就是 QR。另一个细节是 Data Matrix 的两种 ECC 版本。Data Matrix ECC 200是现在绝大多数工业打标在用的老旧的 ECC 000~140 基本退出市场了但如果遇到老设备Halcon 还有Data Matrix ECC 200之外的兼容类型。实际项目里 99% 的情况用 ECC 200 就够了。2.2 default_parameters 的四个档位与代价GenParamName/GenParamValue这一对是最值钱的地方。最常用的一个参数是default_parameters它有四个可选值我把它整理成了一张表取值内部行为倾向耗时相对适用场景low_recognition只做最少量的候选搜索与采样约 1x图像质量极好、码很大的高速流水线standard_recognition默认档平衡速度与鲁棒性约 1.5x大部分常规项目enhanced_recognition增加候选区域、尝试多种对比度假设约 3x有轻微畸变、脏污、反光maximum_recognition穷举式尝试包含多极性、多尺度8x 以上疑难图、离线复判、抽检这张表的耗时倍数是相对量不是绝对值——具体数值跟你图像大小、码的数量强相关。但我可以负责任地说从standard跳到maximum这个跨度在 500 万像素图像上通常就是 30ms 到 300ms 的差别。产线节拍卡在 100ms 的时候这个跳变是致命的。所以在在线检测场景里我的习惯是先用standard_recognition跑一轮统计识别率如果低于 99.5%优先去改光源和镜头而不是直接上maximum_recognition。后者的收益往往没有你想象中那么大但耗时是实打实的。在离线复判场景里就反过来了。比如质量追溯系统需要重新读取三个月前的历史图片这时候时间不是约束直接上maximum_recognition同时打开多极性能救回来不少现场没读到的数据。2.3 polarity 与 module_size_min/max 的真实影响polarity控制极性假设可选dark_on_light深色码在浅色底上最常用、light_on_dark、any。设成any会让 Halcon 对每个候选区都尝试两种极性耗时大约翻倍。什么时候需要any激光打标在金属上由于材质和角度不同有的码看起来是深底浅码。还有 DPM直接部件标识场景由于打点方式不同对比度方向可能翻转。如果你的现场是黑的碳带打在白的标签上老老实实用dark_on_light别贪图省事设any。module_size_min和module_size_max是另一个被严重低估的参数。它们描述的是二维码中单个最小模块的像素尺寸。假设你的视野是 200mm × 200mm相机分辨率 500 万像素2448 × 2048那么一个像素对应 200/2448 ≈ 0.082mm。如果二维码最小模块的物理尺寸是 0.5mm那对应 6.1 个像素module_size_min就可以设成 5 左右。为什么要设这个因为 Halcon 默认会从很小的模块尺寸开始搜索这在大图上非常浪费。给一个合理的下界能直接砍掉大量无效的候选区搜索。我做过一个测试2000 × 2000 的图模块尺寸约 8 像素把module_size_min从默认值改成 6识别时间从 85ms 降到 42ms识别结果完全一致。module_size_max就相反它用来排除那些看起来像二维码但模块特别大的干扰区域比如某些印刷图案。一般设成实测模块尺寸的 2~3 倍就够。2.4 二维码类型差异模组选择速查不同码制的模型创建参数有差异我列一个对照码制必需/强烈建议的参数说明QR Codedefault_parameters,polarity,module_size_min,versionversion可限定 QR 版本减少搜索空间Micro QR Codedefault_parameters,module_size_min模型不能混用必须单独创建Data Matrix ECC 200default_parameters,polarity,module_size_min,dimension_min/max可用dimension_min限定矩阵尺寸PDF417default_parameters,polarity堆叠式对行高敏感Aztec Codedefault_parameters,polarity同心方块定位中心易受污染version这个参数特别值得说。QR Code 从 Version 121×21到 Version 40177×177跨度很大。如果你明确知道现场只用 Version 3 的码把它固定住Halcon 就不会去尝试其他版本的重采样速度提升明显。但注意固定 version 之后如果现场混入了其他版本的码就会读不出来。所以这是个用通用性换速度的取舍只在码制高度统一的产线上用。同样的问题也出现在 Data Matrix 的dimension_min/dimension_max上。数据矩阵的尺寸从 10×10 到 144×144不限定的话搜索空间同样很大。3. find_data_code_2d从灰度图到字符串之间发生了什么3.1 内部大致流程拆解find_data_code_2d是把模型句柄和图像结合起来的执行算子原型是find_data_code_2d(Image, SymbolXLDs, DataCodeHandle, GenParamName, GenParamValue, ResultHandles, DecodedDataStrings)了解一下它内部大致在做哪几步对调参很有帮助。虽然 Halcon 没有公开源码但从行为和官方文档能推断出这么一个链路第一步是候选区域搜索。Halcon 会在图像里找那些符合二维码结构特征的区域。对 QR 来说就是三个角上的回字形定位图形对 Data Matrix 来说就是 L 型实边加对面虚线边。这一步决定了很多根本找不到码的问题——如果你的静区码周围的空白区域被裁掉了或者码被金属边框压住了一边定位图形不完整这一步就会失败。第二步是透视校正与网格划分。找到定位图形后Halcon 会计算出二维码的四个角点做透视变换把倾斜、畸变的码掰正然后按照版本信息划分模块网格。这一步对镜头畸变大、拍摄角度斜的场景特别敏感。第三步是模块采样与二值判决。每个网格中心取一个灰度值跟动态阈值比较得到 0/1 矩阵。这里 Halcon 用的是局部自适应阈值所以即使整张图光照不均只要在单个码的范围内光照变化平缓通常也能采对。第四步是纠错解码。QR 用的是 Reed-Solomon 纠错Data Matrix 也是基于 RS 的。这一步会把采样得到的比特流做纠错然后按掩模规则反推出原始数据最后按编码模式数字、字母数字、字节、汉字解析成字符串。纠错能力取决于是纠错等级 L/M/Q/H分别是 7%/15%/25%/30% 的码字可以被修正。整个流程里第一步的失败是没法通过后面的手段弥补的。这也是为什么我总强调静区、对比度和定位图形的完整性比什么都重要。3.2 返回值的用法三个输出别浪费三个输出各有用途但很多人只用了最后一个。SymbolXLDs是找到的所有二维码的轮廓每个码对应一条 XLD 轮廓或者一组轮廓。这个值在需要定位的场景里非常关键。比如机械臂要去扫这个码你得知道码的中心在哪个像素坐标、旋转了多少度。做法是先smallest_rectangle2_xld拿到最小外接矩形的中心、角度和半宽半高再通过手眼标定矩阵映射到机器人坐标系。smallest_rectangle2_xld(SymbolXLDs, Row, Col, Phi, Length1, Length2)拿到Row、Col、Phi之后反算四个角点就是标准的三角函数计算。注意Phi的范围是-pi/2到pi/2如果要做姿态对齐得先用smallest_rectangle1_xld的宽高比判断长边方向否则会得到相差 90 度的角度。ResultHandles是一个整数元组每个元素对应一个成功或者失败的候选。这个句柄必须留着因为后面get_data_code_2d_results要用它来取详细信息。很多人find_data_code_2d之后直接clear_data_code_2d_model把模型清了然后再想取结果就取不到了。DecodedDataStrings是解码后的字符串元组顺序跟ResultHandles一一对应。这里有个坑不是每个 ResultHandle 都对应一个成功的字符串。如果某个候选区域找到了但解码失败ResultHandles里会有它但DecodedDataStrings里对应位置是空字符串。顺序对应关系还在但你得自己判断空串。所以遍历的时候不能只看字符串非空还得对齐索引。3.3 get_data_code_2d_results 能挖出哪些质量信息这个算子是二维码识别的体检报告生成器用它可以拿到大量诊断信息。常用的ResultNames有这么几类结果名含义典型用途statusdecode_succeeded/decode_failed等判断单个候选的真实状态module_size模块的像素尺寸行/列各一个反推实际物理尺寸、判断对焦polarity实际识别出的极性验证现场光照方向error_correction_level纠错等级追溯码的生成质量num_corrected_errors被纠正的错误模块数印标质量的量化指标quality_isoiec15415ISO/IEC 15415 印刷质量评分质量报告输出versionQR 版本号验证是否混版mirrored是否为镜像码检测翻面或反光造成的镜像structured_append系列结构化追加信息处理分段的大容量码num_corrected_errors是我最常用的一个。它在二维码印刷质量检测里可以直接当成一个量化指标如果某个码的纠错数量长期在纠错上限的 70% 以上说明这个打标机的状态在漂移要么墨量不足要么焦距偏了提前预警比等它彻底读不出来再修要划算得多。我在一个项目里就是用这个指标做了个趋势图打标机墨盒快耗尽的征兆提前两周就暴露了。quality_isoiec15415这套评分包含多个子项比如符号对比度、调制比、固定图案损伤、轴向不均匀性等。取法是在ResultName里写quality_isoiec15415会返回总分写quality_isoiec15415_offsetX这类具体名字会返回分项。要做正式的检测报告就得取分项别只看总分。4. 多二维码识别的三条路线与取舍4.1 直接全图扫最容易上手也最容易踩坑很多人以为多码识别需要特殊配置其实不是。find_data_code_2d天生就支持多码只要你不在GenParamValue里限制结果数量它会把全图所有能识别的码都返回。但是默认行为有一个性能陷阱Halcon 会尽可能把图里所有疑似区域都过一遍。假如图里有 20 个码同时还存在一些看起来像 QR 定位图形的干扰图案比如某些电路板上的焊盘阵列、包装上的点阵图案那搜索时间会膨胀得很厉害。这时候可以用find_data_code_2d(Image, SymbolXLDs, DataCodeHandle, stop_after_result_num, 20, ResultHandles, DecodedDataStrings)stop_after_result_num表示凑够 20 个结果就停。这个参数在你确切知道图里有几个码的时候特别有用能省掉后续的无效搜索。另一个参数是timeout单位毫秒。设成 200 意味着最多搜 200ms 就返回当前结果。这个在实时系统里是保命参数——宁可漏读也不能卡住主流程。但要清楚超时返回的结果不是最优的只是当前搜到的。生产环境里我一般不会把 timeout 设得太紧除非有上层重试机制。还有一个影响性能的参数是num_scanlines。它控制是否用扫描线方式辅助解码。设成 0 表示不用扫描线只用基于结构的方式设成正值表示额外尝试多少条扫描线。扫描线方式对严重畸变的码有帮助但耗时增加。4.2 ROI 分块法什么时候值得多写这几十行如果你的场景是固定的——比如一个托盘上固定摆 12 个工件每个工件的码位置大致固定——那么ROI 分块识别几乎总是比全图扫描快得多。思路很简单用gen_rectangle1或者gen_circle生成 12 个固定 ROI逐个reduce_domain把子图送进find_data_code_2d。这样每次搜索的图像面积只有原来的 1/12而且假候选区域也被物理隔离了。C# 或者 HDevelop 里循环大致长这样for Index : 0 to NumROI - 1 by 1 gen_rectangle1(Rectangle, R1[Index], C1[Index], R2[Index], C2[Index]) reduce_domain(Image, Rectangle, ImageReduced) find_data_code_2d(ImageReduced, SymbolXLDs, DataCodeHandle, [], [], ResultHandles, DecodedDataStrings) * 注意结果坐标是相对 ROI 的需要加上偏移量转化回全图坐标 endfor这里有个坐标转换的坑必须记住find_data_code_2d返回的SymbolXLDs坐标是相对于reduce_domain之后的子图的虽然reduce_domain保留的是原图坐标系因为它是定义域缩减不是裁剪但实际上很多情况下你会需要手工加上 ROI 偏移。稳妥的做法是不要用crop_domain或者crop_rectangle1直接用reduce_domain这样输出的 XLD 坐标系就是原图的不需要额外变换。这个区别我栽过一次当时用了crop_rectangle1做分块结果所有坐标都偏了花了一下午查。ROI 分块的另一个好处是可以并行。Halcon 支持算子级的并行执行也可以在上位机层面开多线程每个线程处理一个 ROI。12 个码分到 12 个线程理论上总耗时接近单个 ROI 的处理时间。当然实际会受内存带宽和 CPU 核心数限制8 核机器上 12 路并行实测加速比大概 6~7 倍。4.3 候选区域预定位的混合方案第三种路线介于前两者之间先用快速的图像处理手段把码所在的大致区域框出来再针对这些区域做精细识别。预定位的常用手段基于thresholdconnectionselect_shape二维码整体是一个明显的矩形块用灰度阈值分割出所有连通域用面积、矩形度和长宽比筛掉大部分剩下的作为候选框。基于edges_sub_pixsegment_contours_xld提取边缘轮廓找四边形结构。基于定位图形的模板匹配用create_shape_model把 QR 的定位图形做成模板find_shape_model快速定位。这个方案准确度高但需要针对不同码制分别建模板。我用得最多的是第一种因为它不依赖码的种类。大致流程是rgb1_to_gray(Image, GrayImage) threshold(GrayImage, Region, 0, 100) connection(Region, ConnectedRegions) select_shape(ConnectedRegions, Candidates, area, and, 2000, 500000) select_shape(Candidates, Candidates, rectangularity, and, 0.6, 1.0)后面再把每个Candidates用shape_trans变成凸包或者用smallest_rectangle1求外接矩形向外扩 10~20 像素保证静区完整然后逐个送进find_data_code_2d。这套方案的识别时间和码数量基本呈线性而不是全图扫描那种非线性膨胀。缺点是增加了对光照和二值化阈值的依赖——如果光照变化大固定的阈值段就会失效。三种路线的取舍我总结成一句话码位置不固定、图不大用全图扫码位置固定、数量多用 ROI 分块码位置变动但数量多、图很大用预定位混合。5. 图像预处理哪些算子真有用哪些是白忙活5.1 emphasize / scale_image / equ_histo_image 的适用边界关于预处理我的核心观点是find_data_code_2d本身已经包含了相当完善的内部预处理大部分情况下你不需要额外做什么。官方文档里其实也暗示了这一点它接受的是灰度图内部会自己处理对比度。但有几个场景确实需要手工干预。emphasize用于增强局部对比度它的原型是emphasize(Image, ImageEmphasize, MaskWidth, MaskHeight, Factor)。这个算子的原理是把原图减去自身的高斯模糊版本再乘上系数加回去效果是增强高频细节。对二维码这种模块化图案它能强化模块之间的边界。实测在低对比度的 DPM 码上emphasize(Image, ImageEmphasize, 7, 7, 1.5)能把识别率从 70% 拉到 88% 左右。但要注意Factor不能设太大超过 2.5 之后噪声也会被同步放大反而降低识别率。scale_image是灰度线性拉伸scale_image(Image, ImageScaled, Mult, Add)执行的是g g * Mult Add。它不改变灰度分布的形状只是整体线性调整。什么时候用当图像的灰度范围被压缩得很窄比如只有 30~90 这一段时先拉伸到 0~255 再送进去能提升内部自适应阈值的稳定性。这个操作很快代价几乎可以忽略所以我通常会无条件先做一次。equ_histo_image是直方图均衡化它把灰度分布重新映射成近似均匀分布。问题在于它是全局操作——如果图里同时有很亮的反光区和大片暗背景直方图均衡会把整体对比度拉得很奇怪二维码所在的局部反而可能变差。所以我的态度是图上只有二维码、背景单一时可以用图上有其他干扰物体时慎用。5.2 不该做的事别把二值图送进去这是个必须强调的点。find_data_code_2d期望的是灰度图不是二值图。我见过不少人的代码里写着threshold(Image, Region, 100, 255) reduce_domain(Image, Region, ImageReduced) * 错误示范 find_data_code_2d(ImageReduced, ...)或者是先生成 Region 再region_to_bin转成二值图。这么做的问题是你实际上把哪里是深、哪里是浅的信息提前固定死了。当码上有一小块污渍、或者光照不均导致部分模块的灰度掉到阈值以下时二值化会把这些模块错误地判成背景色而 Halcon 内部本来可以靠局部自适应阈值正确采样这些模块。正确做法是裁剪出包含二维码的原图区域保留灰度信息直接送进find_data_code_2d。如果你担心背景干扰用reduce_domain缩小定义域是没问题的但不要改灰度值。5.3 光照不均的照明补偿不均匀光照是二维码识别里最麻烦的一类问题尤其是大视野加环形光或者条形光的场景图上会出现明显的亮区暗区。Halcon 提供了一个专门处理这个问题的算子illuminate。illuminate(Image, ImageIllum, MaskWidth, MaskHeight, Factor)它的原理是先用一个很大的窗口MaskWidth、MaskHeight算局部均值把背景照明估出来然后ImageIllum (Image - Mean) * Factor Mean。选择合适的窗口尺寸是关键——窗口必须远大于二维码模块尺寸但小于整体光照变化的尺度。举个例子假设图里二维码模块约 8 像素整体照明不均的特征尺度是几百像素那MaskWidth MaskHeight 51或者101就比较合适。如果设成 11那相当于只对二维码模块本身做均值会把码的对比度也一起抹掉。用它的时候我一般这样调gauss_filter(Image, ImageGauss, 5) illuminate(Image, ImageIllum, 51, 51, 1.2)先高斯去噪再补偿补偿后整体灰度的动态范围会变化所以往往还需要scale_image再拉一次。但这里要泼一盆冷水照明补偿永远只是补救最根本的解法是改打光。如果在项目设计阶段就发现光照不均加两个低角度条形光、或者换成同轴光比在软件里补偿效果好一个数量级。我做过一个对比同一个工件换同轴光之后识别率从 86% 直接到 99.8%而且处理时间还从 60ms 降到了 25ms——因为不需要那些补偿算子了。6. 完整可跑的两套识别脚本6.1 HDevelop 单码识别脚本下面这段是我常用的模板可以直接在 HDevelop 里跑* 读取图像 read_image(Image, qr_sample.png) get_image_size(Image, Width, Height) * 转灰度如果是彩色图 count_channels(Image, Channels) if (Channels 3) rgb1_to_gray(Image, Image) endif * 灰度拉伸代价极低顺手做一下 min_max_gray(Image, Image, 0, Min, Max, Range) if (Range 200) Mult : 255.0 / (Max - Min) Add : -Min * Mult scale_image(Image, Image, Mult, Add) endif * 创建二维码模型 create_data_code_2d_model(QR Code, default_parameters, standard_recognition, DataCodeHandle) * 设置识别参数 set_data_code_2d_param(DataCodeHandle, polarity, dark_on_light) set_data_code_2d_param(DataCodeHandle, module_size_min, 5) set_data_code_2d_param(DataCodeHandle, module_size_max, 40) * 执行识别 find_data_code_2d(Image, SymbolXLDs, DataCodeHandle, [], [], ResultHandles, DecodedDataStrings) * 遍历结果 Count : |ResultHandles| for i : 0 to Count - 1 by 1 if (DecodedDataStrings[i] ! ) * 取出质量信息 get_data_code_2d_results(DataCodeHandle, ResultHandles[i], module_size, ModuleSize) get_data_code_2d_results(DataCodeHandle, ResultHandles[i], num_corrected_errors, NumErrors) get_data_code_2d_results(DataCodeHandle, ResultHandles[i], quality_isoiec15415, Quality) * 定位信息 select_obj(SymbolXLDs, OneSymbol, i 1) smallest_rectangle2_xld(OneSymbol, Row, Col, Phi, L1, L2) disp_message(WindowHandle, Data: DecodedDataStrings[i], window, 12, 12 i * 24, black, true) endif endfor * 清理 clear_data_code_2d_model(DataCodeHandle)注意select_obj对 XLD 的索引是从 1 开始的而ResultHandles和DecodedDataStrings的 tuple 索引是从 0 开始的。这个不一致非常容易写出越界错误我在代码里一律用i 1明确标注。6.2 多码识别加结果分类输出多码场景下除了拿到数据通常还要按空间位置排序——比如按从左到右、从上到下的顺序对应托盘上的工位编号。XLD 本身不带排序信息得自己排。read_image(Image, multi_qr.png) rgb1_to_gray(Image, GrayImage) create_data_code_2d_model(QR Code, default_parameters, enhanced_recognition, DataCodeHandle) set_data_code_2d_param(DataCodeHandle, polarity, dark_on_light) set_data_code_2d_param(DataCodeHandle, module_size_min, 4) set_data_code_2d_param(DataCodeHandle, module_size_max, 30) * 先用 stop_after_result_num 控制上限 find_data_code_2d(GrayImage, SymbolXLDs, DataCodeHandle, stop_after_result_num, 50, ResultHandles, DecodedDataStrings) * 取每个码的中心坐标 Count : |ResultHandles| Rows : [] Cols : [] ValidIdx : [] for i : 0 to Count - 1 by 1 if (DecodedDataStrings[i] ! ) select_obj(SymbolXLDs, OneSymbol, i 1) smallest_rectangle2_xld(OneSymbol, Row, Col, Phi, L1, L2) Rows : [Rows, Row] Cols : [Cols, Col] ValidIdx : [ValidIdx, i] endif endfor * 按行分组行内按列排序 tuple_sort_index(Rows, OrderByRow) * 后续按 50 像素为一个行带分组组内对 Col 排序 * 这里是简化写法实际项目里建议用 ClusterRows 之类的自定义过程排序这件事我没有写完整因为不同现场的行分组策略千差万别。有的项目要求按行优先有的按列优先有的按环形顺序。核心思路是先按一个轴分组组内再按另一个轴排序分组的容差通常设成行间距的一半比较稳。6.3 C# 上位机调用要点在上位机里用 HalconDotNet 调用最需要注意的是句柄的生命周期。模型句柄HTuple在程序启动时创建一次就够了不要每张图都CreateDataCode2dModel再ClearDataCode2dModel——创建一次模型大约要几毫秒到几十毫秒在 100ms 节拍下这是纯粹的浪费。// 初始化阶段只执行一次 private HTuple _dataCodeHandle; private void InitHalcon() { HOperatorSet.CreateDataCode2dModel(QR Code, new HTuple(), new HTuple(), out _dataCodeHandle); HOperatorSet.SetDataCode2dParam(_dataCodeHandle, polarity, dark_on_light); HOperatorSet.SetDataCode2dParam(_dataCodeHandle, module_size_min, 5); HOperatorSet.SetDataCode2dParam(_dataCodeHandle, module_size_max, 40); } // 每帧调用 private string DecodeOne(HObject image) { HObject symbols; HTuple handles, strings; HOperatorSet.FindDataCode2d(image, out symbols, _dataCodeHandle, new HTuple(), new HTuple(), out handles, out strings); if (strings.Length 0) return null; // 取第一个非空字符串 for (int i 0; i strings.Length; i) { string s strings[i].S; if (!string.IsNullOrEmpty(s)) return s; } return null; } // 程序退出时释放 private void DisposeHalcon() { HOperatorSet.ClearDataCode2dModel(_dataCodeHandle); }这里有个性能细节HOperatorSet.FindDataCode2d的GenParamName/GenParamValue如果每帧都传new HTuple()会有轻微的 GC 压力。在几十毫秒级的节拍里不敏感但如果你的节拍是 5ms 级别建议把空 tuple 提取成静态字段复用。另外C# 里strings[i].S取的是字符串值如果对应的字符串是空串.S返回的就是。但如果ResultHandles里对应的状态是decode_failed有时候DecodedDataStrings的长度会小于ResultHandles的长度。这一点在不同 Halcon 版本里行为不完全一致所以稳妥写法是先比较两个 tuple 的长度取较短的那个作为循环上界。7. 把识别率从 80% 拉到 99% 的现场细节7.1 静区、纠错等级和模块尺寸的硬约束有三条物理层面的红线软件层面无论怎么调都突破不了。第一条是静区。QR 码四周要求至少 4 个模块宽度的空白Data Matrix 要求 1 个模块。如果静区被裁掉或者被其他印刷内容占据定位就会失败。我在一个项目中遇到的情况是标签设计得太紧凑二维码离边框只有 1mm而模块尺寸是 0.4mm静区严重不足识别率只有 60%。后来把标签重新设计留出 3mm 的静区识别率直接到 99.5%模型参数一个字都没改。所以拿到新标签设计稿时第一件事就是量静区。第二条是纠错等级。QR 的四个等级 L/M/Q/H 分别对应 7%/15%/25%/30% 的可纠错码字比例。等级越高码里用于纠错的冗余越多同样数据量下码就越大。产线环境差灰尘、油污、反光的时候我建议用 Q 甚至 H因为码大一点无所谓读不到才是大问题。但如果模块尺寸固定用高纠错等级会让版本号升高模块数变多每模块的像素数就下降这又会降低采样可靠性——这是个需要现场权衡的取舍。第三条是模块像素尺寸的下限。从实践经验看单模块在图像上最好有 5 个像素以上低于 4 个像素时识别率会断崖式下降。这不是 Halcon 的问题是采样定理的限制——采样点太少抗噪能力就没了。所以选相机的时候先用码的模块物理尺寸除以所需的最小像素数算出所需的视野和分辨率反推相机型号而不是先买相机再调软件。7.2 常见失败现象与排查对照表现象大概率原因排查动作全图零结果连候选都没有码制不匹配、静区被裁、极性设错换 SymbolType 试polarity改any目视检查静区找到候选但解码失败模块尺寸过小、对比度不足、局部污损检查module_size结果提高default_parameters档位查污损位置同一张图反复跑结果不稳定模块尺寸卡在临界值、信噪比不足提高分辨率或缩短工作距离让模块达到 8 像素以上只能读一部分码光照不均、部分码被遮挡分区测光照检查遮挡识别时间波动极大干扰图案多、全图搜索改用 ROI 分块设stop_after_result_num设timeout读出来的字符串有乱码编码模式判断错误、多字节字符检查decoded_data_partitioned确认码里写的是 UTF-8 还是 GBK这张表里的每一条我都在现场遇到过。其中最容易被忽略的是最后一条——二维码里存中文时字符串编码本身就是个坑。Halcon 返回的是字节流字节流怎么解释成中文完全取决于写码的时候用的什么编码。如果写码端用了 GBK 而读取端按 UTF-8 解释就会出一堆方块。解决办法是在写码的时候统一用 UTF-8或者读取端按字节数组自己转。7.3 性能调优的三个抓手抓手一限制module_size范围。前面已经说了这是性价比最高的一招前提是你能测准现场实际的模块像素尺寸。测法很简单读出一张成功的图用get_data_code_2d_results取module_size多测几张取平均值然后设成均值的 0.7~1.5 倍范围。抓手二控制default_parameters档位。在线用standard离线复判用maximum。不要为了 1% 的识别率提升让产线节拍从 80ms 变成 400ms。如果确实需要enhanced或maximum考虑把它放到重试机制里——第一次用standard失败的码再用maximum补一次。这样平均耗时只增加一点点整体识别率却接近maximum的水平。抓手三并行化。在 C# 或者 C 里用Parallel.For或者线程池把多个 ROI 的处理并行起来。需要注意 Halcon 的模型句柄在多线程下是只读共享安全的——多个线程可以同时用同一个DataCodeHandle调find_data_code_2dHalcon 内部会处理同步。但set_data_code_2d_param是写操作不能在识别进行中调必须先在初始化阶段设好。8. 几个我实际踩过、文档里不会写的坑第一个坑是clear_data_code_2d_model的时机。早期我习惯每次循环结束就清模型后来发现频繁创建销毁模型会让内存碎片化跑几万次之后程序会变慢甚至崩。正确做法是进程启动创建一次退出时清理一次中间就一直复用。第二个坑是DecodedDataStrings里的空白字符。有些设备生成的二维码会在数据前后带空格或者\r\nHalcon 原样返回不做任何 trim。如果你的下游逻辑是做字符串精确匹配一定要先trim一次。我就因为这个在数据库匹配上排查了两个小时。第三个坑是 XLD 的坐标系。用reduce_domain之后 XLD 坐标仍在原图坐标系用crop_rectangle1或者crop_domain之后坐标系就变成子图的局部坐标了。这两个算子名字很像行为差别很大混用会导致所有定位坐标偏移。我的习惯是二维码定位一律用reduce_domain宁可多传一点数据也不做坐标变换。第四个坑是手眼标定的坐标系一致性。二维码 XLD 返回的坐标是像素坐标要让机械臂去扫码中间要经过像素到相机和相机到机器人两次映射。第一次用的是相机内参第二次是手眼标定矩阵。很多人只做了一次映射就去驱动机械臂结果位置总是偏。标定这件事必须做全套而且要注意标定用的图像分辨率必须和识别用的分辨率一致改分辨率之后要重新标定。最后一个体会是关于small_elements_robustness这个参数。它在某些版本的 Halcon 里对 DPM 码特别有用能提升对打点不均匀的容忍度。但这个参数的取值和具体码制、具体打点工艺强相关没有普适推荐值只能在现场用样本调。我一般会取一批评审不合格的码作为测试集把参数从小往大扫一遍取识别率跳变前的那一档。这个扫描过程大概半小时能省掉后面几天的反复调试。
Halcon二维码识别率优化：单码与多码参数调优实战
1. 从一张漏读的现场照片说起第一次在产线上部署二维码识别十个工程师里有八个会经历同一个场景实验室里跑得飞快识别率 100%一上产线就掉到 85%还都是随机漏读——同一张图重新跑一遍有时又能读出来。当时我把问题归结为Halcon 不行后来才发现绝大多数所谓识别不准根子在模型参数和图像质量这两件事上跟算法本身关系不大。Halcon 这套东西有意思的地方在于它把所有视觉能力都封装成了算子Operator——你可以把算子简单理解成一个已经调好内部逻辑的黑盒函数输入图像或者句柄输出结果。threshold是算子find_data_code_2d也是算子连create_data_code_2d_model这种只是创建个句柄的东西也是算子。所有的算子拼起来构成算子链算子链就是你的视觉程序。这跟 OpenCV 那种自己拿函数拼流程的思路不太一样Halcon 更倾向于让你站在已有的算法模块上做组合和调参而不是从数学原理开始推。二维码识别是这条链上使用频率极高的一个场景因为它牵扯到的下游动作特别多扫码定位、字符解析、与 PLC 通讯、跟 MES 对单、写入数据库。它不是一个孤立的图像处理任务而是整条产线数据链的入口。这篇文章我想把单码识别和多码识别这两件事拆开讲透包括create_data_code_2d_model里每个参数到底在控制什么、find_data_code_2d内部大致做了什么、多码场景下三种路线的取舍以及一些我在现场被坑过之后才明白的细节。适合已经能跑通 Demo 但识别率上不去的人也适合刚接触 Halcon 想少走弯路的同行。2. create_data_code_2d_model参数设错后面全白搭2.1 SymbolType 决定了整条识别链的走向create_data_code_2d_model是二维码识别的起点它的原型是create_data_code_2d_model(SymbolType, GenParamName, GenParamValue, DataCodeHandle)第一个参数SymbolType决定了后面所有的内部逻辑。Halcon 支持的常用类型包括QR Code、Micro QR Code、Data Matrix ECC 200、PDF417、Aztec Code以及带 GS1 语义的GS1 DataMatrix、GS1 QR Code等变体。这里最容易踩的坑是把QR Code和Micro QR Code混用。Micro QR 只有 11×11 到 17×17 模块只有一个定位图形而标准 QR 有三个。如果你建了标准 QR 的模型去读 Micro QRHalcon 会一直找不到符合结构的候选区表现就是全图扫了一遍什么都没返回连失败的提示都没有——因为对它来说压根就没有找到候选符号。反过来也一样。所以拿到一个新项目第一件事是确认码制别默认就是 QR。另一个细节是 Data Matrix 的两种 ECC 版本。Data Matrix ECC 200是现在绝大多数工业打标在用的老旧的 ECC 000~140 基本退出市场了但如果遇到老设备Halcon 还有Data Matrix ECC 200之外的兼容类型。实际项目里 99% 的情况用 ECC 200 就够了。2.2 default_parameters 的四个档位与代价GenParamName/GenParamValue这一对是最值钱的地方。最常用的一个参数是default_parameters它有四个可选值我把它整理成了一张表取值内部行为倾向耗时相对适用场景low_recognition只做最少量的候选搜索与采样约 1x图像质量极好、码很大的高速流水线standard_recognition默认档平衡速度与鲁棒性约 1.5x大部分常规项目enhanced_recognition增加候选区域、尝试多种对比度假设约 3x有轻微畸变、脏污、反光maximum_recognition穷举式尝试包含多极性、多尺度8x 以上疑难图、离线复判、抽检这张表的耗时倍数是相对量不是绝对值——具体数值跟你图像大小、码的数量强相关。但我可以负责任地说从standard跳到maximum这个跨度在 500 万像素图像上通常就是 30ms 到 300ms 的差别。产线节拍卡在 100ms 的时候这个跳变是致命的。所以在在线检测场景里我的习惯是先用standard_recognition跑一轮统计识别率如果低于 99.5%优先去改光源和镜头而不是直接上maximum_recognition。后者的收益往往没有你想象中那么大但耗时是实打实的。在离线复判场景里就反过来了。比如质量追溯系统需要重新读取三个月前的历史图片这时候时间不是约束直接上maximum_recognition同时打开多极性能救回来不少现场没读到的数据。2.3 polarity 与 module_size_min/max 的真实影响polarity控制极性假设可选dark_on_light深色码在浅色底上最常用、light_on_dark、any。设成any会让 Halcon 对每个候选区都尝试两种极性耗时大约翻倍。什么时候需要any激光打标在金属上由于材质和角度不同有的码看起来是深底浅码。还有 DPM直接部件标识场景由于打点方式不同对比度方向可能翻转。如果你的现场是黑的碳带打在白的标签上老老实实用dark_on_light别贪图省事设any。module_size_min和module_size_max是另一个被严重低估的参数。它们描述的是二维码中单个最小模块的像素尺寸。假设你的视野是 200mm × 200mm相机分辨率 500 万像素2448 × 2048那么一个像素对应 200/2448 ≈ 0.082mm。如果二维码最小模块的物理尺寸是 0.5mm那对应 6.1 个像素module_size_min就可以设成 5 左右。为什么要设这个因为 Halcon 默认会从很小的模块尺寸开始搜索这在大图上非常浪费。给一个合理的下界能直接砍掉大量无效的候选区搜索。我做过一个测试2000 × 2000 的图模块尺寸约 8 像素把module_size_min从默认值改成 6识别时间从 85ms 降到 42ms识别结果完全一致。module_size_max就相反它用来排除那些看起来像二维码但模块特别大的干扰区域比如某些印刷图案。一般设成实测模块尺寸的 2~3 倍就够。2.4 二维码类型差异模组选择速查不同码制的模型创建参数有差异我列一个对照码制必需/强烈建议的参数说明QR Codedefault_parameters,polarity,module_size_min,versionversion可限定 QR 版本减少搜索空间Micro QR Codedefault_parameters,module_size_min模型不能混用必须单独创建Data Matrix ECC 200default_parameters,polarity,module_size_min,dimension_min/max可用dimension_min限定矩阵尺寸PDF417default_parameters,polarity堆叠式对行高敏感Aztec Codedefault_parameters,polarity同心方块定位中心易受污染version这个参数特别值得说。QR Code 从 Version 121×21到 Version 40177×177跨度很大。如果你明确知道现场只用 Version 3 的码把它固定住Halcon 就不会去尝试其他版本的重采样速度提升明显。但注意固定 version 之后如果现场混入了其他版本的码就会读不出来。所以这是个用通用性换速度的取舍只在码制高度统一的产线上用。同样的问题也出现在 Data Matrix 的dimension_min/dimension_max上。数据矩阵的尺寸从 10×10 到 144×144不限定的话搜索空间同样很大。3. find_data_code_2d从灰度图到字符串之间发生了什么3.1 内部大致流程拆解find_data_code_2d是把模型句柄和图像结合起来的执行算子原型是find_data_code_2d(Image, SymbolXLDs, DataCodeHandle, GenParamName, GenParamValue, ResultHandles, DecodedDataStrings)了解一下它内部大致在做哪几步对调参很有帮助。虽然 Halcon 没有公开源码但从行为和官方文档能推断出这么一个链路第一步是候选区域搜索。Halcon 会在图像里找那些符合二维码结构特征的区域。对 QR 来说就是三个角上的回字形定位图形对 Data Matrix 来说就是 L 型实边加对面虚线边。这一步决定了很多根本找不到码的问题——如果你的静区码周围的空白区域被裁掉了或者码被金属边框压住了一边定位图形不完整这一步就会失败。第二步是透视校正与网格划分。找到定位图形后Halcon 会计算出二维码的四个角点做透视变换把倾斜、畸变的码掰正然后按照版本信息划分模块网格。这一步对镜头畸变大、拍摄角度斜的场景特别敏感。第三步是模块采样与二值判决。每个网格中心取一个灰度值跟动态阈值比较得到 0/1 矩阵。这里 Halcon 用的是局部自适应阈值所以即使整张图光照不均只要在单个码的范围内光照变化平缓通常也能采对。第四步是纠错解码。QR 用的是 Reed-Solomon 纠错Data Matrix 也是基于 RS 的。这一步会把采样得到的比特流做纠错然后按掩模规则反推出原始数据最后按编码模式数字、字母数字、字节、汉字解析成字符串。纠错能力取决于是纠错等级 L/M/Q/H分别是 7%/15%/25%/30% 的码字可以被修正。整个流程里第一步的失败是没法通过后面的手段弥补的。这也是为什么我总强调静区、对比度和定位图形的完整性比什么都重要。3.2 返回值的用法三个输出别浪费三个输出各有用途但很多人只用了最后一个。SymbolXLDs是找到的所有二维码的轮廓每个码对应一条 XLD 轮廓或者一组轮廓。这个值在需要定位的场景里非常关键。比如机械臂要去扫这个码你得知道码的中心在哪个像素坐标、旋转了多少度。做法是先smallest_rectangle2_xld拿到最小外接矩形的中心、角度和半宽半高再通过手眼标定矩阵映射到机器人坐标系。smallest_rectangle2_xld(SymbolXLDs, Row, Col, Phi, Length1, Length2)拿到Row、Col、Phi之后反算四个角点就是标准的三角函数计算。注意Phi的范围是-pi/2到pi/2如果要做姿态对齐得先用smallest_rectangle1_xld的宽高比判断长边方向否则会得到相差 90 度的角度。ResultHandles是一个整数元组每个元素对应一个成功或者失败的候选。这个句柄必须留着因为后面get_data_code_2d_results要用它来取详细信息。很多人find_data_code_2d之后直接clear_data_code_2d_model把模型清了然后再想取结果就取不到了。DecodedDataStrings是解码后的字符串元组顺序跟ResultHandles一一对应。这里有个坑不是每个 ResultHandle 都对应一个成功的字符串。如果某个候选区域找到了但解码失败ResultHandles里会有它但DecodedDataStrings里对应位置是空字符串。顺序对应关系还在但你得自己判断空串。所以遍历的时候不能只看字符串非空还得对齐索引。3.3 get_data_code_2d_results 能挖出哪些质量信息这个算子是二维码识别的体检报告生成器用它可以拿到大量诊断信息。常用的ResultNames有这么几类结果名含义典型用途statusdecode_succeeded/decode_failed等判断单个候选的真实状态module_size模块的像素尺寸行/列各一个反推实际物理尺寸、判断对焦polarity实际识别出的极性验证现场光照方向error_correction_level纠错等级追溯码的生成质量num_corrected_errors被纠正的错误模块数印标质量的量化指标quality_isoiec15415ISO/IEC 15415 印刷质量评分质量报告输出versionQR 版本号验证是否混版mirrored是否为镜像码检测翻面或反光造成的镜像structured_append系列结构化追加信息处理分段的大容量码num_corrected_errors是我最常用的一个。它在二维码印刷质量检测里可以直接当成一个量化指标如果某个码的纠错数量长期在纠错上限的 70% 以上说明这个打标机的状态在漂移要么墨量不足要么焦距偏了提前预警比等它彻底读不出来再修要划算得多。我在一个项目里就是用这个指标做了个趋势图打标机墨盒快耗尽的征兆提前两周就暴露了。quality_isoiec15415这套评分包含多个子项比如符号对比度、调制比、固定图案损伤、轴向不均匀性等。取法是在ResultName里写quality_isoiec15415会返回总分写quality_isoiec15415_offsetX这类具体名字会返回分项。要做正式的检测报告就得取分项别只看总分。4. 多二维码识别的三条路线与取舍4.1 直接全图扫最容易上手也最容易踩坑很多人以为多码识别需要特殊配置其实不是。find_data_code_2d天生就支持多码只要你不在GenParamValue里限制结果数量它会把全图所有能识别的码都返回。但是默认行为有一个性能陷阱Halcon 会尽可能把图里所有疑似区域都过一遍。假如图里有 20 个码同时还存在一些看起来像 QR 定位图形的干扰图案比如某些电路板上的焊盘阵列、包装上的点阵图案那搜索时间会膨胀得很厉害。这时候可以用find_data_code_2d(Image, SymbolXLDs, DataCodeHandle, stop_after_result_num, 20, ResultHandles, DecodedDataStrings)stop_after_result_num表示凑够 20 个结果就停。这个参数在你确切知道图里有几个码的时候特别有用能省掉后续的无效搜索。另一个参数是timeout单位毫秒。设成 200 意味着最多搜 200ms 就返回当前结果。这个在实时系统里是保命参数——宁可漏读也不能卡住主流程。但要清楚超时返回的结果不是最优的只是当前搜到的。生产环境里我一般不会把 timeout 设得太紧除非有上层重试机制。还有一个影响性能的参数是num_scanlines。它控制是否用扫描线方式辅助解码。设成 0 表示不用扫描线只用基于结构的方式设成正值表示额外尝试多少条扫描线。扫描线方式对严重畸变的码有帮助但耗时增加。4.2 ROI 分块法什么时候值得多写这几十行如果你的场景是固定的——比如一个托盘上固定摆 12 个工件每个工件的码位置大致固定——那么ROI 分块识别几乎总是比全图扫描快得多。思路很简单用gen_rectangle1或者gen_circle生成 12 个固定 ROI逐个reduce_domain把子图送进find_data_code_2d。这样每次搜索的图像面积只有原来的 1/12而且假候选区域也被物理隔离了。C# 或者 HDevelop 里循环大致长这样for Index : 0 to NumROI - 1 by 1 gen_rectangle1(Rectangle, R1[Index], C1[Index], R2[Index], C2[Index]) reduce_domain(Image, Rectangle, ImageReduced) find_data_code_2d(ImageReduced, SymbolXLDs, DataCodeHandle, [], [], ResultHandles, DecodedDataStrings) * 注意结果坐标是相对 ROI 的需要加上偏移量转化回全图坐标 endfor这里有个坐标转换的坑必须记住find_data_code_2d返回的SymbolXLDs坐标是相对于reduce_domain之后的子图的虽然reduce_domain保留的是原图坐标系因为它是定义域缩减不是裁剪但实际上很多情况下你会需要手工加上 ROI 偏移。稳妥的做法是不要用crop_domain或者crop_rectangle1直接用reduce_domain这样输出的 XLD 坐标系就是原图的不需要额外变换。这个区别我栽过一次当时用了crop_rectangle1做分块结果所有坐标都偏了花了一下午查。ROI 分块的另一个好处是可以并行。Halcon 支持算子级的并行执行也可以在上位机层面开多线程每个线程处理一个 ROI。12 个码分到 12 个线程理论上总耗时接近单个 ROI 的处理时间。当然实际会受内存带宽和 CPU 核心数限制8 核机器上 12 路并行实测加速比大概 6~7 倍。4.3 候选区域预定位的混合方案第三种路线介于前两者之间先用快速的图像处理手段把码所在的大致区域框出来再针对这些区域做精细识别。预定位的常用手段基于thresholdconnectionselect_shape二维码整体是一个明显的矩形块用灰度阈值分割出所有连通域用面积、矩形度和长宽比筛掉大部分剩下的作为候选框。基于edges_sub_pixsegment_contours_xld提取边缘轮廓找四边形结构。基于定位图形的模板匹配用create_shape_model把 QR 的定位图形做成模板find_shape_model快速定位。这个方案准确度高但需要针对不同码制分别建模板。我用得最多的是第一种因为它不依赖码的种类。大致流程是rgb1_to_gray(Image, GrayImage) threshold(GrayImage, Region, 0, 100) connection(Region, ConnectedRegions) select_shape(ConnectedRegions, Candidates, area, and, 2000, 500000) select_shape(Candidates, Candidates, rectangularity, and, 0.6, 1.0)后面再把每个Candidates用shape_trans变成凸包或者用smallest_rectangle1求外接矩形向外扩 10~20 像素保证静区完整然后逐个送进find_data_code_2d。这套方案的识别时间和码数量基本呈线性而不是全图扫描那种非线性膨胀。缺点是增加了对光照和二值化阈值的依赖——如果光照变化大固定的阈值段就会失效。三种路线的取舍我总结成一句话码位置不固定、图不大用全图扫码位置固定、数量多用 ROI 分块码位置变动但数量多、图很大用预定位混合。5. 图像预处理哪些算子真有用哪些是白忙活5.1 emphasize / scale_image / equ_histo_image 的适用边界关于预处理我的核心观点是find_data_code_2d本身已经包含了相当完善的内部预处理大部分情况下你不需要额外做什么。官方文档里其实也暗示了这一点它接受的是灰度图内部会自己处理对比度。但有几个场景确实需要手工干预。emphasize用于增强局部对比度它的原型是emphasize(Image, ImageEmphasize, MaskWidth, MaskHeight, Factor)。这个算子的原理是把原图减去自身的高斯模糊版本再乘上系数加回去效果是增强高频细节。对二维码这种模块化图案它能强化模块之间的边界。实测在低对比度的 DPM 码上emphasize(Image, ImageEmphasize, 7, 7, 1.5)能把识别率从 70% 拉到 88% 左右。但要注意Factor不能设太大超过 2.5 之后噪声也会被同步放大反而降低识别率。scale_image是灰度线性拉伸scale_image(Image, ImageScaled, Mult, Add)执行的是g g * Mult Add。它不改变灰度分布的形状只是整体线性调整。什么时候用当图像的灰度范围被压缩得很窄比如只有 30~90 这一段时先拉伸到 0~255 再送进去能提升内部自适应阈值的稳定性。这个操作很快代价几乎可以忽略所以我通常会无条件先做一次。equ_histo_image是直方图均衡化它把灰度分布重新映射成近似均匀分布。问题在于它是全局操作——如果图里同时有很亮的反光区和大片暗背景直方图均衡会把整体对比度拉得很奇怪二维码所在的局部反而可能变差。所以我的态度是图上只有二维码、背景单一时可以用图上有其他干扰物体时慎用。5.2 不该做的事别把二值图送进去这是个必须强调的点。find_data_code_2d期望的是灰度图不是二值图。我见过不少人的代码里写着threshold(Image, Region, 100, 255) reduce_domain(Image, Region, ImageReduced) * 错误示范 find_data_code_2d(ImageReduced, ...)或者是先生成 Region 再region_to_bin转成二值图。这么做的问题是你实际上把哪里是深、哪里是浅的信息提前固定死了。当码上有一小块污渍、或者光照不均导致部分模块的灰度掉到阈值以下时二值化会把这些模块错误地判成背景色而 Halcon 内部本来可以靠局部自适应阈值正确采样这些模块。正确做法是裁剪出包含二维码的原图区域保留灰度信息直接送进find_data_code_2d。如果你担心背景干扰用reduce_domain缩小定义域是没问题的但不要改灰度值。5.3 光照不均的照明补偿不均匀光照是二维码识别里最麻烦的一类问题尤其是大视野加环形光或者条形光的场景图上会出现明显的亮区暗区。Halcon 提供了一个专门处理这个问题的算子illuminate。illuminate(Image, ImageIllum, MaskWidth, MaskHeight, Factor)它的原理是先用一个很大的窗口MaskWidth、MaskHeight算局部均值把背景照明估出来然后ImageIllum (Image - Mean) * Factor Mean。选择合适的窗口尺寸是关键——窗口必须远大于二维码模块尺寸但小于整体光照变化的尺度。举个例子假设图里二维码模块约 8 像素整体照明不均的特征尺度是几百像素那MaskWidth MaskHeight 51或者101就比较合适。如果设成 11那相当于只对二维码模块本身做均值会把码的对比度也一起抹掉。用它的时候我一般这样调gauss_filter(Image, ImageGauss, 5) illuminate(Image, ImageIllum, 51, 51, 1.2)先高斯去噪再补偿补偿后整体灰度的动态范围会变化所以往往还需要scale_image再拉一次。但这里要泼一盆冷水照明补偿永远只是补救最根本的解法是改打光。如果在项目设计阶段就发现光照不均加两个低角度条形光、或者换成同轴光比在软件里补偿效果好一个数量级。我做过一个对比同一个工件换同轴光之后识别率从 86% 直接到 99.8%而且处理时间还从 60ms 降到了 25ms——因为不需要那些补偿算子了。6. 完整可跑的两套识别脚本6.1 HDevelop 单码识别脚本下面这段是我常用的模板可以直接在 HDevelop 里跑* 读取图像 read_image(Image, qr_sample.png) get_image_size(Image, Width, Height) * 转灰度如果是彩色图 count_channels(Image, Channels) if (Channels 3) rgb1_to_gray(Image, Image) endif * 灰度拉伸代价极低顺手做一下 min_max_gray(Image, Image, 0, Min, Max, Range) if (Range 200) Mult : 255.0 / (Max - Min) Add : -Min * Mult scale_image(Image, Image, Mult, Add) endif * 创建二维码模型 create_data_code_2d_model(QR Code, default_parameters, standard_recognition, DataCodeHandle) * 设置识别参数 set_data_code_2d_param(DataCodeHandle, polarity, dark_on_light) set_data_code_2d_param(DataCodeHandle, module_size_min, 5) set_data_code_2d_param(DataCodeHandle, module_size_max, 40) * 执行识别 find_data_code_2d(Image, SymbolXLDs, DataCodeHandle, [], [], ResultHandles, DecodedDataStrings) * 遍历结果 Count : |ResultHandles| for i : 0 to Count - 1 by 1 if (DecodedDataStrings[i] ! ) * 取出质量信息 get_data_code_2d_results(DataCodeHandle, ResultHandles[i], module_size, ModuleSize) get_data_code_2d_results(DataCodeHandle, ResultHandles[i], num_corrected_errors, NumErrors) get_data_code_2d_results(DataCodeHandle, ResultHandles[i], quality_isoiec15415, Quality) * 定位信息 select_obj(SymbolXLDs, OneSymbol, i 1) smallest_rectangle2_xld(OneSymbol, Row, Col, Phi, L1, L2) disp_message(WindowHandle, Data: DecodedDataStrings[i], window, 12, 12 i * 24, black, true) endif endfor * 清理 clear_data_code_2d_model(DataCodeHandle)注意select_obj对 XLD 的索引是从 1 开始的而ResultHandles和DecodedDataStrings的 tuple 索引是从 0 开始的。这个不一致非常容易写出越界错误我在代码里一律用i 1明确标注。6.2 多码识别加结果分类输出多码场景下除了拿到数据通常还要按空间位置排序——比如按从左到右、从上到下的顺序对应托盘上的工位编号。XLD 本身不带排序信息得自己排。read_image(Image, multi_qr.png) rgb1_to_gray(Image, GrayImage) create_data_code_2d_model(QR Code, default_parameters, enhanced_recognition, DataCodeHandle) set_data_code_2d_param(DataCodeHandle, polarity, dark_on_light) set_data_code_2d_param(DataCodeHandle, module_size_min, 4) set_data_code_2d_param(DataCodeHandle, module_size_max, 30) * 先用 stop_after_result_num 控制上限 find_data_code_2d(GrayImage, SymbolXLDs, DataCodeHandle, stop_after_result_num, 50, ResultHandles, DecodedDataStrings) * 取每个码的中心坐标 Count : |ResultHandles| Rows : [] Cols : [] ValidIdx : [] for i : 0 to Count - 1 by 1 if (DecodedDataStrings[i] ! ) select_obj(SymbolXLDs, OneSymbol, i 1) smallest_rectangle2_xld(OneSymbol, Row, Col, Phi, L1, L2) Rows : [Rows, Row] Cols : [Cols, Col] ValidIdx : [ValidIdx, i] endif endfor * 按行分组行内按列排序 tuple_sort_index(Rows, OrderByRow) * 后续按 50 像素为一个行带分组组内对 Col 排序 * 这里是简化写法实际项目里建议用 ClusterRows 之类的自定义过程排序这件事我没有写完整因为不同现场的行分组策略千差万别。有的项目要求按行优先有的按列优先有的按环形顺序。核心思路是先按一个轴分组组内再按另一个轴排序分组的容差通常设成行间距的一半比较稳。6.3 C# 上位机调用要点在上位机里用 HalconDotNet 调用最需要注意的是句柄的生命周期。模型句柄HTuple在程序启动时创建一次就够了不要每张图都CreateDataCode2dModel再ClearDataCode2dModel——创建一次模型大约要几毫秒到几十毫秒在 100ms 节拍下这是纯粹的浪费。// 初始化阶段只执行一次 private HTuple _dataCodeHandle; private void InitHalcon() { HOperatorSet.CreateDataCode2dModel(QR Code, new HTuple(), new HTuple(), out _dataCodeHandle); HOperatorSet.SetDataCode2dParam(_dataCodeHandle, polarity, dark_on_light); HOperatorSet.SetDataCode2dParam(_dataCodeHandle, module_size_min, 5); HOperatorSet.SetDataCode2dParam(_dataCodeHandle, module_size_max, 40); } // 每帧调用 private string DecodeOne(HObject image) { HObject symbols; HTuple handles, strings; HOperatorSet.FindDataCode2d(image, out symbols, _dataCodeHandle, new HTuple(), new HTuple(), out handles, out strings); if (strings.Length 0) return null; // 取第一个非空字符串 for (int i 0; i strings.Length; i) { string s strings[i].S; if (!string.IsNullOrEmpty(s)) return s; } return null; } // 程序退出时释放 private void DisposeHalcon() { HOperatorSet.ClearDataCode2dModel(_dataCodeHandle); }这里有个性能细节HOperatorSet.FindDataCode2d的GenParamName/GenParamValue如果每帧都传new HTuple()会有轻微的 GC 压力。在几十毫秒级的节拍里不敏感但如果你的节拍是 5ms 级别建议把空 tuple 提取成静态字段复用。另外C# 里strings[i].S取的是字符串值如果对应的字符串是空串.S返回的就是。但如果ResultHandles里对应的状态是decode_failed有时候DecodedDataStrings的长度会小于ResultHandles的长度。这一点在不同 Halcon 版本里行为不完全一致所以稳妥写法是先比较两个 tuple 的长度取较短的那个作为循环上界。7. 把识别率从 80% 拉到 99% 的现场细节7.1 静区、纠错等级和模块尺寸的硬约束有三条物理层面的红线软件层面无论怎么调都突破不了。第一条是静区。QR 码四周要求至少 4 个模块宽度的空白Data Matrix 要求 1 个模块。如果静区被裁掉或者被其他印刷内容占据定位就会失败。我在一个项目中遇到的情况是标签设计得太紧凑二维码离边框只有 1mm而模块尺寸是 0.4mm静区严重不足识别率只有 60%。后来把标签重新设计留出 3mm 的静区识别率直接到 99.5%模型参数一个字都没改。所以拿到新标签设计稿时第一件事就是量静区。第二条是纠错等级。QR 的四个等级 L/M/Q/H 分别对应 7%/15%/25%/30% 的可纠错码字比例。等级越高码里用于纠错的冗余越多同样数据量下码就越大。产线环境差灰尘、油污、反光的时候我建议用 Q 甚至 H因为码大一点无所谓读不到才是大问题。但如果模块尺寸固定用高纠错等级会让版本号升高模块数变多每模块的像素数就下降这又会降低采样可靠性——这是个需要现场权衡的取舍。第三条是模块像素尺寸的下限。从实践经验看单模块在图像上最好有 5 个像素以上低于 4 个像素时识别率会断崖式下降。这不是 Halcon 的问题是采样定理的限制——采样点太少抗噪能力就没了。所以选相机的时候先用码的模块物理尺寸除以所需的最小像素数算出所需的视野和分辨率反推相机型号而不是先买相机再调软件。7.2 常见失败现象与排查对照表现象大概率原因排查动作全图零结果连候选都没有码制不匹配、静区被裁、极性设错换 SymbolType 试polarity改any目视检查静区找到候选但解码失败模块尺寸过小、对比度不足、局部污损检查module_size结果提高default_parameters档位查污损位置同一张图反复跑结果不稳定模块尺寸卡在临界值、信噪比不足提高分辨率或缩短工作距离让模块达到 8 像素以上只能读一部分码光照不均、部分码被遮挡分区测光照检查遮挡识别时间波动极大干扰图案多、全图搜索改用 ROI 分块设stop_after_result_num设timeout读出来的字符串有乱码编码模式判断错误、多字节字符检查decoded_data_partitioned确认码里写的是 UTF-8 还是 GBK这张表里的每一条我都在现场遇到过。其中最容易被忽略的是最后一条——二维码里存中文时字符串编码本身就是个坑。Halcon 返回的是字节流字节流怎么解释成中文完全取决于写码的时候用的什么编码。如果写码端用了 GBK 而读取端按 UTF-8 解释就会出一堆方块。解决办法是在写码的时候统一用 UTF-8或者读取端按字节数组自己转。7.3 性能调优的三个抓手抓手一限制module_size范围。前面已经说了这是性价比最高的一招前提是你能测准现场实际的模块像素尺寸。测法很简单读出一张成功的图用get_data_code_2d_results取module_size多测几张取平均值然后设成均值的 0.7~1.5 倍范围。抓手二控制default_parameters档位。在线用standard离线复判用maximum。不要为了 1% 的识别率提升让产线节拍从 80ms 变成 400ms。如果确实需要enhanced或maximum考虑把它放到重试机制里——第一次用standard失败的码再用maximum补一次。这样平均耗时只增加一点点整体识别率却接近maximum的水平。抓手三并行化。在 C# 或者 C 里用Parallel.For或者线程池把多个 ROI 的处理并行起来。需要注意 Halcon 的模型句柄在多线程下是只读共享安全的——多个线程可以同时用同一个DataCodeHandle调find_data_code_2dHalcon 内部会处理同步。但set_data_code_2d_param是写操作不能在识别进行中调必须先在初始化阶段设好。8. 几个我实际踩过、文档里不会写的坑第一个坑是clear_data_code_2d_model的时机。早期我习惯每次循环结束就清模型后来发现频繁创建销毁模型会让内存碎片化跑几万次之后程序会变慢甚至崩。正确做法是进程启动创建一次退出时清理一次中间就一直复用。第二个坑是DecodedDataStrings里的空白字符。有些设备生成的二维码会在数据前后带空格或者\r\nHalcon 原样返回不做任何 trim。如果你的下游逻辑是做字符串精确匹配一定要先trim一次。我就因为这个在数据库匹配上排查了两个小时。第三个坑是 XLD 的坐标系。用reduce_domain之后 XLD 坐标仍在原图坐标系用crop_rectangle1或者crop_domain之后坐标系就变成子图的局部坐标了。这两个算子名字很像行为差别很大混用会导致所有定位坐标偏移。我的习惯是二维码定位一律用reduce_domain宁可多传一点数据也不做坐标变换。第四个坑是手眼标定的坐标系一致性。二维码 XLD 返回的坐标是像素坐标要让机械臂去扫码中间要经过像素到相机和相机到机器人两次映射。第一次用的是相机内参第二次是手眼标定矩阵。很多人只做了一次映射就去驱动机械臂结果位置总是偏。标定这件事必须做全套而且要注意标定用的图像分辨率必须和识别用的分辨率一致改分辨率之后要重新标定。最后一个体会是关于small_elements_robustness这个参数。它在某些版本的 Halcon 里对 DPM 码特别有用能提升对打点不均匀的容忍度。但这个参数的取值和具体码制、具体打点工艺强相关没有普适推荐值只能在现场用样本调。我一般会取一批评审不合格的码作为测试集把参数从小往大扫一遍取识别率跳变前的那一档。这个扫描过程大概半小时能省掉后面几天的反复调试。
