reference-to-3d

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reference-to-3D Reconstruction

参考图转3D重建

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.

此技能适用于源锁定建模：参考资产就是标准。请勿凭记忆生成合理对象再进行装饰。首先从提供的文件中提取尺寸、部件数量、轮廓和UV区域，然后构建符合这些尺寸要求的Blender模型。

1:1 reconstruction upgrade

1:1重建升级

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

```
reference-analysis-validator
```
for manifest, masks, part counts, overlay gates.
```
orthographic-registration
```
for front/side/back/top coordinate agreement.
```
contour-to-mesh
```
for silhouette-derived structural meshes.
```
atlas-uv-fitting
```
for per-part texture/UV fitting.
```
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.

当用户要求真正的1:1匹配时，应串联以下技能，而非尝试另一次合理性建模：

```
reference-analysis-validator
```
：用于清单、蒙版、部件数量、叠加验证。
```
orthographic-registration
```
：用于前后左右视图的坐标对齐。
```
contour-to-mesh
```
：用于基于轮廓生成结构化网格。
```
atlas-uv-fitting
```
：用于逐部件纹理/UV适配。
```
mascot-logo-reconstruction
```
：作为品牌吉祥物/标志工作的完整编排器。

在验证JSON和叠加渲染通过清单阈值前，请勿导出最终资产。

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.

如果用户表示输出与模板/纹理/线框不符，请停止常规

text-to-blender

生成，进入此工作流。反复生成看似合理但错误的渲染通常意味着缺少的步骤是参考分析，而非另一次建模迭代。

Source-of-truth hierarchy

源文件优先级

Front template / front wireframe: primary silhouette, visible part count, face/feature positions, brand read.
Texture atlas: exact part shapes, color/material boundaries, decals, lightmap/aura intent.
Side/back/top views: depth, stacking order, thickness, backside forms. They must not change the locked front projection.
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.

在Blender建模前，编写一个小型的

reference_manifest.json

文件：

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
  }
}

如果预期部件数量不明确，请使用分析器从参考图中推导，并向用户说明不确定性，而非猜测。

Pipeline

工作流

1. Inventory and classify sources

1. 清点并分类源文件

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.

对每个提供的资产进行分类：

```
front_template
```
：核心品牌图像或正面线框。
```
side_view
```
、
```
back_view
```
、
```
top_view
```
：正射深度参考图。
```
texture_atlas
```
：包含各部件的基础色/反照率图集。
```
decal
```
：透明面部/表情或细节层。
```
emissive
```
、
```
roughness
```
、
```
bump
```
、
```
normal
```
、
```
lightmap
```
：材质贴图。
```
aura/background
```
：可选视觉背景，不属于结构化主体几何。

2. Analyze images locally

2. 本地分析图像

Use

scripts/template_analyzer.py

for first-pass component extraction:

bash

python3 ${CLAUDE_SKILL_DIR}/scripts/template_analyzer.py   --image /path/to/front_reference.png   --out /tmp/front_analysis.json   --mode edges  # use bright_on_dark/dark_on_bright/alpha when cleaner

The analyzer returns components with area, perimeter-derived score, bbox, centroid, contour, and approximate class hints. Use

--mode edges

for faint grey wireframes and Otsu modes for clean masks/atlases. Treat this as measurement input, not final authority.

使用

scripts/template_analyzer.py

进行首轮组件提取：

bash

python3 ${CLAUDE_SKILL_DIR}/scripts/template_analyzer.py   --image /path/to/front_reference.png   --out /tmp/front_analysis.json   --mode edges  # 当图像更清晰时使用bright_on_dark/dark_on_bright/alpha模式

分析器返回包含面积、周长衍生分数、边界框、质心、轮廓和近似类别提示的组件。对于浅灰色线框使用

--mode edges

，对于清晰蒙版/图集使用Otsu模式。将此视为测量输入，而非最终权威。

3. Lock the front reference in Blender

3. 在Blender中锁定正面参考图

Create a front reference plane or Image Empty in the same orthographic camera used for validation. Prefix it

REF_

and exclude it from export. Official Blender docs describe Image Empties as reference images/blueprints and support front/back depth, opacity, orthographic-only display, and axis-aligned display.

创建正面参考平面或图像空物体，使用与验证相同的正射相机。前缀命名为

REF_

并排除在导出之外。Blender官方文档将图像空物体描述为参考图像/蓝图，并支持前后深度、透明度、仅正射显示和轴对齐显示。

4. Build geometry from source contours

4. 从源轮廓构建几何模型

For each structural part:

Convert the 2D contour to front-view X/Z coordinates.
Generate a quad strip/grid inside that contour.
Assign Project-from-View-style UVs based on front X/Z bounds or exact atlas region.
Add only shallow Y-depth/crown/extrusion after the front silhouette is locked.

Keep part names semantic:

GEO-subject_part_top

GEO-subject_face_shell

, etc.

Do not radial-duplicate a mascot unless the reference is truly radial. Logos often have occlusion, intentional asymmetry, and a fixed visible part count.

对于每个结构部件：

将2D轮廓转换为正视图X/Z坐标。
在该轮廓内生成四边形条带/网格。
根据正面X/Z边界或精确图集区域分配“从视图投影”风格的UV。
仅在正面轮廓锁定后添加浅Y轴深度/弧度/挤出。

部件名称保持语义化：

GEO-subject_part_top

、

GEO-subject_face_shell

等。

除非参考图真正对称，否则不要径向复制吉祥物。标志通常有遮挡、故意不对称和固定的可见部件数量。

5. Multi-view registration

5. 多视图对齐

Front X/Z is locked first.
Side view controls Y/Z depth envelope only.
Top view controls X/Y spread only.
Back view controls hidden/backside geometry and validation, not front silhouette.

If views disagree, keep the front brand read and document the conflict.

首先锁定正面X/Z坐标。
侧视图仅控制Y/Z深度范围。
顶视图仅控制X/Y分布。
背视图控制隐藏/背面几何和验证，不影响正面轮廓。

如果视图存在冲突，请保留正面品牌辨识度并记录冲突。

6. UV and texture mapping

6. UV与纹理映射

Chain-load

blender-uv-texturing

when any texture pack is provided. For atlas-driven parts:

crop or map per atlas region; do not project the whole atlas onto every part;
front-facing hero surfaces use front-projected UVs;
side/back surfaces use side/back UV islands, procedural fill, or baked colors;
alpha decals need transparent material settings and must not introduce black planes;
lightmaps are optional realtime helpers and should not be connected as emission unless specified.

当提供任何纹理包时，串联使用

blender-uv-texturing

。对于图集驱动的部件：

裁剪或映射每个图集区域；不要将整个图集投影到每个部件上；
正面核心表面使用正面投影UV；
侧/背表面使用侧/背UV岛、程序化填充或烘焙颜色；
透明贴花需要透明材质设置，且不得引入黑色平面；
光照贴图是可选的实时辅助工具，除非指定，否则不应连接为发光材质。

7. Validation gates before export

7. 导出前的验证标准

Always produce:

```
front_preview.png
```
```
front_overlay_reference.png
```
```
front_mask_validation.json
```
```
side_preview.png
```
```
back_preview.png
```
```
top_preview.png
```

Use

scripts/silhouette_validator.py

bash

python3 ${CLAUDE_SKILL_DIR}/scripts/silhouette_validator.py   --reference /tmp/reference_mask.png   --render /tmp/render_mask.png   --out /tmp/validation.json

Refuse final export if:

primary part count differs from manifest;
front-mask IoU is below threshold;
face/feature centroid is outside tolerance;
optional aura/decorations are included in the base GLB by mistake.

必须生成以下内容：

```
front_preview.png
```
```
front_overlay_reference.png
```
```
front_mask_validation.json
```
```
side_preview.png
```
```
back_preview.png
```
```
top_preview.png
```

使用

scripts/silhouette_validator.py

：

bash

python3 ${CLAUDE_SKILL_DIR}/scripts/silhouette_validator.py   --reference /tmp/reference_mask.png   --render /tmp/render_mask.png   --out /tmp/validation.json

如果出现以下情况，拒绝最终导出：

主要部件数量与清单不符；
正面蒙版IoU低于阈值；
面部/特征质心超出公差范围；
误将可选光效/装饰包含在基础GLB文件中。

Blender code patterns

Blender代码示例

Reference plane in front-view X/Z

正视图X/Z中的参考平面

python

import bpy

def create_reference_plane(name, image_path, width, height, y=0.2, alpha=0.35):
    img = bpy.data.images.load(image_path, check_existing=True)
    mat = bpy.data.materials.new('MAT-' + name)
    mat.use_nodes = True
    nodes = mat.node_tree.nodes
    bsdf = nodes.get('Principled BSDF')
    tex = nodes.new('ShaderNodeTexImage')
    tex.image = img
    mat.node_tree.links.new(tex.outputs['Color'], bsdf.inputs['Base Color'])
    mat.node_tree.links.new(tex.outputs['Alpha'], bsdf.inputs['Alpha'])
    bsdf.inputs['Alpha'].default_value = alpha
    mat.blend_method = 'BLEND'
    verts = [(-width/2,y,-height/2),(width/2,y,-height/2),(width/2,y,height/2),(-width/2,y,height/2)]
    mesh = bpy.data.meshes.new(name + 'Mesh')
    mesh.from_pydata(verts, [], [(0,1,2,3)])
    mesh.update()
    uv = mesh.uv_layers.new(name='UV')
    for li, uvco in zip(mesh.polygons[0].loop_indices, [(0,0),(1,0),(1,1),(0,1)]):
        uv.data[li].uv = uvco
    obj = bpy.data.objects.new('REF-' + name, mesh)
    bpy.context.collection.objects.link(obj)
    obj.data.materials.append(mat)
    obj.hide_render = True
    return obj

python

import bpy

def create_reference_plane(name, image_path, width, height, y=0.2, alpha=0.35):
    img = bpy.data.images.load(image_path, check_existing=True)
    mat = bpy.data.materials.new('MAT-' + name)
    mat.use_nodes = True
    nodes = mat.node_tree.nodes
    bsdf = nodes.get('Principled BSDF')
    tex = nodes.new('ShaderNodeTexImage')
    tex.image = img
    mat.node_tree.links.new(tex.outputs['Color'], bsdf.inputs['Base Color'])
    mat.node_tree.links.new(tex.outputs['Alpha'], bsdf.inputs['Alpha'])
    bsdf.inputs['Alpha'].default_value = alpha
    mat.blend_method = 'BLEND'
    verts = [(-width/2,y,-height/2),(width/2,y,-height/2),(width/2,y,height/2),(-width/2,y,height/2)]
    mesh = bpy.data.meshes.new(name + 'Mesh')
    mesh.from_pydata(verts, [], [(0,1,2,3)])
    mesh.update()
    uv = mesh.uv_layers.new(name='UV')
    for li, uvco in zip(mesh.polygons[0].loop_indices, [(0,0),(1,0),(1,1),(0,1)]):
        uv.data[li].uv = uvco
    obj = bpy.data.objects.new('REF-' + name, mesh)
    bpy.context.collection.objects.link(obj)
    obj.data.materials.append(mat)
    obj.hide_render = True
    return obj

Validation print contract

验证打印协议

python

print('VALIDATE expected_primary_parts=', expected, 'actual=', actual)
print('VALIDATE front_locked=True reference_overlay_rendered=True')
if actual != expected:
    raise RuntimeError('Part-count mismatch; refusing export')

python

print('VALIDATE expected_primary_parts=', expected, 'actual=', actual)
print('VALIDATE front_locked=True reference_overlay_rendered=True')
if actual != expected:
    raise RuntimeError('Part-count mismatch; refusing export')

When to stop and ask for human input

何时停止并请求人工输入

Ask for a correction only after generating evidence, e.g. an overlay image or JSON showing ambiguity. Do not ask vaguely. Example: “The analyzer finds N prominent structural components plus M faint background/decorative shapes. Should the GLB include only the structural components?”

仅在生成证据后请求修正，例如显示歧义的叠加图像或JSON。请勿模糊提问。示例：“分析器发现N个显著结构部件加上M个模糊的背景/装饰形状。GLB文件应仅包含结构部件吗？”

Sources distilled

参考资料摘要

Blender Manual: Image Empties for reference images/blueprints; front/back display, opacity, orthographic and axis-aligned controls.
Blender Manual: Trace Image to Grease Pencil works best from manually prepared black/white images and controlled resolution.
Blender Manual: Shrinkwrap moves vertices to a target surface and is useful after silhouette lock for conforming secondary details.
Blender Manual: UV/Image Texture and Project-from-View-style workflows require UV maps and material nodes for renders/exports.
OpenCV docs: contour moments, area, perimeter, bounding boxes, template matching.
scikit-image docs: SSIM for image similarity when pixel-MSE is not perceptually meaningful.

Blender手册：用于参考图像/蓝图的图像空物体；前后显示、透明度、正射和轴对齐控制。
Blender手册：将图像追踪为 grease pencil 工具在手动准备的黑白图像和可控分辨率下效果最佳。
Blender手册：收缩包裹工具可将顶点移动到目标表面，在轮廓锁定后用于贴合次要细节。
Blender手册：UV/图像纹理和“从视图投影”风格工作流需要UV贴图和材质节点以进行渲染/导出。
OpenCV文档：轮廓矩、面积、周长、边界框、模板匹配。
scikit-image文档：当像素MSE不具备感知意义时，使用SSIM进行图像相似度比较。