ZXingCpp.Angle 1.1.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package ZXingCpp.Angle --version 1.1.0
                    
NuGet\Install-Package ZXingCpp.Angle -Version 1.1.0
                    
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="ZXingCpp.Angle" Version="1.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ZXingCpp.Angle" Version="1.1.0" />
                    
Directory.Packages.props
<PackageReference Include="ZXingCpp.Angle" />
                    
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 ZXingCpp.Angle --version 1.1.0
                    
#r "nuget: ZXingCpp.Angle, 1.1.0"
                    
#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 ZXingCpp.Angle@1.1.0
                    
#: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=ZXingCpp.Angle&version=1.1.0
                    
Install as a Cake Addin
#tool nuget:?package=ZXingCpp.Angle&version=1.1.0
                    
Install as a Cake Tool

ZXingCpp.Angle

非官方修改版:基于 zxing-cpp 3.1.1 与官方 .NET 封装 ZXingCpp 0.5.3,加强一维条码任意角度识别,并修了一批工程上真实会踩的问题。

⚠️ 这是替代包:请用它替换官方的 ZXingCpp 包,不要把两个包同时引用(托管程序集同名)。

相对上游的改进

项目 上游 3.1.1 本包
一维码可读角度 0°/90°(倾斜约 8~19° 以上就失败,取决于条码宽高比) ±45° + 0°/90°
一维码角度/角点精度 —(只有一条扫描线的位置) 局部方向场与扫描线轴向融合,真实照片平均角误差 10.4° → 2.1°
一维码识别框高度 只覆盖命中扫描线的那条窄带(常只有 10~20 px) 沿法线按亮度剖面自相似外扩到整条码(样例 17.2 → 59.2 px,真值 ≈57 px)
细模组条码(1~2 px/模块、无抗锯齿) 常常失败 亚像素(2 点/像素)采样;仍失败时换固定阈值重跑 + Lanczos3 2× 放大重试(42 张真实标签命中 33 → 38)
小条码在大照片里(占画面 2% 左右) 常失败 瓦片候选区域 + 细角度扫描后可读
反光 / 激光打标二维码 finder 被亮斑切断就整块丢弃 finder 宽松重搜(maxError=1)+ close() 填针孔 + 固定阈值重读,目标样例 0 → 1
反向读取时的识别框 可能被拉成对角线 已修正
耗时 — 主流程与兜底 pass 并行、Lanczos 用 SSE2、解出后跳过冗余金字塔层:两版都能解的图 11.6 → 9.7 ms(-16.9%);多解出的图才会走兜底、多花时间

解码结果(内容、格式、Position、Rotation)语义与官方一致;rotation() 折叠在 (-90°, 90°] (例如同一条轴会报 -64° 而不是 118°,两者等价)。

更新日志

1.1.0(本版)

原生引擎的改动(托管 API 不变):

  1. 一维码角点与角度修正:用条码局部的条带方向(estimateBarAngleInRegion())与两条扫描线中点连线的 垂线(Shear 角)融合,<2° 不动。真实照片各旋转角平均角误差 10.4° → 2.1°。
  2. 识别框高度扩展:沿法线采样亮度剖面(每 ≈1 模块 1 格),与 band 内参考剖面做归一化互相关, 相似度 <0.7 或超出 min(2×半长, 320px) 停止,两侧对称外扩后重设 PositionRect。
  3. 细模块兜底:tryHarder 下,全局固定阈值在原始 ImageView 上重跑一次(自适应与固定阈值互不包含, 所以是加跑);全灭时再用 Lanczos3 放大 2× 重试,坐标 /2 映射回原图。面积 ≤120 万像素才走, 高分辨率照片不受影响。
  4. 多线程 + SIMD:主流程 × 固定阈值 pass 并行、放大后两种二值化并行、Lanczos 两个 pass 按行切块并行 (垂直 pass 用 SSE2,结果与 lround+clamp 逐位一致);第一层已解出时跳过降采样层。 引擎内部 A/B(47 图,串行 → 并行+跳层)1720 → 1075 ms,逐图结果 0 差异; 24 图 × 3 轮 × 6 线程并发调用 0 错误。
  5. 反光 / 激光打标二维码召回:LocateConcentricPattern 增加 maxError 参数,严格搜索 finder ❤️ 且 ≥1 时 用 maxError=1 重搜;全灭时对两种二值化各做一次 close()(3×3 膨胀+腐蚀)后用矩阵 reader 再读, 填针孔与"不掏空暗块"缺一不可。
  6. 修 BarcodeData::operator==:原来要求一维码 rotation() 完全相等,导致同一码用不同二值化/扫描线 报 0° 和 2° 时重复上报;改为角度差 ≤3° 且外接框相交即视为同一个码。

托管层:BarcodeScanner.Scan() 不再无条件整图 Clone(源图已是 32bppArgb 时直接读),大图上省几毫秒。

包级 A/B(同一段驱动代码,只换包版本,42 张真实标签照片 barcode2/images/train):

配置 1.0.0 1.1.0
tryHarder + minLineCount=2:命中图片 / 条码 29 / 30 34 / 35
tryHarder + minLineCount=1:命中图片 / 条码 32 / 33 35 / 38
两版都能解的 29 张,平均耗时 11.6 ms 9.7 ms(-16.9%)
全部 42 张平均耗时 12.5 ms 20.9 ms(多解出的 5 张要走兜底)
回退(1.0.0 能解、1.1.0 解不出) — 0 张

样例:photo_ean13_rotated.png 的一维码角度 22° → 35°(真值 33.5°); 激光打标二维码 1727700985614.png 0 → 1 个(M82282406150115,框贴住符号)。

1.0.0

正式版:托管层内置 demo 的增强 API,目标框架 net8.0-windows;原生引擎提供 ±45° 一维码识别、 亚像素采样、瓦片搜索与反向读取位置修正。取代预发布版 3.1.1-angle.x。

用法(核心 API)

与官方一致。注意用 ZXingCpp.ImageFormat 全限定,避免和 System.Drawing.Imaging.ImageFormat 歧义:

using System.Drawing;
using System.Drawing.Imaging;
using ZXingCpp;

using var bmp = new Bitmap(path);
var data = bmp.LockBits(new Rectangle(0, 0, bmp.Width, bmp.Height),
                        ImageLockMode.ReadOnly, PixelFormat.Format32bppArgb);
var iv = new ImageView(data.Scan0, bmp.Width, bmp.Height, ZXingCpp.ImageFormat.BGRA, data.Stride);
var reader = new BarcodeReader { TryHarder = true, TryRotate = true, TryInvert = true };
foreach (var bc in reader.From(iv))
    Console.WriteLine($"{bc.Format} {bc.Text} rot={bc.Orientation}°");   // 0~359 官方方向角

Barcode.Orientation 是 0~359 的方向角;Barcode.Rotation 是本包把它折叠到 (-90°, 90°] 的便捷值(同一条轴会报 -64° 而不是 118°,两者等价)。Barcode.LineCount 是命中的扫描线条数, 高度扩展后会明显变大。

注意:把图片画到新的 32bpp 位图上时用 DrawImage(src, 0, 0, src.Width, src.Height)(显式宽高), 否则 GDI+ 会按 DPI 缩放,条码被缩小后可能解不出。

增强托管 API(与 demo 一致)

本包内置了 demo 程序使用的一站式封装(using ZXingAngleDemo;),读整图、直接拿结果:

using System.Drawing;
using ZXingCpp;
using ZXingAngleDemo;   // BarcodeScanner / ScanResult / BarcodeInfo

using var bmp = new Bitmap(path);
using var opts = BarcodeScanner.MakeOptions(tryHarder: true, tryRotate: true, tryInvert: true,
                                            tryDownscale: true, formatPreset: "全部", minLineCount: 2, maxSymbols: 0);
var r = BarcodeScanner.Scan(bmp, opts);
foreach (var b in r.Barcodes)
    Console.WriteLine($"{b.Format} \"{b.Text}\" rot={b.Rotation}° lines={b.LineCount} pts={b.Points.Length}");

BarcodeScanner 还提供 MakeOptions、PresetFormats、Rotate(Bitmap, angle, color)、Ensure32bpp。

性能提示

  • 细节兜底(固定阈值 / 放大重试 / 反光 QR 重读)都只在 TryHarder = true 且主流程失败时才跑; 追求吞吐可以关掉 TryHarder,正常光照的标签图照样能解。
  • 引擎内部默认用 min(核数, 8) 个工作线程。调用方自己就在多线程跑多图时,建议设环境变量 ZX_THREADS=2~4,避免线程数相乘。
  • 环境变量开关(默认全关):ZX_THREADS=n、ZX_NO_FALLBACK=1、ZX_NO_LAYER_SKIP=1、 ZX_NO_ANGLE_FIX=1、ZX_DEBUG_TIME=1、ZX_DEBUG_ANGLE=1、ZX_DEBUG_QR=1。

平台

本包托管层面向 net8.0-windows,原生库只带 win-x64 (runtimes/win-x64/native/ZXing.dll)。其它平台请自行用修改后的源码编译 (-DBUILD_SHARED_LIBS=ON -DZXING_C_API=ON)。

许可与声明

Apache-2.0,见随包的 LICENSE。对上游源码的修改清单见 NOTICE.md(Apache-2.0 §4(b) 要求声明修改)。 本项目与 zxing-cpp 作者无关,也未获其背书;问题请提到本包仓库,不要打扰上游。

Product Compatible and additional computed target framework versions.
.NET net8.0-windows7.0 is compatible.  net9.0-windows was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

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
3.1.1-angle.2 81 10/17/2026
3.1.1-angle.1 69 10/17/2026
1.2.1 116 10/26/2026
1.2.0 95 10/26/2026
1.1.0 102 10/25/2026
1.0.0 110 10/18/2026

1.1.0(相对 1.0.0,改动都在原生 DLL,托管 API 不变):① 一维码角点/角度修正,photo 样例 22°→35°(真值 33.5°),真实照片平均角误差 10.4°→2.1°;② 识别框沿法线扩展到整条码(photo 样例 17.2→59.2px);③ 细模块兜底:固定阈值重跑 + Lanczos3 2× 放大重试;④ 多线程 + SSE2,两版都能解的图平均 11.6→9.7ms(-16.9%);⑤ 反光/激光打标二维码召回:finder 宽松重搜 + close() 填针孔 + 固定阈值;⑥ 修同一条码换二值化后重复上报。包级 A/B(42 张真实标签,tryHarder+minLineCount=2):命中 29→34 张 / 30→35 码,回退 0 张;激光打标 QR 样例 0→1。托管层唯一改动:BarcodeScanner.Scan 不再无条件整图 Clone。详见包内 README/NOTICE。