PDF 渲染与高精度提取
概述
比 pdfplumber 更擅长「出图」：把任意页渲染成 PNG 用于插图或 OCR 前处理；同时提供逐词坐标，适合做版面分析。
何时使用
- 把 PDF 页面导出成图片
- 为 OCR / 视觉核对准备渲染图
- 需要文本在页面上的坐标位置
快速使用
# 渲染第 1 页为图片（默认 150dpi）
python3 scripts/pdf_render.py render in.pdf -p 1 -o page1.png
# 批量渲染整本到目录（每页一个 <名>_page_N.png）
python3 scripts/pdf_render.py render in.pdf -d ./imgs/
# 批量渲染指定页码（如第 1~3 和第 5 页）
python3 scripts/pdf_render.py render in.pdf -d ./imgs/ --pages "1-3,5"
# 提高清晰度到 300dpi
python3 scripts/pdf_render.py render in.pdf -d ./imgs/ --dpi 300
# 提取全部文本
python3 scripts/pdf_render.py text in.pdf -o all.txt
依赖安装
# 提示：脚本用相对路径 scripts/，请先 cd 到本技能目录再运行
python3 -m pip install pymupdf
常见错误 / 注意
- PyMuPDF 库为 AGPL-3.0：作为 CLI 调用一般无需开源你的技能，但分发修改版需留意
- 渲染 DPI 越高图片越大，贴图 150 足够，印刷级需 300+
- 仅对含文本层的 PDF 能提取文字；图片型先 OCR
实测验证（v0.1.0）
- 核心依赖：
pymupdf - 安装体积：🟢 57.9 MB（依赖闭包实测，轻量级）
- 环境要求：无外部二进制依赖（自带渲染引擎）。
- 单元测试：
python3 -m unittest tests.test_...（须 cd 到本技能目录运行） - CLI 冒烟：已通过端到端实测
已验证行为
- ✅ render：PDF → PNG（默认 150 DPI）
- ✅ text：按页提取文本
已知边界 / 坑
- ⚠️ PyMuPDF ≥1.24.3 应使用 import pymupdf，旧的 import fitz 已弃用
