把照片中的纸张处理成类似扫描全能王的扫描件:识别四角、透视矫正、去阴影、增强文字,导出单页 JPG 与合并 PDF。支持 OpenCode Skill,也可以直接运行 Python 脚本。
示例由程序生成,不含真实证件、个人信息或真实印章。
- 自动检测纸张四角,生成边界预览;复杂背景支持手动四角修正。
- 透视矫正、轻量纠偏、纸面去阴影与适度锐化。
- 彩色、灰度、黑白和保留原色四种模式;彩色模式保留印章与手写内容。
- A0–A6 输出,默认 A4、300 DPI;按输入顺序生成 JPG 与多页 PDF。
- 可指定合并 PDF 的体积上限,无法满足时明确报错。
- 图像处理在本地运行,无需 API Key,不会把图片上传到外部服务。
需要 Git、Python 3.9+ 和支持 Skill 的 OpenCode。
git clone https://github.com/debugdoctor/paper-scan-skill.git \
"$HOME/.config/opencode/skills/paper-scan"如果目标目录已经存在,请保留现有内容,先克隆到其他目录比较。OpenCode 会发现新增 Skill;需要时输入 /reload 刷新。
然后把图片提供给 Agent,并输入:
@paper-scan 把这两张照片做成彩色扫描版,按顺序合并,PDF 小于 500 KB。
Skill 的工作流程见 SKILL.md。Agent 应检查边界与扫描预览,不能只依赖自动检测评分。
以下命令在仓库目录执行。建议使用独立虚拟环境:
python3 -m venv .venv
.venv/bin/python -m pip install -r scripts/requirements.txtWindows 可将 .venv/bin/python 替换为 .venv\Scripts\python.exe。
先生成边界预览,确认框选的是目标纸张:
.venv/bin/python scripts/scan.py "photo1.jpg" "photo2.jpg" \
--out output --detect-only检查 output/*_边界预览.jpg 和 output/report.json 后,生成扫描件:
.venv/bin/python scripts/scan.py "photo1.jpg" "photo2.jpg" \
--out output --paper A4 --mode color --max-kb 500 --overwrite这里的 --overwrite 用于替换上一步生成的本次任务文件。默认拒绝覆盖同名输出;对其他任务请使用新目录。
叠纸、白色桌面、缺角或纸张超出画面时,自动检测可能不准确。建立 corners.json:
{
"photo1.jpg": [[0.08, 0.04], [0.94, 0.05], [0.99, 0.99], [0.03, 0.99]]
}坐标顺序为 左上、右上、右下、左下。示例为 0–1 归一化坐标;也支持原图像素坐标。坐标以 EXIF 方向修正后的原图 为准,不是缩略图像素。键可以是文件名或输入绝对路径;没有提供四角的图片仍使用自动检测。
.venv/bin/python scripts/scan.py "photo1.jpg" \
--out corrected --corners-file corners.json --max-kb 500| 参数 | 默认值 | 说明 |
|---|---|---|
--out |
必填 | 输出目录 |
--paper |
A4 |
A0–A6 输出纸型 |
--dpi |
300 |
JPG 输出分辨率,允许 72–600;单页上限 4000 万像素 |
--mode |
color |
color、gray、bw 或 original |
--corners-file |
无 | 逐图指定四角的 JSON |
--rotate |
0 |
透视矫正后顺时针旋转 0、90、180 或 270 度 |
--trim |
0 |
每边裁去的比例,最大 0.03;仅在确认边缘空白时使用 |
--max-kb |
无 | 合并 PDF 严格小于指定十进制 KB,1 KB = 1000 字节 |
--detect-only |
关闭 | 只生成边界预览与检测报告 |
--overwrite |
关闭 | 允许覆盖目录中同名的已知输出 |
--max-kb 不限制单页 JPG。PDF 默认使用最高 200 DPI 的嵌入图像;指定体积上限时会逐步降低 JPEG 质量及分辨率,最低尝试 95 DPI(输入 DPI 更低时沿用输入值)。最终可读性仍需目视检查。压缩失败会保留已生成 JPG 和检测报告,并返回非零退出码。
output/
├── 01_photo1_边界预览.jpg
├── 01_photo1_扫描版.jpg
├── 01_photo1_扫描预览.jpg
├── 02_photo2_边界预览.jpg
├── 02_photo2_扫描版.jpg
├── 02_photo2_扫描预览.jpg
├── 合并扫描件.pdf
└── report.json
报告包含输入绝对路径、四角、输出大小、纠偏角度和 PDF 压缩配置,仅供本地检查;分享报告前注意移除本地路径等信息。
- A 系列纸张比例基本相同,单凭照片无法判断真实物理尺寸;
--paper是输出尺寸约定。 - 自动检测使用传统图像处理启发式算法,复杂背景和叠纸需要检查四角;评分不代表统计置信度。
- 横竖方向由四边形估计,文字正反方向需要人工或 Agent 检查;同一批次的
--rotate对所有页面生效。 - 不能恢复照片之外、遮挡处或原图中已模糊丢失的内容,不包含 OCR 或生成式文字重建。
- 四点透视不能完全展平严重弯曲的书页。黑白模式可能损失浅色印章与铅笔细节。
original跳过颜色增强,但仍会进行透视矫正、纠偏以及用户指定的裁边。
测试数据全部在临时目录中合成,覆盖纸张检测、纸型尺寸、彩色保留、多页 PDF、体积上限和输出覆盖保护:
.venv/bin/python -m unittest discover -s tests -v本项目采用 GNU AGPL-3.0。依赖各自遵循其许可证;其中 PyMuPDF 采用 AGPL 或商业授权。商业集成、分发或提供网络服务前,请确认你的使用方式符合相应条款。
