|
|
@@ -0,0 +1,90 @@
|
|
|
+# 可视化颜色系统设计
|
|
|
+
|
|
|
+## 概述
|
|
|
+
|
|
|
+项目中有两类可视化输出：
|
|
|
+
|
|
|
+| 类型 | 模块 | 引擎 | 色域 | 对应文件 |
|
|
|
+|------|------|------|------|----------|
|
|
|
+| 模块级调试 | `module_debug_viz` | OpenCV (cv2) | BGR | `debug/layout_detection/*.png`<br>`debug/ocr_recognition/*.png` |
|
|
|
+| 用户审计图 | `visualization_utils` | PIL (ImageDraw) | RGB | `*_layout.png`、`*_ocr.png` |
|
|
|
+| Web 验证器 | `ocr_validator_layout` | Plotly | RGBA | Streamlit Web UI |
|
|
|
+
|
|
|
+**所有颜色以 `VisualizationUtils.COLOR_MAP`（RGB）为唯一权威源**，其他模块通过 `rgb_to_bgr()` 或直接读取派生所需格式。
|
|
|
+
|
|
|
+## COLOR_MAP 完整定义
|
|
|
+
|
|
|
+文件：`ocr_utils/visualization_utils.py` → `VisualizationUtils.COLOR_MAP`
|
|
|
+
|
|
|
+### 元素类别颜色（layout 图按类型着色）
|
|
|
+
|
|
|
+| 类别 | RGB | 说明 |
|
|
|
+|------|-----|------|
|
|
|
+| `title` | `(102, 102, 255)` | 蓝色 |
|
|
|
+| `text` | `(153, 0, 76)` | 深红 |
|
|
|
+| `table` / `table_body` | `(204, 204, 0)` | 黄色 |
|
|
|
+| `image` / `image_body` / `figure` | `(153, 255, 51)` | 绿色 |
|
|
|
+| `seal` | `(255, 140, 0)` | 亮橙（印章） |
|
|
|
+| `chart` | `(0, 200, 200)` | 青色 |
|
|
|
+| `header` / `footer` | `(128, 128, 128)` | 灰色 |
|
|
|
+| `abandon` / `discarded` | `(100, 100, 100)` | 深灰 |
|
|
|
+
|
|
|
+### 通用工具颜色（非元素类别）
|
|
|
+
|
|
|
+| Key | RGB | 用途 |
|
|
|
+|-----|-----|------|
|
|
|
+| `ocr_box` | `(0, 0, 255)` | 常规 OCR 文字框（亮蓝） |
|
|
|
+| `seal_ocr_box` | `(255, 140, 0)` | 印章 OCR 框（亮橙，与 layout seal 一致） |
|
|
|
+| `cell_box` | `(0, 0, 255)` | 表格单元格框（同 ocr_box） |
|
|
|
+| `discard` | `(128, 128, 128)` | 丢弃元素框（灰色） |
|
|
|
+
|
|
|
+> **向后兼容**：`OCR_BOX_COLOR`、`CELL_BOX_COLOR`、`DISCARD_COLOR` 仍可用，推荐改用 `COLOR_MAP[key]`。
|
|
|
+
|
|
|
+## 颜色转换工具
|
|
|
+
|
|
|
+```python
|
|
|
+# RGB → BGR（供 OpenCV 模块用）
|
|
|
+VisualizationUtils.rgb_to_bgr((255, 140, 0)) # → (0, 140, 255)
|
|
|
+
|
|
|
+# 从 COLOR_MAP 读取+转换
|
|
|
+from ocr_utils.module_debug_viz import _ocr_box_color_bgr
|
|
|
+_ocr_box_color_bgr() # → (255, 0, 0) (BGR 亮蓝)
|
|
|
+```
|
|
|
+
|
|
|
+## 模块间颜色引用关系
|
|
|
+
|
|
|
+```
|
|
|
+COLOR_MAP (RGB) ← 唯一权威源 (visualization_utils.py)
|
|
|
+ │
|
|
|
+ ├── visualization_utils.save_layout_images() ← 直接用 RGB
|
|
|
+ ├── visualization_utils.save_ocr_images() ← 通过 draw_ocr_spans_cv2 间接用
|
|
|
+ │
|
|
|
+ ├── module_debug_viz.draw_ocr_spans_cv2() ← 通过 _ocr_box_color_bgr() 派生 BGR
|
|
|
+ ├── module_debug_viz.draw_layout_boxes_cv2() ← LAYOUT_CATEGORY_COLORS_BGR (独立配色)
|
|
|
+ │
|
|
|
+ ├── ocr_validator_layout.py ← category_to_plotly_rgba() / ocr_box_plotly_rgba()
|
|
|
+ └── output_formatter_v2.py ← COLOR_MAP / OCR_BOX_COLOR / CELL_BOX_COLOR
|
|
|
+```
|
|
|
+
|
|
|
+## LAYOUT_CATEGORY_COLORS_BGR — 为何独立？
|
|
|
+
|
|
|
+`module_debug_viz.LAYOUT_CATEGORY_COLORS_BGR` 是 debug 图专用配色，**不与 COLOR_MAP 合并**，原因：
|
|
|
+
|
|
|
+1. **配色策略不同**：debug 图用高饱和 BGR 色 + 置信度标签，易于开发者快速定位；审计图用柔和 RGB 色 + 半透明填充 + 序号，面向最终用户
|
|
|
+2. **颜色值不同**：debug 图 text 用红色 `(255,0,0)`，审计图用深红 `(153,0,76)`；table 用红色 `(0,0,255)` vs 黄色 `(204,204,0)`——两种场景的视觉需求不同
|
|
|
+
|
|
|
+仅 **seal** 的橙色值在两表中一致（`RGB(255,140,0)` ↔ `BGR(0,140,255)`），确保印章在 debug / 审计图中视觉统一。
|
|
|
+
|
|
|
+## 新增/修改颜色步骤
|
|
|
+
|
|
|
+1. 在 `VisualizationUtils.COLOR_MAP` 中添加或修改 RGB 颜色
|
|
|
+2. `module_debug_viz` 通过 `VisualizationUtils.rgb_to_bgr(COLOR_MAP[key])` 自动获取 BGR 版本，无需手动同步
|
|
|
+3. 若为元素类别颜色，同步更新 `LAYOUT_CATEGORY_COLORS_BGR`
|
|
|
+4. 若需在 `ocr_validator` 中使用，直接读 `COLOR_MAP[key]`
|
|
|
+
|
|
|
+## 设计原则
|
|
|
+
|
|
|
+- **单一数据源**：所有颜色值只存在于 `COLOR_MAP`，派生模块不重复定义
|
|
|
+- **RGB 权威**：`COLOR_MAP` 存储 RGB，BGR 通过 `rgb_to_bgr()` 派生
|
|
|
+- **印章视觉统一**：debug 图、审计图、OCR 图中 seal 均为亮橙 `RGB(255,140,0)`
|
|
|
+- **OCR 框独立配色**：常规 OCR 框亮蓝、印章 OCR 框亮橙，一图区分两种管线来源
|
