加入照片转pdf功能支持
This commit is contained in:
@@ -0,0 +1,159 @@
|
||||
---
|
||||
name: document-photo-to-pdf
|
||||
description: 把手机拍摄的纸质文档照片拉正、去背景,按顺序合并为一个 PDF
|
||||
thinking: true
|
||||
---
|
||||
|
||||
# 文档照片转 PDF
|
||||
|
||||
手机拍的纸质材料 → 一个版正字清的 PDF。适用于合同、票据、证照、手写稿等多页纸质材料,纸张尺寸不限。
|
||||
|
||||
## 怎么跑
|
||||
|
||||
本技能没有 `run` 入口,用 `terminal` 直接执行命令。脚本装在技能目录,而 terminal 的
|
||||
cwd 是会话任务目录——两者不是同一个目录,所以**脚本一律用绝对路径调用**,图片和
|
||||
`out/` 用任务目录里的相对路径:
|
||||
|
||||
```sh
|
||||
python3 /workspace/skills/document-photo-to-pdf/doc_deskew/pipeline.py <子命令> ...
|
||||
```
|
||||
|
||||
## 铁律
|
||||
|
||||
> 以下 8 条为硬约束,违反任一条即视为任务失败:立即停手、向用户说明,不得"先改完再说"。
|
||||
|
||||
1. **先说再做。** 每次调脚本前用一句话说明这次干什么(要标注步骤编号)。
|
||||
2. **坐标只能靠眼睛读,禁止一切自建脚本。** 不另造任何纸张处理的辅助的代码,一次性脚本也不行。确实无法达成目的需要新能力=先停下问用户,不许自己造。
|
||||
3. **不裁切、不放大、不逐角看。** 四个角在同一张网格图上一次读全,直接报 4 组数字。不为了"读准一点"造局部图、加刻度、逐个角反复看。
|
||||
4. **每张图读 2 次,且每次都要有目的。** 网格 1 次 + 角标 1 次,看完就交付。
|
||||
- **读之前先说清这次要确认什么。** 说不出目的就不读。"再看一眼确认一下"不算目的。
|
||||
- **不为读而读。** 允许重读,但必须是被动的、有明确对象的:图没送达/像素没收到、要核对某个具体数字或某条边。没有新对象就直接用手上已有的数字。
|
||||
- **只读这两类图。** 网格、角标。原图、局部放大图、成品图、自己另造的辅助图都不读。
|
||||
- 没把握就按"宁可外扩"给保守值,交给角标图验证,不在读图阶段磨。
|
||||
5. **一次成件,禁止试错。** 一条 `build` 出件 + 检验。一轮里每页最多跑 1 次 `build`;不调参、不重取角点、不换方法、不"先出一版看看"。不通过就报诊断,停下等确认。
|
||||
6. **只有用户明确说"再改"才允许修复。** 完整一轮 = `prepare` → `set`(每页一次)→ `build`(一次)→ 看角标 → 交付。这一轮内发现的任何偏差(框偏了、裁到内容、比例不对),一律只报诊断和坐标建议,**不自行改、不重跑、不补做**。用户在本轮交付后明确说"再改/重做"时才能动手,且还是只跑一轮,改完重新过角标关。
|
||||
7. **指标 ≠ 成品。** 校验只查"框内"像素,框漏掉的内容查不出来。角标图必须亲眼看。
|
||||
8. **违规即停。** 一旦意识到自己正在写脚本、造辅助图、二次 build 或擅自修复,立即停手,向用户说明,不带病交付。
|
||||
|
||||
### 交付前自检(有一项为"是"就停手报告)
|
||||
|
||||
- 本轮是否新建/修改过任何脚本或辅助图?
|
||||
- 本轮 `build` 是否跑超过 1 次?
|
||||
- 是否在用户没说过"再改"时自行调整过角点或重出件?
|
||||
- 每张图是否只读了网格、角标各 1 次?
|
||||
- 校验未过的项是否只报告、没自行修?
|
||||
|
||||
## 流程
|
||||
|
||||
### 1 · 出网格图
|
||||
|
||||
```sh
|
||||
python3 /workspace/skills/document-photo-to-pdf/doc_deskew/pipeline.py prepare 图1.jpg 图2.jpg
|
||||
```
|
||||
|
||||
不传图片名 = 取当前目录所有图片。输出 `out/N-网格-<名称>.png`(100px 红色主线带坐标刻度、50px 蓝色辅助线,两者同宽)。
|
||||
|
||||
### 2 · 从网格图中读出角点,一张图一条命令
|
||||
|
||||
顺序固定:左上 → 右上 → 右下 → 左下(屏幕坐标,原点左上)。
|
||||
|
||||
**要找的是纸张本身真实的四个角**——纸面这个四边形的 4 个顶点,**坐标的质量直接决定最终成品的质量!**。
|
||||
|
||||
读数方法:
|
||||
1. 先找离目标点最近的红线(整百、带数字刻度)读基准值;
|
||||
2. 再识别目标点相对相邻蓝线(50px)的偏移;
|
||||
3. 把目的坐标复述成一句话,例如“右下:x 在 1000 红线右 52px,y 在 1700 红线下 22px → 1052,1722”。
|
||||
|
||||
读数要求:
|
||||
- 读之前先定好这一张要报的 4 组数字,看完立刻 `set` 落盘到 `out/corners.json`。
|
||||
- 角被遮挡:沿两条可见纸边延长交会出顶点。
|
||||
- 角出画面:顺两条边的趋势延长,坐标可为负或超界(脚本接受)。
|
||||
|
||||
写入坐标:
|
||||
```sh
|
||||
python3 /workspace/skills/document-photo-to-pdf/doc_deskew/pipeline.py set 图1.jpg \
|
||||
--quad "左上x,左上y;右上x,右上y;右下x,右下y;左下x,左下y"
|
||||
```
|
||||
- 一次只写一张图,脚本已强制拦截多图(防串页)。
|
||||
- 落盘 `out/corners.json`,同名键覆盖并打印旧值对比;`show` 可随时查看。
|
||||
- 报给用户的只能是 `--quad` 串或 4 组坐标数字,禁止"约 (140,390)、纸略倾斜"这类描述。
|
||||
|
||||
### 3 · 一条命令出件
|
||||
|
||||
```sh
|
||||
python3 /workspace/skills/document-photo-to-pdf/doc_deskew/pipeline.py build \
|
||||
--out 文档照片_校正.pdf --paper a4 --force
|
||||
```
|
||||
|
||||
内部依次:回画角标 → 角点几何校验 → 透视校正+按纸比例拉正+提亮 → 合并 PDF → PDF 渲染检验 → 打印汇总。
|
||||
|
||||
参数:
|
||||
- `--paper`:标准纸必须传 —— `a4`(0.707)、`letter`(0.773)、`16k`(0.712)、`b5`(0.704),或数字比例。票据、异形纸不确定就省略,保留原始比例。
|
||||
- `--force`:角点校验不过也出件(默认)。
|
||||
- 位置参数传图名:只出指定页,如 `build 图2.jpg --out 结果.pdf`(输出 PDF 只含这一页)。
|
||||
- `--dpi`:PDF 检验渲染 dpi,默认 100。
|
||||
|
||||
### 4 · 看角标图(强制,一次)
|
||||
|
||||
**角标图是决定图像处理质量的唯一标准!**
|
||||
|
||||
读 `out/N-角标-*.png`(原图 + 同一套网格 + 四角标注),四个角在同一张图上核对:
|
||||
1. 绿线是否压在纸边交界?
|
||||
2. 纸张上内容是否全在绿线框内?
|
||||
3. 4个角标是否都在纸张实际的角上!
|
||||
|
||||
**只看不改:** 发现问题只记进报告,记录修正前后角标坐标的表格、不重跑 `build`、不补造辅助图。
|
||||
|
||||
| 页码 | 实际使用的角点坐标 | 修正后的角点坐标 |
|
||||
|---|---|---|
|
||||
| 1 | x1,y1;x2,y2;x3,y3;x4,y4 | x1',y1';x2',y2';x3',y3';x4',y4' |
|
||||
|
||||
## 判定与报告
|
||||
|
||||
| 检查项 | 判据 | 不达标含义 |
|
||||
|---|---|---|
|
||||
| 页数 | 与源图数一致 | 合并出错 |
|
||||
| 纸面短边 | ≥ 533px @100dpi | 角点错或分辨率过低 |
|
||||
| 纸张比例 | 仅提示 | 传了 `--paper` 应≈1.00,偏差大说明角点有误 |
|
||||
| 边缘背景残留 | 边带亮度 ≥ 纸面 80% | 角点落在背景上,内收 3~5px |
|
||||
| 内容贴边 | 页边无成片文字级暗像素 | 内容被切,外扩 5px |
|
||||
|
||||
- **全部通过**:给产物路径、大小、页数、指标,加一句角标图上确认的结果。
|
||||
- **"外侧纸面占比 100%"一律当角点错误**,误差是几十到上百 px,回第 2 步重读,不是微调。
|
||||
- **不达标**:只报诊断+ 建议,**不自行改、不重跑、不换方法**。用户明确说"再改"后,才改动后重跑一轮,然后交用户决策。
|
||||
- **用户没发话就交付**:即使只差 1px、即使一眼看出能更好,也不许动。报告里可写建议,手不能动。
|
||||
|
||||
## 内容安全
|
||||
|
||||
**禁止用生成式模型处理这类图片。** 生成模型是重绘而非变换,会改写文档内容,且结果看起来完全正常。本流程只做纯几何变换 + 全局等比提亮,文字、金额、印章保持原始像素。
|
||||
|
||||
## 命令速查
|
||||
|
||||
下表省略公共前缀 `python3 /workspace/skills/document-photo-to-pdf/doc_deskew/`。
|
||||
|
||||
| 场景 | 命令 |
|
||||
|---|---|
|
||||
| 出网格图 | `pipeline.py prepare 图1.jpg 图2.jpg` |
|
||||
| 写角点(一张一次) | `pipeline.py set 图1.jpg --quad "x1,y1;x2,y2;x3,y3;x4,y4"` |
|
||||
| 查看已落盘 | `pipeline.py show` |
|
||||
| 出件 | `pipeline.py build --out 结果.pdf --paper a4` |
|
||||
| 只出指定页(PDF 只含该页) | `pipeline.py build 图2.jpg --out 结果.pdf` |
|
||||
| 复检已有 PDF(不重新出件) | `pipeline.py check 结果.pdf --expect-pages 2` |
|
||||
|
||||
底层模块(与 `pipeline.py` 同目录,由它调用,日常不用直接执行):
|
||||
|
||||
| 模块 | 职责 |
|
||||
|---|---|
|
||||
| `grid.py` | 画带坐标的网格图 |
|
||||
| `preview_quad.py` | 画角标图(叠网格) |
|
||||
| `verify_quad.py` | 角点几何校验 |
|
||||
| `homography.py` | 透视变换 + 提亮 |
|
||||
| `run.py` | 拉正 + 拼页(纯模块,无 CLI) |
|
||||
| `make_pdf.py` | 多页合成 PDF |
|
||||
| `check.py` | 成品 PDF 检验 |
|
||||
|
||||
## 已知边界
|
||||
|
||||
- 纸张出画面的部分无法还原,角点可外扩到画面外。
|
||||
- 不为凑标准比例拉坐标;比例偏离通常是取点不准或纸张非该规格。
|
||||
- 拍摄时四边各留 3%~5% 背景余量。
|
||||
Reference in New Issue
Block a user