ZXingCpp.Angle 1.2.0

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

托管层改成多目标框架,同一份源码出六个 lib 资产,原生引擎与 1.1.0 逐字节相同(解码行为不变):

TFM System.Drawing 来源 额外依赖
net461 框架自带 System.Drawing.dll 无
net48 框架自带 System.Drawing.dll 无
netstandard2.0 System.Drawing.Common 4.7.3
netcoreapp2.0(.NET Core 2.0) System.Drawing.Common 4.7.3
net5.0 System.Drawing.Common 5.0.3
net8.0-windows WinForms 框架引用 无(与 1.0.0/1.1.0 完全一致)
  • 依赖版本特意选在 4.7.2 / 5.0.3 之上——System.Drawing.Common 4.7.0/4.7.1 与 5.0.0~5.0.2 带 CVE-2021-24112(GHSA-rxg9-xrhp-64gj,CVSS 9.8),会让消费方 restore 时弹 NU1904,已避开。
  • 新增 build/ZXingCpp.Angle.targets:.NET Framework 不会自动处理 runtimes\win-x64\native, 这里在编译期把 ZXing.dll 复制到输出目录(exe 旁边),DllImport("ZXing") 才能找到。 .NET Core / .NET 5+ 不用这段,deps.json + host 自己会探测。
  • 托管源码两处为兼容低版本而改(对外行为不变):using System.Text 的条件由 #if NETSTANDARD 改为 #if !NET(net4x 走的是 Encoding.UTF8.GetString 分支);Math.Clamp 换成内部 Clamp() 小函数 (net461/net48/netstandard2.0 没有 Math.Clamp)。
  • net8.0-windows 资产与 1.1.0 完全一致,老用户升级后行为不变。

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。

平台 / 目标框架

TFM 说明
net461、net48 .NET Framework 4.6.1 / 4.8(4.6.1 及以上、4.8.1 也能用)。只依赖框架自带的 System.Drawing.dll,零 NuGet 依赖
netstandard2.0 类库 / Unity / Xamarin / UWP 等,依赖 System.Drawing.Common 4.7.3
netcoreapp2.0 .NET Core 2.0 / 2.1 / 2.2 / 3.x(3.x 及以上会优先挑 net5.0 或 net8.0-windows 资产),依赖 System.Drawing.Common 4.7.3
net5.0 .NET 5 / 6 / 7 及任何 netX.0 非 Windows 专属工程,依赖 System.Drawing.Common 5.0.3
net8.0-windows .NET 8+ WinForms 工程(走 WindowsDesktop 框架,无 NuGet 依赖)

原生库只带 win-x64(runtimes/win-x64/native/ZXing.dll,约 2.6 MB)。.NET Framework 工程 由包内 build/ZXingCpp.Angle.targets 自动把 ZXing.dll 复制到 exe 同目录,不需要手工拷贝。 其它 CPU 架构(x86 / arm64)或其它平台请自行用修改后的源码编译 (-DBUILD_SHARED_LIBS=ON -DZXING_C_API=ON)。

ImageView 的 ReadOnlySpan<byte> 构造只在 .NET 5+ 存在;.NET Framework / netstandard2.0 用 ImageView(byte[], ...) 或本文示例里的 ImageView(IntPtr, ...),两者在所有 TFM 上都有。

许可与声明

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

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  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.  net8.0-windows7.0 is compatible.  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 Core netcoreapp2.0 is compatible.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 is compatible.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos 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
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.2.0:托管层改为多目标框架,同一份源码产出 net461 / net48 / netstandard2.0 / netcoreapp2.0 / net5.0 / net8.0-windows 六个 lib 资产,原生引擎(win-x64)与 1.1.0 完全相同,解码行为不变。.NET Framework 需 4.6.1 及以上,System.Drawing 用框架自带的;netstandard2.0 / netcoreapp2.0 依赖 System.Drawing.Common 4.7.0,net5.0 依赖 5.0.0;net8.0-windows 走 WinForms 框架引用(与 1.0.0/1.1.0 一致,老用户可原地升级)。新增 build/ZXingCpp.Angle.targets:.NET Framework 不会自动处理 runtimes\win-x64\native,这里显式把 ZXing.dll 复制到输出目录。1.1.0 的五项引擎改动(角度/角点修正、框高度扩展、细模块兜底、多线程+SSE2、反光 QR 召回)全部保留,详见包内 README/NOTICE。