zhch158_admin 611a94104f feat(新增可视化颜色系统文档): 在README_COLOR_SYSTEM.md中新增可视化颜色系统设计文档，详细说明颜色定义、转换工具及模块间引用关系，提升项目可维护性与开发者理解。		1 сар өмнө
..
README_COLOR_SYSTEM.md	611a94104f feat(新增可视化颜色系统文档): 在README_COLOR_SYSTEM.md中新增可视化颜色系统设计文档，详细说明颜色定义、转换工具及模块间引用关系，提升项目可维护性与开发者理解。	1 сар өмнө
README_OUTPUT_FORMAT.md	674b43692f feat: 添加多个文档和工具说明，包括 OCR 平台、表格识别模块及其评估算法	6 сар өмнө

可视化颜色系统设计

概述

项目中有两类可视化输出：

类型	模块	引擎	色域	对应文件
模块级调试	`module_debug_viz`	OpenCV (cv2)	BGR	`debug/layout_detection/.png` `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]。

颜色转换工具

# 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 合并，原因：

配色策略不同：debug 图用高饱和 BGR 色 + 置信度标签，易于开发者快速定位；审计图用柔和 RGB 色 + 半透明填充 + 序号，面向最终用户
颜色值不同：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 / 审计图中视觉统一。

新增/修改颜色步骤

在 VisualizationUtils.COLOR_MAP 中添加或修改 RGB 颜色
module_debug_viz 通过 VisualizationUtils.rgb_to_bgr(COLOR_MAP[key]) 自动获取 BGR 版本，无需手动同步
若为元素类别颜色，同步更新 LAYOUT_CATEGORY_COLORS_BGR
若需在 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 框亮橙，一图区分两种管线来源

README_COLOR_SYSTEM.md