blender-geometry-nodes

Blender Geometry Nodes エキスパート

概要

このスキルでは、Blender 5.x のジオメトリノードに関する専門的なガイダンスを提供します。ノードセットアップの設計、ノードツリーをプログラムで構築する Python スクリプトの作成、パフォーマンス問題のデバッグ、ノードカタログ全体の把握を扱います。リファレンスファイルには、ノードの完全な一覧と Python API の使用パターンが記載されています。

MCP ファーストのアプローチ

ノードグループの作成、フィールドの接続、インスタンスの散布、実行中の Blender セッションからの出力の直接読み取りには、公式 Blender MCP Server（Blender Lab、Blender 5.1 以降）を優先してください。MCP サーバーに接続されていない場合に限り、Python スクリプトの出力に切り替えてください。

検出方法： セッション開始時に、execute_blender_code、get_objects_summary、search_api_docs に一致する名前のツールがないか確認してください。これらは公式の blender-mcp サーバーに属します。いずれかがあれば、MCP を利用できます。

このスキルで使用するツール：

• execute_blender_code — ライブセッションで bpy Python を実行します（主な操作）
• get_objects_summary、get_object_detail_summary — 変更前にシーンの状態を確認します
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — ファイルの内容を一覧表示します
• search_api_docs、get_python_api_docs、search_manual_docs — API／オペレーターの正しい名前を呼び出し前に確認します
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 視覚的な結果を確認します
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 変更を表示するために UI を操作します
• render_thumbnail_to_path、render_viewport_to_path — すばやく視覚的なフィードバックを取得します

ワークフロー： get_* / search_* ツールで確認 → execute_blender_code で変更 → スクリーンショットまたは概要ツールで検証します。問題箇所を特定しやすいように、コードブロックは小さく、冪等になるようにしてください。

セットアップについては、docs/blender-mcp-setup.md を参照してください。

タスクの判断フロー

• 「X のジオメトリノードセットアップを作成して」 -> ノードツリーを設計し、「ノードツリーの生成」を参照して Python コードを作成します
• 「ジオメトリノードが遅い」 -> デバッグと最適化のワークフローに従います
• 「X を行うノードはどれですか？」 -> 完全なノードカタログとして references/node_reference.md を参照します
• 「X を Y に接続するには？」 -> ソケットの互換性を確認し、適切なノードチェーンを提案します
• 「ジオメトリノードツリーのスクリプトを書いて」 -> API の使用パターンについて references/python_api.md を参照します

ノードツリーの生成

Python を使ってジオメトリノードセットアップを作成する場合：

1. 正しい API の使用パターンとノードタイプ名について references/python_api.md を読みます
2. 次のパターンに従ってスクリプトを構成します：
   • ノードグループを作成する
   • グループインターフェース（入力／出力）を設定する
   • 正しいタイプ文字列でノードをすべて追加する
   • ノードを読みやすい左から右へのレイアウトに配置する（x 間隔は約 200～300、y 間隔は約 200）
   • 入力にデフォルト値を設定する
   • ノード間のリンクをすべて作成する
   • 対象オブジェクトにモディファイアーとして適用する
3. 複雑なセットアップを論理的なセクションに整理するには、Frame ノードを使用します
4. Group Input ノードと Group Output ノードを明示的に追加します

ノードタイプ文字列の規則

• ほとんどのジオメトリノード：GeometryNode<PascalCaseName>（例：GeometryNodeMeshCube、GeometryNodeSetPosition）
• シェーダーエディターと共有される数学／テクスチャ／カラーのノード：ShaderNode<Name>（例：ShaderNodeMath、ShaderNodeTexNoise、ShaderNodeValToRGB）
• ブール／比較／ランダムのノード：FunctionNode<Name>（例：FunctionNodeBooleanMath、FunctionNodeCompare、FunctionNodeRandomValue）
• 正確なタイプ文字列が不明な場合は、references/python_api.md を参照してください

グループインターフェースのソケットタイプ

NodeSocketFloat, NodeSocketVector, NodeSocketColor, NodeSocketBool,
NodeSocketInt, NodeSocketString, NodeSocketGeometry, NodeSocketObject,
NodeSocketCollection, NodeSocketMaterial, NodeSocketImage,
NodeSocketRotation, NodeSocketMatrix, NodeSocketMenu

よく使われるノードパターン

散布システム

1. ベースメッシュ（例：Grid または任意のメッシュ） -> Distribute Points on Faces -> Instance on Points <- インスタンスジオメトリ
2. Random Value を追加して、インスタンスの回転やスケールに変化を加えます
3. 結果に対してさらにメッシュ操作が必要な場合は、Realize Instances を使用します

プロシージャルな変形

1. Group Input（Geometry） -> Set Position
2. Position に数値演算（Noise Texture -> Vector Math -> Math）を適用して、オフセットを計算します
3. Vector Math（Add）を使って、オフセットを元の位置に加算します

条件付きジオメトリ

1. 選択フィールドを指定した Separate Geometry を使って、ジオメトリを分割します
2. 各分岐を個別に処理します
3. Join Geometry を使って、結果を再び結合します

押し出し + 変形のパターン

1. Extrude Mesh（Faces） -> Top 選択出力
2. Top 出力を、Set Position、Scale Elements、または追加の押し出しの選択として使用します

カーブベースの生成

1. カーブプリミティブ（Circle、Line など） -> プロファイルカーブを指定した Curve to Mesh
2. または、Mesh to Curve -> カーブ操作 -> Curve to Mesh

Repeat Zone（反復操作）

1. Repeat Input -> 処理ノード -> Repeat Output
2. Repeat Zone の反復回数を設定します
3. Iteration 入力を使って、反復ごとに動作を変化させます

Simulation Zone（物理的な挙動）

1. Simulation Input -> 処理ノード -> Simulation Output
2. 状態はフレームをまたいで保持されます
3. Scene Time またはフレームデルタを使って、時間依存の動作を作成します

Simulation Zone の注意点

重要：以下は、実際のプロジェクトで苦労して得られた知見です。違反すると、見つけにくいバグが発生します。

• Group Input の値は Simulation Zone 内に伝わりません — シミュレーションゾーン内のノードが受け取るのは、モディファイアーで指定した値ではなく、インターフェースの デフォルト 値です。回避策：Simulation Zone のステートアイテムとして値を渡します。
• Object Info は Sim Zone 内で動作します — ただし、オブジェクト参照が Group Input 経由ではなく、ノードソケットに直接設定されている場合に限ります。transform_space = 'ORIGINAL' を設定してください。
• Scene Time は Sim Zone 内で動作します — フレームに基づく有効化ロジック（例：フレーム N でエフェクトを開始する）に使用します。
• Sim Zone のジオメトリはフレーム 1 の後に固定されます — 入力ジオメトリ上の Named Attributes は、後続フレームで更新されません。引き継がれるのはステートアイテムのみです。
• Sim Zone の後に Set Position が必要です — 位置のステートアイテムは値を追跡しますが、頂点を移動しません。追跡した位置を、シミュレーションゾーンの出力後にある Set Position ノードに入力します。
• Collection Info の Instance Scale は常に (1,1,1) を返します — 代わりに、ソースオブジェクトに別のモディファイアーを使って、スケールを名前付き属性として書き込みます。
• Empty は Realize Instances の後にジオメトリを生成しません — Empty の代わりに、軽量なプロキシオブジェクトとして単一頂点のメッシュオブジェクトを使用します。
• Capture Attribute の匿名属性は Realize Instances を通過しません — 代わりに、明示的な文字列名を指定して Store Named Attribute を使用します。
• 可視性の制御 — Delete Geometry を使って、非表示にするための空のジオメトリを出力します。ジオメトリノード内からの hide_viewport/hide_render に頼らないでください。
• to_mesh() ではインスタンスを実体化できません — Instance on Points の出力に対して obj.to_mesh() を実行すると、頂点数は 0 になります。デプスグラフで realize_instances=True を指定して evaluated_get(depsgraph) を使うか、ツリーに Realize Instances ノードを追加します。

For Each Element Zone（要素ごとの処理）

1. For Each Element Input -> 処理 -> For Each Element Output
2. 各要素（ポイント、面、スプライン、インスタンス）を個別に処理します
3. Blender 5.0 で追加

Bundle System（Blender 5.0 以降）

1. Combine Bundle を使って、複数のデータストリームを1つの接続にまとめます
2. Separate Bundle または Get Bundle Item を使って、データを取り出します
3. 複雑なデータを1つのソケット経由で渡すのに便利です

Get/Store Bundle Item（Blender 5.1）

1. Get Bundle Item は、バンドルからインデックスで指定したアイテムを取得します — 5.1 で追加
2. Store Bundle Item は、指定したバンドルスロットに値を格納します — 5.1 で追加
3. 個別の分離／結合を行わずに、より柔軟なバンドル操作が可能になります

Bone Info ノード（Blender 5.1）

1. Bone Info ノードは、アーマチュアオブジェクトからボーンのトランスフォームを読み取ります
2. 出力：Pose、Local Pose、Transform Pose、Rest Pose、Rest Length
3. 入力としてアーマチュアオブジェクトとボーン名を受け取ります
4. リグ駆動のノードセットアップや、ジオメトリノードでのアーマチュア変形が可能になります
5. 注意：ノードがボーンを読み取る一方で、同じアーマチュア内の別のボーンが変更されたオブジェクトに依存している場合、依存関係の循環に注意してください

String to Curves（Blender 5.1）

1. Font（5.1で追加された新しいソケットタイプ）を含め、すべての入力が調整可能なフィールドになりました
2. 新しいWord出力により、モーショングラフィックスで単語ごとの制御が可能です
3. 文字ごとおよび単語ごとのカスタマイズに対応しています

Volume Grid ノード（Blender 5.1）

1. Cube Grid Topology — 構造化グリッド用の新しいプリミティブ
2. Clip Grid — バウンディングボックスの外側にあるボクセルを無効化します
3. Grid Mean ／ Grid Median — グリッドデータに対する統計演算
4. Grid to Points — グリッドのボクセルをポイントクラウドに変換します
5. Grid Dilate & Erode — グリッドに対するモルフォロジー演算
6. Set Grid Background を改善 — グリッドの背景値を設定します

UV ノード（Blender 5.1）

1. UV Unwrap がMinimum Stretch（SLIM アルゴリズム）と「No Flip」設定に対応しました
2. Pack UV Islands にカスタムパック領域用の入力が追加されました

Matrix SVD ノード（Blender 5.1）

1. Matrix SVD（特異値分解）は、行列を U、S、V の各成分に分解します
2. トランスフォームの分析や、カスタム制約システムの構築に役立ちます

Font ソケット（Blender 5.1）

1. フォントデータ用の新しいソケットタイプ NodeSocketFont
2. String to Curves ノードや、その他のテキスト関連ノードで使用されます

デバッグと最適化

パフォーマンスの診断

ジオメトリノードツリーが遅くなる一般的な原因を、影響の大きい順に示します。

1. Realize Instances の使用が早すぎる — インスタンス化されたジオメトリは、できるだけ長くそのままにしてください。実体化するとインスタンスが実際のジオメトリに変換され、頂点数が増加します
2. 不要な属性計算 — 名前付き属性ノードと Capture Attribute ノードは、静的な場合でも毎フレーム評価されます。静的な結果には Bake ノードを使用してください
3. ポイントの分布が密すぎる — 密度を下げるか、一様な分布には面上での Distribute Points ではなく、グリッド上での Distribute Points を使用してください
4. レベル数の多い Subdivision Surface — ビューポートのレベル数を低く（1～2）保ち、最終出力にはレンダーレベルを使用してください
5. 複雑なメッシュに対する Boolean 演算 — 入力メッシュを単純化するか、ボリュームベースのブーリアン演算には SDF Grid Boolean を使用してください
6. Simulation Zone のオーバーヘッド — シミュレーションゾーンを通過するジオメトリを最小限にし、毎フレーム変化するものだけを渡してください
7. ネストされた Repeat Zone — 複雑さが積み重なります。フラット化するか、反復回数を減らすことを検討してください
8. 大量の属性転送 — ハイポリメッシュに対して Sample Nearest／Sample Index を使用する場合は注意してください。空間インデックス（組み込み）を使用しつつ、ソースメッシュの複雑さを抑えてください

デバッグ手法

• Viewer ノード：中間出力を Viewer ノードに接続すると、ツリー内の任意の位置でジオメトリを確認できます。属性データは Spreadsheet エディターで表示できます。
• ノードをミュート：Ctrl+M でノードのミュートを切り替え、問題の原因となるセクションを特定できます
• Spreadsheet 内の名前付き属性：Spreadsheet エディターを開くと、すべての属性、そのドメイン、要素ごとの値を確認できます
• フレームレートオーバーレイ：FPS オーバーレイ（Viewport Overlays）を有効にすると、パフォーマンスをリアルタイムで監視できます
• ノードのタイミング：オーバーレイでノードのタイミングを有効にすると、最も時間を消費しているノードを確認できます
• シーンを簡略化：開発中に細分化レベルやパーティクル数を減らすには、Scene Properties > Simplify を使用してください
• ノードの警告を検索：ノードエディターで Ctrl+F を押すと、警告を検索できます（5.1で追加）
• ノードツール：ノードツールがオペレーターとして登録されるようになり、プログラムからアクセスできるようになりました（5.1で追加）

よくあるエラーと解決方法

• ソケット間で「接続できません」：ソケットの種類が一致していません。正しいソケットの種類については、references/node_reference.mdを確認してください。変換ノード（例：Mesh to Points、Float to Integer）を使用してください
• ジオメトリが消える：Set／Delete／Separateノードの選択入力を確認してください。選択がすべてFalseの場合、すべてが削除されます。Viewerノードで確認してください
• 属性が0／空として表示される：ドメインが一致していません。面に保存された属性は、ポイントから直接読み取ることはできません。ドメイン間で転送するには、Evaluate on DomainまたはCapture Attributeを使用してください
• インスタンスに操作が適用されない：ほとんどのメッシュ操作では、最初にRealize Instancesが必要です。Set Positionはインスタンス化されたジオメトリ自体ではなく、インスタンスの原点に作用します
• Zファイティング／面の重なり：Extrude Meshの後も、元の面が残っています。「Top」の選択を反転させたDelete Geometryを使用するか、Merge by Distanceを使用してください

ノードリファレンス

カテゴリ（Input、Output、Attribute、Curve、Geometry、Mesh、Instances、Point、Volume、Simulation、Color、Texture、Utilities）別に整理されたジオメトリノードの完全なカタログについては、references/node_reference.mdを参照してください。

検索する主なカテゴリ：

• メッシュのプリミティブと操作：node_reference.mdで「Mesh」を検索
• カーブのプリミティブと操作：「Curve」を検索
• ポイントの分布：「Point」または「Distribute」を検索
• インスタンス管理：「Instance」を検索
• ボリューム／SDFの操作：「Volume」、「Grid」または「SDF」を検索
• ユーティリティの数学関数：「Math」または「Utilities」を検索

Python APIリファレンス

ノードタイプの文字列、ソケットの種類、リンク、モディファイアの適用など、Python APIのパターン全般については、references/python_api.mdを参照してください。