Files
agent/skills/document-photo-to-pdf/CHANGELOG.md
T

6.3 KiB
Raw Blame History

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 模式返回的字段结构与测试断言不一致)。属既有问题,本次未动。