# OCR 数字化流程（扫描版教辅 → 纯文本）

把「纯图片扫描」的教辅 PDF 逐页提取为可检索文本，纳入 `kids-homework-tutor` 技能。
当前已数字化（截至 2026-07-28）：
- 五上全套：语文基础知识、开心同步作文、英语全解、数学《一课一练》、火箭班培优卷、跟我学单元检测、U1-2 视频课笔记+练习；
- 英语语法通用：基础语法填空 1300 题（含答案）、不规则动词表、Sweet 手写笔记；
- 三下/四上/四下（上海牛津·Sweet&Dore 视频课）：同步资料+习题、必背单词、必背知识+默写、同步精选练习+答案。
全部文件清单见 `references/workbooks_ocr_index.md`（按年级/学科分组检索）。

## 环境与依赖（已验证可用）
- Python venv：`C:\Users\张强\.workbuddy\binaries\python\envs\py312`
  - `paddlepaddle==2.6.2` + `paddleocr==2.7.3` + `numpy==1.26.4`
  - **必须 pin numpy 1.26.4**：numpy 2.x 与 paddlepaddle 2.6.2 / opencv 4.6 ABI 不兼容（`numpy.core.multiarray failed to import`）。
  - 已对 `ppocr` 内的 `skimage` / `imgaug` / `scipy` 顶层 import 加 `try/except` 守卫（scipy 1.18 + numpy 1.26 会报 `np.long` FutureWarning，无害）。
- 模型缓存（**ASCII 路径**，避开中文路径下 Paddle C++ 后端读不了 `inference.pdmodel` 的问题）：
  `C:\wb_paddleocr\.paddleocr\whl`（含 det / rec / cls 三个 `inference.pd*`）。
- 推理参数：`use_mkldnn=True`。
  - 本机 CPU 上 PP-OCRv4 + MKLDNN ≈ **6 s/页**。
  - ⚠️ 不要用默认 venv（paddle 3.3.1）：其 OneDNN(PHI) 后端会在 `fused_conv2d` 崩溃，只能 native 慢速 ≈ 39 s/页。

## 脚本 `ocr_one.py`（位于教辅项目根目录）
- 内存渲染：`fitz.get_pixmap(dpi=160)` → numpy（RGB→BGR），**不写临时 PNG**，省 C 盘空间。
- 断点续跑：每页写 `===== PAGE N =====` 标记；重启时跳过已完成页（取标记最大页号）。
- 单页容错：异常时写 `[OCR ERROR]` 标记并继续，事后可补跑缺失页。
- 中文路径：源 PDF 路径以 ASCII id 硬编码在 `PATHS` 字典（如 `"math"`/`"composition"`/`"english"`/`"chinese"`），避免 Windows 命令行 GBK 乱码导致 `FileNotFoundError`。

## 重新数字化某本（例如数学《一课一练》）
1. 把新的数学 PDF 放到本机，记下其完整路径。
2. 编辑 `ocr_one.py` 的 `PATHS["math"]` 改为新路径（UTF-8 字面量，不要走命令行传中文名）。
3. 运行：
   ```bat
   C:\Users\张强\.workbuddy\binaries\python\envs\py312\Scripts\python.exe ocr_one.py math ^<技能^>\references\workbooks_ocr\wb_yike_math.txt 160
   ```
4. 完成后把 `grade5_workbooks.md` 第四节的数学移到第三节，并补「典型易错题 / 单元练习题型」说明。

## 已知坑
- **C 盘满（~144 MB 空闲）**：`pip cache purge` 可释放 ~22 GB 陈旧下载；安装 paddle 时设
  `CODEBUDDY_SAFE_DELETE_SANDBOX=0` 以允许 pip 清理临时文件（cv2 LICENSE 等会被安全删除钩子拦截）。
- **默认 venv 不可用**：paddle 3.3.1 的 PHI OneDNN 后端在本 CPU 崩溃，只能 native 慢速。
- **模型缓存必须在 ASCII 路径**：中文路径下 Paddle C++ 后端加载 `inference.pdmodel` 失败。
- **同时只跑一个 OCR 进程/本**：曾出现两个 `ocr_one.py` 同写一文件的竞争写入，先确认无残留 python 进程再启动。