# scan-corrector

**Repository Path**: lynli/scan-corrector

## Basic Information

- **Project Name**: scan-corrector
- **Description**: 扫描件智能纠偏工具 — 基于 PyMuPDF + OpenCV 的 PDF 批量自动纠偏桌面应用，支持方向检测、手动修正、OCR 文字朝向二次校验。开箱即用，无需配置环境。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: https://www.cnblogs.com/lyn-li/p/21185047/pdf-scan-orientation-corrector
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 扫描件智能纠偏工具

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-green.svg)](https://www.python.org/)

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

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

## 功能特性

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

## 效果展示

### 软件操作示意

![软件操作示意](docs/assets/software-demo.gif)

### 扫描件处理前后对比

![扫描件处理前后对比](docs/assets/before-after-comparison.gif)

### 手动修正界面

![手动修正界面](docs/assets/manual-rotation-ui.png)

## 适合谁使用

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

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

## 快速开始

### 安装

需要 Python 3.10 或更高版本。

```bash
# 从源码安装，并注册 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**:
```bash
brew install tesseract
```

**Linux (Ubuntu/Debian)**:
```bash
sudo apt-get install tesseract-ocr
```

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

### 运行

**GUI 模式**:
```bash
python main.py
```

**CLI 模式**:
```bash
# 自动检测并修正
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 — 5 种预处理变体投票
    |      variants: orig, blurred, sharpened, binary, otsu
    |      投票: >=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 主窗口
        manual_dialogs.py  # 可视化手动修正对话框
    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 报告生成 |
| sv-ttk | Windows 11 风格主题 |

## 检测方法说明

| 方法标识 | 含义 |
|----------|------|
| `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](https://github.com/ocrmypdf/OCRmyPDF) 是优秀的 OCR 识别工具，方向检测只是其辅助功能。本项目专注于扫描件纠偏场景，与其定位不同：

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

### 适用场景建议

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

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

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

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

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

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

## 打包为 EXE

### 一站式便携版（推荐）

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

```bash
# 第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
  使用说明.md
  使用说明.txt
  LICENSE
  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](https://github.com/tesseract-ocr/tesseract) | Apache 2.0 | OSD 方向检测引擎 |
| [PyMuPDF](https://github.com/pymupdf/PyMuPDF) | AGPL v3 | PDF 渲染与旋转 |
| [OpenCV](https://github.com/opencv/opencv) | Apache 2.0 | 图像处理与霍夫变换 |
| [NumPy](https://github.com/numpy/numpy) | BSD 3-Clause | 数值计算 |
| [Pillow](https://github.com/python-pillow/Pillow) | HPND | 图像格式处理 |
| [openpyxl](https://foss.heptapod.net/openpyxl/openpyxl) | MIT | Excel 报告生成 |

## 开发说明

本项目代码由 AI 辅助编写，项目负责人负责算法设计、架构决策、功能定义和测试验证。所有代码均经人工审查和实机测试后发布。

> 产品功能基于传统计算机视觉（OpenCV）与 OCR（Tesseract OSD）算法实现，不依赖深度学习模型。

## 许可证

本项目基于 [Apache License 2.0](LICENSE) 开源。

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