优化document-photo-to-pdf技能
This commit is contained in:
@@ -0,0 +1,118 @@
|
||||
# CHANGELOG
|
||||
|
||||
本文件记录 `document-photo-to-pdf` 的改造历史。对外接口(`SKILL.md` 里的
|
||||
`images` / `output` 参数、审核页、返回结构)**未变**,仅检测内部实现有改动。
|
||||
|
||||
---
|
||||
|
||||
## 2026-10-24 · 纸张检测修复(基于原 skill 基线)
|
||||
|
||||
### 背景
|
||||
|
||||
原实现在真实拍摄的照片上,`detect()` 返回的角点大面积不可信,`validate()` 判失败后
|
||||
整框被替换成「画面内缩 3% 的兜底矩形」,等于把整张照片塞进 PDF。两个典型样本:
|
||||
|
||||
| 场景 | 原检测角点 (px) | 失效原因 |
|
||||
|---|---|---|
|
||||
| 白纸卡(蓝花布背景) | (464,136) (824,103) (893,1824) (158,2011) | 掩膜把蓝布并进纸面(`paper_frac=0.64`),拟合出的“纸边”其实是照片边框;校验报上/右/下三边内侧混入桌面 |
|
||||
| 词典封面(塑料袋台面) | (152,1898) (1325,1053) (91,3008) (100,3016) | 白书封与塑料袋亮度接近、连通成一片,四边形不满足凸性,右下与左下相距仅 12px |
|
||||
|
||||
根因是四层:阈值硬编码未标定 → 形态学只有闭运算、把高光连进纸面 → 角点用“四方向极值点”
|
||||
在圆角/毛刺下退化成病态求交 → 校验失败后一票否决整框丢弃。
|
||||
|
||||
### 变更
|
||||
|
||||
**1. 掩膜改为多候选打分**(`params.detect.mask_ladder`、`auto_quad.paper_masks`)
|
||||
|
||||
原实现用一组固定阈值 `V>0.50, S<0.45`,实测 Otsu 算出 0.471/0.498 均被
|
||||
`paper_otsu_floor=0.50` 顶成 0.500。改为跑 6 组候选,按 solidity、最小外接矩形填充率、
|
||||
贴边程度、宽高比打分选最优。
|
||||
|
||||
**2. 掩膜收敛加开运算**(`auto_quad._mask_from_bright`)
|
||||
|
||||
原来只有闭运算,布面高光斑点会被“连”到纸上,把最小外接矩形撑大。加开运算后两个样本的
|
||||
`rect_fill` 从 0.51/0.86 升到 0.94/0.86,`solidity` 升到 0.99/0.94。
|
||||
同时把「开→闭→填→取最大→再开→再闭→再填」的 8 次形态学收敛为 4 次
|
||||
(闭运算幂等,取最大连通域后已无细小碎块),单候选 0.3 s → 0.15 s。
|
||||
|
||||
**3. 四角拟合改用最小外接矩形做初始四边形**(`min_area_rect` / `order_quad` / `quad_ok`)
|
||||
|
||||
原来的“四方向极值点当锚点”,在纸张有圆角、掩膜有毛刺时会把四个锚点挤到同一段弧上,
|
||||
相邻两边近似平行,求交得到病态角点。改用凸包 + 旋转卡壳求最小外接矩形,天然凸、天然有序。
|
||||
|
||||
**4. 四边形按 IoU 择优**(`quad_iou`、`detect_quad_corners`)
|
||||
|
||||
**不要**在收紧结果上设“与矩形的夹角 / 角点位移上限”。真实拍摄的纸张是**梯形**,
|
||||
左右两边本来就该一边内收、一边外放;用矩形先验当门槛会把透视关系判成错误,
|
||||
最后退回成平行四边形(现象:角点能落在大致位置,但丢掉了变形)。
|
||||
|
||||
改为在三个候选里按与纸面掩膜的 IoU 选优:
|
||||
|
||||
| 候选 | 样本 A IoU | 样本 B IoU |
|
||||
|---|---|---|
|
||||
| 最小外接矩形 | 0.9163 | 0.8988 |
|
||||
| 掩膜边界逐边拟合 | 0.9825 | 0.9610 |
|
||||
| **边缘点逐边拟合(通常胜出)** | **0.9845** | **0.9634** |
|
||||
|
||||
**5. 逐边支撑度检查**(`params.detect.side_support_frac`)
|
||||
|
||||
一条边的边界点数不足边长的 25% 时,该边退回矩形边。防的是“某条边在掩膜上几乎没被看到、
|
||||
却拿去和邻边求交”导致的飞角——实测出现过 300 px 偏移。
|
||||
|
||||
**6. 校验失败改为“先重拟合、再降级”**(`run.py`)
|
||||
|
||||
原来 `if not v["ok"]` 直接把整个四边形换成画面内缩 3% 的兜底框,`detected_corners`
|
||||
只写不读。现在先尝试 `rect_quad()` 重拟合:通过则 `ready`,不通过则标 `review` 并保留几何,
|
||||
只有完全检测不到纸才用兜底框。
|
||||
|
||||
**7. 收缝**(`auto_quad.shrink_to_mask`)
|
||||
|
||||
最小外接矩形/边线拟合给出的框通常比纸面大 5~40 px,裁出来四边挂背景。沿每条边法向
|
||||
“向内多远才是纸”取中位数后内推,只许向内、有上限。样本 B 据此收掉 38 px。
|
||||
|
||||
### 测试结果
|
||||
|
||||
| 项目 | 结果 |
|
||||
|---|---|
|
||||
| 真实照片 12 张 | 全部 `validate.ok = True` |
|
||||
| 裁剪框内属于纸面的像素比例 | 35.7% / 30.0%(原) → **97.0% / 95.8%** |
|
||||
| 两张梯形透视样本(原版结果已被确认为正确) | 逐角差 **0 px** / 最大 **16 px** |
|
||||
| 合成样张(已知真值) | 角点最大误差 **5.1 px**(用例容差 35 px) |
|
||||
|
||||
### 性能
|
||||
|
||||
| 场景 | 原 skill | 本版本 | 差异 |
|
||||
|---|---|---|---|
|
||||
| 2 张图端到端(含出 PDF) | 均 6.14 s | 均 6.46 s | +5% |
|
||||
| 12 张图检测阶段合计 | — | 21.2 s(约 1.8 s/张) | — |
|
||||
|
||||
改造过程中曾出现严重性能回退(2 张 61.8 s),原因是 `_mask_quality()` 对整张掩膜的
|
||||
约 30 万非零像素跑纯 Python 凸包。已改为「只取掩膜边界点 + 降采样到 1500 点」,
|
||||
单候选 3.4 s → 0.07 s。若后续再改这块,注意别再对全图像素做 Python 循环。
|
||||
|
||||
### 部署
|
||||
|
||||
只改动 3 个文件,其余与原件逐字节相同:
|
||||
|
||||
```
|
||||
run.py ← 改(校验失败改为重拟合/降级)
|
||||
doc_deskew/auto_quad.py ← 改(掩膜候选、最小外接矩形、IoU 择优、收缝)
|
||||
doc_deskew/params.py ← 改(新增候选梯度、支撑度、IoU 等参数)
|
||||
```
|
||||
|
||||
未改动、可直接沿用原件:`SKILL.md`、`REVIEW.md`、`web/index.html`、`validate.py`、
|
||||
`compose.py`、`homography.py`、`check.py`、`state.py`、`review_store.py`、
|
||||
`review_page.py`、`smoke_test.py`。
|
||||
|
||||
对外接口未变,**不需要改 `SKILL.md`**。覆盖前建议备份原文件。
|
||||
|
||||
### 已知局限
|
||||
|
||||
1. `check.py` 的「边缘背景残留 / 内容贴边」仍会报不达标。这两项在 `params.py` 里明确
|
||||
标注为「启发式、未标定、误报多」(`check.edge_warnings` 默认 `False`,只留在 checks
|
||||
不升为 warning)。贴着纸边裁切时必然触发;原版整幅兜底框同样报这两项。
|
||||
2. 纸张本身出画(角点贴在画面边界上)时无法还原,只能出整幅。
|
||||
3. `detect.snap_enable` 默认关闭。贴边吸附(沿法向找梯度极值重拟合)在布面/塑料袋场景
|
||||
会跳到干扰结构上,实测反而更差,保留代码但不启用。
|
||||
4. 自带 `smoke_test.py` 在**未修改的原 skill** 上也跑不过(`KeyError: 'output'`:
|
||||
`run.py` 默认 review 模式返回的字段结构与测试断言不一致)。属既有问题,本次未动。
|
||||
Reference in New Issue
Block a user