# 📏 表格线生成工具

> 基于 OCR bbox 结果自动生成表格线，提升无线表格识别准确率

## 🎯 功能概述

通过 OCR 识别的文本框位置（bbox）自动推测表格结构，生成标准表格线，然后应用 PPStructure 有线表格识别，显著提升准确率。

### 核心功能

- ✅ **自动检测**：基于 OCR bbox 自动分析行列结构
- ✅ **可视化调整**：Streamlit 界面支持人工微调表格线位置
- ✅ **模板复用**：将标注好的表格结构应用到同类型的其他页面
- ✅ **批量处理**：一键应用模板到整个文件夹

## 📋 完整流程

```
OCR识别(bbox) → 自动分析 → 人工调整 → 保存模板 → 批量应用 → PPStructure识别
```

## 🚀 快速开始

### 1️⃣ 准备数据

确保有以下文件：
- **OCR 结果 JSON**：包含文本框坐标（bbox）
- **对应图片**：PNG 或 JPG 格式

**支持的 OCR 格式：**
- PaddleOCR PPStructure V3 格式
- 标准 OCR 格式（含 `text` 和 `bbox` 字段）

### 2️⃣ 打开可视化编辑器

```bash
# 读取缺省配置文件./table_line_generator.yaml
streamlit run streamlit_table_line_editor.py

# 关键是在入口脚本名后加 --，后面的参数才会传递给脚本自身
streamlit run streamlit_table_line_editor.py -- --config /path/to/custom.yaml
```

### 3️⃣ 新建标注（第一页）

#### **选择模式**
在侧边栏选择 **🆕 新建标注**

#### **上传文件**
- 上传 **OCR 结果 JSON**（如 `康强_page_001.json`）
- 上传 **对应图片**（如 `康强_page_001.png`）

#### **调整参数**
- **Y轴聚类容差**：控制行检测的灵敏度（默认 5）
- **X轴聚类容差**：控制列检测的灵敏度（默认 10）
- **最小行高**：过滤高度过小的行（默认 20）

#### **分析并调整**
1. 点击 **🔍 分析表格结构**
2. 查看检测结果（行数、列数、横线数、竖线数）
3. 使用 **🛠️ 手动调整** 功能微调：
   - 调整横线/竖线位置
   - 添加横线/竖线
   - 删除横线/竖线

#### **保存配置**
1. 勾选 **保存表格结构配置**
2. 勾选 **保存表格线图片**（可选）
3. 选择线条颜色（黑色/蓝色/红色）
4. 点击 **💾 保存**

**生成文件：**
- `康强_page_001_structure.json` - 表格结构配置
- `康强_page_001_with_lines.png` - 带表格线的图片

### 4️⃣ 加载已有标注（继续调整）

#### **选择模式**
在侧边栏选择 **📂 加载已有标注**

#### **上传文件**
- 上传 **配置文件**（如 `康强_page_001_structure.json`）
- 上传 **对应图片**（可选，用于查看效果）

#### **继续调整**
- 使用相同的调整功能修改表格线
- 保存更新后的配置

### 5️⃣ 批量应用模板

将标注好的表格结构应用到同类型的其他页面。

#### **命令行方式**

**单文件模式：**
```bash
python table_template_applier.py \
  --template output/table_structures/康强_page_001_structure.json \
  --image-file data/康强_page_002.png \
  --json-file data/康强_page_002.json \
  --output-dir output/batch_results \
  --width 2 \
  --color black
```

**批量模式：**
```bash
python table_template_applier.py \
  --template output/table_structures/康强_page_001_structure.json \
  --image-dir data/images \
  --json-dir data/jsons \
  --output-dir output/batch_results \
  --width 2 \
  --color black
```

#### **无参数快速运行**

直接运行会使用默认配置：
```bash
python table_template_applier.py
```

### 6️⃣ 使用 PPStructure 识别有线表格

```bash
python batch_ocr/batch_process_pdf.py \
  -p ppstructv3 \
  -f output/batch_results/image_list.txt \
  -o output/ppstructv3_results
```

## 📊 参数说明

### 表格结构分析参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| Y轴聚类容差 | 5 | 相近行的Y坐标容差（像素） |
| X轴聚类容差 | 10 | 相近列的X坐标容差（像素） |
| 最小行高 | 20 | 过滤掉高度过小的行（像素） |

### 绘图参数

| 参数 | 选项 | 说明 |
|------|------|------|
| 线条宽度 | 1-5 | 表格线的粗细 |
| 线条颜色 | black/blue/red | 保存时的线条颜色 |

### 显示参数

| 参数 | 说明 |
|------|------|
| 显示模式 | 对比显示 / 仅显示划线图 / 仅显示原图 |
| 图片缩放 | 0.25x - 2.0x |
| 显示线条编号 | 是否显示 R1, C1 等编号 |

## 🎨 功能详解

### 自动检测算法

**行检测：**
1. 提取所有文本框的 Y 坐标
2. 按 Y 坐标排序
3. 聚类相近的 Y 坐标（容差内）
4. 过滤高度过小的行

**列检测：**
1. 提取所有文本框的 X 坐标（左边界和右边界）
2. 聚类相近的 X 坐标
3. 生成列分界线

**行高计算：**
- 排除表头行（通常较小）
- 计算数据行高度的**中位数**
- 用于批量应用时推算行数

### 模板应用原理

**固定参数（从模板继承）：**
- ✅ 表头高度
- ✅ 数据行高度
- ✅ 列宽列表
- ✅ 列的相对位置

**可变参数（自动检测）：**
- 🔄 表格起始位置（锚点）
- 🔄 行数（根据页面内容计算）

### 手动调整功能

| 功能 | 说明 |
|------|------|
| **调整横线** | 修改特定横线的 Y 坐标 |
| **调整竖线** | 修改特定竖线的 X 坐标 |
| **添加横线** | 在指定位置插入新横线 |
| **删除横线** | 批量删除选中的横线 |
| **添加竖线** | 在指定位置插入新竖线 |
| **删除竖线** | 批量删除选中的竖线 |
| **撤销/重做** | 支持多步操作回退 |

## 📁 输出文件说明

### 配置文件（`*_structure.json`）

```json
{
  "rows": [...],                    // 行区间列表
  "columns": [...],                 // 列区间列表
  "horizontal_lines": [700, 735, ...],  // 横线Y坐标
  "vertical_lines": [50, 180, ...],     // 竖线X坐标
  "header_height": 35,              // 表头高度
  "row_height": 59,                 // 数据行高度
  "col_widths": [130, 128, ...],    // 各列宽度
  "table_bbox": [x1, y1, x2, y2],   // 表格边界框
  "modified_h_lines": [0, 5],       // 修改过的横线索引
  "modified_v_lines": [2]           // 修改过的竖线索引
}
```

### 表格线图片（`*_with_lines.png`）

- **预览模式**：彩色编号（红色=已修改，蓝色=原始）
- **保存模式**：纯黑色线条，无编号

### 批量结果（`batch_results.json`）

```json
[
  {
    "source": "/path/to/page_002.png",
    "output": "/path/to/page_002_with_lines.png",
    "structure": "/path/to/page_002_structure.json",
    "num_rows": 15,
    "status": "success"
  }
]
```

## 🎯 使用场景

### 场景 1：单页表格标注

适用于表格结构固定的文档（如银行流水、报表）

```
1. 标注第1页 → 保存配置
2. 应用到其他页面
3. 批量识别
```

### 场景 2：多模板管理

适用于包含多种表格格式的文档

```
1. 为每种格式标注一个模板
2. 根据页面类型选择对应模板
3. 分别批量应用
```

### 场景 3：迭代优化

适用于初次标注不满意的情况

```
1. 加载已有配置
2. 微调表格线位置
3. 保存更新后的配置
4. 重新批量应用
```

## 🔧 故障排查

### 问题 1：检测不到行列

**原因：**
- Y/X 轴容差设置不当
- OCR 结果质量差

**解决：**
- 增大容差值
- 使用更高质量的 OCR 模型

### 问题 2：表头高度不对

**原因：**
- 表头行与数据行混在一起

**解决：**
- 使用"调整横线"功能手动分离表头
- 调整"最小行高"参数

### 问题 3：批量应用后位置偏移

**原因：**
- 不同页面的表格起始位置不同

**解决：**
- 检查 OCR 结果是否正确检测到第一行
- 模板会自动适应不同起始位置

### 问题 4：列宽不一致

**原因：**
- 不同页面的文本框宽度有细微差异

**解决：**
- 适当增大 X 轴聚类容差
- 手动调整有问题的竖线

## 📚 进阶技巧

### 技巧 1：快速定位问题线

在可视化界面中，已修改的线会标记为红色，方便追踪调整历史。

### 技巧 2：使用撤销功能

支持多步撤销/重做，可以放心尝试不同调整方案。

### 技巧 3：分段保存

处理长文档时，可以分段保存配置：
- `template_section1.json` - 表头部分
- `template_section2.json` - 数据部分

### 技巧 4：虚拟画布模式

即使没有图片，也可以加载配置文件查看坐标信息，方便检查配置正确性。

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

### 改进方向

- [ ] 支持合并单元格检测
- [ ] 支持斜线表头处理
- [ ] 支持不规则表格（非矩形）
- [ ] 导出为 Excel 格式
- [ ] 命令行批量处理增强

## 📄 许可证

MIT License

---

**作者**: [Your Name]  
**最后更新**: 2025-01-13