reference-analysis-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reference Analysis Validator

参考分析验证器

This skill converts “looks close” into measurable gates. For brand/logo/mascot work, do not model or export until a source manifest and validation thresholds exist.

该技能将“看起来差不多”转化为可量化的验证标准。针对品牌/标志/吉祥物相关工作，在生成源清单和验证阈值之前，请勿进行建模或导出操作。

Required outputs

必需输出

Create these in the asset output folder:

```
reference_manifest.json
```
— classified source files, expected parts, thresholds.
```
source_analysis/*.json
```
— image metadata, masks/components/landmarks.
```
validation/front_overlay_reference.png
```
— reference and render overlay.
```
validation/front_mask_validation.json
```
— IoU/SSIM/bbox/centroid report.

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

```
reference_manifest.json
```
— 分类后的源文件、预期部件数量、验证阈值。
```
source_analysis/*.json
```
— 图像元数据、遮罩/组件/特征点信息。
```
validation/front_overlay_reference.png
```
— 参考图与渲染图的叠加对比图。
```
validation/front_mask_validation.json
```
— IoU/SSIM/边界框/质心分析报告。

Workflow

工作流程

Classify sources: front, side, back, top, texture atlas, decals, maps, lightmap, aura/context.
Build/refresh
```
reference_manifest.json
```
with hard expected counts and view roles.
Extract masks/components from each source using
```
scripts/reference_manifest_compiler.py
```
or existing analyzers.
Render model from matching orthographic camera with reference planes hidden.
Compare reference mask vs render mask using
```
scripts/render_overlay_validator.py
```
.
Refuse final export if hard gates fail.

对源文件进行分类：正面图、侧面图、背面图、顶面图、纹理图集、贴花、映射图、光照图、特效/背景图。
创建/更新
```
reference_manifest.json
```
，明确部件数量要求和各视图的作用。
使用
```
scripts/reference_manifest_compiler.py
```
或现有分析工具从每个源文件中提取遮罩/组件。
从匹配的正交相机视角渲染模型，隐藏参考平面。
使用
```
scripts/render_overlay_validator.py
```
对比参考图遮罩与渲染图遮罩。
若未通过严格验证标准，则拒绝最终导出。

Modality rule

模态规则

Compare like with like. A wireframe edge mask compared against a shaded beauty render gives misleadingly low IoU. For hard gates, render a flat silhouette/matte pass from Blender or compare reference edges to render edges. Use

render_overlay_validator.py --reference-mode ... --render-mode ...

when the source and render need different mask extraction modes.

同类对比。将线框图边缘遮罩与带阴影的精美渲染图对比会得到偏低的IoU结果。对于严格验证标准，需从Blender渲染出纯色轮廓/哑光通道，或对比参考图边缘与渲染图边缘。当源文件与渲染图需要不同的遮罩提取模式时，使用

render_overlay_validator.py --reference-mode ... --render-mode ...

命令。

Default validation gates

默认验证标准

primary structural part count: exact.
front silhouette IoU: target >= 0.90 for rigid/logotype shapes; >= 0.82 acceptable for first mascot reconstruction pass.
bbox center drift: <= 12 px at 1024 px validation size.
bbox size drift: <= 3% of image dimension.
face/eye/smile landmark drift: <= 2% of image dimension when landmarks are defined.

核心结构部件数量：完全一致。
正面轮廓IoU：刚性/标志类形状目标值≥0.90；吉祥物重建首次提交可接受≥0.82。
边界框中心偏移：在1024px验证尺寸下≤12px。
边界框尺寸偏移：≤图像尺寸的3%。
面部/眼睛/微笑特征点偏移：当定义特征点时，≤图像尺寸的2%。

Failure policy

失败处理策略

If a repeated mismatch occurs, record the measured failure, then route to the missing specialty skill:

wrong silhouette →
```
contour-to-mesh
```
wrong depth/side/back →
```
orthographic-registration
```
wrong textures →
```
atlas-uv-fitting
```
wrong whole workflow →
```
mascot-logo-reconstruction
```

若出现重复不匹配情况，记录测量到的失败项，然后转至对应的专业技能处理：

轮廓错误 →
```
contour-to-mesh
```
深度/侧面/背面错误 →
```
orthographic-registration
```
纹理错误 →
```
atlas-uv-fitting
```
整体工作流程错误 →
```
mascot-logo-reconstruction
```

Read when needed

必要时阅读

```
references/metrics-and-thresholds.md
```
for metric definitions and recommended gates.

```
references/metrics-and-thresholds.md
```
：包含指标定义和推荐验证标准。

Sources distilled

参考资料

Official/library docs to prefer while extending this skill:

OpenCV contour features: moments, area, perimeter, bounding rectangles.
OpenCV shape matching / Hu moments.
OpenCV homography and geometric transforms.
scikit-image SSIM for perceptual comparison.

扩展该技能时优先参考的官方/库文档：

OpenCV轮廓特征：矩、面积、周长、边界矩形。
OpenCV形状匹配/ Hu矩。
OpenCV单应性与几何变换。
scikit-image SSIM：用于感知对比。