基于 PP-OCR 的本地离线 OCR：文字检测 → 方向分类 → 文字识别。 纯离线、纯 CPU、不联网、图片不出本机。
版本：v2.0.0（首个公开发行版，纯 CPU）
提供三种形态：GUI 演示（exe） / CLI 工具 / Agent Skill。
输入图片
│
▼
[1] DB 文本检测 textbox_detect_v2 ── 找出所有文本行的四边形框
│
▼
[2] 方向分类 textbox_cls_v1 ── 判断文本行是否倒置(0°/180°)，转正
│
▼
[3] CRNN 文字识别 textbox_rec_v2 ── 逐行识别成文字（CTC 解码）
│
▼
纯文本 + 带框标注图
- 中文/英文混排，自动检测、方向矫正、逐行识别。
- 超长竖图（长宽比 > 3）自动纵向分片，重叠去重后拼接。
- 单张普通图约 0.3 s（CPU），长图按行数线性增长。
LocalOCR/
├── models/ # PP-OCR 通用权重（使用前请阅读 NOTICE.md）
│ ├── det/ textbox_detect_v2.xml/.bin
│ ├── cls/ textbox_cls_v1.xml/.bin
│ ├── rec/ textbox_rec_v2.xml/.bin + ppocr_keys_v1.txt
│ ├── optional/ dewarp_coarse/fine、doc_detect
│ └── NOTICE.md # 模型来源与使用限制
├── demo/
│ ├── ppocr_pipeline.py # 三段推理 + DB 后处理 + CTC 解码
│ ├── batch_io.py # 文件采集 / 相对路径 / 安全命名
│ ├── export_ocr.py # 逐图 .txt / 合并 .md
│ ├── ocr_demo.py # 单图 CLI
│ ├── ocr_tall.py # 超长竖图分片 CLI
│ └── make_sample.py # 生成测试图
├── app/
│ └── gui_ocr.py # GUI（拖拽/批量/任务列表/进度/导出）
├── cli/
│ └── ocr_cli.py # Agent/脚本调用（多图/文件夹/导出/--json）
├── tools/
│ ├── slim_dist.py # 打包瘦身
│ └── regress.py # 兼容性回归
├── RELEASE_NOTES.md / CHANGELOG.md
├── build_exe.bat # 一键打包
└── requirements.txt
| 形态 | 入口 | 适用 |
|---|---|---|
| GUI 演示 | dist\LocalOCR\LocalOCR.exe |
人手动操作 |
| CLI 工具 | cli\ocr_cli.py --image X --json |
脚本 / Agent |
| Agent Skill | ~/.workbuddy/skills/local-ocr/ |
Agent 自动识别 |
- 拖拽：把图片或文件夹直接拖进窗口即可（支持多图/文件夹递归）。
- 批量：
添加图片（多选）/添加文件夹，左侧任务列表显示状态、行数、耗时；带进度条与取消。 - 左侧可滚动预览：长图按宽度自适应，支持滚动条 + 鼠标滚轮 + 缩放滑块（20%–300%）。
- 右侧上下分栏：上为逐行结果（序号 / 置信度 / 文本），下为可编辑纯文本框。
- 导出：当前文本 / 当前标注图 / 每图一个
.txt/ 合并.md（## 文件名分段）。
# 单图
.venv\Scripts\python.exe cli\ocr_cli.py --image demo\sample.png
# 多图 / 整个文件夹（递归），并导出
.venv\Scripts\python.exe cli\ocr_cli.py --image a.png b.png --json
.venv\Scripts\python.exe cli\ocr_cli.py --dir pics --out-dir out --merge-file out\all.md⛔ Agent 硬性规定：必须传图片真实文件路径，禁止传聊天窗口剪贴板 /
blobs图片——粘贴管线会按长边 1920 压缩，识别必然失败。CLI 已内置拦截（退出码 4）。
# 直接跑（环境已就绪）
.venv\Scripts\python.exe demo\ocr_demo.py --image demo\sample.png
# 从零搭建
python -m venv --system-site-packages .venv
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple openvino opencv-python numpy Pillow tkinterdnd2build_exe.bat # -> dist\LocalOCR（约 286MB，纯 CPU）手动构建（必须用干净环境，避免无关包干扰 PyInstaller）：
.venv-build\Scripts\python.exe -m PyInstaller --noconfirm --clean --onedir --windowed ^
--name LocalOCR --paths demo ^
--add-data "models;models" --add-data "demo/sample.png;demo" ^
--collect-binaries openvino --collect-data openvino ^
--collect-all tkinterdnd2 ^
app\gui_ocr.py
.venv-build\Scripts\python.exe tools\slim_dist.py --dist "dist\LocalOCR\_internal"自检：dist\LocalOCR\LocalOCR.exe --selftest，结果写入 dist\LocalOCR\selftest.log。
| 阶段 | 输入 | 输出 |
|---|---|---|
| 检测 | x : [?,3,?,?] |
sigmoid : [?,1,?,?] |
| 方向 | x : [?,3,?,?] |
softmax : [?,2] |
| 识别 | x : [?,3,48,?] |
softmax : [?,?,6625] |
- 识别类别 6625 = 1(blank) + 6623(字典) + 1(空格)。
- 输入为动态尺寸：检测/方向对 H、W 无约束（建议 32 的倍数），识别固定高 48、宽自由。
- 推理：OpenVINO Runtime（CPU），IR 格式。
- 图像：OpenCV（透视裁剪、DB 后处理）。
- 解码：纯 Python CTC 贪心解码（合并重复 + 去 blank）。
- 路径兼容：
cv2.imread在 Windows 下不支持非 ASCII 路径，已用np.fromfile + cv2.imdecode封装替代。
| 参数 | 位置 | 默认 | 调大效果 |
|---|---|---|---|
limit_side_len |
detect() |
960/1280 | 小字更准，更慢 |
thresh |
detect() |
0.3 | 减少误检，可能漏检 |
box_thresh |
detect() |
0.6 | 过滤低质量框 |
unclip_ratio |
detect() |
1.6 | 框更松，适合密排文字 |
tile |
长图模式 | 1200 | 分片更高，重叠更少 |
测试图：1080×25070 长截图（约 316 行），纯 CPU，仅计推理时间（不含模型编译）。
| 配置 | 耗时 | 相对基线 |
|---|---|---|
基线（逐行识别、limit 1280） |
8.30 s | 1.00× |
+ 批量识别（默认，batch=32） |
4.76 s | 1.74× |
+ 检测限 960（--limit 960） |
4.01 s | 2.07× |
+ 跳过方向分类（--no-cls） |
3.52 s | 2.36× |
- 批量识别已默认开启：多行按最大宽度 padding 成
[N,3,48,Wmax]一次推理，无精度损失。 - 小图（5 行）同样受益：0.063 s → 0.049 s。
THROUGHPUT性能提示在本机反而更慢（0.10 s vs 0.06 s），故未启用。- FP16 量化在本机提升 < 5%，未采用。
- 更大的分片（1800/2400）可再快 ~20%，但会增加行合并误差，默认仍用 1200。
建议：
- 默认配置已优化（批量），一般无需改动。
- 追求速度：
--limit 960 --no-cls --batch 32（端正文档可用；GUI 勾选「快速模式」）。 - 追求质量：保持
limit 1280并开启方向分类。 - 批量处理多图：复用同一进程，避免每次重复编译模型（单次省约 1 s）。
| 现象 | 原因 / 处理 |
|---|---|
| 打开图片不显示 | 已修复（ImageTk 导入缺失）；当前版本改用可滚动 Canvas |
| 长图只能看到一条 | 已修复：按宽度自适应 + 滚动条/滑块 |
| 识别全是碎片 | 图片被降采样（宽 < 300px），换原图 |
| 中文路径读不到 | 已用 imread_unicode 修复 |
| 文字正确但缺空格 | 中文 OCR 模型特性 |
| 首次识别慢 1–2 s | 首次编译模型，正常 |
- 本仓库的代码用于学习与研究；模型为通用 PP-OCR 权重。
- 模型权重版权归其原权利人所有，本仓库仅作个人学习与研究用途，禁止商用或再分发。
- 如权利人认为本仓库的使用方式不当，请联系维护者，我们将立即移除相关权重。
- 如需商用，请使用 PaddleOCR（Apache-2.0），本项目的管线代码可直接复用。
- 请遵守你所在地区及软件许可协议的相关规定。