ZXingCpp.Angle
1.2.0
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
<PackageReference Include="ZXingCpp.Angle" Version="1.2.0" />
<PackageVersion Include="ZXingCpp.Angle" Version="1.2.0" />
<PackageReference Include="ZXingCpp.Angle" />
paket add ZXingCpp.Angle --version 1.2.0
#r "nuget: ZXingCpp.Angle, 1.2.0"
#:package ZXingCpp.Angle@1.2.0
#addin nuget:?package=ZXingCpp.Angle&version=1.2.0
#tool nuget:?package=ZXingCpp.Angle&version=1.2.0
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.Common4.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 不变):
- 一维码角点与角度修正:用条码局部的条带方向(
estimateBarAngleInRegion())与两条扫描线中点连线的 垂线(Shear 角)融合,<2° 不动。真实照片各旋转角平均角误差 10.4° → 2.1°。 - 识别框高度扩展:沿法线采样亮度剖面(每 ≈1 模块 1 格),与 band 内参考剖面做归一化互相关,
相似度 <0.7 或超出
min(2×半长, 320px)停止,两侧对称外扩后重设 PositionRect。 - 细模块兜底:
tryHarder下,全局固定阈值在原始 ImageView 上重跑一次(自适应与固定阈值互不包含, 所以是加跑);全灭时再用 Lanczos3 放大 2× 重试,坐标 /2 映射回原图。面积 ≤120 万像素才走, 高分辨率照片不受影响。 - 多线程 + SIMD:主流程 × 固定阈值 pass 并行、放大后两种二值化并行、Lanczos 两个 pass 按行切块并行
(垂直 pass 用 SSE2,结果与
lround+clamp 逐位一致);第一层已解出时跳过降采样层。 引擎内部 A/B(47 图,串行 → 并行+跳层)1720 → 1075 ms,逐图结果 0 差异; 24 图 × 3 轮 × 6 线程并发调用 0 错误。 - 反光 / 激光打标二维码召回:
LocateConcentricPattern增加maxError参数,严格搜索 finder ❤️ 且 ≥1 时 用maxError=1重搜;全灭时对两种二值化各做一次close()(3×3 膨胀+腐蚀)后用矩阵 reader 再读, 填针孔与"不掏空暗块"缺一不可。 - 修
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 | Versions 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. |
-
.NETCoreApp 2.0
- System.Drawing.Common (>= 4.7.3)
-
.NETFramework 4.6.1
- No dependencies.
-
.NETFramework 4.8
- No dependencies.
-
.NETStandard 2.0
- System.Drawing.Common (>= 4.7.3)
-
net5.0
- System.Drawing.Common (>= 5.0.3)
-
net8.0-windows7.0
- 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.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。