blender

Blender の操作

Blender（/Applications/Blender.app）は、bpy、bmesh、mathutils に対する Python スクリプトで操作できます。Blender Bridge を通じて操作します。これは 起動中の Blender GUI 内で実行されるスクリプトで、127.0.0.1:8736 に POST されたビルドスクリプトを実行します。メインスレッド上のライブセッションで実行されるため、bpy.data への書き込みが可能で、ビルド中にビューポートが更新され、ビューポートのスクリーンショットも取得できます。ここに記載した内容はすべて、Blender 5.2.2 LTS（同梱の Python 3.13）で実行・検証済みです。これは現在の安定版であり、5.2 は LTS 系列なので、すべての 5.2.x で有効です。ping の応答にある version を確認してください。より新しいリリースでは、ここに記載した内容よりライブセッションを優先し、決めつける前に動作を確認してください。

• scripts/blender-bridge.py — Blender 内で実行するブリッジです。
• scripts/blender-send.sh — .py ファイル（または -c 'inline'）を送信し、取得した出力を表示します。--ping で起動状態を確認し、--state でシーンを JSON として出力します。
• scripts/example-product-shot.py — モデル作成 → マテリアル → 3 点照明 → カメラ → 計測 → レンダリング。
• scripts/example-animated-logo.py — テキスト → キーフレーム → ジオメトリノードによる散布 → フレームシーケンス → 動画。

何かを書く前に references/gotchas.md をお読みください。 Blender の API は 5.x で大幅に変更されており、モデルが記憶している多くの内容（action.fcurves、scene.node_tree、mod["Socket_2"]、BLENDER_EEVEE_NEXT、use_nodes = True など）は、現在では誤りか非推奨です。

操作の流れ

1. ユーザーがブリッジを起動します（初回のみ）。これはリモートから実行できません。bash scripts/blender-send.sh --ping に応答がない場合、次のいずれかを行うようユーザーに依頼してください。

   • scripts/blender-bridge.py を ~/Library/Application Support/Blender/5.2/scripts/startup/blender_bridge.py にコピーする（フォルダー名は実行中の major.minor バージョンです）ことを依頼し、Blender を再起動します。以後、起動時に自動で実行されます（推奨）。または、
   • Scripting ワークスペースを開き、ファイルをテキストエディターに貼り付けて、Run Script（⌥P）を押します。この方法では、そのセッション中のみ有効です。または、
   • Preferences ▸ Add-ons ▸ Install からアドオンとしてインストールします。

   ping が成功すると、 {"ok": true, "bridge": "blender", "bridge_version": "1.2.0", "version": "5.2.2 LTS", ...} が返されます。 bridge_version が古い場合は、ユーザーがインストールしたコピーが古くなっています。ファイルを再コピーするよう依頼してください（古いコピーでは、カメラやエンプティに対する metrics() がクラッシュします）。

2. 作成前に状態を確認します：bash scripts/blender-send.sh --state を実行すると、オブジェクトとそのタイプ、コレクション、マテリアル、ノードグループ、フレーム範囲、解像度、エンジン、ファイルに未保存の変更があるかどうかが返されます。確認用のスクリプトを書くより手軽です。

3. ビルドスクリプトを作成します。以下のチートシートと適切なリファレンスファイルを参考に、スクラッチパッドに作成してください。

4. 送信します：OUT=/path/to/outdir bash scripts/blender-send.sh /path/build.py。ブリッジがライブセッション内でスクリプトを実行し、スクリプトの 取得した標準出力 を返します。エラー時は トレースバック を返し、送信側はゼロ以外の終了コードで終了します。重いレンダリングやベイクには BLENDER_SEND_TIMEOUT=900（秒）を設定してください。スクリプトは Blender 内で実行されるため、シェルの環境変数は 引き継がれません。送信時に --arg quality=final --arg samples=128 のようにパラメーターを指定し、ARGS.get("quality", "preview") で読み取ってください（値は文字列です）。

5. 結果を確認します：まず返された標準出力を確認します。構造化されたジオメトリのチェックには metrics(...)、ビューポートの PNG を Read するには snapshot(...)、実際のレンダリングには render(...) を使います。

6. 反復します：確認し、修正して、再送信します。スクリプトは 再実行可能 にしてください。stage("name") 内でビルドすれば、再送信時に出力が重複せず、自分の出力と置き換わります。

リファレンスの案内

タスク	参照先
作業を始める前に確認すること	gotchas.md
データブロック、トランスフォーム、コレクション、依存関係グラフ、シーン	api-reference.md
bmesh、モディファイアー、カーブ、テキスト、UV、ブーリアン	modeling.md
マテリアル、シェーダーノード、テクスチャ、ワールド/HDRI、ライト、カメラ	shading.md
プロシージャルジオメトリ、散布、インスタンス化、フィールド、ゾーン	geometry-nodes.md
キーフレーム、Fカーブ、ドライバー、NLA、アーマチュア、IK、シェイプキー	animation-rigging.md
剛体、クロス、ソフトボディ、パーティクル、ヘア、流体、ベイク	simulation.md
EEVEE/Cycles の設定、パス、コンポジター、出力、動画	rendering.md
2D／トゥーンの線画、Line Art	grease-pencil.md
クリップの編集、タイトル、トランジション、最終カット	vse.md
glTF、FBX、USD、Alembic、OBJ、STL、.blend の追加／リンク	io-formats.md

注入される名前空間

インポート済み：bpy、bmesh、mathutils、Vector、Matrix、Euler、Quaternion、 math、os、json、さらに OUT（$OUT から取得。os.environ["OUT"] からも取得可能）、ARGS（ --arg KEY=VALUE 文字列を辞書にしたもの）、および以下のヘルパー：

ヘルパー	機能
stage(name)	名前付きコレクションを取得または再作成し、アクティブにします。再送信時も冪等になります（古いオブジェクトが孤立させたメッシュ、マテリアル、ノードグループも解放します）
sync()	view_layer.update()。matrix_world を読み取る前に必ず実行してください
evaluated(ob)	依存関係グラフで評価されたオブジェクト（モディファイアー／ジオメトリノードの結果）
frame(n)	frame_set(n) と依存関係グラフの更新
metrics(objs, path=)	辞書と JSON：カウント、頂点／三角形、ワールド境界ボックス、マテリアル、フレーム範囲
snapshot(path, view=, shading=, fit=)	ビューポートの PNG（高速な視覚チェック）
render(path, engine=, samples=, ...)	EEVEE/Cycles による実レンダーの静止画。変更した設定はすべて復元します
frame_view(objs, view=)	ビューポートの向きを設定します（ISO／FRONT／TOP／CAMERA／…）
world_bounds(objs)	ワールド空間の (min, max)
fcurves(ob) / fcurve(ob, path, i) / channelbag(ob)	スロット付きアクションの F カーブへのアクセス
gn_input(mod, name, value=, attribute=)	ジオメトリノードモディファイアーの入力を名前で読み取り／設定します
ui_override(area)	エディターが必要な一部の bpy.ops 用コンテキストオーバーライド

チートシート

単位はメートルとラジアンです。データ API を優先してください。bpy.ops はモード変更、 smart_project、rigidbody.*、nla.bake、およびインポーター／エクスポーターに使用します。

ジオメトリの作成（再実行可能）

coll = stage("hero_v1")                       # owns its own output; safe to re-send
me = bpy.data.meshes.new("Body")
bm = bmesh.new()
bmesh.ops.create_cube(bm, size=2.0)
bmesh.ops.bevel(bm, geom=list(bm.edges), offset=0.06, segments=3, affect="EDGES")
bm.to_mesh(me); bm.free()
ob = bpy.data.objects.new("Body", me)
coll.objects.link(ob)
ob.location = (0, 0, 1)
sync()                                        # before ANY matrix_world read

マテリアル

m = bpy.data.materials.new("Shell")
b = m.node_tree.nodes["Principled BSDF"]
b.inputs["Base Color"].default_value = (0.75, 0.2, 0.15, 1.0)
b.inputs["Roughness"].default_value = 0.35
b.inputs["Metallic"].default_value = 0.0      # no "Specular"/"Emission" inputs since 4.0
ob.data.materials.append(m)

被写体に向けたカメラ

cd = bpy.data.cameras.new("Cam"); cd.lens = 50
cam = bpy.data.objects.new("Cam", cd); coll.objects.link(cam)
cam.location = (6, -6, 4)
cam.rotation_euler = (Vector((0, 0, 1)) - cam.location).to_track_quat("-Z", "Y").to_euler()
bpy.context.scene.camera = cam

フィードバック

m = metrics([ob], path=OUT + "/metrics.json")
print("METRICS", json.dumps(m))               # comes straight back through the sender
print(snapshot(OUT + "/check.png", view="ISO"))
print(render(OUT + "/hero.png", engine="BLENDER_EEVEE", samples=64,
             width=1280, height=720))

キーフレーム

for f, z in ((1, 0.0), (24, 3.0), (48, 0.0)):
    ob.location.z = z
    ob.keyframe_insert("location", index=2, frame=f)
for kp in fcurves(ob)[0].keyframe_points:     # NOT action.fcurves — that is gone
    kp.interpolation = "BEZIER"
    kp.easing = "EASE_IN_OUT"

エクスポート

bpy.context.view_layer.objects.active = ob; ob.select_set(True)
bpy.ops.export_scene.gltf(filepath=OUT + "/hero.glb", export_format="GLB",
                          use_selection=True)
bpy.ops.wm.obj_export(filepath=OUT + "/hero.obj", export_selected_objects=True)
bpy.ops.wm.save_as_mainfile(filepath=OUT + "/hero.blend", copy=True)

検証

• 返された stdout が即時の確認手段です。print(...) の内容がそのまま返されます。
• metrics(...) は構造化された確認手段です（オブジェクト数／頂点数／三角形数、ワールド境界ボックス、マテリアル）。 $OUT/metrics.json に書き出して読み取り、目視せずにジオメトリを確認します。
• snapshot(...) は高速な視覚チェックです。フルレンダーではなく、ビューポートの OpenGL PNG を出力します。 shading="RENDERED" を指定すると、マテリアルとライトをプレビューできます。
• render(...) は納品用です。Blender が成功を報告したのに何も書き出されなかった場合、診断用の RuntimeError を発生させます。 変更した設定はすべて実行後に復元します。そのため、同じショットを再レンダーできる .blend（F12）もユーザーが必要とする場合は、保存前にシーンの解像度、エンジン、サンプル数を自分で設定してください。
• 引き渡し：$OUT 内の .glb／.blend は、ユーザーがすでに持っている環境で開けます。

セキュリティ

このスキルをインストールすると、ユーザーのマシン上でコード実行サーバーが起動します。ブリッジの起動を依頼する前に、そのことを伝えてください。

• ブリッジは 127.0.0.1:8736（BLENDER_BRIDGE_PORT）にバインドし、/run に POST された任意の Python コードを、ライブセッション内で実行します。実行にはユーザーの権限が使われ、ユーザーが開いているファイルに作用します。リクエストに認証はありません。ローカルのすべてのプロセスと、共有マシン上の他のすべてのユーザーが、ブリッジ経由で Blender を操作できます。
• Web ページからは操作できません。Origin ヘッダーまたはクロスサイトの Sec-Fetch-Site を含むリクエストは 403 で拒否されるため、ユーザーのブラウザーで開いたページからブリッジにアクセスすることはできません。このチェックだけが保護策であり、トークンはありません。
• インストール方法によって、ポートが開いたままになる時間が決まります。 「スクリプティング」ワークスペース ▸「スクリプトを実行」の場合、Blender を終了するまで開いたままです。上記では利便性のため scripts/startup/ へのインストールを推奨していますが、この方法ではエージェントが操作しているかどうかにかかわらず、Blender を起動するたびに待ち受け状態になります。決めつけず、このトレードオフを提示してください。
• ブリッジを停止するには、Blender を終了してください。 リモートからのシャットダウンには対応していません。ポートはプロセスの終了時に解放されます。

安全性

• 開いているファイルに未保存の作業が含まれている可能性があります。確認せずに bpy.ops.wm.read_homefile() や bpy.data.batch_remove を呼び出さないでください。stage() は非破壊のデフォルトですが、ジオメトリを分離するだけで、シーンレベルの設定は分離しません。
• レンダリング、ベイク、シミュレーションはメインスレッドをブロックし、完了するまで UI がフリーズします。小規模な処理を繰り返し、時間のかかる処理を行う前にユーザーへ警告してください。
• ユーザーの .blend ファイルに上書きせず、$OUT に保存してください。save_as_mainfile(..., copy=True) を使うと、ライブセッションはユーザー自身のファイルを開いた状態のままになります。