blender-geometry-nodes

Geometry Nodes

実行モデルはblender-coreにあります。scripts/gn_builder.pyを使ってツリーを構築します。コンパクトなJSON仕様なので、生のbpyを使うよりはるかに効率的です。ソケット名はバージョンによって変わるため、まず正確な名前を確認してください。

scripts/gn_builder.py -- --describe GeometryNodeDistributePointsOnFaces GeometryNodeInstanceOnPoints
scripts/gn_builder.py -- --spec scatter.json --apply Ground --set Density=20 Seed=3 Mask=@paint_mask

--set Name=@attrを指定すると、名前付き属性からモディファイアー入力に値を渡せます。結果には、評価後の頂点数・面数とノードの警告が表示されます。仕様の形式はスクリプトのdocstringに記載されています。完全な例はreferences/recipes.mdを参照してください。

基本概念（正しく理解しないと何も動きません）

• ジオメトリは、円形のソケットを通って左から右へ流れます。フィールド（ひし形のソケット）は、要素ごとに評価される関数で、フィールドを使用するノード上のドメイン／コンテキストで評価されます。
• ドメイン：Point、Edge、Face、Face Corner、Spline、Instance、Layerです。Capture Attributeはグラフ内の特定の位置（トポロジーが変化する前）でフィールドを固定し、Evaluate on Domainはドメイン間で変換します。
• 属性：組み込み属性（position、normal、sharp_face、material_index、UVMapなど）と、Store Named Attributeを使った名前付き属性があります。名前付き属性はモディファイアーの適用後も保持されます。これにより、GNのデータをシェーダー（Attributeノード）やエクスポーター（glTFのexport_attributes。_で始まる名前をエクスポート）に渡せます。
• インスタンスは効率的です（1つのメッシュと複数のトランスフォーム）。インスタンスごとのジオメトリを編集する場合や、単一のメッシュとしてエクスポートする場合に限り、Realize Instancesを使います。実体化はできるだけ後回しにしてください。
• グループインターフェースで公開した入力は、モディファイアー入力になります（5.2：mod.properties.inputs.<identifier>.value）。パネルは入力をグループ化し、メニューソケットは列挙値を指定します。

ゾーンと高度な型

機能	ノード	用途
シミュレーションゾーン	GeometryNodeSimulationInput/Output（ペア）	フレームごとの状態：成長、パーティクル、浸食。保持するにはベイクします
リピートゾーン	GeometryNodeRepeatInput/Output	N回反復（Lシステム、緩和、再帰的な細分化）
各要素に対して実行	GeometryNodeForeachGeometryElementInput/Output	要素ごとにサブグラフを実行（建物の区画ごと、アイランドごと）
クロージャー／バンドル（5.0以降）	NodeClosureInput/Output、NodeCombineBundle/NodeSeparateBundle、Evaluate Closure	関数／構造化データを受け渡し、再利用可能な「ストラテジー」ノードグループを作成します
リスト（5.2）	GeometryNodeFieldToList、ListGetItem、ListLength、SortList、FilterList	フィールドではなく、実際の配列
グリッド／SDF（4.x～5.x）	MeshToSDFGrid、SDFGridBoolean、SDFGridFillet、SDFGridOffset、GridToMesh	スムーズなブーリアン、リメッシュ、フィレット、ボクセル効果
物理（5.2、実験的）	GeometryNodeXPBDSolver + バンドル	ノードベースのクロス／ヘア。blender-simulationを参照
ギズモ	GizmoLinear/Dial/Transform	入力用のビューポートハンドル

ゾーンではinput.pair_with_output(output)（仕様キーpairs）に加え、出力ノード上の項目（repeat_items、state_itemsなど。仕様の第4ノードフィールド）が必要です。

手順

1. データフローをスケッチします：ソースジオメトリ → 選択／マスク（フィールド） → 生成／インスタンス化 → トランスフォーム／ランダム化 → 実体化／統合 → マテリアル／シェーディングの設定 → 出力。
2. 使用するノード型ごとに--describeを実行してから、仕様を記述してビルドします。node_warningsと評価後の数を確認してください。
3. 意味のある入力（密度、シード、スケール範囲、マテリアル）のみを公開し、最小値／最大値を設定します。
4. 結果を確認し（look）、エクスポートする場合はblender-asset-qaで確認します（実体化したジオメトリ）。インスタンス数と三角形数はblender-game-optimizationで確認してください。
5. 提供方法を決めます。プロシージャルなまま（.blend／アセットライブラリ）にするか、エクスポーター向けにモディファイアーを適用するか、visual_geometry_to_objectsを使います。

ルール

• ランダム性：常に Seed を公開し、Random Value では ID／Index フィールドを使用して、数を変更しても結果が安定するようにします。
• スケールに依存しないセットアップでは、Object Info（Relative）と実単位を使用します。オブジェクトのスケールを適用するか、明示的に読み取ってください。
• マテリアル：ツリー内で Set Material を使用します。マテリアルはファイル内に存在する必要があり、インスタンスはそれぞれ独自のマテリアルを保持します。
• シェーディング：GN の出力では自動スムーズが失われます。Set Shade Smooth と（5.x の）Smooth by Angle エッセンシャルグループを追加するか、sharp_edge を保存してください。
• UV：プリミティブは UV 出力を介して UVMap を出力します。Store Named Attribute（Face Corner、2D Vector、名前 UVMap）で保存しないと、失われます。
• パフォーマンス：数百万のインスタンスを実体化するのは避け、散布には Points とインスタンスを優先し、Merge by Distance の使用は控えめにしてください。また、シミュレーションゾーンを再生／エクスポートするにはベイクが必要です（object.geometry_node_bake_single またはモディファイアーの bakes）。
• ノードツール（ng.is_tool = True、is_mode_edit など）を使うと、グループが 3D ビューメニュー内の編集ワークフロー向けオペレーターになります。

注意点

• 5.2：mod["Socket_2"] は使えなくなりました。getattr(mod.properties.inputs, ident).value を使用し、属性入力には .type = "ATTRIBUTE" と .attribute_name を使用してください。Compare と Random Value のソケットが変更されました。Random Value には、data_type で型が決まる Min／Max／Value の動的ソケットが 1 つずつあります。名前でリンクし、判断に迷う場合は --describe を使用してください。
• 現在のモード／データ型で無効になっているソケットも、同じ名前で node.inputs 内に存在します。ビルダーは有効なソケットを選択します（ビルダーはリンクの前にプロパティを設定します）。先に data_type／mode のプロパティを設定してください。
• nt.interface.new_socket(...) は 4.0 以降の API です（ng.inputs.new は廃止されています）。
• エクスポーターが参照するのは評価済みメッシュです。インスタンスは glTF のインスタンシング（export_gpu_instances）に変換されるか、エクスポート時に実体化されます。