6.3 KiB
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。覆盖前建议备份原文件。
已知局限
check.py的「边缘背景残留 / 内容贴边」仍会报不达标。这两项在params.py里明确 标注为「启发式、未标定、误报多」(check.edge_warnings默认False,只留在 checks 不升为 warning)。贴着纸边裁切时必然触发;原版整幅兜底框同样报这两项。- 纸张本身出画(角点贴在画面边界上)时无法还原,只能出整幅。
detect.snap_enable默认关闭。贴边吸附(沿法向找梯度极值重拟合)在布面/塑料袋场景 会跳到干扰结构上,实测反而更差,保留代码但不启用。- 自带
smoke_test.py在未修改的原 skill 上也跑不过(KeyError: 'output':run.py默认 review 模式返回的字段结构与测试断言不一致)。属既有问题,本次未动。