扫描件智能纠偏工具

自动检测 PDF 中方向错误（颠倒/旋转）的页面，并一键批量旋转修正。完全本地处理，无需联网，文件不离开你的电脑。

当前版本定位：这是一个可发布的“经典引擎版”扫描件纠偏工具。它优先保证离线、本地、可解释和保守决策；现代轻量方向分类模型（PaddleOCR / ONNX）适合作为后续可选引擎增强，而不是当前版本的必要前置条件。

功能特性

• 智能方向检测 — 6 种检测方法融合决策：Tesseract OSD（8 预处理变体）、霍夫变换、四向试探法、文字密度比对、区域 OSD、多区域放大重检
• 批量处理 — 一键修正整个 PDF，多线程并行检测
• 横竖版混排 — 智能识别横版、竖版页面，逐页独立判定
• 手动修正 — 自动检测遗漏时可手动指定页面旋转角度
• 处理报告 — 生成 JSON + Excel 双格式详细报告
• 100% 本地 — 所有处理在本地完成，零数据上传

效果展示

软件操作示意

扫描件处理前后对比

手动修正界面

适合谁使用

• 隐私敏感文件：合同、档案、试卷、内部资料等不适合上传云端的 PDF
• 批量纠偏工作流：需要逐页检测、批量旋转、生成报告，而不只是判断单张图片方向
• 需要可解释结果：报告中保留 method 与置信度，便于定位疑难页
• 需要人工兜底：自动检测不确定时，可通过 CLI/GUI 手动指定页码旋转

如果只追求单张图像方向分类的极限准确率，轻量 CNN/ONNX 模型通常更有优势；本项目的优势在于完整 PDF 工作流、离线部署、可解释报告和保守纠错策略。

快速开始

安装

需要 Python 3.10 或更高版本。

# 从源码安装，并注册 scan-corrector / scan-corrector-gui 命令
pip install .

# 参与开发时安装测试依赖
pip install -e ".[dev]"

从源码安装时的系统依赖

如果通过 pip install . 从源码安装，需要系统安装 Tesseract OCR（方向检测引擎）。

Windows: 下载安装 https://github.com/UB-Mannheim/tesseract/wiki，安装时勾选 OSD 方向检测数据。

macOS:

brew install tesseract

Linux (Ubuntu/Debian):

sudo apt-get install tesseract-ocr

一站式便携版用户无需安装 Tesseract：便携发布包内置了完整的 OCR 引擎和方向检测模型（位于 EXE 同级的 tesseract\ 文件夹中），解压即用。

运行

GUI 模式:

python main.py

CLI 模式:

# 自动检测并修正
python cli.py input.pdf [output_dir]

# 仅查看检测报告（不修改文件）
python cli.py --dry-run input.pdf

# 手动指定页面旋转
python cli.py --manual input.pdf 9:90 20:180 21:90 26:270

技术架构

检测决策树

detect_orientation(image)
    |
    +-- 1) Tesseract OSD — 8 种预处理变体投票
    |      variants: orig, blurred, blurred2, sharpened, binary, otsu, scaled_up, scaled_down
    |      投票: >=3 变体一致 -> +15 分; >=2 变体一致 -> +5 分
    |
    +-- 2) 霍夫变换 — 横/纵判断（惰性计算）
    |      4 阈值叠加 (50/80/110/150), 边缘 5% 裁剪
    |
    +-- 3) 四向试探 — 5 种预处理 x 4 方向 = 20 次 OSD
    |
    +-- 4) 文字密度比对 — 投影标准差，独立于 Tesseract
    |
    +-- 5) 区域 OSD — 裁剪正文区（去页眉页脚 12%）
    |
    +-- 6) 多区域放大重检 — 5 个裁剪区域各自 2x 放大后 OSD
    |
    +-- 决策树综合以上信息，给出最终判定

项目结构

scan-corrector/
    main.py                # GUI 入口
    cli.py                 # CLI 入口（自动/手动/只读报告三种模式）
    core/
        __init__.py
        pdf_handler.py     # PDF 渲染/旋转/保存（PyMuPDF）
        orientation.py     # 方向检测核心（6 种方法 + 决策树）
        rotator.py         # 批处理调度器（并行/串行/报告生成）
    gui/
        __init__.py
        main_window.py     # Tkinter GUI 界面
    utils/
        __init__.py        # 辅助函数
    tests/
        test_core.py       # 核心模块测试
    requirements.txt
    build_exe.bat         # PyInstaller 打包脚本

技术栈

依赖	用途
PyMuPDF (fitz)	PDF 渲染与 /Rotate 元数据写入
pytesseract	OSD 方向检测
Tesseract OCR 5.x	底层 OSD 引擎（需 osd.traineddata）
OpenCV	图像预处理 + 霍夫变换
NumPy	投影分析 + 数学计算
Pillow	图像格式桥接
openpyxl	Excel 报告生成

检测方法说明

方法标识	含义
tesseract_high	Tesseract 高置信度（>=20%）直接信任
tess_hough_0/90	Tesseract + 霍夫变换一致，+25 分
tess_verified_probe	Tesseract 非零 + 探针交叉验证通过
tess_density_90	Tesseract + 密度法均判断竖版
probe_rotation	四向试探明确指向非零角度
density_hough_regional_0	密度 + 霍夫 + 区域OSD 三重一致横版
regional_over_density	区域OSD 竖版覆盖密度横版
hough_90_fallback	仅霍夫检测到竖版 + 页面窄高
tess_scaled_180	放大2倍后确认180度
multi_region_*	多区域放大重检确认180度

与其他项目的对比

与 OCRmyPDF 的区别

OCRmyPDF 是优秀的 OCR 识别工具，方向检测只是其辅助功能。本项目专注于扫描件纠偏场景，与其定位不同：

特性	OCRmyPDF	本项目
主要功能	OCR 文字识别	方向检测与修正
检测方法	单一 Tesseract OSD	6 种方法融合决策
预处理变体	无	8 种预处理变体投票
四向试探法	无	✅ 20 次 OSD 交叉验证
文字密度分析	无	✅ 独立于 OCR 引擎
区域裁剪重检	无	✅ 5 区域放大检测
中文扫描优化	通用配置	✅ DPI 300、置信度调优
GUI 界面	无	✅ Tkinter 图形界面
手动修正模式	无	✅ CLI 手动指定旋转

适用场景建议

• 仅需方向修正：使用本项目，轻量、快速、无需 OCR
• 需要 OCR 识别：使用 OCRmyPDF，可附加 --rotate-pages 参数
• 两者结合：先用本项目修正方向，再用 OCRmyPDF 进行识别

与现代方向分类模型的关系

PaddleOCR / ONNX 轻量方向分类模型适合做 0/90/180/270 四分类，准确率和速度上限通常高于 Tesseract OSD。但它主要解决“单页图像方向判断”这一层，不覆盖 PDF 渲染、旋转写回、批处理、报告、GUI、手动兜底和保守决策。

本项目后续更适合演进为混合架构：

模型高置信度 -> 直接采用
模型低置信度 -> 交给现有 Tesseract + OpenCV 规则系统复核
模型与规则冲突 -> 保守不转，并在报告中标记为需人工检查

因此，现代模型是增强方向，而不是当前经典引擎版发布的阻塞项。

打包为 EXE

一站式便携版（推荐）

从源码安装仍需要 Python 和 Tesseract。面向终端用户的便携发布包则无需任何依赖：包内自带 OCR 引擎和方向检测模型，用户解压后直接双击 EXE 即可。

# 第1步：获取 Tesseract 便携文件（仅首次需要）
#   下载后校验 SHA-256 → 用 7z 安全提取（不执行安装包） → --version + OSD 冒烟测试
setup_tesseract_portable.bat

# 第2步：构建 GUI + CLI onedir 共享依赖发布包
build_exe.bat

构建输出是一个干净的 release\ 目录。每次构建都会重新创建，排除旧文件和处理报告：

release\扫描件智能纠偏工具\
  扫描件智能纠偏工具.exe           <- GUI 程序
  扫描件智能纠偏工具-cli.exe       <- CLI 程序
  _internal\                      <- 共享 Python 运行时和依赖
  tesseract\                       <- 便携 OCR 引擎
    tesseract.exe
    *.dll
    tessdata\
      osd.traineddata
  README.txt
  SHA256SUMS.txt

GUI 和 CLI 使用 PyInstaller onedir 模式打包，共享 _internal\ 目录，避免两个独立的 onefile 可执行文件各自内置 Python、OpenCV、PyMuPDF、Pillow、NumPy 等运行时文件。

将整个 release\扫描件智能纠偏工具\ 文件夹打包为 ZIP 即可分发。

发布包的使用方式

需求	命令
图形界面	双击 扫描件智能纠偏工具.exe
命令行检测报告	扫描件智能纠偏工具-cli.exe --dry-run test.pdf
命令行自动处理	扫描件智能纠偏工具-cli.exe input.pdf
命令行手动指定	扫描件智能纠偏工具-cli.exe --manual input.pdf 3:90 5:180

仅打包 EXE（不含 Tesseract）

如果目标电脑已安装 Tesseract，可直接运行 build_exe.bat（跳过第一步）。脚本检测到 vendor\tesseract\ 不完整时会询问是否仅打包 EXE。

已知限制

1. 纯图片扫描件 — 无文字或文字极少的页面，检测置信度极低
2. 非标准旋转 — 只支持 90 度整数倍旋转，不支持 1-359 度的任意角度
3. 180 度检测保守 — 180 度倒置检测极其保守，漏检率高于 90/270 度
4. 扫描噪声 — 极低质量扫描件可能导致霍夫变换误判
5. 自动检测不是承诺 100% — 当前测试集可达到很高准确率，但真实文件版式差异很大，建议保留报告检查和手动修正流程

致谢

本项目使用了以下优秀的开源组件：

依赖	许可证	用途
Tesseract OCR	Apache 2.0	OSD 方向检测引擎
PyMuPDF	AGPL v3	PDF 渲染与旋转
OpenCV	Apache 2.0	图像处理与霍夫变换
NumPy	BSD 3-Clause	数值计算
Pillow	HPND	图像格式处理
openpyxl	MIT	Excel 报告生成

许可证

本项目基于 Apache License 2.0 开源。

项目依赖的 PyMuPDF 采用 AGPL v3 / 商业双许可证。源码使用、EXE 打包或闭源再分发时，请根据实际发布方式遵守 PyMuPDF 的许可证要求；需要专有分发时可购买其商业许可证，或替换 PDF 处理依赖。本节仅作依赖许可证提示，不构成法律意见。