Skip to content

About

Local paper scanning skill for OpenCode: perspective correction, shadow removal, color enhancement, and JPG/PDF export.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Paper Scan Skill

把照片中的纸张处理成类似扫描全能王的扫描件:识别四角、透视矫正、去阴影、增强文字,导出单页 JPG 与合并 PDF。支持 OpenCode Skill,也可以直接运行 Python 脚本。

合成文档的原图与扫描效果

示例由程序生成,不含真实证件、个人信息或真实印章。

功能

  • 自动检测纸张四角,生成边界预览;复杂背景支持手动四角修正。
  • 透视矫正、轻量纠偏、纸面去阴影与适度锐化。
  • 彩色、灰度、黑白和保留原色四种模式;彩色模式保留印章与手写内容。
  • A0–A6 输出,默认 A4、300 DPI;按输入顺序生成 JPG 与多页 PDF。
  • 可指定合并 PDF 的体积上限,无法满足时明确报错。
  • 图像处理在本地运行,无需 API Key,不会把图片上传到外部服务。

安装为 OpenCode Skill

需要 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.txt

Windows 可将 .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 或商业授权。商业集成、分发或提供网络服务前,请确认你的使用方式符合相应条款。

About

Local paper scanning skill for OpenCode: perspective correction, shadow removal, color enhancement, and JPG/PDF export.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages