CvSharp.Barcode 1.2.9

dotnet add package CvSharp.Barcode --version 1.2.9
                    
NuGet\Install-Package CvSharp.Barcode -Version 1.2.9
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CvSharp.Barcode" Version="1.2.9" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CvSharp.Barcode" Version="1.2.9" />
                    
Directory.Packages.props
<PackageReference Include="CvSharp.Barcode" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add CvSharp.Barcode --version 1.2.9
                    
#r "nuget: CvSharp.Barcode, 1.2.9"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package CvSharp.Barcode@1.2.9
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=CvSharp.Barcode&version=1.2.9
                    
Install as a Cake Addin
#tool nuget:?package=CvSharp.Barcode&version=1.2.9
                    
Install as a Cake Tool

CvSharp.Barcode

.NET 平台上识别率全面超越 ZXing-C++ 的条码识别库。

移植 ZXing-C++ 全部码制解码核心,换掉它已显老态的图像前端,换上 CvSharp 现代视觉算子, 再加三项 ZXing-C++ 根本没有的能力。在 MVTec HALCON 工业标准测试图集上实测: ZXing-C++ 能解的我们全解,ZXing-C++ 解不出的 32 张我们解出,反向差距为零。

硬数据:与 ZXing-C++ 逐项对比

测试集:MVTec HALCON-10.0 标准工业条码图集 + 自生成退化样本集(旋转/噪声/模糊/低对比度/透视/反色), 同一批图、同一台机器、双侧均开最大努力模式。

测试集 双方一致 仅 CvSharp.Barcode 解出 仅 ZXing-C++ 解出
一维码(9 种码制全集) 48 13 0
GS1 DataBar 全族(8 目录 28 张) 17 7 0
DataMatrix ECC200(78 张) 19 5 0
PDF417(HALCON 26 张) 5 7 0
QR 合成退化集 命中 100% — ZXing 95%
PDF417 合成集(37 张) 37/37 双方全中 — —
Aztec 合成集(29 张) 28/29 — ZXing 26/29(2 张为其绑定层转义差异)

全部码制,没有一张图是 ZXing-C++ 能解而我们解不出的。

三项 ZXing-C++ 没有的能力

1. 任意角度旋转一维码 ZXing-C++ 只能扫水平和垂直方向的一维码,斜置 30° 就瞎。 CvSharp.Barcode 沿 ±15°~±75° 任意角度做双线性扫掠采样,斜着、歪着、贴在曲面上的码照解。

2. 维纳反卷积去模糊重试 离焦、运动模糊导致全部码制识别失败时,自动对图像做维纳反卷积增强后重试。 HALCON ecc200_to_preprocess、ean13_to_preprocess 这批双方全败的样本,就是这样被救回来的。 这是现代反卷积算法对 ZXing 时代预处理思路的代差碾压。

3. 单门面全码制 + 多角度多策略流水线 一个 BarcodeReader 通吃 16 种码制,直方图双峰取谷行扫描、分块黑点估计二值化(HybridThreshold)、 灰度重采样回退、反色重试、斜扫重试、去模糊重试按最优顺序自动接力。 你只需要 Decode(img),剩下的它自己想办法。

支持的码制

类别 码制
二维码 QR Code、DataMatrix (ECC200)、PDF417、Aztec(含 Rune)
一维码 EAN-13、EAN-8、UPC-A、UPC-E、Code 39、Code 93、Code 128、Codabar、ITF
GS1 DataBar DataBar(含 Truncated / Stacked / Omnidirectional)、DataBar Expanded(含 Stacked)、DataBar Limited

GS1 系码制(DataBar 全族与带 FNC1 的一维码)文本中的 FNC1 分隔符以原始 GS 字符(\x1D)输出, 不做 (AI) 括号转义,方便直接进你自己的 GS1 解析器。堆叠/全向变体统一归并到对应主码制, 四点位置信息照常给出。

30 秒上手

using CvSharp;
using CvSharp.Barcode;

using Mat img = Cv.ImRead("barcode.png", ImreadMode.Grayscale);

var reader = new BarcodeReader();
BarcodeResult? r = reader.Decode(img);
Console.WriteLine($"[{r.Format}] {r.Text}");

// 一张图里有多少解多少
foreach (var b in reader.DecodeMulti(img))
    Console.WriteLine($"{b.Format}: {b.Text}");

失败返回 null / 空数组,永不抛异常——生产线级的健壮性约定: 单个码制的解析异常被隔离吞没,绝不会因为一个坏图崩掉你的识别进程。

性能调优选项

属性 默认 说明
Formats All 限定码制是最有效的提速手段
Preset FullPower 性能预设:Speed(关全部增强,仅 Otsu+Hybrid 二值化)/ Balanced(增强全开,去掉最慢的 DynThreshold)/ FullPower(识别率优先)。赋值后仍可单独覆盖任一开关
ScanRegion null(整图) ROI 扫描区域,只在该矩形内识别,结果坐标自动换算回原图坐标系;视野固定时同时提速并抑制视野外干扰
UseRegionProposals 开 候选区调度(检测先行):CvSharp 核心算子 Cv.LocateBarcodes(梯度密度 + 形态学闭运算 + 连通域分析,C++ 原生实现)先定位含码纹理区域,码制读者只在候选区内解码;全图无候选区时走快速拒绝路径(无码帧毫秒级返回)。某码制在候选区未命中会自动全图兜底该码制,召回不受影响;仅调试时关闭
TimeoutMs 0(不限) 工业在线必设:单次识别时间预算,到点按当前进度返回。500 万像素噪声图实测:设 500 实际约 0.9s 返回,设 200 实际约 0.22s
TryHarder 开 关闭约提速一倍,识别率略降
TryMultiAngle 开 任意角度斜扫;只扫正置码可关
TryDeblur 开 去模糊重试,仅在完全失败路径触发,大图自动降采样到长边 1024,成功图零开销
TryInverted / TryRotate / TryPure / TryGrayResampling 开 各条增强通道,均可独立关闭
Binarizers All Otsu / Hybrid / AdaptiveGaussian / DynThreshold 按需裁剪
MaxSymbols 16 多码返回上限

1.2.x 起多码流水线做了三项架构级提速(取代 ZXing-C++ 的逐读者串行架构): 候选区检测先行——Sobel 梯度密度 + 形态学闭运算 + 连通域分析的 CvSharp 原生流水线 先回答"哪里有码",四个 2D 码制(QR/DataMatrix/PDF417/Aztec)只在候选区裁剪内解码 (640×480 单 QR 图从整图扫掠约 70ms 降到 6ms);全图无任何条码纹理时快速拒绝 (1280×1024 空白无码帧约 20ms 返回,此前要走完全部重试通道)。 纯一维码帧在 1D 通道命中后,若候选区均已被已解码符号"认领"(结果框沿识读方向贯穿候选区, 未认领的噪声级小候选合计不超过图像 5%),整个 2D 扫掠直接跳过——HALCON DataBar 校准图 (1280×1024,含印刷文字干扰)整帧耗时从约 260ms 降到约 75ms。 四个 2D 码制共享二值化——每层二值化只算一次喂给所有读者; 且二值化层、多角度扫掠、纠斜重试等独立通道多线程并行(各任务私有状态,合并时保持 与顺序执行一致的优先级与去重)。实测 1280×1024 全码制多码最坏路径:约 900ms → 约 200ms; 配合预设:Balanced 约 150ms,Speed 约 40ms。成功路径不受影响(一维码命中即返回,通常 <20ms)。

另:堆叠 DataBar(RSS Expanded Stacked / RSS-14 Stacked)的检测框从「首末字符对窄条」 修正为整符号包围框——取全部行对的横向包围范围,再按像素密度向上下扩展到条带真实边缘 (ZXing-C++ 同样只框首末对,HALCON 风格的整符号框是工业验收习惯)。

DataBar Expanded 另加了一道序列几何一致性校验防误报:Expanded 没有整体校验位, 跨行累积的字符对池在噪声图上可能凑出"校验和合法"的垃圾序列(ZXing-C++ 同款架构的固有弱点)。 本库要求拼出的字符对序列在几何上"排得起来"——同条带相邻对 x 首尾相接且 y 差受旋转斜率约束, 条带切换必须换 y 带且落在已覆盖 x 范围附近(兼容多列堆叠布局与旋转)。 实测纯白噪声 / 强纹理无码图零误报,HALCON DataBar 全系列回归不掉点。

典型耗时(600×600 工业图,全通道全开):成功识别约 40–200ms(限定单码制 + 候选区命中时可低至个位数毫秒)。 无纹理的无码帧(空白/均匀底,工业无件状态的大多数)由候选区检测快速拒绝,约 20ms 返回; 最坏情况剩下大面积强纹理背景(粗糙工件、密集印刷):所有重试通道都会认真扫一遍,500 万像素噪声图默认约 9s—— 在线场景请务必限定 Formats、设置 ScanRegion 与 TimeoutMs(这正是 HALCON / Dynamsoft / Scandit 等工业库的通行做法:码制 + ROI + 时间预算三件套),即可把最坏耗时钉死在预算量级(± 一个码制分支的粒度):

// 产线推荐配置:预设 + 码制 + ROI + 时间预算
var reader = new BarcodeReader
{
    Preset = BarcodePreset.Balanced,          // 或 Speed:节拍紧张时
    Formats = BarcodeFormat.QRCode | BarcodeFormat.DataMatrix,
    ScanRegion = new RectI(100, 80, 800, 600), // 视野中码可能出现的区域
    TimeoutMs = 500,   // 最坏情况约 0.5~1s 内必然返回
};

首次识别慢是 JIT 与线程池的一次性开销(分层编译要跑几遍才出优化代码),与算法无关。 程序启动时在后台线程调一次 BarcodeReader.Warmup() 即可消除,不阻塞界面:

Task.Run(() => BarcodeReader.Warmup());   // 后台约 3s,之后首帧即稳态耗时

目标框架

  • .NET 8
  • .NET Framework 4.6.1(老产线、老工控机直接可用,编码走框架内置实现)

依赖 CvSharp ≥ 1.2.14(候选区定位算子 Cv.LocateBarcodes 自该版本起进入 CvSharp 核心)。 依赖为最低版本约束:你的项目使用更新版本的 CvSharp 时 NuGet 自动取高版本,无冲突。 .NET Framework 项目引用时请设置 RuntimeIdentifier(如 win-x64), 以便 CvSharp 原生库随输出部署。

许可

Apache-2.0。部分解码核心移植自 ZXing / ZXing-C++(Apache-2.0),图像前端与增强流水线为原创实现。

GreatBear 出品。

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.2.9 151 10/19/2026
1.2.4 112 10/18/2026
1.0.0 113 10/18/2026