- 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>
7.2 KiB
7.2 KiB
调试图像记录体系说明
概述
本系统在图像识别的每个关键步骤(像素识别、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.png20241201_143025_ocr_福袋内容_preprocessed_mode_0_size_590x230_source_screenshot.png20241201_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
使用方法
查看调试图像
- 按日期查看:进入
pic/debug_captures/YYYY-MM-DD/目录 - 按操作类型筛选:文件名包含操作类型(pixel_detect、ocr、template_match)
- 按步骤筛选:文件名包含步骤(before_detect、preprocessed、after_ocr、matched、detected)
排查问题
当识别出现偏差或错误时:
-
查看日志:找到对应的调试图像路径
-
对比图像:
- 检查区域定位是否准确(坐标信息)
- 检查图像预处理效果(OCR预处理图像)
- 检查匹配结果(模板匹配框位置)
- 检查像素检测结果(红色像素比例)
-
分析问题:
- 区域定位不准 → 调整坐标参数
- 图像预处理不当 → 调整预处理参数
- 模板选择有误 → 更换模板或调整阈值
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个文件)
注意事项
- 文件大小:调试图像可能占用较多磁盘空间,建议定期清理
- 性能影响:图像保存操作是异步的,不会显著影响识别性能
- 文件名长度:Windows系统限制文件名长度为260字符,系统会自动截断
- 并发安全:多线程环境下,每个线程使用独立的会话ID以避免文件名冲突
更新日志
2024-12-01
- 初始版本发布
- 实现像素识别、OCR、模板匹配的调试图像保存
- 添加按日期分类的目录结构
- 添加图像标注功能
- 关联日志记录