scenario-zbrush-automation

ZBrush の自動化（ツールとパイプライン TD）

熟練した ZBrush TD は、契約と証拠に基づいて自動化します。すべてのファイルをそれぞれ独立したツールとして扱い、各ステップをタイムリミット付きの個別呼び出しにし、すべての出力をディスクから読み戻します。プラグインがハングしても失われるのは 1 ファイルだけで、バッチ全体ではありません。ZBrush にはタイムアウト機能がなく、Python からアンドゥを制御できず、コードから応答できないダイアログもあるため、安全性はエージェント側にあります。実行ツール、チェックポイント、レポートがその役割を担います。ここに記載された兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で作業する場合は、ツールのスキーマに基づいて進め、不足している点を明記してください。

必須の背景知識： scenario-zbrush-expert（ブリッジ、zb_launch、zb_ops、zb_audit、レビューループ、2026 年の落とし穴）。

ステータス（2026-09-24、リファクタリング第 2 段階）： ここにある ZBrush の呼び出しはすべて、まだ ZBrush で実行されていません（セッションが割り当てられておらず、README の起動時の停止問題も未解決です）。オフラインでは 56 件のテストが成功しています（tests/code/zbrush-automation/run_offline.py）。これには、ZBrush 自身の ZResources/DXFStar.GoZ とバイト単位で一致する GoZ リーダーとライターも含まれます。ライブスイート：tests/code/zbrush-automation/run_live.sh。

スタンス（専門家の知見との差分）

• 1回の呼び出しにつき、1ファイル、1ツール、1ステップです。「一度にアクティブにできる zscript/plugin は1つだけです。そのため、zscript が UV Mapper のようなものを呼び出すと、制御が UV Mapper に渡り、それ以上のコマンドは実行されません」（marcus_civis、ZBrushCentral 2014）。Decimation Master の Pre-process を押すと ijacobs のスクリプト（2013）は終了し、cgside は2回実行するヘルパー（2022、[00:06:56]）を使わざるを得ませんでした。そのため、バッチ処理はエージェント側のループ（zb_batch.run_folder）として実行し、各ステップをそれぞれタイムアウト付きの独立したブリッジ呼び出しで送信します。タイムアウト後に ping を送り、ハングした場合は ZBrush を再起動します。ZBrush 内で実行する長いスクリプトは、最初にプラグインが停止した時点で終了します。[設計を追加]
• **プラグインは最後に、チェックポイントは最初に。**cgside は ProjectAll の「プログラムがクラッシュするかもしれない」ため、実行前に保存します [00:02:19]。zb_ops.project_all はバージョン付きの保存ファイルがないと実行されず、save_ztl がオフの場合でも、レシピの project ステップでは保存ファイル（{stem}_preproject.ztl）を指定します。Decimation Master は、価値ある出力をすべてディスクに保存した後、最後に実行します。そのため、ここでハングしても失われるのはファイルではなく partial ファイルです。[追加]
• **インタープリターは、起動時の状態に戻します。**ZBrush ではセッション中に使える Python は1つだけで、スクリプトフォルダーは sys.path に含まれていません（Maxon Style Guide）。コードは remote_call／zb_launch.run 経由でのみ送信します。モジュールはパスからインポートし、その後 sys.path、sys.modules、stdout、作業ディレクトリを復元します。エラーが発生した場合も同様です。バッチの最後には zb_launch.hygiene() を実行し、リストが空であることを確認します。
• **ダイアログは自動化の妨げになります。実行前に対処を見込んでください。**あるスタジオは Note ダイアログが原因で ZBrush をファームから外しました（danvas 2017）。「成功したかエラーになったかを検出する方法がない」（BigRoyNL 2024）、「エクスポートプラグインでポップアップが出たら、もうお手上げです」（m_adam、Maxon 2025）。set_next_filename が指定できるのは組み込みボタンだけです。FBX ExportImport ではオプションが表示され、「回避できません」（ferdinand、Maxon 2025）。USD Format はプリセットを無視します（usd-portal）。無人エクスポートでは、パスを指定して OBJ または .GoZ を使います。ボタンを押した後も has_next_filename() が true の場合、ダイアログが表示されたままの可能性があります。[追加]
• **名前は識別子です。**GoZ では「読み込んだすべての Tool 間も含めて」一意な名前が必要です（GoZ docs）。Decimation Master のキャッシュと UV Master のコントロールマップはツール名をキーにしているため、以前と同じ名前の新しいツールは古いデータを引き継ぎます（plugin docs）。インポート前に各入力を一意かつサニタイズ済みの名前でステージングします（stage_input）。この Mac の大文字小文字を区別しないディスクでは、rock.obj と Rock.OBJ は同じファイルです。[追加]
• **パスは推測せず、ZBrush から取得します。**記録には正確なパスと、隠れた前提条件が示されています（Maxon ZScript manual、MadPony DnLlDJxfxHs [00:02:16]）。Ctrl キーを押しながらホバーするとパスが表示されます。エージェントにとって最も手軽な参照元は ZBrush 独自の Activity log です。ここにはクリックや設定が正規のパスとともに記録されます（zb_batch.ActivityWatch、05:20 のログで実証済み）。その後、zb_plugin_ops.probe() で exists、範囲、タイトルを確認します。
• **一度記録し、すべてに適用します。**Pavlovich は ZRepeat It を使い、表示されているすべての SubTool に1つの記録を再生します [00:37:30]。ZRepeat It は 2026.2.1 には同梱されていません。Python で同等の処理を行うには for_each_subtool を使います。
• **アプリ間の受け渡しには、ライブリンクではなくファイルを使います。**GoZ は最も低いサブディビジョンレベルを送信し（GoZ docs、FlippedNormals [00:04:02]）、名前を基準に更新します。また、トポロジーが変わると再投影の確認を求めます。エージェントは .GoZ または OBJ ファイルとマニフェストを受け渡し、相手側アプリのエージェントにインポートを任せます。

まず確認すること

入力	変更内容	指定がない場合のデフォルト
入力：ファイル数、形式、ファイルあたりの面数	タイムアウト、DynaMesh 解像度、再起動の頻度	OBJ。まず zb_audit で監査します
出力：ポリゴン数、マップのサイズと容量、プレビュー数	レシピのパラメーター	brief の数値。なければ DEFAULT_PARAMS [追加]
ファイルあたりのパーツ数、意味のあるポリグループ	ZRemesher のグループ設定	cgside：コピーに Auto Groups を適用してから ZRemesher Keep Groups を適用し、ローポリがパーツに沿うようにします（MyhwQvkcnwI [00:08:38]）。入力のグループが重要な場合は zr_auto_groups=False
対象アプリ：Maya、Blender、Unreal、Unity	V の反転、グリーンチャンネル、軸、形式	Maya：OBJ ＋ V を反転したタンジェント PNG、OpenGL グリーン [追加]
誰の ZBrush か	再起動の権限	バッチが起動していない ZBrush は、再起動も終了もしません
監視あり、または無人実行	パイロットの規模、スクリーンショットの使用	1 ファイルでパイロットを実施し、監視します
共有設定が許可されるか（GoZ フォルダー、Macro パレット）	GoZ の送信、キー応答マクロ	いいえ：まず確認します

ワークフロー

1. セッションとプローブ。 zb_launch.start()を実行するか、実行中のブリッジを再利用します。レシピで使用するすべてのパスに対してzb_plugin_ops.probe()を実行し、memory()も実行します。ゲート：pingが2026.2を返すこと、レシピのすべてのパスが存在すること、プラグインが存在すること。
2. ドライランを計画。 zb_batch.plan(files, out, params)は、ZBrushを起動せずに、すべてのファイルのステップ、パス、タイムアウトを解決します。ゲート：出力先がインストール先の外であること（2026.1以降は読み取り専用）、ステムが一意であること、FBXまたはUSDのステップがないこと。
3. 1ファイルでパイロット実行し、監視。 run_folder([f], out, params)を実行します。sheet.pngとノーマルマップを開き、ターゲットアプリにローポリモデルとマップをインポートします（scenario-maya-pipeline-scriptingまたはBlenderスキルを使用）。ゲート：ファイルがokであること、ステップの所要時間が記録されていること、ターゲットアプリでマップの向きを確認すること（それまではVの反転とグリーンチャンネルは[verify]のままです）。
4. バッチを実行。 デフォルトではブリッジモードを使用します。live_a05でZBrushの終了方法が確認できたら、mode="script"（ファイルごとにZBrush -scriptプロセスを1つ起動）を使用します。出力フォルダーにSTOPファイルを置くと、ファイル間で終了します。再実行すると、sha1とレシピのハッシュを使って再開します。ゲート：ファイルごとにreport.jsonが書き込まれること。
5. 復旧。 failedまたはpartialの各ファイルについて、steps[].outcome（error、timeout_recovered、hang）、ハングの証拠（画面のロックが解除されている場合はスクリーンショット。ZBrush Notesはキャンバス上に描画され、スクリーンショットでのみ確認できます）、およびbatch.blockedを確認します。パラメーターまたはパスを修正して再実行します。完了済みのファイルはスキップされます。ゲート：okでないすべてのファイルについて、レポートに原因が記載されていること。
6. レビューと納品。 コンタクトシートを開き、low_audit、preview_audit、normal_statsを確認し、引き継ぎ用マニフェストを作成します。ゲート：数値が基準を満たしていること、シートを確認済みであること、レポートとマニフェストを納品すること。

数値

値	対象	出典
UV Master：最大 100k～150k 面。3k なら数秒、150k なら最大 5 分	展開する SubTool の面	UV Master doc
Divide は面数を 4 倍にします。レベル数は、低ポリゴン数 x 4^n が元の面数以上になる最小の n です。上限は 8M です	投影スタック	Pablo Logic Part 7；上限は [added]
Decimation の % of decimation は保持するポイントの割合です。100 は変化なし、0.01 は最大圧縮	ポイント。ポイントあたり約 2 三角形なので、% = 100 x 目標面数 / 2 / ポイント数	DM doc；ijacobs 2013；Euler [added]
DM の品質：40～100 % は同じ見た目、2 % でも良好、1 % では劣化します	元のモデル	DM doc
ZRemesher の目標値は千単位で、おおよその値です（5 で 4,963 になりました）	目標ポリゴン数	Pablo Logic Part 7
Project All Dist は 0.1 に設定し、明示的に指定します	同じ形状、新しいトポロジー	Drust nxMYYsyJt3o [00:02:19]；ツールキットのデフォルト
create_normal_map(..., local_coordinates=True) = タンジェント；デフォルトの False = ワールド座標	マップ空間	SDK stub
マクロファイル名は 8 文字以上にし、サブフォルダーに配置します。新しいフォルダーを追加した場合は再起動が必要です	<Asset Dir>/ZStartup/Macros/	Maxon interfaces doc
ステップのタイムアウトは 30～1,800 s です。最も遅かった実測値の 4 倍まで引き上げ、基本上限の 10 倍とします。10 ファイルごとに再起動します	ステップごと、セッションごと	[added]
タンジェントマップの妥当性確認：ピクセルの 90 % で青が 128 以上	最終 PNG	[added]
Maya GoZ は Y と Z を双方向に反転し、法線マップを垂直方向に反転します	GoZ_Info.txt	local file 2026-09-24
ZBrush からの Blender FBX インポート：スケール 1000	FBX	FlippedNormals [00:11:21]

品質ゲート

• 各ステップ（コード）： インポート数はファイルの数と一致します（import_mesh の警告）。DynaMesh は remeshed になります。 ZRemesher の比率は目標の 0.5～1.5 です［追加］。UV のバウンディングボックスは 0..1 の範囲内です。Divide の比率はレベルごとに 4 です。すべての 出力ファイルが存在し、空ではありません。各 zb_ops gate（get_polymesh3d_volume によるボリューム、is_polymesh3d_solid による 水密性、投影スパイク）は check_step に渡されます。DynaMesh の崩壊または肥大化、あるいはスパイクがあれば、そのファイルは失敗となります。
• 各ファイル（コード）： low OBJ は zb_audit.verdict(..., "game")（UV、n-gon なし）に合格します。low のバウンディングボックスは入力のバウンディングボックスと 2 % 以内で一致します（OBJ のインポートで Export Scale: Outgang が設定されます［00:24:03］）［許容誤差を追加］。法線マップは指定されたサイズで、単色ではなく、タンジェント空間のような見た目です。プレビューのポリゴン数は目標に近い値です。
• 各バッチ： report.json に counts、restarts、blocked、aborted を記録します。report.csv は人が確認するためのものです。
• ビジュアル： sheet.png（ファイルごとに 1 枚のキャンバススナップショット、MatCap Gray）で、低解像度の DynaMesh による薄いパーツの溶け、投影スパイク、パーツの欠落を確認します。法線マップをターゲットアプリで適用し、側面から照らして、継ぎ目やディテールの上下反転・反転を確認します。

よくある間違い

間違い	発生する問題	対処法
すべてのファイルを 1 つの ZBrush ループで処理する	最初に停止したプラグインがすべてをフリーズさせ、レポートが生成されない	run_folder：ステップごとに 1 回呼び出し、ファイルごとにレポートを生成する
タイムアウトなしでプラグインを実行する	ブリッジが何分も応答しない	プラグインのステップを個別に呼び出し、wait_recovery の後に再起動する
アクティブなツールにインポートする	アクティブな SubTool が置き換えられる	import_mesh：まず PolyMesh3D star を使用する（usd-portal）
同じ名前の入力ファイルまたはツール	Decimation キャッシュが古いままになり、GoZ が誤った SubTool を更新する	unique_stems + stage_input
無人実行で FBX または USD を使う	オプションウィンドウが表示され、バッチが停止する	パスを指定して OBJ または .GoZ を使用する
マスターをデシメーションする	スカルプトが失われ、Python から元に戻せない	ZTL のチェックポイントを作成し、最後にデシメーションするか、複製で行う
2 つの SubTool から法線マップを作成する	マップにディテールが現れない	マップは 1 つの SubTool のレベル間を比較します（AskZBrush n0qqpwvn-jA [00:01:14]）
デフォルトでワールド空間マップを使う	マップが虹色になり、エンジンでシェーディングが正しく表示されない	local_coordinates=True
ユーザーの ZBrush を再起動する	保存されていない作業が失われる	BridgeSession.owned を確認し、代わりに中止する
set() を信用する	スライダーが変わらず、エラーも発生しない	exists() を実行してから値を読み戻す（zb_ops.set_checked）

ハンドオフ

• すべてのペルソナに対応： 手順のバッチ版（for_each_subtool、zb_batch.step で構築したレシピ）、GoZ または書き出し前のインベントリ、パスの検出です。各ペルソナの手順とパラメーターを受け取り、report.json、report.csv、sheet.png およびファイルごとの出力を生成します。
• scenario-maya-pipeline-scripting または Blender スキルから： OBJ または .GoZ ファイルとマニフェスト（名前、単位、更新対象の SubTool）。インポート前に zb_goz.check_names で名前を確認します。
• scenario-maya-pipeline-scripting、scenario-zbrush-retopology-export、scenario-blender-uv-baking へ： UV 付きの低ポリゴン OBJ、タンジェント空間法線 PNG（V の反転と緑チャンネルの設定を明記）、デシメーション済みプレビュー、監査数値、Export Scale と軸に関する注記です。
• 人間またはコンピューター操作エージェントへ： ダイアログが必要な操作（FBX オプション、SubTool Rename と New Folder のプロンプト、End Macro の保存ダイアログ、GoZ のアプリ選択、再投影のプロンプト）です。

ZBrush 2026 に関する注記

• Python（2026.0）は ZScript と並行して実行されます。press_key は「動作しない」、merge_undo は「未実装」（2026.1 のスタブ）です。キーを押したままにする操作や、1 回の取り消しで済ませる一連の操作には、Python から実行する ZScript マクロが必要です［要確認］。
• 長い決定論的な一連の操作では、SDK GUI リファレンスの freeze(fn) と show_actions(0) を、zb_ops.sequence、frozen、quiet、または for_each_subtool(..., freeze=True) 経由で使います。プラグインの実行やキャンバスの書き出しには使用しないでください［追加］。
• 2026.1 以降、インストール先は読み取り専用です。マクロ、プラグイン、Python/init.py は Asset Directory に配置します。この場合は ~/Library/Preferences/Maxon/ZBrush_03C27D49/ です。
• ZRepeat It、Turntabler、ZFileUtils は 2026.2.1 に同梱されていません（リスト）。名前変更 API は存在しません（Maxon フォーラム、2026-09）。
• GoZ は現在も「version 1.01 - April, 11th 2011」と報告します。この Mac の Maya の GoZ 設定は、インストールされていない Maya 2017 を参照しています（zb_goz.app_info）。
• 05:29 に kill -9 を実行した後、再起動が停止しました（README、原因不明）。ハング後の再起動も停止する可能性があります。その場合、実行ツールは再開可能なレポートを出力して中断します。

参考資料

• references/procedures.md：各手順のコード全体（セッション、プローブ、インポート、ファイルごとのレシピ、フォルダのバッチ処理、-script、プラグイン、マップ、SubTool ループ、名前、GoZ、Maya と Blender の往復処理、マクロ、ファイルドロップ、レポート、インタープリターの衛生管理）。バッチを書く前に読み込んでください。
• references/expert-notes.md：タイムスタンプ付きの各ソースの原則と、意見が異なる箇所での判断です。ここで扱われていない設計上の判断が必要な場合に読み込んでください。
• references/critique.md：バッチ、スクリプト、往復処理を評価するための基準です。報告前に読み込んでください。
• references/gui-paths.md：人間またはコンピューター操作エージェント向けに、同じ操作をパレットとホットキーで行う方法です。GUI が必要な手順で読み込んでください。
• references/sources.md：認証情報と URL を含むすべてのソースです。
• scripts/zb_batch.py（エージェント側：実行ツール、セッション、レポート、-script、Activity オラクル、ZScript ジェネレーター）、scripts/zb_plugin_ops.py（ZBrush 内：ファイルごとの手順とプラグイン）、scripts/zb_batch_job.py（-script エントリーポイント）、scripts/zb_goz.py（GoZ ファイルとフォルダ、任意の Python）。