# 项目当前状态

**更新时间**: 2025-10-29
**分支**: `paddleocr-improvements`
**PaddleOCR版本**: 2.7.3 (稳定版本)

---

## 当前进度总结

### ✅ 已完成

1. **PaddleOCR服务器部署** (192.168.30.36:5555)
   - 版本: PaddleOCR 2.7.3
   - GPU: 启用
   - 语言: 中文
   - 状态: 稳定运行

2. **基础Pipeline实现**
   - ✅ PDF → 图像渲染 (DPI=300)
   - ✅ PaddleOCR文字检测 (26个区域/页)
   - ✅ 文本区域遮罩 (padding=25px)
   - ✅ 候选区域检测
   - ✅ 区域合并算法 (12→4 regions)

3. **OpenCV分离方法测试**
   - Method 1: 笔画宽度分析 - ❌ 效果差
   - Method 2: 连通组件基础分析 - ⚠️ 中等效果
   - Method 3: 综合特征分析 - ✅ **最佳方案** (86.5%手写保留率)

4. **测试结果**
   - 测试文件: `201301_1324_AI1_page3.pdf`
   - 预期签名: 2个 (楊智惠, 張志銘)
   - 检测结果: 2个签名区域成功合并
   - 保留率: 86.5% 手写内容

---

## 技术架构

```
PDF文档
  ↓
1. 渲染 (PyMuPDF, 300 DPI)
  ↓
2. PaddleOCR检测 (识别印刷文字)
  ↓
3. 遮罩印刷文字 (黑色填充, padding=25px)
  ↓
4. 区域检测 (OpenCV形态学)
  ↓
5. 区域合并 (距离阈值: H≤100px, V≤50px)
  ↓
6. 特征分析 (大小+笔画长度+规律性)
  ↓
7. [TODO] VLM验证
  ↓
签名提取结果
```

---

## 核心文件

| 文件 | 说明 | 状态 |
|------|------|------|
| `paddleocr_client.py` | PaddleOCR REST客户端 | ✅ 稳定 |
| `test_mask_and_detect.py` | 基础遮罩+检测测试 | ✅ 完成 |
| `test_opencv_separation.py` | OpenCV方法1+2测试 | ✅ 完成 |
| `test_opencv_advanced.py` | OpenCV方法3(最佳) | ✅ 完成 |
| `extract_signatures_paddleocr_improved.py` | 完整Pipeline (Method B+E) | ⚠️ Method E有问题 |
| `PADDLEOCR_STATUS.md` | 详细技术文档 | ✅ 完成 |

---

## Method 3: 综合特征分析 (当前最佳方案)

### 判断依据

**您的观察** (非常准确):
1. ✅ **手写字比印刷字大** - height > 50px
2. ✅ **手写笔画长度更长** - stroke_ratio > 0.4
3. ✅ **印刷体规律，手写潦草** - compactness, solidity

### 评分系统

```python
handwriting_score = 0

# 大小评分
if height > 50: score += 3
elif height > 35: score += 2

# 笔画长度评分
if stroke_ratio > 0.5: score += 2
elif stroke_ratio > 0.35: score += 1

# 规律性评分
if is_irregular: score += 1  # 不规律 = 手写
else: score -= 1              # 规律 = 印刷

# 面积评分
if area > 2000: score += 2
elif area < 500: score -= 1

# 分类: score > 0 → 手写
```

### 效果

- 手写像素保留: **86.5%** ✅
- 印刷像素过滤: 13.5%
- Top 10组件全部正确分类

---

## 已识别问题

### 1. Method E (两阶段OCR) 失效 ❌

**原因**: PaddleOCR无法区分"印刷"和"手写"，第二次OCR会把手写也识别并删除

**解决方案**:
- ❌ 不使用Method E
- ✅ 使用Method B (区域合并) + OpenCV Method 3

### 2. 印刷名字与手写签名重叠

**现象**: 区域包含"楊 智 惠"(印刷) + 手写签名
**策略**: 接受少量印刷残留，优先保证手写完整性
**后续**: 用VLM最终验证

### 3. Masking padding 矛盾

**小padding (5-10px)**: 印刷残留多，但不伤手写
**大padding (25px)**: 印刷删除干净，但可能遮住手写边缘
**当前**: 使用 25px，依赖OpenCV Method 3过滤残留

---

## 下一步计划

### 短期 (继续当前方案)

- [ ] 整合 Method B + OpenCV Method 3 为完整Pipeline
- [ ] 添加VLM验证步骤
- [ ] 在10个样本上测试
- [ ] 调优参数 (height阈值, merge距离等)

### 中期 (PP-OCRv5研究)

**新branch**: `pp-ocrv5-research`

- [ ] 研究PaddleOCR 3.3.0新API
- [ ] 测试PP-OCRv5手写检测能力
- [ ] 对比性能: v4 vs v5
- [ ] 评估是否升级

---

## 服务器配置

### PaddleOCR服务器 (Linux)

```
Host: 192.168.30.36:5555
SSH: ssh gblinux
路径: ~/Project/paddleocr-server/
版本: PaddleOCR 2.7.3, numpy 1.26.4, opencv-contrib 4.6.0.66
启动: cd ~/Project/paddleocr-server && source venv/bin/activate && python paddleocr_server.py
日志: ~/Project/paddleocr-server/server_stable.log
```

### VLM服务器 (Ollama)

```
Host: 192.168.30.36:11434
模型: qwen2.5vl:32b
状态: 未在当前Pipeline中使用
```

---

## 测试数据

### 样本文件

```
/Volumes/NV2/PDF-Processing/signature-image-output/201301_1324_AI1_page3.pdf
- 页面: 第3页
- 预期签名: 2个 (楊智惠, 張志銘)
- 尺寸: 2481x3510 pixels
```

### 输出目录

```
/Volumes/NV2/PDF-Processing/signature-image-output/
├── mask_test/              # 基础遮罩测试结果
├── paddleocr_improved/     # Method B+E测试 (E失败)
├── opencv_separation_test/ # Method 1+2测试
└── opencv_advanced_test/   # Method 3测试 (最佳)
```

---

## 性能对比

| 方法 | 手写保留 | 印刷去除 | 总评 |
|------|---------|---------|------|
| 基础遮罩 | 100% | 低 | ⚠️ 太多印刷残留 |
| Method 1 (笔画宽度) | 0% | - | ❌ 完全失败 |
| Method 2 (连通组件) | 1% | 中 | ❌ 丢失太多手写 |
| Method 3 (综合特征) | **86.5%** | 高 | ✅ **最佳** |

---

## Git状态

```
当前分支: paddleocr-improvements
基于: PaddleOCR-Cover
标签: paddleocr-v1-basic (基础遮罩版本)

待提交:
- OpenCV高级分离方法 (Method 3)
- 完整测试脚本和结果
- 文档更新
```

---

## 已知限制

1. **参数需调优**: height阈值、merge距离等在不同文档可能需要调整
2. **依赖文档质量**: 模糊、倾斜的文档可能效果变差
3. **计算性能**: OpenCV处理较快，但完整Pipeline需要优化
4. **泛化能力**: 仅在1个样本测试，需要更多样本验证

---

## 联系与协作

**主要开发者**: Claude Code
**协作方式**: 会话式开发
**代码仓库**: 本地Git仓库
**测试环境**: macOS (本地) + Linux (服务器)

---

**状态**: ✅ 当前方案稳定，可继续开发
**建议**: 先在更多样本测试Method 3，再考虑PP-OCRv5升级