简介OpenCV 的 Barcode 模块对 Code128 类型支持不足这套 VS2015 x64 项目正好补足条码解码与生成两端。代码基于 C 实现共 27 个文件以 8 个 h 头文件与 6 个 cpp 源文件为核心配合 VS 工程文件、测试图片、运行日志和说明文档模块边界清楚既有可直接运行的工程也便于剥离算法逻辑进行二次集成。压缩包仅 1.67MB非常轻量。已有 769 人学习下载。通过源码可以梳理条码图像预处理、码型编码与解码的完整流程借助自带测试图可快速验证效果对于需要落地 Code128 识别或生成功能的 OpenCV 开发者是兼具参考价值与实用性的实例。1. 项目概述与整体思路1.1 这个项目在解决什么问题做图像处理和自动化相关的项目条码识别基本是绕不开的坎。我这次要搞定的是Code128 条码。市面上讲 OpenCV 的教程不少但大多停留在人脸识别、边缘检测这种 demo 层面真正落到条码识别和生成这种具体业务场景资料就稀碎了很多。Code128 是目前工业物流、医疗设备、零售标签里用得最普遍的条码格式特点是占用空间小、信息密度高能编码数字、大写字母、小写字母甚至 ASCII 控制符。相比之下EAN-13 只能编数字Code39 长度太长、密度太低实际项目中扫到 Code128 的概率远高于其他格式。我选择OpenCV来完成这套识别和生成流程核心原因有三一是 OpenCV 在图像预处理上足够成熟灰度化、二值化、形态学操作都有现成接口二是跨平台特性好C 和 Python 都能跑部署到工控机或者树莓派都方便三是完全不依赖第三方云服务条码数据不出本地这对很多生产环境来说是硬性要求。这篇内容适合谁一是需要在嵌入式或桌面端做条码识别的开发者二是想弄懂条形码底层编码原理而不是只会调 zbar 接口的同学三是被网上各种复制粘贴就能跑的代码坑过、想搞清楚背后原理的人。1.2 方案选型为什么不用现成的 zbar/zxing这里可能有人要问识别条码而已用 zbar 或者 zxing 一行代码就解决了何必自己用 OpenCV 从底层搞这个问题我在项目评审时也被问过。先说结论zbar、zxing 这类库在有稳定调试环境、标准印刷品条码的情况下表现很好几乎是无脑调用。但实际项目里经常遇到非理想情况比如条码在强反光材质上、拍摄角度倾斜、条码被部分遮挡或者条码本身印得模糊。这种时候 zbar 经常会直接返回空结果甚至连错误信息都没有根本没法定位问题。而用 OpenCV 自己做识别虽然代码量上去了但每一步都可控。预处理参数可以针对特定产线环境调优解码失败时能可视化看到是哪一步出了问题——是二值化把条码断裂了还是边缘检测把静区干扰了。这种可调试性在生产项目里非常值钱。当然务实的选择是两套方案结合OpenCV 负责图像增强和条码区域定位zbar 负责最终解码。但在本文里我会把 OpenCV 独立完成定位解码的完整链路讲清楚这样你既能理解条码识别的本质也能在关键时刻不依赖任何第三方库。2. Code128 编码原理看懂条码的加密协议2.1 条码不是简单的黑白条纹我第一次接触条码时以为它就是把二进制数字直接画成黑白条。直到自己动手编解码才发现条码内部有完整的协议栈。Code128 的完整结构包括五部分静区、起始符、数据符、校验符、终止符。静区是条码两侧的空白区域作用是让扫描设备能识别到条码从哪里开始。按规范静区宽度至少是 10 个模块宽度。模块是条码的最小宽度单位所有条和空的宽度都是模块宽度的整数倍。起始符有三种分别对应三种字符集Code A适合大写字母和数字Code B适合大小写混合文本Code C适合纯数字把两位数字合成一个符号密度最高。数据符就是我们真正要编码的内容每个符号由 3 条 3 空组成总共 11 个模块。校验符是对整个条码做加权求和对 103 取模得到的终止符则是固定的 13 位模式。这就像网络协议里的报文结构一样有包头、有数据、有校验、有结束标记。弄懂这个结构后面的识别和生成就都有章可循了。2.2 校验位的计算逻辑校验位的计算很多人容易搞错。规则是起始符本身对应一个值Code A 起始符值是 103Code B 是 104Code C 是 105数据符号按其在数据流中的位置加权位置从 1 开始计数。计算公式是校验值 (起始符的值 每个数据符号值 × 位置序号) mod 103。举个例子用 Code B 编码 Hi符号值分别是 H40i73这里用 ASCII 码减去 32 得出 Code128 符号值。校验值 (104 40×1 73×2) % 103 (104 40 146) % 103 290 % 103 84。所以完整的编码序列就是Start B104→ H40→ i73→ 校验符84→ 终止符。校验位算错是生成侧最典型的错误生成的条码用扫码枪扫描时会直接报错。所以无论用哪个库生成条码做自校验时都建议把这条逻辑单独写个单测。2.3 三种字符集的切换策略三种字符集不是随机选的选错了条码长度会差很多。编码纯数字时用Code C两个数字合成一个符号长度直接减半在标签宽度受限的场景下特别有用。混合大小写文本时用Code B需要切大写时也可以临时换成 Code A 配合 Shift 符使用。3. 条码生成用 OpenCV 从零渲染 Code1283.1 生成流程总览条码生成的本质就是把目标字符串按 Code128 规则编码成位串然后把位串渲染成图像。用 OpenCV 做渲染而不直接生成矢量图好处是方便控制图像分辨率、添加背景干扰、合成测试样本——这些在自动化测试里极其有用。完整流程分五步根据字符串内容选择最优字符集将字符映射为符号值并计算校验位把符号值翻译成 11 位二进制模式拼装完整位串起始符数据校验终止符用 OpenCV 按模块宽度绘制黑白条3.2 Python 实现示例import cv2 import numpy as np # Code B 字符集映射ASCII码减32即为符号值 def char_to_value(ch: str) - int: return ord(ch) - 32 # Code128 符号模式表部分示例完整表需从标准获取 CODE128_PATTERNS { 0: [1, 1, 0, 0, 0, 0, 1, 1, 0, 0, 1], 1: [1, 1, 0, 0, 0, 1, 1, 0, 0, 0, 1], 2: [1, 1, 0, 0, 0, 1, 1, 0, 1, 0, 0], # ... 此处省略后续映射 104: [1, 1, 0, 1, 0, 0, 0, 0, 1, 0, 0], # Start B 105: [1, 1, 0, 1, 0, 0, 0, 1, 0, 0, 0], # Start C } def generate_code128(data: str, module_width2, height80): # 1. 选择字符集这里简化用Code B values [104] # Start B values.extend(char_to_value(ch) for ch in data) # 2. 计算校验位 checksum values[0] for i, v in enumerate(values[1:], start1): checksum i * v values.append(checksum % 103) values.append(106) # Stop 符号值 # 3. 拼接位串 bits [] for v in values: bits.extend(CODE128_PATTERNS[v]) bits.extend([1, 1, 0, 0, 0, 1, 1, 0, 1, 0, 1, 1, 1]) # 终止符13位 # 4. 渲染图像留静区 quiet_zone 10 * module_width total_width quiet_zone * 2 len(bits) * module_width img np.zeros((height, total_width), dtypenp.uint8) x quiet_zone for bit in bits: if bit 1: img[:height, x:x module_width] 255 x module_width return img img generate_code128(Hello123) cv2.imwrite(code128_demo.png, img)注意上面的映射表我故意只写了部分实际使用时需要补全完整的 Code128 符号模式表。手动录 107 项太容易出错建议去下载标准编码表导出 CSV 再读取。3.3 C 实现与绘制细节C 端用 OpenCV 的 Mat 类实现类似核心绘制用cv::rectangle或cv::fillPoly都行。关键参数是模块宽度module_width和高度。模块宽度建议至少 2 像素太细了打印出来容易糊。高度一般取 40~100 像素太矮扫描枪角度稍有偏差就识别不了。cv::Mat generateCode128(const std::string data, int moduleWidth, int height) { // 编码逻辑与Python版一致 std::vectorint values {104}; // Start B for (char ch : data) { values.push_back((int)ch - 32); } int checksum values[0]; for (size_t i 1; i values.size(); i) { checksum i * values[i]; } values.push_back(checksum % 103); values.push_back(106); // Stop // 拼接位串需完整的模式表 std::vectorint bits; for (int v : values) { auto it patterns.find(v); bits.insert(bits.end(), it-second.begin(), it-second.end()); } std::vectorint stopBits {1,1,0,0,0,1,1,0,1,0,1,1,1}; bits.insert(bits.end(), stopBits.begin(), stopBits.end()); // 渲染 int quietZone 10 * moduleWidth; int width quietZone * 2 (int)bits.size() * moduleWidth; cv::Mat img cv::Mat::zeros(height, width, CV_8UC1); int x quietZone; for (int bit : bits) { if (bit 1) { cv::rectangle(img, cv::Point(x, 0), cv::Point(x moduleWidth - 1, height), cv::Scalar(255), cv::FILLED); } x moduleWidth; } return img; }另外两条细节要特别提醒第一静区必须留够。很多同学生成的条码扫码枪不识别排查半天发现是静区不够把条码两侧贴得太满。静区不是装饰是协议的一部分好比写文章标题要留页边距扫描设备需要靠静区来区分图像边缘和条码起点。第二绘制时用纯黑纯白不要用灰色或者做抗锯齿。条码识别对边缘的锐度要求很高抗锯齿虽然看着更美观但会让二值化后的边界位置偏移反过来害了识别率。记住条码是给机器看的不是给人看的。4. 条码识别从图像到字符串的逆过程4.1 图像预处理识别比生成复杂得多。现实场景中的条码图像存在各种干扰光照不均、透视畸变、印刷噪点、背景纹理。所以我用 OpenCV 搭建的识别管线分四步走。第一步是灰度化。OpenCV 的cvtColor一行搞定但要注意如果原图是 PNG 带透明通道或者 CMYK 空间需要先转换到标准 BGR 空间再做灰度化否则会得到错误的明暗关系。第二步是二值化。优先用 Otsu 自适应阈值因为它不需要手工设定阈值对光照不均的抗性明显好于固定阈值。代码是cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY | cv2.THRESH_OTSU)。但如果条码印在玻璃或者薄膜上会有明显反光Otsu 也会失灵这时候需要用形态学闭运算先填补断裂的条。第三步是条码区域定位。Code128 条码最显著的特征是条纹密集、梯度变化强烈。我在实际项目里一般先算水平方向的梯度幅值再用形态学闭运算把梯度响应连成连通区域最后按轮廓的宽高比过滤出条码候选区。宽高比小于 3:1 的基本可以直接排除因为正常条码的长宽比通常在 5:1 以上。第四步是透视矫正。如果拍摄角度不垂直于条码平面条码会变形。用findContours找到条码四边形的四个角点后通过getPerspectiveTransformwarpPerspective矫正成矩形。这一步能显著提高倾斜拍摄条件下的识别率。4.2 逐列扫描提取宽度序列条码区域矫正完成后核心解码问题变成了如何从图像中提取条码的宽度序列。我采用的思路是在条码高度方向的中间位置取一行像素取多行求平均更稳然后从左到右扫描像素值的变化点。每遇到一次黑白跳变就记下当前色带的宽度用像素数表示。这一步得到的就是条码的宽度序列。比如说得到序列[2, 1, 3, 1, 1, 2, ...]这些数字分别代表第一个条宽两个模块、第一个空宽一个模块以此类推。问题在于像素宽度不直接等于模块数因为图像可能被缩放或者打印分辨率不同。所以要做归一化。归一化的做法是找到所有色带宽度中的最大公约数GCD或者统计宽度值的众数作为单位模块宽度然后把每个实际宽度除以单位宽度并四舍五入。这一步是整个识别流程里最容易出错的环节如果条码边缘有毛刺或者图像有轻微模糊宽度值就会漂移四舍五入后可能整体偏移一个模块。4.3 符号匹配与解码归一化得到模块序列后按每 11 个模块切分成一个符号。Code128 的符号结构是 3 条 3 空所以遍历序列时从起始符开始切 11 位转换成(条宽序列:空宽序列)的结构再到 Code128 符号表里反查对应的字符值。解码流程定位起始符判断字符集类型A/B/C依次切分后续 11 位符号反查符号值遇到校验符时用之前保存的符号值重新计算校验值进行比对遇到终止符停止解码输出字符串需要注意的是字符串可能包含不同字符集间的切换符。比如 Code B 编码中间切到 Code A序列里会出现 SHIFT98、Code A101、Code B100等控制符号。解码时遇到这些符号要即时切换映射表否则后面的字符全会解错这个细节很多人第一次实现时会踩。4.4 识别核心代码示例def decode_code128_from_image(img_path): # 1. 读取与预处理 img cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) _, binary cv2.threshold(img, 0, 255, cv2.THRESH_BINARY | cv2.THRESH_OTSU) # 2. 定位条码区域 contours, _ cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) # 按面积过滤取最大候选区域 x, y, w, h cv2.boundingRect(max(contours, keycv2.contourArea)) roi binary[y:yh, x:xw] # 3. 提取宽度序列 row roi[h // 2, :] # 取中间一行 widths [] count 1 for i in range(1, len(row)): if row[i] row[i-1]: count 1 else: widths.append(count) count 1 widths.append(count) # 4. 归一化用集合中最小宽度作为单位不做缩放时 module_unit min(widths) modules [round(w / module_unit) for w in widths] # 5. 匹配起始符并解码实际需要完整模式表 # ... 按上述解码流程逐符号匹配这个示例里的min(widths)做单位估算只适合无缩放的场景更稳的方式还是统计众数或者对宽度序列做聚类因为条码中最细的色带如果因为模糊而缺失最小宽度就会变成两倍模块宽整个归一化就全错了。5. 常见问题与排查技巧实录5.1 生成的条码扫码枪不识别这是我被问得最多的问题没有之一。发生这种情况按以下顺序排查现象排查方向解决方案扫码枪完全没反应静区不够两侧至少加 10 个模块宽度扫到了但读出乱码校验位计算错误自查符号值对应关系部分设备能扫部分不行模块宽度太小模块宽度提到 2px 以上扫描距离近才能读白条对比度不足确保纯黑纯白、无灰阶还有一个坑是很多人把人类可读文本也画进了条码区域。虽然文本本身不影响识别逻辑但如果文本的像素侵入了条码的扫描行就会干扰宽度序列。规范做法是把人类可读文本放在条码下方至少 10 像素的位置。5.2 识别率不稳定识别率问题往往出在二值化上。我自己踩过的坑是直接用固定阈值 127结果在不同光照条件下识别率剧烈波动。改用 Otsu 之后稳定很多但遇到条码上有胶带反光时仍然会失败。后来我在二值化前先对灰度图做高斯模糊5×5 核平滑掉噪点识别率又提升了一截。如果条码是直接打印在瓦楞纸箱上的纸箱本身的纹理也会严重干扰二值化。这时可以尝试先用 top-hat 形态学操作提取亮条纹结构再做二值化。这个方法对纹理背景特别有效操作是cv2.morphologyEx(gray, cv2.MORPH_TOPHAT, kernel)核的大小用条码最小模块宽度的 3 倍左右。5.3 OpenCV 环境配置问题文章开头热词里有个非常典型的报错ModuleNotFoundError: No module named opencv。官方包的导入名其实不叫opencv而是cv2。你如果装了但导入失败先确认安装的是opencv-python而不是opencv这个包。conda 环境下 pip 安装容易混装建议在虚拟环境里安装pip install opencv-python python -c import cv2; print(cv2.__version__)C 环境下的坑主要是库路径和运行时 DLL 问题。Windows 里用 Visual Studio 配置 OpenCV 时除了在附加包含目录填错路径之外最容易漏的是把opencv_worldXXXX.dll复制到可执行文件目录或者把包含 opencv 的bin目录加到系统 PATH。运行时报找不到 dll 的99% 是这一步没做。VS 里的具体配置顺序项目属性 → VC 目录 → 包含目录填...\opencv\build\include库目录填...\opencv\build\x64\vc15\lib链接器 → 输入 → 附加依赖项填opencv_world470.lib具体版本号按你装的来然后确认运行平台是 x64 而不是 x86。这三处缺一不可缺了不是编译报错就是运行报错。6. 后记一些实战经验最后分享几个我在实际项目中沉淀下来的小经验。条码生成侧建议把编码表独立成数据文件不要硬编码在业务代码里。Code128 的符号模式表一共 107 项手动录入容易抄错可以找标准编码表导出 CSV或者直接引用开源库的数据结构。相比手抄这种方式能避免很多低级错误。条码识别侧如果要部署到产线建议在现场采集至少 100 张真实样本做回归测试。自己生成的测试图太干净不能反映真实的脏污、反光、畸变情况。我在项目里封装了一个简单的测试脚本把每张图的识别结果和预期值做比对输出失败样本的预处理中间图排查效率高很多。如果识别速度是硬指标可以把整张图的扫描改成分层采样先从 1/4 分辨率图粗定位条码区域再在原图上精确解码。这样在 1920×1080 的图上能把处理时间从 120ms 压到 40ms 左右基本满足实时流水线的要求。Code128 这块内容看起来简单真正做一遍生成再解码对图像处理的理解会加深不少。特别是宽度归一化这里理论上一句话的事实操里发丝偏差就能让结果完全错掉。按本文的流程走一遍踩过的坑基本都有对应的解法。如果你在实现过程中遇到别的奇怪问题欢迎把现象和预处理中间图整理好我们一起分析。本文还有配套的精品资源点击获取