# 掩膜质量恢复：离线评估与新边界拟合原型

## 本轮范围

用户报告最新26张已复核且初稿质量下降，并批准执行改进方案。本轮不是新的配额续批：
不激活新图库、不生成新的生产人工事件、不覆盖任何修订、不训练位姿模型、不放宽冻结传播算法。
先将质量回放与新的参考/边界拟合方法实现为独立离线研究链；是否进入小批试验由实际隔离评估结果决定，不能把验收通过当作轮廓准确。

代码入口：

- `pallet/mask_quality_metrics.py`：像素中心掩膜IoU、双向边界距离、HD95、1原生像素边界F1、面积比和循环/方向无关的顶点差异。
- `pallet/mask_boundary_fit.py`：新的原生像素边缘线拟合与多参考一致性原型，不修改旧传播器。
- `pallet/mask_quality_recovery.py`：真实来源审计、全部初稿/修订回放、train内分组交叉验证和拒绝/交付率统计。
- `scripts/build_mask_quality_recovery_review.py`：读取完成的离线证据，将原始初稿与当前真实人工修订生成并排对照；不重画或写回标签。
- `scripts/verify_mask_quality_recovery.py`：独立核验入口，核验范围与结果写入其独立报告，不以生成器自检代替独立验证。

## 防止来源与评估泄漏

1. 读取新的只读SQLite快照，按真实publication、base proposal哈希、目标键解析规范发布与独立预标注v1/v2/v3；
   每条事件验证绑定，当前记录必须与唯一最新事件的UTF-8原字节匹配。
2. 沿用已验证482份位姿人工轮廓，检查当前载荷仍与原证据一致；它们是研究标签参考，不自动成为GT。
3. 旧原框复核、待专项复核两条原框、会话侧记、隔离/删除/暂缓/确认目标不充当新人工轮廓。
4. 原始图像相同、PCD相同、同一帧、同采集组或满足明确近重复条件的记录先合并成隔离连通分量，再确定三折。
5. 新方法及受控旧算法基线只处理正式train目标，只使用其它折的train参考；必须同候选类、同sensor policy和明确相同候选视面。
   未知视面不当作通配符，Class14因长/短面尚未充分结构化，暂整体拒绝自动参考拟合。
6. 采集组和身份只用于防泄漏过滤、日志及可复算绑定，不作为数值拟合特征。目标人工轮廓、位姿、标尺、选面均不进入候选生成。
   目标人工轮廓只在候选已确定后用于离线评分，不能按评分选择参考或候选。
7. 历史val/test只描述已发生的初稿—修订差异；新算法不生成或评分val/test候选，不用于参数调优或模型选择。

来源相互独立、同为primary及同类，都不足以证明物理观察面兼容。新原型保持保守拒绝；未精分的观察面需要补充可信语义证据，
不能靠顶点数或框长宽比自动确认。当前粗结构签名只用于否决明显冲突，不授予生产传播资格。

## 新原型如何生成轮廓

1. 对合格参考按目标图像归一化patch相关度检索，最多尝试三个不同隔离分量。
2. 原有相关度0.55、ECC0.84、边界相关度0.78和仿射畸变限制保留为粗定位证据，不将其叫作正确率。
3. 沿每条粗定位边，在原生像素法向±4像素范围搜索灰度跳变，使用参考边界的跳变方向避免内外反转。
4. 每条边要求足够对比度与支持率，用Huber直线拟合；弱边、过短边、接近图边、斜率不稳或残差过大均拒绝。
5. 以相邻拟合线交点生成顶点，保持来源原顶点数量和顺序，并保留位移、面积与合法性约束；不补造凹槽或第五点。
6. 至少两份不同隔离分量的参考，在相同来源结构族内逐顶点相差≤1.5原生像素才形成研究候选；不平均、也不按目标人工标签择优。

四点人工参考仅在这个独立实验分支中参与边界拟合，不加入旧版要求超过四点的传播模板池，不改变其资格规则。
所有结果都是研究候选，不是人工保存、GT、正式训练标签或机器人指令。

受控旧算法基线仍调用冻结 `attempt_target`，只使用超过四点的人工来源，沿用全部原门槛，但每目标同样限制三个独立参考。
因此这项基线是新的公平预算对照，不冒充历史全模板扫描的结果。

## 质量门禁与报告要求

预先声明的小批试验目标：

- 至少10份独立组隔离的可评估候选；
- IoU中位数≥0.95，至少90%达到0.90；
- 每份HD95≤`max(2原生像素, 目标框高度×0.10)`；
- 另行检查错面、错层、虚构结构、遮挡边界，不用统计分数替代这项语义检查。

门禁通过也只说明可继续考虑受控人工小批，不自动授权上线。门禁未通过、候选不足或全部拒绝时必须明确阻断，不将空集质量记作1。
必须同时报告全体目标分母、逐类交付率、参考不足比例、配准/边界拒绝类型；不允许只挑容易样本掩盖难例。
本次原型没有训练神经网络，也没有用已看过的test重选冻结模型。

## 可复现执行

```bash
PYTHONDONTWRITEBYTECODE=1 OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
  .venv/bin/python -m pallet.mask_quality_recovery \
  --output outputs/pallet_mask_quality_recovery_v2
```

输出必须是未存在的新目录，重跑时使用新版本号。快照和原始来源目录为私有权限，不通过现有图库白名单公开。
`result.json` 绑定新代码、来源快照、配置、设置和全部生成物哈希；两库逻辑指纹、配置与20,768份正式文件前后必须保持一致。
首次v1在读取历史第九版别名时失败，尚未创建标签快照或运行候选生成；失败目录与原因保留，不覆盖，后续改用v2。

## 本次实际结果

`outputs/pallet_mask_quality_recovery_v2/result.json` 已完成：1,484份真实来源、1,002对初稿/修订、
658份正式train分组隔离目标。新方法0/658交付，518份无兼容异组来源，140份进入参考尝试；
171次尝试中13次未过图像门槛，158次过粗配准但全部未过完整原生边界拟合。因此质量为null、发布门禁阻断。

受控旧算法基线23/658交付（3.50%），IoU中位0.9451，16/23达到0.90；仍未达到建议试运行目标。
这不是全历史模板池扫描，也不是独立GT正确率。

独立核验已通过，见 `outputs/pallet_mask_quality_recovery_v2/independent_verification.json`：
重算全部1,002对修订差异、重放171次新方法尝试及受控旧基线，核验193个隔离分量、两库原字节历史及20,768份正式文件保护。
独立核验与相关测试108项通过；与其它测试集合可能重叠，不把数量相加。
核验通过证明来源、重放和结果报告可信，**不证明新方法轮廓质量通过**。

已知范围限制：当前残差/支持率拒绝并不显式辨别所有竞争平行强边，原生成HTML的“歧义拒绝”概括过宽。
158次失败中首个失败边151次为线形/残差不稳、3次来源跳变弱、4次支持不足；统计是首失败边，不代表已检查全部后续边。
后续应研究整条边的连续一致性及多峰竞争，不降低冻结门槛。保留本次不可变结果，不将同一train OOF的后续开发再称为新盲测。

32张只读初稿/修订对照（全部最新26份＋6份历史较大误差）位于
`outputs/pallet_mask_quality_recovery_review_v1/report_zh.html`；不是新人工任务，不重派旧目标。
并行模型路线见 `docs/pallet_mask_model_research.md`，本轮只调研，不启动训练。

新代码、独立核验及相关旧传播/横梁/预标注/图库保存回归的联合测试运行198项通过；
该集合包含上述108项中的测试，不能把计数相加。
