用途
Reference Analysis Validator 用于在宣布重建达到 1:1 之前，对提供的参考图像、线框、纹理图集和 Blender 渲染进行测量与验证。它把“看起来接近”转化为可测量的门禁，适用于任何涉及遮罩、叠加、部件数量、质心、边界框、SSIM/IoU、源清单或导出前失败门禁的 1:1 参考/模型验证任务。对于品牌、标志、吉祥物类工作，在源清单和验证阈值存在之前，不应进行建模或导出。
主要能力
该技能要求生成以下输出，并放在资产输出文件夹中：
- reference_manifest.json：分类后的源文件、预期部件、阈值。
- source_analysis/*.json：图像元数据、遮罩/组件/地标。
- validation/front_overlay_reference.png：参考与渲染叠加图。
- validation/front_mask_validation.json：IoU/SSIM/bbox/质心报告。
使用方式
工作流程如下：
- 分类源文件：正面、侧面、背面、顶部、纹理图集、贴花、贴图、光照贴图、光环/上下文。
- 构建或刷新 reference_manifest.json，包含硬性预期数量和视图角色。
- 使用 scripts/reference_manifest_compiler.py 或现有分析器从每个源提取遮罩/组件。
- 从匹配的正交相机渲染模型，隐藏参考平面。
- 使用 scripts/render_overlay_validator.py 比较参考遮罩与渲染遮罩。
- 如果硬性门禁失败，拒绝最终导出。
在首次调用 Blender 之前，需阅读 ../text-to-blender/references/mcp-backends.md。优先使用官方 MCP 以获取共享能力；在整个任务中保持所选后端不变。配方中的工具名称是客户端/旧版示例：通过该参考及其 agent-host 指南进行映射。
模态规则：同类比较。将线框边缘遮罩与着色美颜渲染进行比较会产生误导性的低 IoU。对于硬性门禁，从 Blender 渲染平面剪影/遮罩通道，或将参考边缘与渲染边缘进行比较。当源和渲染需要不同的遮罩提取模式时，使用 render_overlay_validator.py --reference-mode ... --render-mode ...。
默认验证门禁
- 主要结构部件数量：精确。
- 正面剪影 IoU：刚性/标志形状目标 >= 0.90；首次吉祥物重建通过可接受 >= 0.82。
- bbox 中心漂移：在 1024 px 验证尺寸下 <= 12 px。
- bbox 尺寸漂移：<= 图像尺寸的 3%。
- 面部/眼睛/微笑地标漂移：当地标定义时 <= 图像尺寸的 2%。
失败策略
如果重复出现不匹配，记录测量到的失败，然后路由到缺失的专业技能：
- 剪影错误 → contour-to-mesh
- 深度/侧面/背面错误 → orthographic-registration
- 纹理错误 → atlas-uv-fitting
- 整个工作流错误 → mascot-logo-reconstruction
适用场景
适用于需要严格验证参考图与模型一致性的任务，特别是品牌、标志、吉祥物类资产的重建，以及任何需要量化验证遮罩、部件数量、边界框、质心、SSIM/IoU 的场景。
限制
该技能依赖源清单和验证阈值的预先建立。如果硬性门禁失败，必须拒绝最终导出。模态规则要求同类比较，否则 IoU 结果可能误导。需要阅读相关参考文档以正确映射工具名称和选择后端。
参考
需要时阅读 references/metrics-and-thresholds.md 以获取指标定义和建议门禁。
扩展此技能时优先使用的官方/库文档：
- OpenCV 轮廓特征：矩、面积、周长、边界矩形。
- OpenCV 形状匹配 / Hu 矩。
- OpenCV 单应性和几何变换。
- scikit-image SSIM 用于感知比较。