# OCR 识别工具使用指南

## 📋 目录
- [快速开始](#快速开始)
- [功能特性](#功能特性)
- [安装配置](#安装配置)
- [使用方法](#使用方法)
- [自定义训练模型](#自定义训练模型)
- [性能优化](#性能优化)
- [常见问题](#常见问题)

---

## 🚀 快速开始

### 1. NuGet 包安装

在项目中安装以下 NuGet 包：

```powershell
Install-Package Tesseract -Version 5.2.0
Install-Package OpenCvSharp4 -Version 4.8.0.20230708
Install-Package OpenCvSharp4.runtime.win -Version 4.8.0.20230708
```

### 2. 下载语言数据文件

从 [Tesseract 官方仓库](https://github.com/tesseract-ocr/tessdata) 下载需要的语言文件：

- **英文**: `eng.traineddata`
- **简体中文**: `chi_sim.traineddata`
- **繁体中文**: `chi_tra.traineddata`

将下载的文件放入项目的 `tessdata` 文件夹中。

### 3. 基本使用

```csharp
using OCRTest;

// 方式1：使用默认单例（推荐）
var ocrEngine = OCREngine.Instance;
var result = ocrEngine.RecognizeText("image.png");
Console.WriteLine($"识别结果：{result.Text}");
Console.WriteLine($"置信度：{result.Confidence}%");
Console.WriteLine($"耗时：{result.ElapsedMilliseconds}ms");

// 方式2：中英文混合识别
var ocrEngineChi = OCREngine.GetInstance("chi_sim+eng");
var result2 = ocrEngineChi.RecognizeText("image.png");
```

---

## ✨ 功能特性

### 核心功能
- ✅ **高性能识别**：基于 Tesseract 5.x LSTM 引擎
- ✅ **多语言支持**：支持 100+ 种语言
- ✅ **自定义训练**：可训练专用模型提高特定场景准确率
- ✅ **图像预处理**：自动灰度化、二值化、降噪
- ✅ **批量处理**：支持批量图片识别
- ✅ **线程安全**：单例模式，多线程安全访问
- ✅ **灵活配置**：支持字符白名单、PSM 模式等高级配置

### 技术优势
- 🎯 **准确率高**：LSTM 深度学习模型
- ⚡ **速度快**：优化的图像预处理流程
- 🔧 **易扩展**：模块化设计，易于定制
- 📊 **可监控**：提供置信度、耗时等指标

---

## 📦 安装配置

### 项目结构

```
OCRTest/
├── OCREngine.cs          # 核心引擎类
├── Program.cs            # 测试程序
├── tessdata/             # 语言数据文件夹
│   ├── eng.traineddata   # 英文模型
│   └── chi_sim.traineddata  # 简体中文模型
└── packages.config       # NuGet 包配置
```

### 配置文件示例

```xml
<!-- packages.config -->
<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Tesseract" version="5.2.0" targetFramework="net48" />
  <package id="OpenCvSharp4" version="4.8.0.20230708" targetFramework="net48" />
  <package id="OpenCvSharp4.runtime.win" version="4.8.0.20230708" targetFramework="net48" />
</packages>
```

---

## 💻 使用方法

### 1. 基础识别

```csharp
// 创建引擎实例
var ocrEngine = OCREngine.Instance;

// 识别图片文件
OCRResult result = ocrEngine.RecognizeText("test.png");

if (result.Success)
{
    Console.WriteLine($"文本：{result.Text}");
    Console.WriteLine($"置信度：{result.Confidence:F2}%");
    Console.WriteLine($"耗时：{result.ElapsedMilliseconds}ms");
}
else
{
    Console.WriteLine($"错误：{result.Error}");
}
```

### 2. 自定义配置

```csharp
var config = new OCRConfig
{
    Language = "eng",                    // 识别语言
    EngineMode = EngineMode.LstmOnly,    // 仅使用LSTM（更快）
    Whitelist = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", // 字符白名单
    EnablePreprocessing = true,          // 启用预处理
    PageSegMode = PageSegMode.Auto       // 自动页面分割
};

var ocrEngine = OCREngine.GetInstance(config);
var result = ocrEngine.RecognizeText("test.png");
```

### 3. 从 Bitmap 识别

```csharp
using (var bitmap = new Bitmap("test.png"))
{
    var result = ocrEngine.RecognizeFromBitmap(bitmap);
    Console.WriteLine(result.Text);
}
```

### 4. 批量识别

```csharp
string[] imagePaths = {
    "image1.png",
    "image2.png",
    "image3.png"
};

var results = ocrEngine.RecognizeBatch(imagePaths);

for (int i = 0; i < results.Count; i++)
{
    Console.WriteLine($"图片{i+1}: {results[i].Text}");
}
```

### 5. 工业场景示例

```csharp
// 场景：识别产品序列号（仅数字和字母）
var config = new OCRConfig
{
    Language = "eng",
    EngineMode = EngineMode.LstmOnly,
    Whitelist = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-",
    EnablePreprocessing = true
};

var ocrEngine = OCREngine.GetInstance(config);

// 连续识别
while (true)
{
    var result = ocrEngine.RecognizeText("product_sn.png");
    
    if (result.Success && result.Confidence > 85)
    {
        Console.WriteLine($"序列号：{result.Text}");
        break;
    }
    
    Thread.Sleep(100);
}
```

---

## 🎓 自定义训练模型

### 为什么要训练自己的模型？

- 📈 **提高特定场景准确率**：如工业字体、特殊符号
- 🎯 **减少误识别**：通过白名单和专用模型
- ⚡ **提升识别速度**：精简字符集
- 🔒 **适应特殊需求**：如手写体、艺术字

### 训练步骤

#### 步骤 1：准备训练数据

1. **收集样本图片**
   - 至少 100-500 张代表性图片
   - 覆盖所有需要识别的字符
   - 包含不同光照、角度、清晰度

2. **标注文本**
   - 为每张图片创建对应的 `.txt` 文件
   - 文件名相同，扩展名不同
   ```
   sample001.png
   sample001.txt  (内容: "ABC123")
   
   sample002.png
   sample002.txt  (内容: "DEF456")
   ```

#### 步骤 2：使用 jTessBoxEditor 工具

1. **下载工具**
   - [jTessBoxEditor](https://sourceforge.net/projects/vietocr/files/jTessBoxEditor/)

2. **生成 TIFF 训练文件**
   - 打开 jTessBoxEditor
   - Tools → Merge TIFF
   - 选择所有样本图片
   - 输出为 `myfont.exp0.tif`

3. **标注校正**
   - Box Editor → Open
   - 加载生成的 TIFF 文件
   - 逐张检查并修正识别框
   - 保存为 `myfont.exp0.box`

#### 步骤 3：命令行训练

创建批处理文件 `train.bat`：

```batch
@echo off
set LANG=myfont
set TESSDATA_PREFIX=C:\path\to\tessdata

echo 步骤1: 生成训练文件...
tesseract %LANG%.exp0.tif %LANG%.exp0 batch.nochop makebox

echo 步骤2: 生成字符集...
tesseract %LANG%.exp0.tif %LANG%.exp0 nobatch box.train

echo 步骤3: 计算字符集...
unicharset_extractor %LANG%.exp0.box

echo 步骤4: 生成形状文件...
shapeclustering -F unicharset -O unicharset %LANG%.exp0.tr

echo 步骤5: 聚集字符...
mftraining -F unicharset -U unicharset -O myfont.unicharset %LANG%.exp0.tr

echo 步骤6: 合并字符...
cntraining %LANG%.exp0.tr

echo 步骤7: 重命名文件...
rename normproto myfont.normproto
rename inttemp myfont.inttemp
rename pffmtable myfont.pffmtable
rename shapetable myfont.shapetable

echo 步骤8: 组合训练数据...
combine_tessdata myfont.

echo 完成！生成 myfont.traineddata
pause
```

#### 步骤 4：使用训练好的模型

```csharp
// 将 myfont.traineddata 放入 tessdata 文件夹

var config = new OCRConfig
{
    Language = "myfont",  // 使用自定义模型
    EngineMode = EngineMode.LstmOnly,
    EnablePreprocessing = true
};

var ocrEngine = OCREngine.GetInstance(config);
var result = ocrEngine.RecognizeText("test.png");
```

### 在线训练工具推荐

1. **[Tesseract Training Tools](https://github.com/tesseract-ocr/tesseract/wiki/TrainingTesseract)**
   - 官方训练工具集
   - 功能完整，文档齐全

2. **[OCR-D](https://ocr-d.de/)**
   - 现代化训练流程
   - 支持深度学习

3. **[Transkribus](https://transkribus.eu/)**
   - 图形化界面
   - 适合手写体训练

---

## ⚡ 性能优化

### 1. 引擎模式选择

```csharp
// 最快：仅使用 LSTM
EngineMode.LstmOnly

// 平衡：LSTM + 传统引擎
EngineMode.Default

// 最准确：仅传统引擎（慢）
EngineMode.TesseractOnly
```

### 2. 图像预处理优化

```csharp
var config = new OCRConfig
{
    EnablePreprocessing = true,  // 启用预处理
    // 预处理会自动进行：
    // - 灰度化
    // - 二值化（Otsu算法）
    // - 降噪
};
```

### 3. 字符白名单

```csharp
// 限制识别字符范围，大幅提升速度和准确率
config.Whitelist = "0123456789";  // 仅数字
config.Whitelist = "ABCDEF0123456789";  // 十六进制
```

### 4. PSM 模式选择

```csharp
// 根据版面选择合适的模式
PageSegMode.SingleLine          // 单行文本
PageSegMode.SingleWord          // 单个单词
PageSegMode.SingleChar          // 单个字符
PageSegMode.Auto                // 自动检测（默认）
```

### 5. 单例复用

```csharp
// ✅ 推荐：复用引擎实例
var engine = OCREngine.Instance;
for (int i = 0; i < 1000; i++)
{
    var result = engine.RecognizeText($"image{i}.png");
}

// ❌ 不推荐：频繁创建销毁
for (int i = 0; i < 1000; i++)
{
    using (var engine = new TesseractEngine(...))
    {
        // ...
    }
}
```

### 6. 并行处理

```csharp
// 批量并行识别
var imagePaths = Directory.GetFiles("images", "*.png");

Parallel.ForEach(imagePaths, path =>
{
    var result = OCREngine.Instance.RecognizeText(path);
    Console.WriteLine($"{Path.GetFileName(path)}: {result.Text}");
});
```

### 性能对比表

| 优化项 | 优化前 | 优化后 | 提升 |
|--------|--------|--------|------|
| 引擎模式 | Default | LstmOnly | 30-50% |
| 字符白名单 | 无 | 有限字符集 | 40-60% |
| 图像预处理 | 无 | 启用 | 10-20% 准确率 |
| 单例复用 | 每次创建 | 复用实例 | 80-90% |
| 并行处理 | 串行 | Parallel | N倍（CPU核心数） |

---

## ❓ 常见问题

### Q1: 识别准确率低怎么办？

**解决方案：**
1. 启用图像预处理
2. 设置字符白名单
3. 使用更高分辨率图片（建议 300 DPI 以上）
4. 训练专用模型
5. 调整 PSM 模式

```csharp
var config = new OCRConfig
{
    EnablePreprocessing = true,
    Whitelist = "你的字符集",
    PageSegMode = PageSegMode.SingleLine  // 根据实际调整
};
```

### Q2: 如何识别中文？

**步骤：**
1. 下载 `chi_sim.traineddata`（简体）或 `chi_tra.traineddata`（繁体）
2. 放入 `tessdata` 文件夹
3. 使用：

```csharp
var engine = OCREngine.GetInstance("chi_sim");  // 简体中文
var engine = OCREngine.GetInstance("chi_sim+eng");  // 中英混合
```

### Q3: 内存占用过高？

**解决方案：**
```csharp
// 定期清理不用的实例
OCREngine.Cleanup();

// 或使用 using 语句
using (var engine = OCREngine.GetInstance("eng"))
{
    // 使用后自动释放
}
```

### Q4: 如何提高识别速度？

**优化方案：**
1. 使用 `EngineMode.LstmOnly`
2. 设置字符白名单
3. 降低图片分辨率（不低于 200 DPI）
4. 裁剪无关区域
5. 使用 SSD 存储 tessdata

### Q5: 支持哪些语言？

完整语言列表见 [Tesseract 语言包](https://github.com/tesseract-ocr/tessdata)

常用语言代码：
- `eng` - 英语
- `chi_sim` - 简体中文
- `chi_tra` - 繁体中文
- `jpn` - 日语
- `kor` - 韩语
- `deu` - 德语
- `fra` - 法语

### Q6: 如何处理倾斜图片？

**方案：**
```csharp
// 使用 OpenCvSharp 进行矫正
using (var src = Cv2.ImRead("image.png"))
{
    // 检测倾斜角度
    // 旋转矫正
    // 然后传入 OCR 引擎
    var result = ocrEngine.RecognizeFromBitmap(src.ToBitmap());
}
```

---

## 📞 技术支持

- **Tesseract 官方文档**: https://tesseract-ocr.github.io/
- **GitHub 仓库**: https://github.com/tesseract-ocr/tesseract
- **问题反馈**: 提交 Issue 到项目仓库

---

## 📄 许可证

本项目使用的 Tesseract OCR 遵循 Apache 2.0 许可证。

---

**祝使用愉快！** 🎉