report-detect/TEST_ACCURACY_BATCH_README.md

# test_accuracy_batch_full.py - 使用指南

## 📋 概述

`test_accuracy_batch_full.py` 是一个用于批量测试PDF报告中CMA（中国计量认证）标志和机构印章识别准确性的Python脚本。它使用OCR技术自动提取CMA编号和机构名称，并与预期结果进行对比验证。

### 主要功能

- ✅ **CMA标志识别**：使用模板匹配和OCR技术提取CMA编号
- ✅ **印章文字识别**：检测红色印章并提取机构名称
- ✅ **批量测试**：支持批量处理多个PDF文件
- ✅ **准确率统计**：自动计算CMA和机构名称的识别准确率
- ✅ **详细报告**：生成HTML和JSON格式的测试报告
- ✅ **可视化输出**：生成印章检测、解扭曲的可视化图像

## 🚀 快速开始

### 环境要求

```bash
# Python版本
Python 3.8+

# 必需依赖
pip install paddlepaddle
pip install paddleocr
pip install opencv-python
pip install numpy
pip install pillow

# 可选依赖（用于PaddleOCR-VL高级功能）
pip install paddleocr[doc-parser]
```

### 基础用法

```bash
# 运行批量测试（使用默认设置）
python test_accuracy_batch_full.py --batch

# 指定处理数量
python test_accuracy_batch_full.py --batch --batch-size 20

# 使用ppocr_v5模型（推荐，速度更快）
python test_accuracy_batch_full.py --ocr-model ppocr_v5 --batch
```

## 📦 命令行参数

### 基本参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--pdf` | string | - | 单个PDF文件的路径（桥接模式） |
| `--output-dir` | string | `bridge_output` | 输出目录 |
| `--ocr-model` | choice | `paddleocr_vl` | OCR模型选择：`ppocr_v5` 或 `paddleocr_vl` |
| `--batch` | flag | False | 启用批量测试模式 |
| `--batch-size` | int | 20 | 处理的PDF数量 |
| `--pdf-names` | string | - | 逗号分隔的PDF名称列表 |

### 高级参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--disable-paddleocrvl` | flag | False | 禁用PaddleOCRVL备份识别 |
| `--paddleocrvl-timeout` | int | 60 | PaddleOCRVL超时时间（秒） |

## 🎯 使用场景

### 场景1：快速批量测试

使用ppocr_v5模型进行快速测试：

```bash
python test_accuracy_batch_full.py \
  --ocr-model ppocr_v5 \
  --batch \
  --batch-size 20
```

**特点**：
- ⚡ 速度快（~18秒/PDF）
- 🎯 CMA准确率：85-100%
- 📊 机构准确率：27-100%

### 场景2：高精度识别

使用paddleocr_vl模型获得更高准确率：

```bash
python test_accuracy_batch_full.py \
  --ocr-model paddleocr_vl \
  --batch \
  --batch-size 20 \
  --paddleocrvl-timeout 300
```

**特点**：
- 🎯 识别准确率更高
- ⏱️ 处理时间较长（每个印章最多5分钟）
- 💪 需要更多内存（至少3GB可用）

### 场景3：禁用PaddleOCRVL（最快）

完全禁用PaddleOCRVL以获得最快速度：

```bash
python test_accuracy_batch_full.py \
  --ocr-model ppocr_v5 \
  --batch \
  --batch-size 20 \
  --disable-paddleocrvl
```

**特点**：
- ⚡⚡ 最快速度
- 💾 内存占用最小
- ⚠️ 识别准确率可能略低

### 场景4：处理单个PDF

使用桥接模式处理单个PDF：

```bash
python test_accuracy_batch_full.py \
  --pdf path/to/report.pdf \
  --output-dir my_output
```

## 📂 文件结构

### 输入文件

```
src/test/resources/data/pdfs/
├── 1.pdf
├── 2.pdf
├── WTS2025-21283.pdf
└── ... (测试PDF文件)

src/test/resources/data/results.json
└── 包含每个PDF的预期CMA编号和机构名称
```

### 输出文件

```
test_reports_full/
├── summary.html              # 测试总结报告
├── test_report.json          # JSON格式详细结果
│
├── 1.pdf/
│   ├── doc_page.png          # 原始页面图像
│   ├── doc_layout_viz.png    # 版面分析可视化
│   ├── cma_roi.png           # CMA标志区域
│   ├── seal_crop_0.png       # 印章裁剪
│   ├── seal_unwarp_0.png     # 印章解扭曲
│   ├── seal_polar_viz_0.png  # 极坐标可视化
│   ├── seal_marked_0.png     # 页面标记
│   └── index.html            # 单个PDF详细报告
│
└── ... (其他PDF的输出)
```

## 🔍 配置文件

### ground truth (results.json)

```json
{
  "1.pdf": {
    "cma": "20211901583",
    "institution": "深圳市中安质量检验认证有限公司"
  },
  "WTS2025-21283.pdf": {
    "cma": "220020349627",
    "institution": "威凯检测技术有限公司"
  }
}
```

### CMA模板

脚本会自动从CMA模板文件加载：
- `src/main/resources/models/cma_logo_template.png`（主模板）
- `cma_extraction_template_primary.py`（主模板提取逻辑）

## 📊 结果解读

### 测试报告示例

```
================================================================================
BATCH TEST COMPLETED - FINAL RESULTS
================================================================================
Total Processed: 20

CMA Code Results:
  Exact Match: 17/20 (85.0%)
  Partial Match: 1/20 (5.0%)
  Acceptable Match: 0/20 (0.0%)
  No Match: 2/20 (10.0%)
  ** CMA Accuracy: 85.0% **

Institution Name Results:
  Exact Match: 5/18 (27.8%)
  Partial Match: 1/18 (5.6%)
  Acceptable Match: 3/18 (16.7%)
  No Match: 9/18 (50.0%)
  ** Institution Accuracy: 50.0% (including acceptable) **
```

### 匹配类型说明

| 匹配类型 | 说明 | 相似度要求 |
|---------|------|-----------|
| `exact` | 完全匹配 | 100% |
| `partial` | 部分匹配 | >= 80% |
| `acceptable` | 可接受匹配 | >= 60% |
| `no_match` | 不匹配 | < 60% |

### 性能指标

```
Performance:
  Total Time: 385.2s (6.4min)
  Average Time: 19.3s per PDF
  CMA Time: 9.7s per PDF
  Seal Time: 9.3s per PDF
```

## 🐛 故障排除

### 问题1：内存不足

**错误信息**：
```
Insufficient memory for PaddleOCRVL (2.6 GB < 3.0 GB)
```

**解决方案**：
```bash
# 关闭其他应用程序
# 或使用--disable-paddleocrvl参数
python test_accuracy_batch_full.py --batch --disable-paddleocrvl
```

### 问题2：PaddleOCRVL超时

**错误信息**：
```
PaddleOCRVL recognition timeout (60s) for seal_crop_0.png
```

**解决方案**：
```bash
# 增加超时时间到5分钟
python test_accuracy_batch_full.py --batch --paddleocrvl-timeout 300
```

### 问题3：OCR识别率低

**可能原因**：
- PDF质量不佳
- 印章模糊或变形
- CMA标志不清晰

**解决方案**：
- 尝试不同的OCR模型
- 增加`--paddleocrvl-timeout`时间
- 手动检查PDF图像质量

### 问题4：找不到results.json

**错误信息**：
```
Ground truth file not found: src/test/resources/data/results.json
```

**解决方案**：
```bash
# 检查文件路径
ls -la src/test/resources/data/results.json

# 如果不存在，需要创建该文件
```

## ⚙️ 高级配置

### 自定义CMA模板

1. 准备CMA标志图像（PNG格式，白色背景）
2. 放置在：`src/main/resources/models/cma_logo_template.png`
3. 脚本会自动加载并使用

### 调整匹配阈值

编辑脚本中的以下参数：

```python
# 机构名称匹配阈值
INSTITUTION_MATCH_THRESHOLDS = {
    'exact': 100.0,      # 100%相似度
    'partial': 80.0,     # 80%相似度
    'acceptable': 60.0   # 60%相似度
}

# CMA编号正则表达式
CMA_PATTERNS = [
    r'2\d{10}',      # 11位，以2开头
    r'\d{11,12}'     # 11-12位数字
]
```

### 印章检测参数

```python
# 红色印章检测
RED_COLOR_LOWER = [0, 100, 100]   # HSV下界
RED_COLOR_UPPER = [10, 255, 255]  # HSV上界

# 最小印章尺寸
MIN_SEAL_SIZE = 50  # 像素
```

## 📈 性能优化建议

### 1. 选择合适的OCR模型

| 模型 | 速度 | 准确率 | 内存 | 推荐场景 |
|------|------|--------|------|---------|
| ppocr_v5 | 快 | 中等 | 低 | 快速测试、大批量 |
| paddleocr_vl | 慢 | 高 | 高 | 精确验证、小批量 |

### 2. 调整超时时间

```bash
# 快速测试（可能超时）
--paddleocrvl-timeout 30

# 标准测试（推荐）
--paddleocrvl-timeout 60

# 高准确率测试
--paddleocrvl-timeout 300
```

### 3. 批量处理

```bash
# 分批处理大量PDF
for batch in 1 2 3 4 5; do
  python test_accuracy_batch_full.py \
    --batch \
    --batch-size 20 \
    --pdf-names $(get_pdf_names_for_batch $batch)
done
```

## 🔗 相关文档

- [PADDLEOCRVL_TIMEOUT_FIX_SUMMARY.md](PADDLEOCRVL_TIMEOUT_FIX_SUMMARY.md) - 超时机制实现详情
- [PADDLEOCRVL_5MIN_TIMEOUT_GUIDE.md](PADDLEOCRVL_5MIN_TIMEOUT_GUIDE.md) - 5分钟超时使用指南
- [3PDF_SEAL_INVESTIGATION_REPORT.md](3PDF_SEAL_INVESTIGATION_REPORT.md) - 印章识别问题调查
- [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) - 实现总结
- [INTEGRATION_TEST_REPORT.md](INTEGRATION_TEST_REPORT.md) - 集成测试报告

## 🛠️ 开发指南

### 添加新的OCR模型

1. 在脚本中添加模型初始化代码
2. 实现OCR识别函数
3. 在主流程中集成新模型
4. 更新命令行参数

### 调试技巧

```bash
# 启用详细日志
export PYTHONUNBUFFERED=1
python test_accuracy_batch_full.py --batch --batch-size 1

# 查看中间结果
ls -la test_reports_full/1.pdf/

# 检查日志
grep "WARNING\|ERROR" test_reports_full/test_report.json
```

### 测试单个功能

```python
# 测试CMA提取
from test_accuracy_batch_full import extract_cma_from_page
result = extract_cma_from_page(page_img, ocr_engine)

# 测试印章检测
from test_accuracy_batch_full import detect_red_seals
seals = detect_red_seals(page_img, output_dir)
```

## 📝 更新日志

### v1.2.0 (2026-03-03)

- ✨ 添加PaddleOCRVL超时保护机制
- ✨ 添加`--paddleocrvl-timeout`参数
- ✨ 添加`--disable-paddleocrvl`参数
- 🐛 修复PaddleOCRVL无限期挂起问题
- 🐛 修复OCR结果解析的IndexError
- 🎨 改进CMA模板匹配算法
- 📚 完善文档和测试报告

### v1.1.0

- ✨ 支持批量测试
- ✨ 支持多种OCR模型
- ✨ 生成HTML可视化报告
- 🎨 添加印章解扭曲可视化

### v1.0.0

- 🎉 初始版本
- ✨ CMA标志识别
- ✨ 印章文字提取
- ✨ 准确率统计

## 💡 最佳实践

1. **首次使用**：先用小批量测试（`--batch-size 5`）
2. **模型选择**：速度优先用ppocr_v5，准确率优先用paddleocr_vl
3. **超时设置**：根据实际网络和硬件情况调整`--paddleocrvl-timeout`
4. **结果验证**：检查`test_report.json`和HTML报告
5. **错误处理**：关注WARNING和ERROR日志

## 🤝 贡献指南

1. Fork项目
2. 创建特性分支：`git checkout -b feature/new-feature`
3. 提交更改：`git commit -am 'Add new feature'`
4. 推送分支：`git push origin feature/new-feature`
5. 创建Pull Request

## 📄 许可证

本项目采用内部许可证，仅供公司内部使用。

## 📞 联系方式

- 项目维护：开发团队
- 问题反馈：通过项目Issue提交
- 技术支持：联系技术负责人

---

**最后更新**：2026-03-03
**版本**：v1.2.0
**维护者**：Claude Sonnet 4.6 & 开发团队