reference-analysis-validator

参考分析验证器

此技能可将“看起来差不多”转化为可衡量的门槛。对于品牌标识、徽标或吉祥物相关工作，在源清单和验证阈值确定之前，不要建模或导出。

必需输出

在资产输出文件夹中创建以下文件：

• reference_manifest.json — 已分类的源文件、预期部件和阈值。
• source_analysis/*.json — 图像元数据、蒙版、组件和地标。
• validation/front_overlay_reference.png — 参考图与渲染图叠加结果。
• validation/front_mask_validation.json — IoU／SSIM／边界框／质心报告。

工作流

1. 对源文件进行分类：正面、侧面、背面、顶部、纹理图集、贴花、贴图、光照贴图、光环／上下文。
2. 创建或更新 reference_manifest.json，设置明确的预期数量和视图角色。
3. 使用 scripts/reference_manifest_compiler.py 或现有分析器，从每个源文件中提取蒙版／组件。
4. 使用匹配的正交相机渲染模型，并隐藏参考平面。
5. 使用 scripts/render_overlay_validator.py 比较参考蒙版与渲染蒙版。
6. 如果硬性门槛未通过，则拒绝最终导出。

模态规则

比较同类内容。将线框边缘蒙版与着色的精美渲染图比较，会导致 IoU 值低得具有误导性。对于硬性门槛，请从 Blender 渲染纯色剪影／蒙版，或将参考边缘与渲染边缘进行比较。当源文件和渲染图需要使用不同的蒙版提取模式时，请使用 render_overlay_validator.py --reference-mode ... --render-mode ...。

默认验证门槛

• 主要结构部件数量：必须完全一致。
• 正面剪影 IoU：刚性形状／标识形状的目标值 >= 0.90；吉祥物首次重建时 >= 0.82 即可接受。
• 边界框中心偏移：在 1024 px 验证尺寸下 <= 12 px。
• 边界框尺寸偏差：<= 图像尺寸的 3%。
• 面部／眼睛／微笑地标偏移：定义了地标时，<= 图像尺寸的 2%。

失败处理策略

如果反复出现同一种不匹配，请记录实测失败情况，然后转交给缺少的专项技能：

• 剪影错误 → contour-to-mesh
• 深度／侧面／背面错误 → orthographic-registration
• 纹理错误 → atlas-uv-fitting
• 整体工作流错误 → mascot-logo-reconstruction

按需阅读

• references/metrics-and-thresholds.md：指标定义和推荐门槛。

整理的来源

扩展此技能时，优先参考官方文档／库文档：

• OpenCV 轮廓特征：矩、面积、周长、边界矩形。
• OpenCV 形状匹配／Hu 矩。
• OpenCV 单应性和几何变换。
• scikit-image 的 SSIM 感知比较。