reference-to-3d

参考图到 3D 重建

此技能用于源文件锁定建模：参考资产就是约定标准。不要凭记忆生成一个看似合理的物体，然后再加以装饰。应先从提供的文件中提取尺寸、部件数量、轮廓和 UV 区域，再构建符合这些测量结果的 Blender 模型。

1:1 重建升级方案

当用户要求真正的 1:1 匹配时，应串联使用以下技能，而不是再次尝试看似合理的建模：

1. reference-analysis-validator 用于清单、蒙版、部件数量和叠加验证关卡。
2. orthographic-registration 用于校准正面、侧面、背面和顶面的坐标。
3. contour-to-mesh 用于从轮廓生成结构网格。
4. atlas-uv-fitting 用于逐部件纹理／UV 拟合。
5. mascot-logo-reconstruction 用于完整编排品牌吉祥物／标志的重建工作。

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

触发的故障模式

如果用户表示输出与模板／纹理／线框不符，请停止常规的 text-to-blender 生成并进入此工作流。反复生成看似合理却不正确的渲染，通常意味着缺少的是参考图分析，而不是再进行一次建模迭代。

信息源优先级

1. 正面模板／正面线框：主要轮廓、可见部件数量、面部／特征位置、品牌辨识度。
2. 纹理图集：精确的部件形状、颜色／材质边界、贴花、光照贴图／光环意图。
3. 侧面／背面／顶面视图：深度、堆叠顺序、厚度、背面形态。不得改变锁定的正面投影。
4. 用户反馈：硬性约束；应将其纳入验证关卡。

必须执行的预检清单

在 Blender 建模之前，编写一份简短的 reference_manifest.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
  }
}

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

流程

1. 清点并分类素材

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

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

2. 在本地分析图像

使用 scripts/template_analyzer.py 进行第一轮组件提取：

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

分析器会返回各组件的面积、基于周长计算的分数、边界框、质心、轮廓和近似类别提示。对于较淡的灰色线框，使用 --mode edges；对于干净的蒙版／纹理图集，使用 Otsu 模式。将这些结果作为测量输入，而非最终依据。

3. 在 Blender 中锁定正面参考

创建正面参考平面或 Image Empty，并使用验证时所用的同一台正交相机。将其前缀设为 REF_，并从导出中排除。Blender 官方文档将 Image Empty 描述为参考图／蓝图，并支持正面／背面深度、不透明度、仅正交视图显示以及按轴对齐显示。

4. 根据源轮廓构建几何体

对每个结构部件：

1. 将 2D 轮廓转换为正视图的 X/Z 坐标。
2. 在轮廓内部生成四边形条带／网格。
3. 根据正面 X/Z 边界或精确的纹理图集区域分配类似 Project-from-View 的 UV。
4. 只有在正面轮廓锁定后，才添加少量 Y 向深度／弧度／挤出。
5. 使用语义化的部件名称：GEO-subject_part_top、GEO-subject_face_shell 等。

除非参考图确实呈放射状，否则不要对吉祥物进行径向复制。标志往往存在遮挡、有意的不对称，以及固定的可见部件数量。

5. 多视图配准

• 首先锁定正面 X/Z 视图。
• 侧视图仅控制 Y/Z 深度轮廓。
• 俯视图仅控制 X/Y 延展范围。
• 背视图用于控制隐藏面/背面几何和验证，不用于控制正面轮廓。

如果各视图不一致，应优先保留正面品牌呈现效果，并记录冲突。

6. UV 和纹理映射

提供任何纹理包时，都要链式加载 blender-uv-texturing。对于由图集驱动的部件：

• 按图集区域裁剪或映射；不要将整个图集投射到每个部件上；
• 正面主视觉表面使用正面投射 UV；
• 侧面/背面使用侧面/背面 UV 岛、程序化填充或烘焙颜色；
• Alpha 贴花需要透明材质设置，且不得引入黑色平面；
• 光照贴图是可选的实时辅助贴图，除非另有说明，否则不要将其连接到自发光输入。

7. 导出前的验证关卡

始终生成：

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

使用 scripts/silhouette_validator.py：

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 代码模式

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

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

验证输出约定

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')

何时停止并请求人工输入

只有在生成证据（例如显示歧义的叠加图像或 JSON）后，才请求修正。不要含糊地提问。示例：“分析器检测到 N 个显著结构组件和 M 个较淡的背景/装饰形状。GLB 是否只应包含结构组件？”

整理后的来源

• Blender 手册：用于参考图/蓝图的 Image Empties；正面/背面显示、不透明度、正交视图和轴向对齐控件。
• Blender 手册：Trace Image to Grease Pencil 最适合使用手动准备的黑白图像和受控分辨率。
• Blender 手册：Shrinkwrap 会将顶点移动到目标表面，适合在锁定轮廓后用于贴合次要细节。
• Blender 手册：UV/Image Texture 和类似 Project-from-View 的工作流需要 UV 映射和材质节点才能进行渲染/导出。
• OpenCV 文档：轮廓矩、面积、周长、边界框、模板匹配。
• scikit-image 文档：当像素均方误差（MSE）无法反映感知差异时，使用 SSIM 衡量图像相似度。