blender-pipeline-automation

パイプラインの自動化

実行モデルは blender-core にあります（run_in_blender.py は Blender を見つけ、JSON の結果のみを出力します）。

バッチ処理のワンライナー

blender -b -P scripts/batch_process.py -- --in "assets/**/*.fbx" --op convert --to glb --out export/
blender -b -P scripts/batch_process.py -- --in library/ --op report                      # inventory JSON lines
blender -b -P scripts/batch_process.py -- --in "src/*.blend" --op script \
    --script ../blender-asset-qa/scripts/qa_check.py --kwargs '{"profile":"game"}'       # QA a whole library
blender -b -P scripts/batch_process.py -- --in src/ --op script --script ../blender-game-optimization/scripts/make_lods.py \
    --kwargs '{"rename":true}' --save-to processed/                                      # LODs for every file

各ファイルは、ok、処理時間、結果を含む 1 行の JSON としてストリーミングされます。失敗してもバッチ処理は停止せず、サマリーに失敗した項目が表示されます。並列処理：--shard 0/N ～ --shard N-1/N を指定して N 個のプロセスを起動します（Blender の Python は 1 コアを使用するため、プロセス数を CPU／GPU 数に合わせて拡張できます）。

ヘッドレス CLI の基本

フラグ	意味
-b	バックグラウンドで実行し、UI を表示しません。最初に指定してください
file.blend	スクリプトの実行前に開きます。引数は左から右に実行されるため、順序が重要です
-P script.py / --python-expr "..."	Python を実行します
--python-exit-code 1	スクリプトで例外が発生した場合、終了コードを 0 以外にします（CI 用）
--factory-startup	ユーザー設定／アドオンを無視します（再現性を確保）。同梱のアドオンは引き続き読み込まれます
--addons rigify,io_scene_fbx	指定したアドオンを有効にします
-E CYCLES -o //out/#### -F PNG -s 1 -e 10 -a / -f 5	レンダリングします（blender-rendering）
--command extension build/validate/install-file	拡張機能のツール（blender-addon-development）
-- --my args	-- 以降はすべてスクリプトに渡されます（sys.argv[sys.argv.index("--")+1:]）
--log "*", --debug-python	デバッグ用です。5.0 ではログ形式が変更されたため、進捗行を正規表現で処理しないでください
環境変数：BLENDER_USER_SCRIPTS、BLENDER_USER_EXTENSIONS、BLENDER_SYSTEM_PYTHON。カスタムカラー設定には OCIO を使用します。

Python モジュールとしての bpy

pip install bpy==5.2.* を実行すると（Python 3.13、Blender のリリースに対応）、通常の Python で import bpy を利用できます。pytest／CI／ウェブサービスで便利です。UI はなく、デフォルトでは GPU モジュールもありません。また、サイズは大きめです（約 300 MB）。対象とする Blender のバージョンに合わせて固定してください。bpy の wheel と CLI は、データ API の操作では同じように動作します。

ライブラリのパターン

• 追加／リンク：bpy.data.libraries.load(path, link=...)（blender-core/references/bpy-patterns.md を参照）。5.2 では、読み込み時に data_from.libraries からネストされたライブラリパスを取得できます。
• 一部を書き出す：bpy.data.libraries.write(path, {datablocks}, fake_user=True, path_remap="RELATIVE_ALL") を使うと、セッションからアセット／ライブラリファイルを作成できます。
• ファイルを検索する：bpy.data.file_path_foreach(...)（5.2 のフラグ：UDIM には EXPAND_TOKENS、シーケンスには EXPAND_SEQUENCES、キャッシュには EXPAND_CACHES）を使用します。また、bpy.utils.blend_paths(absolute=True) はすべての外部パスを一覧表示します。
• パスを再マップ／移動する：bpy.ops.file.find_missing_files(directory=...)、make_paths_relative、pack_all を使用します。ライブラリの場合は、lib.filepath = new; lib.reload() を使用します。
• すべての ID を反復処理する：bpy.data.all_ids（5.2）を使用します。クリーンアップには bpy.data.orphans_purge(do_recursive=True) を使用します。

堅牢性に関するルール

• 可能な限り、プロセスごとに 1 つのタスクを実行します。Blender の長時間セッションでは、画像や取り消しデータが蓄積します。batch_process.py はプロセスを再利用しますが、read_factory_settings(use_empty=True)／open_mainfile でリセットします。
• デフォルトではソースフォルダーに書き込まないでください。別の --out／--save-to を使用し、copy=True を指定して書き込みます。
• スクリプトは冪等にします。再実行時に、スクリプト自身が生成した出力を置き換えるようにします（名前のプレフィックス、exist_ok）。
• 自然言語ではなく JSON をログに記録します。ファイル／ジョブごとに 1 つのオブジェクトにすると、エージェントや CI で簡単に解析できます。
• プロジェクトでは Blender のバージョン（5.2 LTS）を固定します。出力に bpy.app.version_string とハッシュ（bpy.app.build_hash）を記録します。
• パス：bpy.path.abspath("//x") は開いている .blend からの相対パスです。ヘッドレスバッチでは絶対パスを使用するか、open_mainfile の後に設定します。
• コンテナでの GPU：Cycles CUDA／OptiX には NVIDIA コンテナランタイムが必要です。それ以外の場合は CPU を使用してください。ヘッドレスでも EEVEE には GPU／EGL が必要です。

CI のレシピ（GitHub Actions）

Linux tarball（https://download.blender.org/release/Blender5.2/blender-5.2.2-linux-x64.tar.xz）をダウンロードしてキャッシュし、blender -b --factory-startup --python-exit-code 1 -P tests/run_all.py を実行します。このリポジトリの .github/workflows/ci.yml は実用的な例です。