Files
douyin_guaji-main/docs/DEBUG_IMAGE_SYSTEM.md
T
CodexandClaude Opus 4.7 818c3139b1 docs: 收尾 DEBUG_IMAGE_SYSTEM + ocr_engine_decision 路径
- DEBUG_IMAGE_SYSTEM.md: 'path_config.py' → 'douyin/core/path_config.py'
- ocr_engine_decision.md: 'Underlying_Operations.py' → 'douyin/core/underlying_operations.py'

至此活文档(除 docs/完整技术文档.md 头部对照表里的旧→新示例外)已无
裸路径残留。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 13:38:47 +08:00

305 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 调试图像记录体系说明
## 概述
本系统在图像识别的每个关键步骤(像素识别、OCR、模板匹配)执行时,自动截取对应位置的图像并保存,建立完整的调试图像记录体系。
## 功能特性
### 1. 目录结构
调试图像按日期/会话分类存储:
```
pic/
├── debug_captures/ # 调试图像存档根目录
│ └── YYYY-MM-DD/ # 按日期分类(每天一个目录)
│ ├── 20241201_143022_pixel_detect_lucky_draw_result_before_detect_(181,1261)-(890,1389).png
│ ├── 20241201_143025_ocr_福袋内容_preprocessed_mode_0_size_590x230.png
│ └── 20241201_143030_template_match_fudai_icon_matched_score_0.8523_loc_(45,120).png
└── ocr/ # OCR临时文件目录
├── latest_attempt_pixel.png
├── latest_attempt_ocr.png
└── latest_attempt_template.png
```
### 2. 文件命名规范
调试图像文件名格式:
```
YYYYMMDD_HHMMSS_操作类型_图片名_步骤_坐标_额外信息.png
```
示例:
- `20241201_143022_pixel_detect_lucky_draw_result_before_detect_(181,1261)-(890,1389)_threshold_0.8_region_size_709x128.png`
- `20241201_143025_ocr_福袋内容_preprocessed_mode_0_size_590x230_source_screenshot.png`
- `20241201_143030_template_match_fudai_icon_matched_score_0.8523_loc_(45,120)_size_50x50.png`
### 3. 关键步骤截图
#### 3.1 像素识别(Pixel Detection)
**截图节点:**
- **检测前**:截取待检测的目标区域图像
- **检测成功**:保存检测结果,包含红色像素比例、采样点数等信息
**实现位置:**
- `douyin_pixel.py::detect_lucky_draw_result_popup()` - 抽奖结果弹窗检测
- `douyin_pixel.py::detect_attend_button_red_area()` - 参与按钮检测
**保存信息:**
- 检测区域坐标
- 红色像素比例
- 采样点数
- 阈值设置
#### 3.2 OCR识别
**截图节点:**
- **预处理后**:保存预处理后的图像(二值化、锐化、对比度增强等)
- **OCR后**:保存OCR结果,包含识别文本预览
**实现位置:**
- `douyin/core/underlying_operations.py::cut_pic()` - 裁剪图像时保存
- `douyin/core/underlying_operations.py::analyse_pic_word()` - OCR识别前后保存
**保存信息:**
- 预处理模式(彩色/二值化)
- 图像尺寸
- OCR识别文本预览
- 使用的图像版本(img1/img2)
#### 3.3 模板匹配(Template Matching)
**截图节点:**
- **匹配前**:保存搜索区域图像
- **匹配成功**:保存带匹配框标注的图像,显示匹配位置和分数
**实现位置:**
- `douyin_detection.py::check_have_fudai_with_ready_screenshot()` - 福袋图标检测
**保存信息:**
- 搜索区域坐标
- 模板文件路径
- 匹配分数
- 匹配位置坐标
- 模板尺寸
### 4. 图像标注
调试图像会自动添加标注信息:
- 在图像底部添加白色半透明背景
- 显示图片名称、步骤、坐标、额外信息等
- 模板匹配结果图像会绘制红色匹配框和分数文本
### 5. 日志关联
所有调试图像保存都会记录到日志中:
**日志格式:**
```
[调试图像] cut_pic保存: pic/debug_captures/2024-12-01/20241201_143022_cut_pic_福袋内容_before_ocr_(390,1240)-(980,1470).png
[调试图像] OCR预处理保存: pic/debug_captures/2024-12-01/20241201_143025_ocr_福袋内容_preprocessed_mode_0_size_590x230.png
[调试图像] OCR结果保存: pic/debug_captures/2024-12-01/20241201_143030_ocr_福袋内容_after_ocr_mode_0_text_len_25_text_preview_共1份1173人已参与.png, 文本: 共1份1173人已参与
[调试图像] 模板匹配前保存: pic/debug_captures/2024-12-01/20241201_143035_template_match_fudai_icon_before_match_(100,200)-(500,400).png
[调试图像] 模板匹配成功保存: pic/debug_captures/2024-12-01/20241201_143040_template_match_fudai_icon_matched_score_0.8523_loc_(45,120).png, score=0.8523, location=(45,120)
[调试图像] 像素检测前保存: pic/debug_captures/2024-12-01/20241201_143045_pixel_detect_lucky_draw_result_before_detect_(181,1261)-(890,1389).png
[调试图像] 像素检测成功保存: pic/debug_captures/2024-12-01/20241201_143050_pixel_detect_lucky_draw_result_detected_red_ratio_0.8523.png, red_ratio=0.8523
```
## 使用方法
### 查看调试图像
1. **按日期查看**:进入 `pic/debug_captures/YYYY-MM-DD/` 目录
2. **按操作类型筛选**:文件名包含操作类型(pixel_detect、ocr、template_match)
3. **按步骤筛选**:文件名包含步骤(before_detect、preprocessed、after_ocr、matched、detected)
### 排查问题
当识别出现偏差或错误时:
1. **查看日志**:找到对应的调试图像路径
2. **对比图像**:
- 检查区域定位是否准确(坐标信息)
- 检查图像预处理效果(OCR预处理图像)
- 检查匹配结果(模板匹配框位置)
- 检查像素检测结果(红色像素比例)
3. **分析问题**:
- 区域定位不准 → 调整坐标参数
- 图像预处理不当 → 调整预处理参数
- 模板选择有误 → 更换模板或调整阈值
## API 参考
### 核心函数
#### `save_debug_image()`
保存调试图像到存档目录。
**参数:**
- `image`: PIL Image 对象
- `operation_type`: 操作类型("pixel_detect", "ocr", "template_match", "cut_pic")
- `picname`: 图片名称(可选)
- `step`: 步骤描述(可选,如 "before_ocr", "preprocessed", "after_ocr")
- `coords`: 坐标信息 (x1, y1, x2, y2)(可选)
- `extra_info`: 额外信息字典(可选)
- `session_id`: 会话ID(可选,默认使用当前日期)
- `annotate`: 是否在图像上添加标注信息(默认True)
**返回:**
- 保存的文件路径,失败返回None
#### `save_debug_image_with_match_result()`
保存模板匹配结果的调试图像(带匹配框标注)。
**参数:**
- `image`: PIL Image 对象(搜索区域图像)
- `operation_type`: 操作类型
- `match_score`: 匹配分数
- `match_location`: 匹配位置 (x, y)
- `template_size`: 模板尺寸 (width, height)
- `picname`: 图片名称(可选)
- `session_id`: 会话ID(可选)
**返回:**
- 保存的文件路径,失败返回None
## 配置说明
### 目录配置
调试图像目录通过 `douyin/core/path_config.py` 配置:
- `get_pic_dir()`: 返回 pic 目录路径
- `get_debug_captures_dir()`: 返回调试图像存档目录路径
### 清理策略
建议定期清理旧的调试图像:
- 保留最近7天的调试图像
- 或设置最大文件数限制(如每个会话最多1000个文件)
## 注意事项
1. **文件大小**:调试图像可能占用较多磁盘空间,建议定期清理
2. **性能影响**:图像保存操作是异步的,不会显著影响识别性能
3. **文件名长度**:Windows系统限制文件名长度为260字符,系统会自动截断
4. **并发安全**:多线程环境下,每个线程使用独立的会话ID以避免文件名冲突
## 更新日志
### 2024-12-01
- 初始版本发布
- 实现像素识别、OCR、模板匹配的调试图像保存
- 添加按日期分类的目录结构
- 添加图像标注功能
- 关联日志记录