浏览代码

feat: add comprehensive documentation for `unclip_ratio` parameter in OCR text detection, detailing its function, effects, and configuration recommendations for optimal performance

zhch158_admin 6 天之前
父节点
当前提交
05f77c04db
共有 1 个文件被更改,包括 288 次插入0 次删除
  1. 288 0
      zhch/universal_doc_parser/unclip_ratio参数说明.md

+ 288 - 0
zhch/universal_doc_parser/unclip_ratio参数说明.md

@@ -0,0 +1,288 @@
+# `unclip_ratio` 参数说明
+
+## 📋 概述
+
+`unclip_ratio` 是 OCR 文本检测中的一个重要参数,用于控制检测框的扩展比例。
+
+## 🎯 作用原理
+
+### 1. **Vatti Clipping 算法**
+
+`unclip_ratio` 使用 **Vatti Clipping 算法**对检测到的文字区域进行扩张(unclip)。
+
+### 2. **工作原理**
+
+```
+原始检测框(可能过紧)
+┌─────────┐
+│  文本   │  ← 检测模型输出的框可能太紧,裁剪了文字边缘
+└─────────┘
+
+应用 unclip_ratio = 1.5 后
+┌───────────────┐
+│               │
+│    文本       │  ← 扩展后的框,包含完整的文字区域
+│               │
+└───────────────┘
+```
+
+### 3. **数学公式**
+
+```python
+# 计算扩展后的框尺寸
+width = x2 - x1
+height = y2 - y1
+
+new_width = width * unclip_ratio
+new_height = height * unclip_ratio
+
+# 保持中心点不变,扩展框
+center_x = x1 + width / 2
+center_y = y1 + height / 2
+
+new_x1 = center_x - new_width / 2
+new_y1 = center_y - new_height / 2
+new_x2 = center_x + new_width / 2
+new_y2 = center_y + new_height / 2
+```
+
+## 📊 参数影响
+
+### 不同 `unclip_ratio` 值的效果
+
+| unclip_ratio | 扩展程度 | 适用场景 | 优缺点 |
+|-------------|---------|---------|--------|
+| **1.0** | 不扩展 | 检测框已经很精确 | ✅ 精确度高<br>❌ 可能裁剪文字边缘 |
+| **1.3** | 轻微扩展 | 高质量扫描件 | ✅ 精确度较高<br>✅ 包含完整文字 |
+| **1.5** | 中等扩展 | **推荐值**(PPStructureV3默认) | ✅ 平衡精确度和完整性<br>✅ 适合大多数场景 |
+| **1.8** | 较大扩展 | MinerU默认,质量较差的扫描件 | ✅ 确保包含完整文字<br>❌ 可能包含过多背景 |
+| **2.0+** | 大幅扩展 | 极低质量图像 | ✅ 最大程度包含文字<br>❌ 精确度低,可能包含相邻文字 |
+
+## 🔍 实际效果对比
+
+### 示例1:正常文本
+
+```
+原始检测框(unclip_ratio=1.0)
+┌────────┐
+│ 货币资金 │  ← 可能裁剪了"货"字的左边
+└────────┘
+
+unclip_ratio=1.5(推荐)
+┌───────────┐
+│  货币资金  │  ← 包含完整文字
+└───────────┘
+
+unclip_ratio=1.8(过大)
+┌─────────────┐
+│   货币资金   │  ← 包含过多空白,可能影响识别
+└─────────────┘
+```
+
+### 示例2:密集文本(表格)
+
+```
+unclip_ratio=1.5(推荐)
+┌─────┐ ┌─────┐
+│ 资产 │ │ 负债 │  ← 框精确,不重叠
+└─────┘ └─────┘
+
+unclip_ratio=1.8(过大)
+┌──────┐┌──────┐
+│ 资产  ││ 负债 │  ← 框重叠,可能合并相邻单元格
+└──────┘└──────┘
+```
+
+## ⚙️ 参数调优建议
+
+### 1. **根据文档质量调整**
+
+```yaml
+# 高质量扫描件(清晰、无倾斜)
+ocr:
+  unclip_ratio: 1.3  # 较小扩展,保持精确
+
+# 中等质量扫描件(推荐)
+ocr:
+  unclip_ratio: 1.5  # 平衡精确度和完整性
+
+# 低质量扫描件(模糊、倾斜)
+ocr:
+  unclip_ratio: 1.8  # 较大扩展,确保包含完整文字
+```
+
+### 2. **根据文档类型调整**
+
+```yaml
+# 表格场景(密集文本)
+ocr:
+  unclip_ratio: 1.5  # 较小扩展,避免框重叠
+  enable_merge_det_boxes: false  # 不合并框
+
+# 普通文本场景
+ocr:
+  unclip_ratio: 1.6  # 中等扩展
+  enable_merge_det_boxes: true  # 可以合并框
+
+# 稀疏文本场景
+ocr:
+  unclip_ratio: 1.8  # 较大扩展,确保包含完整文字
+```
+
+### 3. **与 `box_thresh` 配合使用**
+
+```yaml
+# 严格检测 + 精确扩展
+ocr:
+  det_threshold: 0.6      # 高阈值,减少噪声框
+  unclip_ratio: 1.5       # 精确扩展
+
+# 宽松检测 + 较大扩展
+ocr:
+  det_threshold: 0.3      # 低阈值,检测更多框
+  unclip_ratio: 1.8       # 较大扩展,确保包含文字
+```
+
+## 📈 性能影响
+
+### 识别准确率
+
+| unclip_ratio | 文字完整性 | 精确度 | 相邻文字干扰 | 综合评分 |
+|-------------|----------|--------|------------|---------|
+| 1.3 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| **1.5** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | **⭐⭐⭐⭐⭐** |
+| 1.8 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
+
+### 处理速度
+
+- `unclip_ratio` 对处理速度影响很小(< 1%)
+- 主要影响识别准确率,而非速度
+
+## 🎯 推荐配置
+
+### PPStructureV3 配置(推荐)
+
+```yaml
+ocr:
+  det_threshold: 0.6
+  unclip_ratio: 1.5      # ✅ 推荐值
+  enable_merge_det_boxes: false
+```
+
+### MinerU 默认配置
+
+```yaml
+ocr:
+  det_threshold: 0.3
+  unclip_ratio: 1.8      # ⚠️ 可能过大,建议改为1.5
+  enable_merge_det_boxes: true
+```
+
+### 优化后的配置
+
+```yaml
+ocr:
+  det_threshold: 0.6     # 提高检测阈值
+  unclip_ratio: 1.5      # 降低扩展比例(从1.8改为1.5)
+  enable_merge_det_boxes: false  # 表格场景不合并
+```
+
+## 🔧 代码实现
+
+### PaddleOCR 中的使用
+
+```python
+# 在文本检测后处理中使用
+def unclip_boxes(boxes, unclip_ratio):
+    """
+    扩展检测框
+    
+    Args:
+        boxes: 检测框列表 [(x1, y1, x2, y2), ...]
+        unclip_ratio: 扩展比例(如 1.5)
+    
+    Returns:
+        扩展后的检测框列表
+    """
+    expanded_boxes = []
+    for box in boxes:
+        x1, y1, x2, y2 = box
+        width = x2 - x1
+        height = y2 - y1
+        
+        # 计算扩展后的尺寸
+        new_width = width * unclip_ratio
+        new_height = height * unclip_ratio
+        
+        # 保持中心点不变
+        center_x = x1 + width / 2
+        center_y = y1 + height / 2
+        
+        # 计算新的坐标
+        new_x1 = center_x - new_width / 2
+        new_y1 = center_y - new_height / 2
+        new_x2 = center_x + new_width / 2
+        new_y2 = center_y + new_height / 2
+        
+        expanded_boxes.append([new_x1, new_y1, new_x2, new_y2])
+    
+    return expanded_boxes
+```
+
+## ⚠️ 常见问题
+
+### Q1: `unclip_ratio` 越大越好吗?
+
+**A:** 不是。过大的 `unclip_ratio` 会导致:
+- 检测框包含过多背景
+- 相邻文字框重叠
+- 识别准确率下降
+
+**建议**:从 1.5 开始,根据实际效果调整。
+
+### Q2: 为什么 PPStructureV3 使用 1.5,而 MinerU 使用 1.8?
+
+**A:** 
+- **PPStructureV3 (1.5)**:更注重精确度,适合高质量文档
+- **MinerU (1.8)**:更注重完整性,适合低质量扫描件
+
+**建议**:对于表格等密集文本,使用 1.5 更合适。
+
+### Q3: 如何判断 `unclip_ratio` 是否合适?
+
+**A:** 检查识别结果:
+- **框太紧**:文字被裁剪 → 增大 `unclip_ratio`
+- **框太松**:包含相邻文字 → 减小 `unclip_ratio`
+- **框重叠**:相邻单元格合并 → 减小 `unclip_ratio` 或关闭 `enable_merge_det_boxes`
+
+### Q4: `unclip_ratio` 和 `box_thresh` 的关系?
+
+**A:** 
+- `box_thresh`:控制哪些检测框被保留(过滤低置信度框)
+- `unclip_ratio`:控制检测框的扩展程度(调整框的大小)
+
+两者独立,但可以配合使用:
+- 高 `box_thresh` + 低 `unclip_ratio`:严格检测,精确扩展
+- 低 `box_thresh` + 高 `unclip_ratio`:宽松检测,较大扩展
+
+## 📚 相关文档
+
+- [OCR识别差异分析与改进方案.md](./OCR识别差异分析与改进方案.md) - 参数优化说明
+- [模型统一框架.md](./模型统一框架.md) - OCR配置说明
+
+## 🎯 总结
+
+| 特性 | 说明 |
+|-----|------|
+| **作用** | 扩展文本检测框,确保包含完整文字 |
+| **算法** | Vatti Clipping 算法 |
+| **推荐值** | **1.5**(PPStructureV3默认) |
+| **范围** | 1.0 - 2.0(通常 1.3 - 1.8) |
+| **影响** | 主要影响识别准确率,对速度影响很小 |
+| **调优** | 根据文档质量和类型调整 |
+
+**最佳实践**:
+- ✅ 表格场景:`unclip_ratio=1.5`,`enable_merge_det_boxes=false`
+- ✅ 普通文本:`unclip_ratio=1.5-1.6`,`enable_merge_det_boxes=true`
+- ✅ 低质量扫描件:`unclip_ratio=1.8`,`enable_merge_det_boxes=true`
+