SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场reference-to-3d

reference-to-3d

设计与创作

查看项目

更新于 10-15 14:56

技能介绍

用途

reference-to-3d 是一个面向 Blender 的源锁定建模技能，用于根据用户提供的参考素材重建模型。其核心原则是：参考资产即契约。不应凭记忆生成一个看似合理的物体再加以装饰，而应先从提供的文件中提取测量值、部件数量、轮廓和 UV 区域，再构建满足这些测量的 Blender 模型。

适用场景包括：用户提供参考图像、模板、纹理图集或正交视图并要求模型与之匹配；或反复出现视觉不匹配反馈，需要进入参考锁定的纠正循环。

主要能力

  • 参考素材清点与分类：将素材归类为 front_template（主品牌图或前视图线框）、side_view/back_view/top_view（正交深度参考）、texture_atlas（含部件的 basecolor/albedo 图集）、decal（透明面部/表情或细节层）、emissive/roughness/bump/normal/lightmap（材质贴图）、aura/background（可选视觉上下文，非结构几何）。
  • 本地图像分析：使用 scripts/template_analyzer.py 进行首轮组件提取，返回组件的面积、周长派生分数、bbox、质心、轮廓和近似类别提示。
  • 前视图锁定：在用于验证的同一正交相机中创建前缀为 REF_ 的前参考平面或 Image Empty，并排除导出。
  • 基于源轮廓构建几何：将 2D 轮廓转换为前视图 X/Z 坐标，在轮廓内生成四边形条带/网格，分配 Project-from-View 风格 UV，锁定前轮廓后再添加浅 Y 深度。
  • 多视图配准：前视图 X/Z 优先锁定；侧视图仅控制 Y/Z 深度包络；顶视图仅控制 X/Y 展开；后视图控制隐藏/背面几何与验证，不改变前轮廓。
  • UV 与纹理映射：图集驱动部件按区域裁剪或映射，不将整张图集投影到每个部件；正面主表面使用前投影 UV；侧面/背面使用侧/后 UV 岛、程序化填充或烘焙颜色；alpha 贴花需透明材质设置。
  • 导出前验证门：生成 front_preview.png、front_overlay_reference.png、front_mask_validation.json、side_preview.png、back_preview.png、top_preview.png，并使用 scripts/silhouette_validator.py 校验。

使用方式

  1. 在首次 Blender 调用前，阅读 ../text-to-blender/references/mcp-backends.md。优先使用官方 MCP 处理共享能力；在整个任务中保持所选后端不变。配方中的工具名称为客户端/旧版示例，需通过该参考及其 agent-host 指南进行映射。

  2. 建模前编写 reference_manifest.json，包含 source_files、primary_view、expected_primary_parts、structural_parts、decorative_parts、texture_regions 和 validation_thresholds（如 front_mask_iou_min、bbox_center_tolerance_px、part_count_exact）。若预期部件数量不明确，用分析器从参考图推导并向用户展示不确定性，而非猜测。

  3. 使用 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 模式。将其视为测量输入，而非最终权威。

  1. 在 Blender 中锁定前参考，创建参考平面或 Image Empty，前缀 REF_ 并排除导出。

  2. 从源轮廓构建几何，保持语义化部件命名，如 GEO-subject_part_top、GEO-subject_face_shell。除非参考确实是径向的，否则不要径向复制吉祥物。

  3. 进行多视图配准，若视图冲突，保留前品牌读取并记录冲突。

  4. 当提供任何纹理包时，链式加载 blender-uv-texturing 进行 UV 与纹理映射。

  5. 导出前始终生成验证产物，并使用 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 低于阈值、面部/特征质心超出容差，或可选 aura/装饰被误包含进基础 GLB，则拒绝最终导出。

1:1 重建升级

当用户要求真正的 1:1 匹配时，应链式使用以下技能，而非再次尝试近似建模：

  • reference-analysis-validator：用于清单、蒙版、部件数量、叠加门。
  • orthographic-registration：用于前/侧/后/顶坐标一致。
  • contour-to-mesh：用于轮廓派生的结构网格。
  • atlas-uv-fitting：用于逐部件纹理/UV 拟合。
  • mascot-logo-reconstruction：作为品牌吉祥物/Logo 工作的完整编排器。

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

触发式失败模式

如果用户表示输出与模板/纹理/线框不匹配，应停止常规 text-to-blender 生成并进入此工作流。反复出现看似合理但错误的渲染，通常意味着缺失的步骤是参考分析，而非另一次建模迭代。

事实来源层级

  • 前模板/前线框：主要轮廓、可见部件数量、面部/特征位置、品牌读取。
  • 纹理图集：精确部件形状、颜色/材质边界、贴花、lightmap/aura 意图。
  • 侧/后/顶视图：深度、堆叠顺序、厚度、背面形态。它们不得改变已锁定的前投影。
  • 用户反馈：硬约束；将其提升为验证门。

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 是否应仅包含结构组件？”

适用场景

  • 用户提供参考图并要求模型匹配。
  • 反复出现视觉不匹配，需要参考锁定的纠正循环。
  • 品牌吉祥物/Logo 重建（通过 mascot-logo-reconstruction 编排）。
  • 需要 1:1 匹配的源锁定建模。

限制

  • 需要 Blender 环境与 MCP 后端。
  • 工具名称需通过 mcp-backends.md 映射，配方中的名称为客户端/旧版示例。
  • 在验证 JSON 和叠加渲染通过清单阈值前不得导出最终资产。
  • 若视图冲突，保留前品牌读取并记录冲突。
  • 预期部件数量不明确时需向用户展示不确定性，不得猜测。
  • 关于收费、价格、平台支持等具体信息暂未提供。