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

7.2 KiB
Raw Blame History

调试图像记录体系说明

概述

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