PDF to Excel GUI（保留版式）

这是一个桌面 GUI 工具，用于把 PDF 转成 Excel，并尽量保留原始版式（行列相对位置、块状结构、基础边框感）。

1. 这个“格式几乎不变”是怎么做到的

核心不是“按行读文本”，而是“按坐标重建版面”：

1. 从 PDF 读取每个文本块/单词的坐标（x、y、宽、高）
2. 对 x 坐标做聚类，得到“列轨道”；对 y 坐标做聚类，得到“行轨道”
3. 把文本块映射到最接近的 Excel 单元格
4. 根据坐标跨度尝试合并单元格
5. 按页面高度映射 Excel 行高、按页面宽度映射列宽
6. 读取 PDF 的线条信息，映射为 Excel 边框（基础还原）

注意：PDF 本质是“绘图结果”，不是结构化表格。任何“100% 完全一致”都很难保证。这个方案是业界最常用、效果最稳定的可控方案。

2. 功能清单

• 单个 PDF 转换为 Excel
• 批量处理文件夹下所有 PDF
• GUI 实时日志 + 进度条
• 输出目录可自定义
• 支持每页转换到独立工作表
• 支持 OCR 兜底（可选插件，处理扫描版/图片型 PDF）
• 支持可视化调参（X/Y 聚类容差）
• 支持严格保真模式（页面外观优先，几乎与 PDF 完全一致）

3. 运行环境

• Windows / macOS / Linux
• Python 3.10+

4. 安装

4.1 创建虚拟环境（推荐）

python -m venv .venv

Windows 激活：

.venv\Scripts\activate

4.2 安装依赖

pip install -r requirements.txt

5. 启动 GUI

python app.py

6. 参数与返回说明

6.1 单文件转换

• 输入参数：
  • pdf_path: PDF 文件路径
  • output_path: 输出 Excel 文件路径
• 返回：
  • 成功返回 True 与消息文本
  • 失败返回 False 与错误原因

6.2 批量转换

• 输入参数：
  • input_dir: PDF 所在目录
  • output_dir: Excel 输出目录
• 返回：
  • 总数、成功数、失败数、失败详情

7. 项目结构

PDFtoEXCEL/
├─ app.py
├─ requirements.txt
├─ README.md
└─ pdf_to_excel/
   ├─ __init__.py
   └─ converter.py

8. 已知限制

• 扫描版 PDF 的 OCR 依赖目前为可选插件，在 Python 3.14 下暂不可直接安装
• 超复杂图文混排可能出现位置偏移
• 跨页复杂表格无法做到绝对一致

严格保真模式说明（硬性保外观）

• 当前 GUI 已强制开启严格保真模式（不可关闭）。
• 每页 PDF 会以高分辨率渲染图像写入 Excel。
• 该模式目标是视觉结果与原 PDF 尽量一致，适合“格式不能变”的场景。
• 该模式输出内容主要用于展示/打印，不适合做单元格级数据编辑。

OCR 可选插件说明

当前主功能在 Python 3.14 下可正常使用。
若你希望启用 OCR 兜底，请使用 Python 3.12/3.11 创建环境后额外安装：

pip install rapidocr-onnxruntime numpy

9. 下一步改进建议

• 增加“模板学习模式”（对特定供应商单据做规则增强）
• 增加导出质量评分与可视化校验页面
• 增加一键打包 .exe（PyInstaller）和自动更新机制

10. 最小化打包（Windows）

目标：生成尽量小、可直接双击运行的单文件 exe。

10.1 一键打包（推荐）

在项目根目录执行：

powershell -ExecutionPolicy Bypass -File .\build_minimal.ps1

打包完成后产物位置：

• dist/PDFtoEXCEL_min.exe

10.2 手动打包命令（等价）

.\.venv\Scripts\python -m PyInstaller --clean --noconfirm --onefile --windowed .\app.py --name PDFtoEXCEL_min --collect-all customtkinter --exclude-module matplotlib --exclude-module scipy --exclude-module IPython --exclude-module notebook --exclude-module jupyter --exclude-module pytest --exclude-module pandas

10.3 体积说明

• --onefile：单文件可执行程序，便于发给别人使用
• --exclude-module ...：排除本项目没用到的大包，减小体积
• 首次启动会比源码运行稍慢（属正常现象）

10.4 常见问题

• 如果提示缺少依赖，先执行：pip install -r requirements.txt pyinstaller
• 若被杀毒软件拦截，请将 dist 目录加入信任后再试