# 调试图像记录体系说明 ## 概述 本系统在图像识别的每个关键步骤(像素识别、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、模板匹配的调试图像保存 - 添加按日期分类的目录结构 - 添加图像标注功能 - 关联日志记录