Bitzsoft.Integrations.Ocr
1.1.0
dotnet add package Bitzsoft.Integrations.Ocr --version 1.1.0
NuGet\Install-Package Bitzsoft.Integrations.Ocr -Version 1.1.0
<PackageReference Include="Bitzsoft.Integrations.Ocr" Version="1.1.0" />
<PackageVersion Include="Bitzsoft.Integrations.Ocr" Version="1.1.0" />
<PackageReference Include="Bitzsoft.Integrations.Ocr" />
paket add Bitzsoft.Integrations.Ocr --version 1.1.0
#r "nuget: Bitzsoft.Integrations.Ocr, 1.1.0"
#:package Bitzsoft.Integrations.Ocr@1.1.0
#addin nuget:?package=Bitzsoft.Integrations.Ocr&version=1.1.0
#tool nuget:?package=Bitzsoft.Integrations.Ocr&version=1.1.0
Bitzsoft.Integrations.Ocr
OCR 文字识别集成 -- 基于 Tesseract + Emgu.CV 的图像文字识别,支持中英文多语种、验证码生成与识别。
功能特性
- 多数据源输入:文件路径、字节数组、Base64 字符串、URL
- 区域识别:指定图像矩形区域进行精准 OCR
- 多语种支持:英文(eng)、简体中文(chi_sim)、繁体中文(chi_tra),全部核心识别方法(文件、字节数组、Base64、远程 URL 与矩形裁剪)均提供按请求透传
language(如"chi_sim+eng")的无状态重载,内置路径穿越与非法字符拦截且绝不污染容器单例OCROptions.Language;远程 URL 识别受取数前与连接期双重 SSRF 校验(逐跳重定向复检)并受OCROptions.MaxDownloadBytes(默认 20MB)下载字节上限保护 - 图像预处理:基于 Emgu.CV 的灰度、二值化、去噪等预处理管线
- 验证码生成:可配置尺寸与长度的随机验证码图片
- 验证码识别:自动识别验证码图像中的文本
- 置信度过滤:低于
MinConfidence阈值的结果自动标记为失败 - 第三方请求日志:内置 RequestLogging DelegatingHandler,记录 URL 输入源的 HTTP 请求与响应,便于问题排查
- 识别结果包含区域坐标、独立置信度、处理耗时等详细信息
- Options 强类型配置,支持
IConfigurationSection绑定
安装
dotnet add package Bitzsoft.Integrations.Ocr
或直接在项目文件中引用:
<PackageReference Include="Bitzsoft.Integrations.Ocr" Version="1.0.0" />
配置
在 appsettings.json 中添加 OCR 服务配置:
{
"OCR": {
"Enabled": true,
"Language": "chi_sim+eng",
"TessDataPath": "./tessdata",
"EngineMode": 0,
"PreprocessImage": true,
"SavePreprocessedImage": false,
"MaxDownloadBytes": 20971520,
"MinConfidence": 60,
"PageSegMode": 3,
"RemoteFetchTimeout": "00:00:15",
"MaxRedirectHops": 3,
"HttpClientName": "Ocr"
}
}
注册服务
using Bitzsoft.Integrations.Ocr;
// 方式一:通过 IConfigurationSection 绑定
builder.Services.AddOCRService(builder.Configuration.GetSection("OCR"));
// 方式二:通过委托手动配置
builder.Services.AddOCRService(options =>
{
options.Enabled = true;
options.Language = "chi_sim+eng";
options.TessDataPath = "./tessdata";
options.PreprocessImage = true;
options.MinConfidence = 60;
});
第三方请求日志
内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道,默认使用 NullRequestLogStore 不持久化。
// ① 默认:启用记录管道但不持久化(日志丢弃)
services.AddOCRService(options => { /* ... */ });
// ② 持久化:宿主注册 IRequestLogStore 实现后,所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
opts.MaxInMemoryBodyBytes = 64 * 1024; // 仅控制内存/加密临时文件切换,不截断正文
opts.SensitiveFields.Add("mySecret");
});
services.AddOCRService(options => { /* ... */ });
使用示例
以下示例展示发票图像识别,提取关键字段并校验置信度:
using Bitzsoft.Integrations.Ocr;
/// <summary>
/// 发票识别服务
/// </summary>
public class InvoiceOcrService
{
private readonly IOCRService _ocr;
/// <summary>
/// 初始化发票识别服务实例
/// </summary>
/// <param name="ocr">OCR 文字识别服务(由 DI 注入)</param>
public InvoiceOcrService(IOCRService ocr)
{
_ocr = ocr;
}
/// <summary>
/// 识别发票图像并提取关键信息
/// </summary>
/// <param name="invoiceImagePath">发票图片文件路径</param>
/// <param name="cancellationToken">取消令牌</param>
/// <returns>识别到的发票文本内容及各区域置信度</returns>
public async Task<InvoiceRecognitionResult> RecognizeInvoiceAsync(
string invoiceImagePath,
CancellationToken cancellationToken = default)
{
// 对整张发票进行全量识别
OCRResult fullResult = await _ocr.RecognizeFromFileAsync(
invoiceImagePath,
cancellationToken);
if (!fullResult.Success)
{
return new InvoiceRecognitionResult
{
Success = false,
ErrorMessage = fullResult.ErrorMessage
};
}
// 过滤低置信度区域,仅保留可靠识别结果
var reliableRegions = fullResult.Regions
.Where(r => r.Confidence >= 80)
.ToList();
// 针对发票号码区域进行精准二次识别(假设发票号位于右上方区域)
OCRResult invoiceNoResult = await _ocr.RecognizeRegionAsync(
imagePath: invoiceImagePath,
x: 500,
y: 50,
width: 300,
height: 40);
return new InvoiceRecognitionResult
{
Success = true,
FullText = fullResult.Text,
MeanConfidence = fullResult.MeanConfidence,
ProcessingTimeMs = fullResult.ProcessingTimeMs,
ReliableRegions = reliableRegions,
InvoiceNumber = invoiceNoResult.Success ? invoiceNoResult.Text.Trim() : null
};
}
/// <summary>
/// 生成并识别验证码(用于测试或自动化场景)
/// </summary>
/// <returns>验证码文本与对应图像数据</returns>
public async Task<CaptchaResult> GenerateAndRecognizeCaptchaAsync()
{
// 生成 4 位验证码图片
byte[] captchaImage = _ocr.GenerateCaptcha(
width: 120,
height: 40,
length: 4);
// 识别生成的验证码
OCRResult result = await _ocr.RecognizeCaptchaAsync(captchaImage);
return new CaptchaResult
{
Text = result.Text,
Confidence = result.MeanConfidence,
ImageData = captchaImage
};
}
}
/// <summary>
/// 发票识别结果
/// </summary>
public class InvoiceRecognitionResult
{
/// <summary>是否识别成功</summary>
public bool Success { get; set; }
/// <summary>错误消息</summary>
public string? ErrorMessage { get; set; }
/// <summary>完整识别文本</summary>
public string FullText { get; set; } = string.Empty;
/// <summary>平均置信度(0-100)</summary>
public float MeanConfidence { get; set; }
/// <summary>处理耗时(毫秒)</summary>
public long ProcessingTimeMs { get; set; }
/// <summary>高置信度区域列表</summary>
public List<TextRegion> ReliableRegions { get; set; } = new();
/// <summary>发票号码</summary>
public string? InvoiceNumber { get; set; }
}
/// <summary>
/// 验证码结果
/// </summary>
public class CaptchaResult
{
/// <summary>验证码文本</summary>
public string Text { get; set; } = string.Empty;
/// <summary>识别置信度</summary>
public float Confidence { get; set; }
/// <summary>验证码图像数据</summary>
public byte[] ImageData { get; set; } = Array.Empty<byte>();
}
远程图片抓取安全防护(SSRF)与扩展能力
AddOCRService 会自动装配 IOcrRemoteImageFetcher(默认实现 OcrUrlSafeImageFetcher)、非破坏性 OCROptions 参数校验器以及绑定 OcrSafeHttpHandlerFactory 与 AddRequestLogging("Ocr") 的命名 HttpClient:
- 协议与 URL 规范约束:仅放行
http/https,拦截嵌入式凭据(UserInfo)、控制字符、超长 URL(默认上限 2048 字符)及localhost/*.localhost/*.local/*.internal等保留主机名。 - 公网路由与防 DNS 重绑定:预检与 TCP 建连
ConnectCallback均拦截全部私网、环回、CGNAT(100.64.0.0/10)、云元数据(169.254.0.0/16)、IPv6 ULA(fc00::/7)、IPv4 映射 IPv6(::ffff:0:0/96)、NAT64/6to4/Teredo/保留段,且双记录中任一地址非公网即整体拒绝。 - 手动逐跳重定向与内容校验:底层禁用
AllowAutoRedirect,最多手动跟踪MaxRedirectHops(默认 3 跳)并对每一跳重新校验 URL 与 DNS 解析;响应强制检查 MIME(拒绝text/html、application/json、image/svg+xml等)、PNG/JPEG/GIF/BMP/TIFF/WebP 魔数签名与MaxDownloadBytes流式字节上限。 - 超时与取消隔离:受控于
RemoteFetchTimeout(默认 15 秒),超时抛出TimeoutException,调用方主动取消无损传播OperationCanceledException。 - 区域裁剪、语言查询与结构化结果:支持
RecognizeRegionAsync(byte[], ...)字节数组区域识别及防溢出 ROI 边界校验;提供GetSupportedLanguages(bool installedOnly = false)查询内置及磁盘tessdata模型列表;OCRResult与TextRegion统一暴露结构化OcrBoundingBox、Confidence与DurationMs。
Tesseract 语言数据(tessdata)
Tesseract 需要对应语言的 .traineddata 文件才能执行 OCR。项目源码中 tessdata/ 目录仅包含说明文件,不随 NuGet 包分发实际的语言数据文件(单文件 15–56 MB,体积过大)。
下载地址
| 数据集 | 精度 | 下载地址 | 适用场景 |
|---|---|---|---|
tessdata |
标准 | https://github.com/tesseract-ocr/tessdata | 生产环境(推荐) |
tessdata_best |
最高 | https://github.com/tesseract-ocr/tessdata_best | 对精度要求极高的场景 |
tessdata_fast |
快速 | https://github.com/tesseract-ocr/tessdata_fast | 对速度要求极高的场景 |
常用语言文件
| 语言代码 | 语言 | 文件名 | 大小(约) |
|---|---|---|---|
eng |
英语 | eng.traineddata |
22 MB |
chi_sim |
简体中文 | chi_sim.traineddata |
42 MB |
chi_tra |
繁体中文 | chi_tra.traineddata |
56 MB |
jpn |
日语 | jpn.traineddata |
34 MB |
kor |
韩语 | kor.traineddata |
15 MB |
完整语言列表请查阅上述 GitHub 仓库。
安装步骤
- 从对应仓库下载所需语言的
.traineddata文件 - 将文件放入应用程序运行目录下的
tessdata/文件夹 - 在配置中指定语言代码(多语言用
+连接):
{
"OCR": {
"Language": "chi_sim+eng"
}
}
注意:
TessDataPath配置项默认为./tessdata,需确保该路径相对于应用工作目录正确。在 ASP.NET Core 项目中,通常将tessdata/放在项目根目录并设置"复制到输出目录"为"如果较新则复制"。
相关包
- Bitzsoft.Integrations.Sms -- 短信双通道集成
- Bitzsoft.Integrations.CrawlingService -- 网页爬取服务集成客户端
| 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 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 is compatible. 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. |
-
net10.0
- Bitzsoft.Integrations.RequestLogging (>= 1.0.4)
- Emgu.CV (>= 4.10.0.5680)
- Emgu.CV.runtime.windows (>= 4.10.0.5680)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.14)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Http (>= 10.0.14)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Options (>= 10.0.14)
- Tesseract (>= 5.2.0)
-
net5.0
- Bitzsoft.Integrations.RequestLogging (>= 1.0.4)
- Emgu.CV (>= 4.7.0.5276)
- Emgu.CV.runtime.windows (>= 4.7.0.5276)
- Microsoft.Extensions.Configuration.Abstractions (>= 5.0.0)
- Microsoft.Extensions.Configuration.Binder (>= 5.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 5.0.0)
- Microsoft.Extensions.Http (>= 5.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 5.0.0)
- Microsoft.Extensions.Options (>= 5.0.0)
- Tesseract (>= 5.2.0)
-
net8.0
- Bitzsoft.Integrations.RequestLogging (>= 1.0.4)
- Emgu.CV (>= 4.10.0.5680)
- Emgu.CV.runtime.windows (>= 4.10.0.5680)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.14)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Http (>= 10.0.14)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Options (>= 10.0.14)
- Tesseract (>= 5.2.0)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Bitzsoft.Integrations.Ocr:
| Package | Downloads |
|---|---|
|
Bitzsoft.Integrations.All
Bitzsoft 第三方集成聚合包 — net5.0 包含传统连接器,net8.0+ 额外包含受上游 TFM 限制的 AI 模块 |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.1.0 | 98 | 11/14/2026 |
| 1.0.4 | 175 | 9/23/2026 |
| 1.0.2 | 166 | 8/29/2026 |
| 1.0.1 | 184 | 8/3/2026 |
| 1.0.0 | 186 | 8/2/2026 |
| 1.0.0-alpha.10 | 97 | 7/26/2026 |
| 1.0.0-alpha.9 | 96 | 7/12/2026 |
| 1.0.0-alpha.8 | 299 | 7/1/2026 |
| 1.0.0-alpha.7 | 98 | 6/16/2026 |
| 1.0.0-alpha.6 | 95 | 6/16/2026 |
| 1.0.0-alpha.5 | 93 | 6/14/2026 |
| 1.0.0-alpha.3 | 98 | 6/7/2026 |
| 1.0.0-alpha.2 | 94 | 5/29/2026 |
| 1.0.0-alpha.1 | 91 | 5/28/2026 |