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.
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.
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.
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.
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
Read when needed
references/metrics-and-thresholds.md for metric definitions and recommended gates.
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.
1---
2name: reference-analysis-validator
3description: Measure and validate supplied reference images, wireframes, texture atlases, and Blender renders before declaring a reconstruction 1:1. Use when an asset must match a template, when visual feedback says the output is off, when part counts must be exact, or before exporting a brand mascot/logo reconstruction. Pairs with reference-to-3d, contour-to-mesh, orthographic-registration, atlas-uv-fitting, and Blender MCP.
4when_to_use: Any 1:1 reference/model validation task involving masks, overlays, part counts, centroids, bounding boxes, SSIM/IoU, source manifests, or fail-before-export gates.
5allowed-tools: Read Bash Glob Grep mcp__blender__execute_blender_code mcp__blender__get_scene_info mcp__blender__get_object_info
6---
7
8# Reference Analysis Validator
9
10This 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**.
11
12## Required outputs
13
14Create these in the asset output folder:
15
16- `reference_manifest.json` — classified source files, expected parts, thresholds.
17- `source_analysis/*.json` — image metadata, masks/components/landmarks.
18- `validation/front_overlay_reference.png` — reference and render overlay.
19- `validation/front_mask_validation.json` — IoU/SSIM/bbox/centroid report.
20
21## Workflow
22
231. Classify sources: front, side, back, top, texture atlas, decals, maps, lightmap, aura/context.
242. Build/refresh `reference_manifest.json` with hard expected counts and view roles.
253. Extract masks/components from each source using `scripts/reference_manifest_compiler.py` or existing analyzers.
264. Render model from matching orthographic camera with reference planes hidden.
275. Compare reference mask vs render mask using `scripts/render_overlay_validator.py`.
286. Refuse final export if hard gates fail.
29
30## Modality rule
31
32Compare 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.
33
34## Default validation gates
35
36- primary structural part count: exact.
37- front silhouette IoU: target >= 0.90 for rigid/logotype shapes; >= 0.82 acceptable for first mascot reconstruction pass.
38- bbox center drift: <= 12 px at 1024 px validation size.
39- bbox size drift: <= 3% of image dimension.
40- face/eye/smile landmark drift: <= 2% of image dimension when landmarks are defined.
41
42## Failure policy
43
44If a repeated mismatch occurs, record the measured failure, then route to the missing specialty skill:
45
46- wrong silhouette → `contour-to-mesh`
47- wrong depth/side/back → `orthographic-registration`
48- wrong textures → `atlas-uv-fitting`
49- wrong whole workflow → `mascot-logo-reconstruction`
50
51## Read when needed
52
53- `references/metrics-and-thresholds.md` for metric definitions and recommended gates.
54
55## Sources distilled
56
57Official/library docs to prefer while extending this skill:
58
59- OpenCV contour features: moments, area, perimeter, bounding rectangles.
60- OpenCV shape matching / Hu moments.
61- OpenCV homography and geometric transforms.
62- scikit-image SSIM for perceptual comparison.
roble3