reference-to-3d

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: reference-to-3d
description: Reconstruct Blender models from supplied reference sheets, branding templates, texture atlases, orthographic front/side/back/top views, or mascot/logo art where visual fidelity to the source is more important than a plausible generated object. Use when the user says the model must match a template, wireframe, texture pack, character sheet, mascot sheet, or brand asset exactly; also use after feedback like "does not look like the reference", "fit the texture 1:1", "wrong number of visible parts", or "compare against the template". Requires Blender MCP plus local Python with Pillow/OpenCV/numpy; pairs with blender-uv-texturing, wireframe-to-3d, blender-modeling, blender-materials, and blender-export.
when_to_use: User supplies reference images/templates/texture atlases/orthographic views and wants a model matching them, or repeated visual mismatch feedback requires a reference-locked corrective loop.
allowed-tools: Read Bash Glob Grep mcp__blender__execute_blender_code mcp__blender__get_scene_info mcp__blender__get_object_info mcp__blender__get_viewport_screenshot
---

# Reference-to-3D Reconstruction

This skill is for **source-locked modeling**: the reference asset is the contract. Do not generate a plausible object from memory and then decorate it. Extract measurements, part counts, silhouettes, and UV regions from the supplied files first, then build the Blender model to satisfy those measurements.

## 1:1 reconstruction upgrade

When the user requires true 1:1 matching, chain these skills instead of attempting another plausible modeling pass:

1. `reference-analysis-validator` for manifest, masks, part counts, overlay gates.
2. `orthographic-registration` for front/side/back/top coordinate agreement.
3. `contour-to-mesh` for silhouette-derived structural meshes.
4. `atlas-uv-fitting` for per-part texture/UV fitting.
5. `mascot-logo-reconstruction` as the full orchestrator for brand mascot/logo work.

Do not export a final asset until the validation JSON and overlay render pass the manifest thresholds.

## Triggered failure mode

If the user says the output does not match the templates/textures/wireframes, stop regular `text-to-blender` generation and enter this workflow. Repeated plausible-but-wrong renders usually mean the missing step is **reference analysis**, not another modeling iteration.

## Source-of-truth hierarchy

1. **Front template / front wireframe**: primary silhouette, visible part count, face/feature positions, brand read.
2. **Texture atlas**: exact part shapes, color/material boundaries, decals, lightmap/aura intent.
3. **Side/back/top views**: depth, stacking order, thickness, backside forms. They must not change the locked front projection.
4. **User feedback**: hard constraints; promote it into validation gates.

## Mandatory preflight checklist

Before Blender modeling, write a small `reference_manifest.json` with:

```json
{
  "source_files": [],
  "primary_view": "front",
  "expected_primary_parts": {"count": null, "labels": []},
  "structural_parts": [],
  "decorative_parts": [],
  "texture_regions": [],
  "validation_thresholds": {
    "front_mask_iou_min": 0.90,
    "bbox_center_tolerance_px": 12,
    "part_count_exact": true
  }
}
```

If the expected part count is unclear, derive it from the reference sheet with the analyzer and show the user the uncertainty instead of guessing.

## Pipeline

### 1. Inventory and classify sources

Classify each provided asset:

- `front_template`: hero brand image or front wireframe.
- `side_view`, `back_view`, `top_view`: orthographic depth references.
- `texture_atlas`: basecolor / albedo atlas containing pieces.
- `decal`: transparent face/expression or detail layer.
- `emissive`, `roughness`, `bump`, `normal`, `lightmap`: material maps.
- `aura/background`: optional visual context, not structural body geometry.

### 2. Analyze images locally

Use `scripts/template_analyzer.py` for first-pass component extraction:

```b