摘要：在工业视觉项目中，算法验证（Python）与生产交付（C#/Halcon）的技术栈异构，常常导致识别结果不一致、不可见字符乱码等问题。本文详细复盘了如何构建一套跨语言、行为完全一致的 Barcode条码识别方案，涵盖 Halcon、OpenCV-Python 及 C# OpenCvSharp、以及博主自研视觉通用框架实现。本文复盘了一套通用型 Barcode 识别方案，支持 Code 128、EAN-13、Code 39 等主流码制，重点解决了多语言环境下参数配置统一、不可见字符转义、跨平台 UI 交互三大难题。

---

一、问题的提出：为什么“能识别”不等于“可用”？

很多工程师认为条码识别“调个库就行”，但在多语言异构交付中，常遇到以下问题：

1、码制参数不一致

Halcon叫 Code128，ZXing 叫BarcodeFormat.CODE_128。如何让 Python 和 C# 共用同一套配置？

2、控制字符黑洞

通用条码（如 LOGMARS、Code 39）常包含 \t、\n、GS等控制字符，直接输出会导致 C# 端解析协议崩溃。

3、交互逻辑断层

Halcon 的 stop()调试模式在 OpenCV 中难以复现。

为此，我们确立了通用化架构的三大原则：

• 配置解耦：支持动态传入码制列表，而非硬编码。

• 数据归一化:所有 ASCII < 32 的字符统一转义为 \xNN

• 行为对齐：窗口、绘制、按键逻辑在三端完全一致。

二、问题的提出：为什么“能识别”不等于“可用”？

Halcon 作为基准，关键在于不指定单一码制，而是建立通用的模型处理能力。

1.Halcon实现通用代码与执行过程，博主这里选取一维码案例Code128来进行实现

* 功能：识别 Code 128 类型的一维条码
* 
* ===================== 1. 创建条码识别模型 =====================
* 创建通用条码识别模型，参数为空（使用默认设置），返回模型句柄 BarCodeHandle
create_bar_code_model ([], [], BarCodeHandle)
* ===================== 2. 窗口初始化与显示设置 =====================
* 关闭当前图形窗口
dev_close_window ()
* 打开 600x600 的黑色窗口，获取窗口句柄
dev_open_window (0, 0, 600, 600, 'black', WindowHandle)
* 设置窗口显示字体：16号、等宽、粗体
set_display_font (WindowHandle, 16, 'mono', 'true', 'false')
* 设置绘制模式：轮廓模式（不填充）
dev_set_draw ('margin')
* 设置绘制颜色：绿色
dev_set_color ('green')
* 设置绘制线宽：3
dev_set_line_width (3)
* ===================== 3. 循环识别 3 张 Code 128 条码图像 =====================
for I := 1 to 3 by 1
    * 读取当前条码图像：code128/code12801.png ~ code12803.png
    read_image (Image, 'barcode/code128/code128' + (I$'.2'))
    * 自适应调整窗口大小，匹配图像尺寸
    dev_resize_window_fit_image (Image, 0, 0, -1, -1)

    * ===================== 核心：识别 Code 128 条码 =====================
    * 在图像中查找并识别 Code 128 条码
    * 输入：Image(图像)、BarCodeHandle(模型)、'Code 128'(指定码型)
    * 输出：SymbolRegions(条码区域轮廓)、DecodedDataStrings(解码字符串)
    find_bar_code (Image, SymbolRegions, BarCodeHandle, 'Code 128', DecodedDataStrings)

    * 获取条码识别的参考结果（可选，用于验证）
    get_bar_code_result (BarCodeHandle, 0, 'decoded_reference', Reference)

    * ===================== 4. 解码字符串后处理（转义不可打印字符） =====================
    String := ''
    * 遍历解码字符串的每个字符
    for J := 0 to strlen(DecodedDataStrings) - 1 by 1
        * 如果字符的 ASCII 码 < 32（不可打印控制字符）
        if (ord(DecodedDataStrings{J}) < 32)
            * 格式化为 \x 开头的十六进制转义序列（如 \x00）
            Char := '\\x' + ord(DecodedDataStrings{J})$'02x'
        else
            * 可打印字符直接保留
            Char := DecodedDataStrings{J}
        endif
        * 拼接处理后的字符
        String := String + Char
    endfor

    * ===================== 5. 结果可视化 =====================
    * 显示原始图像
    dev_display (Image)
    * 显示条码区域轮廓（绿色）
    dev_display (SymbolRegions)
    * 在窗口左上角显示处理后的解码字符串
    disp_message (WindowHandle, String, 'window', 12, 12, 'black', 'true')

    * 非最后一张图像，显示“按 F5 继续”提示并暂停
    if (I < 3)
        disp_continue_message (WindowHandle, 'black', 'true')
        stop ()
    endif
endfor

2.Halcon 关键算子

算子	功能	工业价值
create_bar_code_model	创建条码识别模型（支持 Code 128、EAN-13、QR 等）	通用模型，适配绝大多数一维码
find_bar_code	查找并识别指定类型的条码，输出区域和解码字符串	核心识别算子，自动处理条码定位、解码
get_bar_code_result	获取识别结果的详细信息（参考值、置信度、码型等）	用于验证识别结果、质量评估

3.标准识别的流程

1)模型创建：create_bar_code_model 初始化识别器（默认参数即可覆盖 90% 场景）；

2)图像循环：批量读取条码图像

3)核心识别：find_bar_code 指定码型（如 'Code 128'），自动定位 + 解码；

4)结果后处理：转义不可打印字符、格式化解码字符串；

5)可视化验证：标注条码区域、显示解码结果。

4.识别的效果展示

三、Python + pyzbar+OpenCV实现相同的功能

OpenCV 本身的条码识别依赖 opencv-contrib 模块，pyzbar 是更轻量、易用的 Python 条码识别库，完美支持 Code 128。

1. 环境准备

pip install opencv-python pyzbar numpy

pip install opencv-python

2. python端实现，Python 端通过列表传参实现通用码制支持，这是连接算法与交付的关键。

import cv2
import numpy as np
from pyzbar import pyzbar
from pyzbar.pyzbar import ZBarSymbol
def handle_control_chars(decoded_bytes):
    """
    与Halcon逻辑完全一致：处理不可打印字符（ASCII<32），转为十六进制
    """
    result_str = ""
    for byte in decoded_bytes:
        if byte < 32:
            # 转义控制字符：\x + 两位十六进制
            result_str += f"\\x{byte:02x}"
        else:
            # 可打印字符直接显示
            result_str += chr(byte)
    return result_str
def detect_code128():
    # 窗口设置
    WINDOW_NAME = "Code 128 条码识别"
    cv2.namedWindow(WINDOW_NAME, cv2.WINDOW_NORMAL)
    cv2.resizeWindow(WINDOW_NAME, 600, 600)
    # 循环读取3张测试图像（对应Halcon的code12801~03）
    for index in range(1, 4):
        # ===================== 1. 读取图像 =====================
        # 请根据你的实际图像路径修改！
        img_path = f"barcode/code128/code128{index:02d}.png"
        img = cv2.imread(img_path)
        if img is None:
            print(f"错误：无法读取图像 {img_path}")
            continue
        # ===================== 2. 条码识别 =====================
        # 仅识别Code128，提升精度
        barcodes = pyzbar.decode(img, symbols=[ZBarSymbol.CODE128])
        # ===================== 3. 绘制结果 =====================
        for barcode in barcodes:
            # 1. 提取条码位置 + 解码数据
            (x, y, w, h) = barcode.rect
            data = barcode.data
            # 处理不可打印字符
            final_result = handle_control_chars(data)
            # 2. 绘制绿色条码框（线宽3，和Halcon一致）
            cv2.rectangle(img, (x, y), (x + w, y + h), (0, 255, 0), 3)
            # 3. 在图像上显示解码结果（左上角，白色文字+黑色背景）
            cv2.putText(img, f"Result: {final_result}", (12, 40),
                        cv2.FONT_HERSHEY_SIMPLEX, 1.2, (0, 0, 0), 4)  # 黑色描边
            cv2.putText(img, f"Result: {final_result}", (12, 40),
                        cv2.FONT_HERSHEY_SIMPLEX, 1.2, (255, 255, 255), 2)  # 白色文字
        # ===================== 4. 显示图像窗口 =====================
        cv2.imshow(WINDOW_NAME, img)
        # ===================== 5. 按键切换图像 =====================
        if index < 3:
            print("按任意键查看下一张条码...")
            cv2.waitKey(0)  # 等待按键
        else:
            print("全部识别完成！按任意键退出")
            cv2.waitKey(0)
    # 释放窗口
    cv2.destroyAllWindows()
if __name__ == "__main__":
    detect_code128()

代码核心特性（完全匹配 Halcon）

1、窗口显示结果，

解码文字直接绘制在图像窗口左上角，绿色矩形框标注条码位置（线宽 3），和 Halcon 视觉效果一致。

2、字符处理逻辑

完全复刻 Halcon 代码：

※可打印字符直接显示

※ASCII＜32 的控制字符转为 \x00 格式十六进制

3、交互逻辑

※自动循环 3 张图像

※按任意键切换下一张

※最后一张按任意键退出

4、精准识别

识别Code 128码，杜绝误识别，速度快、精度高。

3.识别的效果展示

四、C#+OpenCvSharp + ZXing 的工业级交付

C# 端最大的挑战是 ZXing 的多码制配置 和 OpenCV 窗口稳定性。

1.环境准备

Uninstall-Package OpenCvSharp4.Windows
Uninstall-Package OpenCvSharp4
Install-Package OpenCvSharp -Version 2.4.10.20150624
Install-Package ZXing.Net

2、C#端实现

using System;
using System.Text;
using System.Drawing;
using OpenCvSharp;
// 强制指定Point，彻底解决命名冲突
using Point = OpenCvSharp.Point;
using ZXing;
namespace Code128_Detector_Net472
{
    class Program
    {
        // 固定窗口名称
        private const string WindowName = "Code128 条码识别";
        // 控制台程序STA线程模式，修复OpenCV窗口崩溃
        [STAThread]
        static void Main(string[] args)
        {
            try
            {
                // 循环读取3张测试图 code12801~code12803
                for (int i = 1; i <= 3; i++)
                {
                    // ===================== 修改为你的本地图像路径 =====================
                    string imgPath = $"barcode/code128/code128{i:D2}.png";
                    IplImage mat = Cv.LoadImage(imgPath, LoadMode.Color);
                    // 图像判空
                    if (mat == null)
                    {
                        Console.WriteLine($"无法读取图像：{imgPath}");
                        continue;
                    }
                    // 1. 核心：ZXing解码Code128
                    Result decodeResult = DecodeCode128(mat);
                    // 2. 处理不可打印字符（完全复刻Halcon逻辑）
                    string finalResult = HandleUnprintableChars(decodeResult?.Text ?? "未识别到条码");
                    // 3. 绘制结果：绿色框 + 文本
                    DrawResult(mat, decodeResult, finalResult);
                    // 4. 直接显示图像（修复NULL window报错，最简模式）
                    Cv.ShowImage(WindowName, mat);
                    // 5. 按键切换图像（对标Halcon stop()）
                    if (i < 3)
                    {
                        Console.WriteLine("按任意键查看下一张...");
                        Cv.WaitKey(0);
                    }
                    else
                    {
                        Console.WriteLine("识别完成！按任意键退出");
                        Cv.WaitKey(0);
                    }
                    // 释放图像资源
                    mat.Release();
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("错误：" + ex.Message);
                Cv.WaitKey(0);
            }
            finally
            {
                // 销毁所有窗口
                Cv.DestroyAllWindows();
            }
        }
        /// <summary>
        /// 解码Code128条码（适配.NET4.7.2）
        /// </summary>
        private static Result DecodeCode128(IplImage image)
        {
            try
            {
                // 配置ZXing仅识别Code128
                var reader = new BarcodeReader
                {
                    Options = new ZXing.Common.DecodingOptions
                    {
                        PossibleFormats = new[] { BarcodeFormat.CODE_128 },
                        TryHarder = true
                    }
                };
                // OpenCvSharp 转 Bitmap
                using Bitmap bitmap = OpenCvSharp.Extensions.BitmapConverter.ToBitmap(image);
                return reader.Decode(bitmap);
            }
            catch
            {
                return null;
            }
        }
        /// <summary>
        /// 处理不可打印字符（ASCII<32转\x00，和Halcon一致）
        /// </summary>
        private static string HandleUnprintableChars(string input)
        {
            if (string.IsNullOrEmpty(input))
                return "未识别到条码";
            StringBuilder sb = new StringBuilder();
            foreach (char c in input)
            {
                byte asciiCode = (byte)c;
                if (asciiCode < 32)
                {
                    sb.Append($"\\x{asciiCode:X2}");
                }
                else
                {
                    sb.Append(c);
                }
            }
            return sb.ToString();
        }
        /// <summary>
        /// 绘制文本 + 绿色条码框
        /// </summary>
        private static void DrawResult(IplImage mat, Result result, string text)
        {
            // 绘制文本（左上角显示）
            Cv.PutText(mat, $"Result: {text}", new Point(12, 40),
                FontFace.HersheySimplex, 1.2, new CvScalar(0, 0, 0), 4);
            Cv.PutText(mat, $"Result: {text}", new Point(12, 40),
                FontFace.HersheySimplex, 1.2, new CvScalar(255, 255, 255), 2);
            // 绘制绿色条码框（线宽3，对标Halcon）
            if (result != null && result.ResultPoints != null)
            {
                Point[] pts = new Point[result.ResultPoints.Length];
                for (int j = 0; j < result.ResultPoints.Length; j++)
                {
                    pts[j] = new Point((int)result.ResultPoints[j].X, (int)result.ResultPoints[j].Y);
                }
                Cv.PolyLine(mat, new[] { pts }, true, new CvScalar(0, 255, 0), 3);
            }
        }
    }
}

3、1:1 还原 Halcon 功能

✅ 识别 Code128 条码

✅ 窗口实时显示解码结果

✅ 绿色框标注条码（线宽 3）

✅ 不可打印字符转义 \x00

✅ 按任意键切换图像

4.识别的效果展示

4、技术总结与选型

维度	Halcon	python(pyzbar)	C#(ZXing)
通用性	⭐⭐⭐⭐⭐ (原生支持泛型)	⭐⭐⭐⭐ (需手动映射)	⭐⭐⭐⭐ (需枚举配置)
工程重点	模型参数调优	动态传参与字节流处理	环境稳定性与枚举对齐
适用场景	高精度产线	算法验证、快速迭代	上位机、MES 对接

五、自研视觉通用框架的工业级交付（基于WPF+HALCON）

从最初用 Python/OpenCV 验证算法，到用 C# OpenCV//ZXing 实现功能，再到如今用 WPF + Halcon 搭建通用视觉框架，这是一个典型的工业视觉工程师的成长路径。

1.总结与行业价值

⭐框架开发的的核心价值在于将零散的代码变成可复用的软件资产。

⭐统一团队开发规范，新人入职一周即可上手开发项目。

⭐降本增效：将项目交付周期从 1 个月压缩至 1 周（仅需配置参数）。