Files

119 lines
6.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 模式返回的字段结构与测试断言不一致)。属既有问题,本次未动。