# 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': '...', '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