- Deleted obsolete files including test scripts and configuration files to streamline the project. - Introduced new modules for handling Douyin functionalities, including core operations, logging, and GUI components. - Updated import paths to reflect the new module structure, enhancing code organization and maintainability. - Added configuration files and documentation to support the new structure and improve user guidance.
305 lines
7.1 KiB
Markdown
305 lines
7.1 KiB
Markdown
# 调试图像记录体系说明
|
||
|
||
## 概述
|
||
|
||
本系统在图像识别的每个关键步骤(像素识别、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结果,包含识别文本预览
|
||
|
||
**实现位置:**
|
||
- `Underlying_Operations.py::cut_pic()` - 裁剪图像时保存
|
||
- `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
|
||
|
||
## 配置说明
|
||
|
||
### 目录配置
|
||
|
||
调试图像目录通过 `path_config.py` 配置:
|
||
- `get_pic_dir()`: 返回 pic 目录路径
|
||
- `get_debug_captures_dir()`: 返回调试图像存档目录路径
|
||
|
||
### 清理策略
|
||
|
||
建议定期清理旧的调试图像:
|
||
- 保留最近7天的调试图像
|
||
- 或设置最大文件数限制(如每个会话最多1000个文件)
|
||
|
||
## 注意事项
|
||
|
||
1. **文件大小**:调试图像可能占用较多磁盘空间,建议定期清理
|
||
2. **性能影响**:图像保存操作是异步的,不会显著影响识别性能
|
||
3. **文件名长度**:Windows系统限制文件名长度为260字符,系统会自动截断
|
||
4. **并发安全**:多线程环境下,每个线程使用独立的会话ID以避免文件名冲突
|
||
|
||
## 更新日志
|
||
|
||
### 2024-12-01
|
||
- 初始版本发布
|
||
- 实现像素识别、OCR、模板匹配的调试图像保存
|
||
- 添加按日期分类的目录结构
|
||
- 添加图像标注功能
|
||
- 关联日志记录
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|