feat: 更新README文档，增强OCR可视化验证系统的功能描述和使用指南

README.md

@@ -1,303 +1,374 @@
-# OCR验证系统
-
-一个基于视觉语言模型(VLM)的OCR识别与验证系统，专门用于处理财务报表、数据表格等文档的OCR识别和结果对比验证。
-
-## ✨ 主要功能
-
-- 🔍 **高精度OCR识别**：使用多模态大语言模型进行图片文字识别
-- 📊 **智能表格处理**：专业的表格结构识别和数据提取，支持DataFrame分析
-- 🔧 **数字格式标准化**：自动处理全角/半角字符、千分符格式
-- 📝 **结果对比验证**：详细的OCR结果差异分析
-- 🎯 **可视化校验**：点击文本高亮图片位置，快速发现识别错误
-- 📈 **多种输出格式**：支持Markdown、JSON、DataFrame表格等格式输出
-- ⚙️ **灵活配置**：支持多种API提供商和参数调整
+# 🔍 OCR 可视化验证系统
+
+一个功能强大的 OCR 识别与验证系统，集成了多种 OCR 工具支持、智能交叉验证、可视化校验和表格数据分析功能，专为财务报表、数据表格等复杂文档设计。
+
+## ✨ 核心功能
+
+### 🎯 多工具 OCR 支持
+- **Dots OCR**：专业 VLM OCR 引擎
+- **PaddleOCR PPStructV3**：结构化文档识别
+- **Table Recognition V2**：专业表格识别
+- **MinerU VLM-2.5.3**：多模态文档理解
+
+### 🔄 智能交叉验证
+- **多数据源对比**：支持不同 OCR 工具结果的交叉验证
+- **细粒度差异检测**：精确到单元格级别的差异分析
+- **智能表格对比**：
+  - 标准表格模式
+  - 流水表格模式（支持表头位置检测）
+- **差异分类统计**：
+  - 金额差异（`table_amount`）
+  - 日期时间差异（`table_datetime`）
+  - 文本差异（`table_text`）
+  - 表头差异（位置、内容、结构）
+  - 段落差异
+
+### 📊 可视化校验工具
+- **交互式图像标注**：点击文本高亮对应图像位置
+- **精确坐标定位**：基于 bbox 的精确位置标示
+- **旋转角度处理**：
+  - 自动检测文档旋转角度
+  - 支持手动调整旋转
+  - 智能坐标转换
+- **多渲染模式**：
+  - HTML 渲染（支持横向滚动）
+  - Markdown 渲染
+  - DataFrame 表格
+  - 原始文本
+
+### 📈 表格数据分析
+- **智能表格解析**：自动识别并转换 HTML 表格
+- **交互式操作**：
+  - 过滤（按列值、关键词）
+  - 排序（升序/降序）
+  - 分页显示
+  - 列选择显示
+- **数据导出**：支持 CSV、Excel 格式
+- **统计分析**：自动生成数值列统计信息
+
+### 🔧 数字标准化
+- 全角/半角字符转换
+- 千分位分隔符标准化
+- 小数点格式统一
+- 支持批量标准化处理
 
 ## 🚀 快速开始
 
 ### 环境配置
 
 ```bash
-# 创建conda环境
+# 创建 conda 环境
 conda create -n py312 python=3.12 -y
 conda activate py312
 
-#
-git config --local user.name "zhch158_admin"
-git config --local user.email "zhch158@sina.com"
-# 自定义缓存时间（如7200秒）
-git config --global credential.helper 'cache --timeout=7200'
-
 # 克隆项目
 git clone https://gitee.com/zhch158_admin/ocr_verify.git
 cd ocr_verify
 
 # 安装依赖
-pip install openai python-dotenv beautifulsoup4 markdown streamlit plotly pandas pillow numpy opencv-python openpyxl
+pip install -r requirements.txt
+# 或手动安装
+pip install streamlit plotly pandas pillow numpy opencv-python openpyxl \
+    beautifulsoup4 pyyaml fuzzywuzzy python-Levenshtein
 ```
 
-### 环境变量配置
-
-复制 [.env](.env) 文件并配置您的API密钥：
-
-```bash
-cp .env.example .env
-# 编辑.env文件，配置相应的API密钥
+### 配置文件
+
+编辑 [`config.yaml`](config.yaml) 配置数据源：
+
+```yaml
+data_sources:
+  - name: "至远彩色_2023年报"
+    ocr_tool: "ppstructv3"
+    ocr_out_dir: "/path/to/ppstructv3/output"
+    src_img_dir: "/path/to/source/images"
+    description: "使用 PPStructV3 的识别结果"
+  
+  - name: "至远彩色_2023年报"
+    ocr_tool: "mineru"
+    ocr_out_dir: "/path/to/mineru/output"
+    src_img_dir: "/path/to/source/images"
+    description: "使用 MinerU 的识别结果"
 ```
 
-支持的API提供商：
-
-- DeepSeek
-- 阿里云DashScope
-- ModelScope
-- Google Gemini
-- Ollama (本地部署)
-
 ## 📖 使用指南
 
-### 1. OCR识别
-
-使用 [ocr_by_vlm.py](ocr_by_vlm.py) 进行图片OCR识别：
+### 1️⃣ 启动可视化验证工具
 
 ```bash
-# 标准OCR识别（启用数字标准化）
-python ocr_by_vlm.py image.png -o output/
+# 启动 Streamlit 应用
+python -m streamlit run streamlit_ocr_validator.py
 
-# 禁用数字标准化
-python ocr_by_vlm.py image.png --no-normalize
+# 或使用启动脚本
+python run_streamlit_validator.py
+```
 
-# 批量标准化已有文件
-python ocr_by_vlm.py --batch-normalize ./markdown_files/ -o ./normalized/
+**功能模块：**
 
-# 自定义参数
-python ocr_by_vlm.py image.png -t 0.05 -m 8192 --timeout 300
-```
+#### 📄 内容人工检查
+- 选择数据源和页码
+- 点击文本内容查看图像位置
+- 旋转图像调整角度
+- 显示所有文本框或仅显示选中框
 
-**参数说明：**
+#### 🔍 交叉验证结果
+- 选择两个不同的 OCR 数据源
+- 点击「交叉验证」按钮运行批量验证
+- 查看详细的差异对比结果
+- 下载验证报告（Excel、JSON）
 
-- `-o, --output`：输出目录
-- `-t, --temperature`：生成温度（默认0.1）
-- `-m, --max-tokens`：最大token数（默认4096）
-- `--timeout`：超时时间（默认180秒）
-- `--no-normalize`：禁用数字标准化
-- `--batch-normalize`：批量标准化模式
+#### 📊 表格分析
+- 解析 HTML 表格为 DataFrame
+- 过滤、排序、搜索表格数据
+- 导出表格为 CSV 或 Excel
+- 查看统计信息
 
-### 2. 结果对比
+### 2️⃣ 命令行对比工具
 
-使用 [`compare_ocr_results.py`](compare_ocr_results.py) 对比两个OCR结果：
+使用 [`compare_ocr_results.py`](compare_ocr_results.py) 进行命令行对比：
 
 ```bash
 # 基本对比
 python compare_ocr_results.py file1.md file2.md
 
-# 指定输出格式和文件名
-python compare_ocr_results.py file1.md file2.md -o comparison_result -f both
+# 使用流水表格模式
+python compare_ocr_results.py file1.md file2.md \
+    --table-mode flow_list \
+    --similarity-algorithm ratio \
+    -o output/comparison_result \
+    -f both
 
-# 生成详细报告
-python compare_ocr_results.py file1.md file2.md --ignore-images
+# 仅生成 JSON 报告
+python compare_ocr_results.py file1.md file2.md \
+    -f json -o report
 ```
 
-**输出格式：**
-
-- JSON报告：机器可读的详细差异数据
-- Markdown报告：人类友好的对比报告
-
-### 3. 高级验证功能
-
-查看 [`ocr_vlm_verify`](ocr_vlm_verify) 目录了解升级后的验证功能：
-
-```bash
-# 运行高精度验证演示
-cd ocr_vlm_verify
-python quick_demo.py
+**参数说明：**
+- `-o, --output`：输出文件名（不含扩展名）
+- `-f, --format`：输出格式（`json`、`markdown`、`both`）
+- `--table-mode`：表格比对模式（`standard`、`flow_list`）
+- `--similarity-algorithm`：相似度算法（`ratio`、`partial_ratio`、`token_sort_ratio`、`token_set_ratio`）
+- `--ignore-images`：忽略图片内容对比
 
-# 查看升级对比说明
-cat README_Upgrade_Comparison.md
-```
+### 3️⃣ 数字标准化工具
 
-### 4. 🎯 OCR可视化校验工具
+使用 [`normalize_financial_numbers.py`](normalize_financial_numbers.py)：
 
-提供多种交互方式的OCR结果校验工具：
+```python
+from normalize_financial_numbers import normalize_financial_numbers, normalize_json_file
 
-#### Web版本（推荐）
-```bash
-# Streamlit完整版本 - 功能丰富
-python3 -m streamlit run streamlit_ocr_validator.py
+# 标准化文本中的数字
+text = "２０２３年净利润为２８，２３９，３０５．４８元"
+normalized = normalize_financial_numbers(text)
+# 输出: "2023年净利润为28,239,305.48元"
 
-# 或使用启动脚本
-python3 run_streamlit_validator.py
+# 批量标准化 JSON 文件
+normalize_json_file("input.json", "output.json")
 ```
 
-**功能特点：**
-- 🖱️ **点击交互**：点击文本内容，图片显示对应位置的红色边框
-- 📍 **精确定位**：基于bbox坐标精确标示文本位置  
-- 💡 **直观校验**：快速发现OCR识别错误和位置偏差
-- 📊 **数据分析**：统计图表和详细数据视图（Streamlit版）
-- ❌ **错误管理**：标记和管理识别错误（Streamlit版）
-- 📈 **表格分析**：HTML表格转DataFrame，支持排序、过滤、导出
-
-
-详细使用说明：
-- [Streamlit版本指南](STREAMLIT_GUIDE.md)
-
 ## 📁 项目结构
 
 ```
 ocr_verify/
-├── .env                        # 环境变量配置
-├── README.md                   # 项目说明文档
-├── ocr_by_vlm.py              # 主OCR识别脚本
-├── compare_ocr_results.py     # 结果对比工具
-├── streamlit_ocr_validator.py # 完整Streamlit校验工具
-├── run_streamlit_validator.py # Streamlit启动脚本
-├── STREAMLIT_GUIDE.md         # Streamlit版使用指南
-├── ocr_vlm_verify/            # 用vlm直接校验，效果不佳，无法比对表格数字
-│   ├── ocr_verification.py    # 高级验证功能
-│   ├── quick_demo.py          # 功能演示
-│   ├── simple_ocr_test.py     # 简化测试
-│   └── README_Upgrade_Comparison.md  # 升级说明
-├── sample_data/               # 测试样本数据
-├── output/                    # 输出结果目录
-├── image_edit/               # 图片处理工具
-│   ├── config.yaml            # 图片处理配置
-│   ├── fix_photo.sh           # 图片修复脚本
-│   ├── image_generator.py     # 图片生成工具
-│   └── output/               # 图片处理输出
-└── __pycache__/              # Python缓存
+├── streamlit_ocr_validator.py          # 主应用入口
+├── streamlit_validator_core.py         # 核心验证器类
+├── streamlit_validator_ui.py           # UI 组件
+├── streamlit_validator_table.py        # 表格处理
+├── streamlit_validator_cross.py        # 交叉验证
+├── streamlit_validator_result.py       # 结果展示
+├── ocr_validator_layout.py             # 布局管理
+├── ocr_validator_utils.py              # 工具函数
+├── ocr_validator_file_utils.py         # 文件处理
+├── compare_ocr_results.py              # OCR 结果对比
+├── normalize_financial_numbers.py      # 数字标准化
+├── config.yaml                         # 配置文件
+├── styles.css                          # 样式文件
+├── output/                             # 输出目录
+│   └── pre_validation/                 # 交叉验证结果
+├── .streamlit/                         # Streamlit 配置
+│   └── config.toml                     # Streamlit 设置
+└── README.md                           # 项目文档
 ```
 
-## 🔧 核心功能详解
-
-### OCR识别功能
+## 🎯 核心功能详解
 
-- **多模态识别**：支持图片转Markdown格式
-- **数字标准化**：自动处理财务数据格式
-- **表格优化**：专业的表格结构识别
-- **格式保持**：保持原文档的布局结构
+### 交叉验证流程
 
-### 对比验证功能
+1. **数据源选择**
+   - 选择 OCR 数据源（如 PPStructV3）
+   - 选择验证数据源（如 MinerU）
 
-- **表格差异检测**：逐项对比表格数据
-- **段落差异分析**：智能段落匹配对比
-- **金额验证**：专门的数字金额对比
-- **位置定位**：精确的差异位置标记
+2. **批量验证**
+   - 自动匹配相同页码的文件
+   - 逐页进行差异检测
+   - 生成详细验证报告
 
-### 可视化校验功能
+3. **差异分析**
+   - 表格差异：逐单元格对比
+   - 段落差异：智能段落匹配
+   - 结构差异：表头位置、行缺失等
 
-- **交互式界面**：点击文本高亮图片位置
-- **bbox精确定位**：基于坐标的准确位置标示
-- **快速错误发现**：直观的视觉校验方式
-- **多格式支持**：兼容各种OCR输出格式
+4. **结果展示**
+   - 差异列表（按类型、严重程度分类）
+   - 统计图表（饼图、柱状图）
+   - 详细对比视图（左右对照）
 
-### 表格数据分析功能 ⭐ 新增
+### 表格对比算法
 
-- **HTML表格解析**：自动识别并转换HTML表格为DataFrame
-- **多种渲染模式**：HTML渲染、Markdown渲染、DataFrame表格、原始文本
-- **表格交互操作**：过滤、排序、搜索、编辑
-- **数据导出**：支持CSV、Excel格式导出
-- **统计分析**：自动生成表格统计信息
+#### 标准模式 (`standard`)
+- 适用于结构固定的表格
+- 逐行逐列对比
+- 适合财务报表、数据统计表
 
-### 数字标准化功能
+#### 流水表格模式 (`flow_list`)
+- 智能检测表头位置
+- 支持表头前内容对比
+- 自动列类型检测（数字、日期、文本）
+- 适合银行流水、交易记录等
 
-自动处理以下格式转换：
+### 图像旋转处理
 
-- 全角数字 → 半角数字
-- 全角标点 → 半角标点
-- 千分符标准化
-- 小数点格式统一
+```python
+# 自动检测旋转角度
+detection_result = detect_image_orientation_by_opencv(image_path)
 
-## 📊 使用示例
+# 手动调整旋转
+validator.layout_manager.rotated_angle = 90  # 顺时针 90 度
 
-### 示例1：处理财务报表
+# 坐标自动转换
+rotated_image, rotated_bboxes = rotate_image_and_coordinates(
+    image, angle, coordinates_list, rotate_coordinates=True
+)
+```
 
-```bash
-# 识别财务报表图片
-python ocr_by_vlm.py 财务报表.png -o output/
+## 📊 输出示例
 
-# 使用Streamlit工具分析表格
-python -m streamlit run streamlit_ocr_validator.py
+### 交叉验证报告
 
-# 对比两个版本的识别结果
-python compare_ocr_results.py output/财务报表.md reference/标准版本.md -o 对比报告
+#### JSON 格式
+```json
+{
+  "differences": [
+    {
+      "type": "table_amount",
+      "position": "第15行第5列",
+      "file1_value": "15.00",
+      "file2_value": "15,00",
+      "description": "金额不一致: 15.00 vs 15,00",
+      "severity": "medium",
+      "column_name": "金额",
+      "column_type": "numeric"
+    }
+  ],
+  "statistics": {
+    "total_differences": 42,
+    "table_differences": 35,
+    "amount_differences": 8,
+    "datetime_differences": 3,
+    "text_differences": 24,
+    "paragraph_differences": 7,
+    "high_severity": 8,
+    "medium_severity": 20,
+    "low_severity": 14
+  }
+}
 ```
 
-### 示例2：批量处理
+#### Markdown 格式
+```markdown
+# OCR结果对比报告
+
+## 统计信息
+- 总差异数量: **42**
+- 表格差异: **35**
+  - 金额差异: **8**
+  - 日期差异: **3**
+  - 文本差异: **24**
+- 段落差异: **7**
+
+## 差异详情
+| 序号 | 位置 | 类型 | 原OCR结果 | 验证结果 | 描述 |
+|------|------|------|-----------|----------|------|
+| 1 | 第15行第5列 | table_amount | 15.00 | 15,00 | 金额不一致 |
+```
 
-```bash
-# 批量标准化已有的Markdown文件
-python ocr_by_vlm.py --batch-normalize ./原始文件/ -o ./标准化文件/
+## 🔧 高级配置
+
+### OCR 工具配置
+
+在 [`config.yaml`](config.yaml) 中配置工具参数：
+
+```yaml
+ocr:
+  tools:
+    ppstructv3:
+      name: "PPStructV3"
+      json_structure: "object"
+      rotation:
+        coordinates_are_pre_rotated: true
+    
+    mineru:
+      name: "MinerU"
+      json_structure: "array"
+      rotation:
+        coordinates_are_pre_rotated: false
 ```
 
-### 示例3：表格数据分析 ⭐ 新增
+### Streamlit 配置
 
-```bash
-# 启动Streamlit进行表格分析
-python -m streamlit run streamlit_ocr_validator.py
+编辑 [`.streamlit/config.toml`](.streamlit/config.toml)：
 
-# 在界面中：
-# 1. 选择包含表格的OCR结果文件
-# 2. 选择"DataFrame表格"渲染模式
-# 3. 使用过滤、排序功能分析数据
-# 4. 导出Excel或CSV文件
-```
+```toml
+[theme]
+primaryColor = "#0288d1"
+backgroundColor = "#ffffff"
+secondaryBackgroundColor = "#f5f5f5"
 
-### 表格处理能力升级 ⭐ 新增
+[server]
+maxUploadSize = 200
+enableXsrfProtection = true
+```
 
-- **智能表格识别**：自动检测HTML表格并转换为可分析的DataFrame
-- **多维度过滤**：支持按列内容、数值范围等条件过滤
-- **数据可视化**：集成Plotly图表，支持交互式数据展示
-- **批量导出**：一键导出所有表格为Excel文件，支持多工作表
+## 🐛 常见问题
 
-详细升级内容请查看 [`ocr_vlm_verify/README_Upgrade_Comparison.md`](ocr_vlm_verify/README_Upgrade_Comparison.md)
+### Q1: 图像显示位置不正确？
+**A:** 检查 OCR 工具的坐标是否已预旋转，在 `config.yaml` 中调整 `coordinates_are_pre_rotated` 设置。
 
-## 🔧 Visual Studio Code配置
+### Q2: 交叉验证结果为空？
+**A:** 确保两个数据源包含相同页码的文件，且文件名格式为 `*_page_XXX.json`。
 
-项目包含预配置的VSCode调试配置，请参考 [`.vscode/launch.json`](.vscode/launch.json)：
+### Q3: 表格对比差异过多？
+**A:** 尝试切换到 `flow_list` 模式，或调整相似度算法参数。
 
-```json
-{
-    "configurations": [
-        {
-            "name": "Python Debugger: Current File",
-            "type": "debugpy",
-            "request": "launch",
-            "program": "${file}",
-            "console": "integratedTerminal",
-            "cwd": "${fileDirname}",
-            "env": {"PYTHONPATH":"${workspaceFolder};${env:PYTHONPATH}"},
-            "envFile": "${workspaceFolder}/.env",
-            "justMyCode": false
-        }
-    ]
-}
-```
+## 📝 开发说明
 
-## 📄 输出示例
+### 扩展开发
+- 新增 OCR 工具：在 `ocr_validator_utils.py` 中添加解析函数
+- 自定义对比算法：继承 `OCRResultComparator` 类
+- 新增渲染模式：在 `ocr_validator_layout.py` 中扩展
 
-### OCR识别输出
+## 🤝 贡献指南
 
-- **Markdown文件**：格式化的文档内容
-- **JSON元数据**：处理信息和配置参数
-- **标准化报告**：字符变更统计
+欢迎提交 Issue 和 Pull Request！
 
-### 对比报告示例
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 提交 Pull Request
 
-查看 [`output/comparison_result.md`](output/comparison_result.md) 了解详细的对比报告格式。
+## 📄 许可证
 
-### 表格分析输出 ⭐ 新增
+本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
 
-- **DataFrame视图**：可交互的表格数据展示
-- **统计报告**：表格行列数、数值列统计、数据类型分析
-- **导出文件**：CSV、Excel格式的表格数据
-- **可视化图表**：基于表格数据的统计图表
+## 📞 联系方式
 
+- **作者**: zhch158_admin
+- **邮箱**: zhch158@sina.com
+- **仓库**: https://gitee.com/zhch158_admin/ocr_verify.git
 
-# config文件配置- Streamlit配置文件：[config.toml](.streamlit/config.toml)
-- 配置文件路径：`.streamlit/config.toml`
-- 详细配置说明见官方文档：
-https://docs.streamlit.io/develop/api-reference/configuration/config.toml
+## 🙏 致谢
 
-## 📞 联系方式
+---
 
-- 作者：zhch158_admin
-- 邮箱：zhch158@sina.com
-- 仓库：https://gitee.com/zhch158_admin/ocr_verify.git
+**最后更新**: 2025年10月10日