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を、明瞭なマスク／アトラスには大津の二値化モードを使用してください。これらは測定の入力として扱い、最終的な判断基準とはしないでください。

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 アイランド、プロシージャルな塗りつぶし、またはベイクした色を使用してください。
• アルファデカールには透明マテリアルの設定が必要です。また、黒い平面が生じないようにしてください。
• ライトマップはリアルタイム表示を補助する任意の要素です。指定がない限り、放射として接続しないでください。

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。