# `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`