# Tasks: Extract Table Cell Boxes

## 重要發現 (2025-11-28)

**PPStructureV3 (PaddleX 3.3.9) 確實提供 `table_res_list`！**

之前的實現假設需要額外調用 SLANeXt 模型，但經過深入測試發現：
- `result.json['res']['table_res_list']` 包含所有表格的 `cell_box_list`
- 不需要額外的模型調用
- 已移除多餘的 SLANeXt 代碼

## Phase 1: 基礎設施 (已完成)

### Task 1.1: 配置項
- [x] ~~添加 `enable_table_cell_boxes_extraction` 配置~~ (已移除，不再需要)
- [x] 確認 PPStructureV3 提供 `table_res_list`

### Task 1.2: 模型緩存機制
- [x] ~~實現 SLANeXt 模型緩存~~ (已移除，不再需要)
- [x] 直接使用 PPStructureV3 內建的 `table_res_list`

## Phase 2: Cell Boxes 提取 (已完成)

### Task 2.1: 從 table_res_list 提取
- [x] 從 `result.json['res']['table_res_list']` 獲取 `cell_box_list`
- [x] 通過 HTML 內容匹配表格
- [x] 驗證座標格式 (已是絕對座標)

### Task 2.2: Image-in-Table 處理
- [x] 從 `layout_det_res` 獲取 image boxes
- [x] 檢測表格內的圖片
- [x] 裁切保存圖片
- [x] 嵌入到表格 HTML

## Phase 3: PDF 生成優化 (已完成)

### Task 3.1: ~~利用 Cell Boxes 推斷網格~~ (已棄用)
- [x] ~~修改 `draw_table_region` 使用 cell_boxes~~
- [x] ~~根據實際 cell 位置計算行高列寬~~
- [x] 測試渲染效果 → **發現問題：HTML 結構與 cell_boxes 不匹配**

### Task 3.2: 方案 B - 分層渲染 (Layered Rendering) ✓ 已完成

**問題分析 (2025-11-30)**：
- HTML 表格結構與 cell_boxes 不匹配，無法正確推斷網格
- 嘗試在 cell 內繪製文字失敗（超出邊框、匹配錯誤）

**解決方案**：分層渲染 - 分離表格邊框與文字繪製
- Layer 1: 使用 cell_boxes 繪製表格邊框
- Layer 2: 使用 raw OCR positions 繪製文字（獨立於表格結構）
- Layer 3: 繪製 embedded_images

**實作步驟 (2025-11-30)**：
- [x] 修改 `GapFillingService._is_region_covered()` - 跳過 TABLE 元素覆蓋檢測
- [x] 簡化 `_draw_table_with_cell_boxes()` - 只繪製邊框 + 圖片
- [x] 修改 `regions_to_avoid` - 排除表格，讓文字穿透表格區域
- [x] 整合測試：test_layered_rendering.py

### Task 3.3: 備選方案
- [x] 當 cell_boxes 不可用時，使用 ReportLab Table
- [x] 確保向後兼容

## Phase 4: 測試與驗證 (已完成)

### Task 4.1: 單元測試
- [x] 測試 cell_box_list 提取 (29 cells 成功)
- [x] 測試 Image-in-Table 處理 (1 image embedded)
- [x] 測試錯誤處理

### Task 4.2: 整合測試
- [x] 使用實際 PDF 測試 OCR Track (test_layered_rendering.py)
- [x] 驗證 PDF 版面還原效果
- [x] 分層渲染測試結果：
  - 50 text elements (從 raw OCR 補充，原本只有 5 個)
  - 31 cell_boxes (8 + 23)
  - 1 embedded_image
  - PDF 生成成功 (57,290 bytes)

## Phase 5: 清理 (已完成)

### Task 5.1: 移除舊代碼
- [x] 移除 SLANeXt 模型緩存代碼
- [x] 移除 `_get_slanet_model()`, `_get_table_classifier()`, `_extract_cell_boxes_with_slanet()`, `release_slanet_models()`
- [x] 移除 `enable_table_cell_boxes_extraction` 配置
- [x] 清理調試日誌

---

## 技術細節

### 關鍵代碼位置

| 文件 | 修改內容 |
|------|---------|
| `backend/app/core/config.py` | 移除 `enable_table_cell_boxes_extraction` |
| `backend/app/services/pp_structure_enhanced.py` | 使用 `table_res_list`, 添加 `_embed_images_in_table()` |
| `backend/app/services/pdf_generator_service.py` | 分層渲染：只繪製邊框，排除表格區域的文字過濾 |
| `backend/app/services/gap_filling_service.py` | `_is_region_covered()` 跳過 TABLE 元素 |
| `backend/tests/test_layered_rendering.py` | 分層渲染整合測試 |

### PPStructureV3 數據結構

```python
result.json = {
    'res': {
        'parsing_res_list': [...],      # 解析結果
        'layout_det_res': {...},        # Layout 檢測結果
        'table_res_list': [             # 表格識別結果
            {
                'cell_box_list': [[x1,y1,x2,y2], ...],  # ← 關鍵！
                'pred_html': '<html>...',
                'table_ocr_pred': {...}
            }
        ],
        'overall_ocr_res': {...}
    }
}
```

### 測試結果

- Task ID: `442f9345-09ba-4a7d-949f-3bc88c2fa895`
- cell_boxes: 29 cells (source: table_res_list)
- embedded_images: 1 (img_in_table_935_838_1118_1031)

### 本地 vs 雲端差異

| 特性 | 本地 PaddleX 3.3.9 | 雲端 pp_demo |
|------|-------------------|--------------|
| `table_res_list` | ✓ 提供 | ✓ 提供 |
| `cell_box_list` | ✓ 29 cells | ✓ 27+8 cells |
| Layout 識別 | 1 個合併表格 | 2 個獨立表格 |
| Image-in-Table | 需自行處理 | 自動嵌入 HTML |

### 遺留問題

1. **Layout 識別合併表格**：本地 Layout 模型把多個表格合併成一個大表格
   - 這導致 `table_res_list` 只有 1 個表格
   - 雲端識別為 2 個獨立表格
   - 可能需要調整 Layout 模型參數或後處理邏輯

---

## 分層渲染技術設計 (2025-11-30)

### 問題根因

ReportLab Table 需要規則矩形網格，但 PPStructureV3 的 cell_boxes 反映實際視覺位置，與 HTML 邏輯結構不匹配。嘗試在 cell 內繪製文字會導致：
- 文字超出邊框
- 匹配錯誤
- 部分文字遺失

### 解決方案：分層渲染

將表格渲染解耦為三個獨立層次：

```
┌─────────────────────────────────────────┐
│  Layer 3: Embedded Images               │
│  (從 metadata['embedded_images'] 獲取)   │
├─────────────────────────────────────────┤
│  Layer 2: Text at Raw OCR Positions     │
│  (從 GapFillingService 補充的原始 OCR)   │
├─────────────────────────────────────────┤
│  Layer 1: Table Cell Borders            │
│  (從 metadata['cell_boxes'] 繪製)        │
└─────────────────────────────────────────┘
```

### 實作細節

**1. GapFillingService 修改** (`_is_region_covered`):
```python
# 跳過 TABLE 元素覆蓋檢測，讓表格內文字通過
if skip_table_coverage and element.type == ElementType.TABLE:
    continue
```

**2. PDF Generator 修改** (`regions_to_avoid`):
```python
# 排除表格，只避免與圖片重疊
regions_to_avoid = [img for img in images_metadata if img.get('type') != 'table']
```

**3. 簡化的 `_draw_table_with_cell_boxes`**:
```python
def _draw_table_with_cell_boxes(...):
    """只繪製邊框和圖片，不處理文字"""
    # 1. 繪製每個 cell 的邊框
    for box in cell_boxes:
        pdf_canvas.rect(x, y, width, height, stroke=1, fill=0)

    # 2. 繪製 embedded_images
    for img in embedded_images:
        self._draw_embedded_image(...)
```

### 優勢

1. **解耦**：邊框渲染與文字渲染完全獨立
2. **精確**：文字位置直接使用 OCR 結果，不需推斷
3. **穩定**：不受 cell_boxes 與 HTML 不匹配影響
4. **相容**：visualization 中 overall_ocr_res.png 的效果可直接還原

### 測試結果

- Task ID: `84899366-f361-44f1-b989-5aba72419ca5`
- cell_boxes: 31 (8 + 23)
- 原始 text elements: 5
- 補充後 text elements: 50 (從 raw OCR 補充)
- PDF 大小: 57,290 bytes

---

## 混合渲染優化 (2025-11-30)

### 問題發現

分層渲染後仍有問題：
1. 表格歪斜：cell_boxes 有 2-11 像素的座標偏差
2. Title 等元素樣式未應用：OCR track 不套用樣式

### 解決方案：混合渲染 + 網格對齊

**1. Cell Boxes 網格對齊** (`_normalize_cell_boxes_to_grid`):
```python
def _normalize_cell_boxes_to_grid(self, cell_boxes, threshold=10.0):
    """
    將相鄰座標聚合為統一值，消除 2-11 像素的偏差。
    - 收集所有 X/Y 座標
    - 聚類相近座標（threshold 內）
    - 使用平均值作為對齊後的座標
    """
```

**2. 元素類型樣式** (OCR track):
```python
# 在 draw_text_region 中加入元素類型檢查
element_type = region.get('element_type', 'text')

if element_type == 'title':
    font_size = min(font_size * 1.3, 36)  # 30% 放大
elif element_type == 'header':
    font_size = min(font_size * 1.15, 24)  # 15% 放大
elif element_type == 'caption':
    font_size = max(font_size * 0.9, 6)  # 10% 縮小
```

**3. 元素類型傳遞**:
```python
# convert_unified_document_to_ocr_data 中加入
text_region = {
    'text': text_content,
    'bbox': bbox_polygon,
    'element_type': element.type.value  # 新增
}
```

### 改進後效果

| 項目 | 改進前 | 改進後 |
|------|--------|--------|
| 表格邊框 | 歪斜 (2-11px 偏差) | 網格對齊 |
| Title 樣式 | 無 (與普通文字相同) | 36pt 放大字體 |
| 混合渲染 | 只用 raw OCR | PP-Structure + raw OCR |

### 測試結果 (2025-11-30)

- Task ID: `3a3f350f-2d81-4af4-8a18-021ea09ac433`
- Table 1: 8 cell_boxes → 網格對齊
- Table 2: 23 cell_boxes → 網格對齊 + 1 embedded image
- Title: Applied title style: size=36.0
- PDF 大小: 104,082 bytes
