Skip to content

DEBUGGING.md

Latest commit

 

History

History
222 lines (151 loc) · 6.91 KB

DEBUGGING.md

File metadata and controls

222 lines (151 loc) · 6.91 KB
Raw

调试指南

本文档介绍如何调试翻译效果和排查问题。

🔍 调试流程

当翻译效果不理想时，可以通过详细日志查看中间处理步骤，找出问题所在。

开启详细日志

在"基础设置"标签页中，勾选 详细日志 选项。

详细日志会产生什么

  • 日志窗口会输出更多 DEBUG 级别信息（检测/OCR/渲染中间过程）
  • 每次运行会生成：
    • result/log_时间戳.txt（Qt UI 运行日志）
    • result/时间戳-图片名-目标语言-翻译器/（中间调试文件目录）
  • 建议仅在排查问题时开启，日常使用可关闭以减少日志噪音和磁盘占用

调试文件说明

开启详细日志后，每次运行都会在 result/时间戳-图片名-目标语言-翻译器/ 文件夹中生成调试文件：

检测阶段

  • detection_raw_boxes.png：检测器输出的原始文本框（未经过滤）

    • 显示检测器找到的所有可能的文本区域
    • 每个框用不同颜色标识

  • bboxes_unfiltered.png：经过检测器筛选后的文本框（未经过 OCR 筛选）

    • 显示通过检测器置信度阈值的文本框
    • 红色边框标识

  • hybrid_detection_boxes.png：混合检测结果（如果启用多检测器）

    • 显示多个检测器的结果融合

OCR 阶段

  • ocrs/ 文件夹：每个文本框的 OCR 识别图片

    • 0.png, 1.png, 2.png ... 每个文件对应一个文本框
    • 可以查看 OCR 识别的具体内容
    • 垂直文字会自动旋转为水平显示

  • bboxes.png：最终经过 OCR 筛选后的文本框

    • 显示成功识别出文字的文本框
    • 包含文字概率置信度信息
    • 显示文本框的阅读顺序（panel 编号）

蒙版和修复阶段

  • bboxes_with_scores.png：带有置信度分数的文本框

    • 显示每个文本框的检测置信度

  • mask_binary.png：二值化蒙版

    • 文本区域的黑白蒙版

  • mask_raw.png：原始文本擦除蒙版（热力图）

    • 未优化的原始蒙版，带颜色条显示置信度

  • mask_comparison.png：蒙版对比图（如果存在多个蒙版）

    • 对比不同蒙版生成方法的效果

  • mask_final.png：优化后的文本擦除蒙版

    • 经过膨胀和优化的最终蒙版

  • inpaint_input.png：输入到修复模型的图片

    • 准备进行修复的图片

  • inpainted.png：擦除文字后的图片

    • 文字擦除和背景修复后的结果

渲染阶段

  • balloon_fill_boxes.png：智能气泡模式的文本框（如果使用 balloon_fill 排版）

    • 显示智能气泡排版的文本框位置

  • final.png：最终翻译结果

    • 渲染译文后的完整图片

其他调试文件

  • input.png：原始输入图片（在某些处理模式下）
    • 保存的原始输入图像

可调节参数

如果检测或识别效果不理想，可以在"高级设置"标签页中调节以下参数：

检测器参数

  • 文本置信度（text_threshold）：0.1 - 0.9，默认 0.5

    • 检测器判断某个区域是否为文本的置信度阈值
    • 降低：检测更多文本，但可能误检非文本区域
    • 提高：只检测明显的文本，可能漏检模糊文本

  • 文本框生成置信度（box_threshold）：0.1 - 0.9，默认 0.5

    • 生成文本框的置信度阈值
    • 降低：生成更多文本框
    • 提高：只生成高置信度的文本框

  • Unclip 比例（unclip_ratio）：1.0 - 3.0，默认 2.5

    • 文本框扩展比例
    • 增大：文本框更大，包含更多周边区域
    • 减小：文本框更紧凑，贴合文字边缘

OCR 参数

  • OCR 置信度（prob）：0.0 - 1.0，默认 0.1
    • OCR 识别文字的置信度阈值
    • 降低：保留更多识别结果，但可能包含错误识别
    • 提高：只保留高置信度的识别结果，可能漏掉一些文字

调试流程示例

  1. 检查检测阶段：

    • 查看 bboxes_unfiltered.png，确认检测器是否找到了所有文本区域
    • 如果漏检：降低 文本置信度 和 文本框生成置信度
    • 如果误检：提高 文本置信度 和 文本框生成置信度

  2. 检查 OCR 阶段：

    • 查看 ocrs/ 文件夹中的图片，确认每个文本框的内容
    • 查看 bboxes.png，确认哪些文本框被成功识别
    • 如果识别率低：降低 OCR 置信度，或提高 Unclip 比例（让文本框包含更多周边区域）
    • 如果识别错误多：提高 OCR 置信度

常见问题排查

检测不到文本

可能原因：

  • 检测置信度过高
  • 图像分辨率太低
  • 文本颜色与背景对比度低

解决方法：

  1. 降低"文本置信度"和"边界框生成阈值"
  2. 增大"检测大小"（如 2560 或 3072）
  3. 调整图像质量后重试，或优先提高"检测大小"

OCR 识别错误

可能原因：

  • 文本框太小或太大
  • 文字模糊或变形
  • OCR 模型不适合

解决方法：

  1. 调整"Unclip比例"，让文本框更合适
  2. 尝试不同的 OCR 模型（48px、48px_ctc、mocr）
  3. 启用"混合OCR"，同时使用两个模型

翻译结果排版错误

可能原因：

  • 字体大小不合适
  • 排版模式不适合
  • 文本框位置不准确

解决方法：

  1. 调整"排版模式"（推荐"智能缩放"）
  2. 修改"字体大小偏移量"
  3. 在可视化编辑器中手动调整文本框

文字擦除不干净

可能原因：

  • 蒙版范围不够
  • 修复模型效果不佳

解决方法：

  1. 增大"遮罩扩张偏移"（默认 70，可增加到 100-150）
  2. 切换修复模型为"lama_large"（效果最好）
  3. 在可视化编辑器中手动修改蒙版

🧹 日志清理方法（Qt UI）

当你已经排查完问题，建议定期清理旧日志与调试目录。

方法 1：手动清理（推荐）

  1. 关闭 Qt UI（避免程序仍在写日志）
  2. 打开项目根目录下的 result/
  3. 删除不再需要的内容：
    • log_*.txt（运行日志）
    • 时间戳-图片名-目标语言-翻译器 这类调试目录
  4. 保留你仍需回溯的问题样本目录

方法 2：Windows PowerShell 一键清理（删除全部日志与调试目录）

在项目根目录执行：

# 删除所有日志文件
Get-ChildItem .\result -File -Filter "log_*.txt" | Remove-Item -Force

# 删除所有调试目录（目录名通常以 14 位时间戳开头）
Get-ChildItem .\result -Directory | Where-Object { $_.Name -match '^\d{14}-' } | Remove-Item -Recurse -Force

方法 3：仅清理较旧日志（保留最近 7 天）

$deadline = (Get-Date).AddDays(-7)
Get-ChildItem .\result -File -Filter "log_*.txt" | Where-Object { $_.LastWriteTime -lt $deadline } | Remove-Item -Force
Get-ChildItem .\result -Directory | Where-Object { $_.LastWriteTime -lt $deadline -and $_.Name -match '^\d{14}-' } | Remove-Item -Recurse -Force