scenario-zbrush-expert

ZBrush エキスパート（ルーターおよびエージェントプロトコル）

エージェントは、決定論的なパレット操作、合成したストローク、固定ビューからのキャンバスレンダリングをループとして実行し、各段階でゲートを設けて ZBrush の専門的な作業を行います。1 つの長いスクリプトを使う方法ではありません。このスキルは、すべての ZBrush タスクが従うプロトコルであり、scripts/ にある共有ツールキットであり、チームスキルへの案内図でもあります。対象は、プロジェクトの Python ブリッジ経由で操作する macOS 上の ZBrush 2026.2.1 です。ここで名前が挙がっている兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人実行の場合は、ツールのスキーマに基づいて進め、不足している点を明記してください。

1. 実行チャネル

チャネル	用途	ルール
実行中の ZBrush へのブリッジ（scripts/zb_launch.py、クライアント scripts/zb_bridge.py 経由）	すべての対話的な作業：パレット操作、ストローク、レンダリング、計測	zb_launch.start() は ZBrush を ZBRUSH_PLUGIN_PATH=scripts/zb_plugins および ZB_BRIDGE_AUTOSERVE=1 を設定して起動します。「plugin loaded」、ポート、ping を待ってから、ZHomePage ヘルパーを終了します。zb_launch.run(code) または zb_launch.call("zb_ops", "dynamesh", 256) で作業します。zb_launch.stop(save_to=".../x.ztl") で終了します。
-script バッチ起動	保存済みファイルに対する無人ジョブ（すべての SubTool のエクスポート、レポートなど）	ZBrush.app/Contents/MacOS/ZBrush -script /abs/job.py args /abs/scene.ZPR：シーンは最後の引数です。スクリプト引数は sys.argv.index("-script") + 2 から始まります。ファイルを通じてレポートし、sys.exit(code) を使用します（Maxon クイックスタート）。終了時に ZBrush が終了するかどうかは［要確認］です。

ブリッジのルール：

• メインスレッドのみ。 すべての zbc 呼び出しはメインモードで実行されます。これは run と call のデフォルトです。埋め込み VM は ZBrush のメインスレッド上で GIL を保持するため、ソケットスレッドだけでは処理が滞ります。実績のある設計は、メインスレッド上でサーブループを実行し、ポーリングの間に update(redraw_ui=True) を呼び出す方法です（README）。
• ドライバーは 1 つ。 一度に ZBrush を操作するエージェントは 1 つだけです。ZBrush は単一インスタンスです。start() は 2 つ目のインスタンスの起動を拒否し、自身が起動していない ZBrush を終了することはありません。
• 短時間で計測可能な呼び出し。 各呼び出しは数値（面数、体積、ファイルのバイト数）を返します。ZRemesher、Decimation、大量の Divide などの長時間処理には、数分単位のタイムアウトを設定します。タイムアウトしても、キューに入ったコードはキャンセルされず、メインスレッドが空き次第実行されます。それ以上の処理を送る前に、Ping を実行して状態を読み取ってください。
• UI をブロックしない。 message_*、ask_*、show_note(..., 0) は呼び出さないでください。進行状況を表示するには、set_notebar_text(text, progress) を使用します。
• 共有インタープリターは 1 つ。 ZBrush はセッション全体を通じて埋め込み Python を 1 つ保持します。呼び出しによる変更は、再起動するまで残ります。run と call は、見つかった時点の sys.path、sys.modules、stdout、作業ディレクトリを復元し、エラー後もツールキットのすべてのモジュールをアンロードします（Maxon Style Guide。サーバーが復元フックを実行します）。フォルダーを sys.path に恒久的に追加しないでください。また、zb_launch.run の外部でツールキットのコードをインポートしないでください。zb_launch.hygiene() は空のリストを返す必要があります。漏れがある場合は purge() で削除します。
• 長いシーケンス。 決定的な手順は 1 回の呼び出しにまとめます。 zb_ops.sequence([["divide", [2]], ["polish", [10]]]) は freeze 内で show_actions(0) を指定して実行します。quiet() と frozen(fn) がその構成要素です（SDK GUI reference）。 プラグインのボタン操作やキャンバスのエクスポート中にフリーズしないでください。スナップショットを作成する前に update(redraw_ui=True) を呼び出してください。
• 画面ロック中。 Document:Export は引き続きキャンバスの PNG を書き出します（v03）。screencapture に表示されるのはロック画面だけです。2026-09-24 の 05:30 に起動が Home Page のボタン操作後に停止しましたが、同じロック状態での 05:20 の起動は成功しました。start() は停止を検出し、自身が起動したプロセスを終了して、診断結果を報告します（詳細は zb_launch.py を参照）。
• 以降の内容を信頼する前に、zbrush_info(0) = 2026.2 であることを確認してください。

2. 機能マトリックス（ZBrush 2026.2.1、2026-09-24）

操作	状態	代替手段
パスによるパレット項目の押下、設定、読み取り（DynaMesh、Divide、マスク、エクスポート）	はい、実証済み（v01、v03）	必ず最初に exists() を実行してください。誤ったパスに対する set() は何も通知されずに失敗します
合成ストローク Stroke("(ZObjStrokeV02n<N>=H<x>V<y>...)") と canvas_stroke	はい、実証済み（v02：ボリュームが4.189から4.193に増加）
オフセット付きの記録済みストロークの再生	はい（v01：ボリュームが4.184から4.189に増加）。回転とスケールは[ドキュメント参照]
canvas_click でのドラッグによるスカルプト	いいえ（v01：変化なし）	canvas_stroke
ダイアログなしでのキャンバスPNGおよびOBJのエクスポート	はい（v03：0.04秒、0.08秒）
パスによるZTL保存	パスは存在。ダイアログなし［要検証］
モデル上の点を狙ったストローク	v03のOBJを使って正面ビューで測定済み。他のビューは［live_04で要検証］	zb_stroke.fit_convention
文字列でのペン圧力	不明［live_02で要検証］	ストロークごとのDraw:Z IntensityとDraw Size
ストロークごとのスムージング（Shift）	いいえ：SmoothブラシはShiftブラシになるだけです	Tool:Deformation:Polish、hPolishブラシ
ZModelerのポリゴン押下、Gizmoのドラッグ、ピボット配置	いいえ	Deformationスライダー、Geometry X/Y/Z PositionとXYZ Size、Booleansを使ったDynaMesh、ZRemesher。それ以外は人間またはコンピューター操作エージェントに任せてください
テキストプロンプト（SubTool Rename、New Folder）	いいえ	作成時にパーツに名前を付けてください。set_tool_pathで名前を変更できるのは最上位のSubToolのみです
FBXエクスポートオプションのダイアログ	いいえ（「GUIから抜け出すことはできません」、Maxonフォーラム）	パスによるOBJまたは.GoZ
press_key	いいえ（スタブでは「動作しません」）	IKeyPressを使うZScriptマクロ［要検証］。外部からのSystem Events
merge_undo、元に戻す操作	いいえ（「未実装」）	バージョン管理されたZTL保存、Tool:Morph Target:StoreMT
マスク、レイヤー、ポリグループのデータ	APIなし（Maxonフォーラム、2026年）	ボタンと目視確認。ジオメトリにはOBJエクスポート
UV MasterとDecimation Masterの押下	パスは存在。制御の返却は［live_08、live_09で要検証］	ネイティブのTool:UV Map:Create (Unwrap):Unwrap

3. ZBrush のエキスパートループ

1. 数値でブリーフを明確にします。 目的（映画、ゲーム、印刷、コンセプト）、各段階のポリゴン数、印刷時の高さ（mm）、スタイル、参考資料を指定します。ブリーフに記載がない場合は、対象分野のスキルに記載されたデフォルトを選び、記録します。
2. 大きな形から小さな形へと計画します。 プリミティブ、ZSpheres、または低解像度の DynaMesh でブロックアウトし、次にプライマリ、セカンダリ、ターシャリの形を作ります。トポロジー、UV、エクスポートは最後に行います（Pablo Munoz Gomez 著 Understanding ZBrush's Logic の手順）。
3. まず決定論的な操作で1つの段階を作ります。 それらは正確で低コストです。形状に必要な箇所に限ってストロークを使います。ストロークを行う前に、Edit モードをオンにし、意図した対称性の状態を選び、ブラシと Draw の値を設定して読み戻し、set_transform でビューを固定します。ストロークの前後でボリュームを記録し、ストロークでスカルプトした証拠を残します。
4. 段階ごとにゲート判定します。
   • 数値：zb_ops.stats() に加え、OBJ エクスポートに対して zb_audit.audit() を実行します。破壊的なラッパー（DynaMesh、ZRemesher、Divide、Decimate、Polish、Project All）はすべて gate を返します。get_polymesh3d_volume() によるボリューム比と、is_polymesh3d_solid() による水密性が含まれます。リメッシュの崩れや爆発は問題、水密状態の喪失は警告です。zb_ops.require_gate(r) は例外を発生させます。範囲は[追加された]開始値です。
   • レビューシート：zb_review.review(out_dir) は、ニュートラルな MatCap（MatCap Gray）を使って正面、右側面、背面、斜め前方、上面をレンダリングし、ラベル付きのシートに並べます（正面以外の3方向は[verify live_03]。上下逆や反対側のタイルはシート上で確認できます）。画像リーダーで開き、対象分野のスキルに基づいて講評します。エキスパートは常にモデルを回転させて確認します。シートはエージェントにとっての回転確認です。
5. ディテールの前に修正します。 ブロックアウト時に見つかったプロポーションの誤りは1回の呼び出しで直せますが、投影後に見つかると段階全体のやり直しになります。
6. 破壊的な操作の前にチェックポイントを作成します。 DynaMesh、ZRemesher、Project All、ブーリアン、マージ、Decimation の前に、バージョン付きの ZTL を保存します。元に戻す操作はありません。zb_ops.project_all(checkpoint="/abs/x.ztl") は、Project All が「プログラムをクラッシュさせる可能性がある」（cgside）ため、チェックポイントがないと実行を拒否します。その後、最上位にモーフターゲットと New Layer を保存し（FlippedNormals）、Dist を 0.1 に設定し（Drust）、スパイク（可視バウンディングボックスの外側にある頂点）をフラグ付けします。morph_repair(points)（Morph ブラシで保存済みターゲットに戻す）またはレイヤーで修復し、スムージングでは修復しないでください（FlippedNormals）。
7. 証拠を添えて納品します。 最終シート、監査の数値、ファイルパス、未検証の項目を提示します。

最終状態のキャンバスレンダリングを確認せずに、モデルが完成したと報告してはいけません。

4. ファイルの安全性

• キャンバスでストロークを行う前に Edit モードをオンにします（zb_ops.ensure_edit()）。Edit がオフの状態でドラッグすると、ツールの別の pixol コピーがスタンプされます（Pablo、Logic Part 1）。
• バージョン付きの .ZTL ファイルを保存します。zb_ops.save_ztl(path) は次に空いている _vNNN を選び、上書きしません。最低3つのバージョンを残します。AutoSave だけでは不十分です（Maxon、Saving Your Work）。QuickSave はクラッシュ復旧用であり、バージョン管理用ではありません。
• 未保存のツールがある状態で、プロジェクトを開いてはいけません。.ZPR を開くと、読み込まれているすべてのツールが削除されます（Pavlovich 005）。変更したツールはそれぞれ先に保存します。Ctrl+S で保存されるのはプロジェクトであり、モデルではありません。
• SubTool は作成時に名前を付けます。後から名前を変更するには、テキストプロンプトが必要です。保存時には、最上位の SubTool の名前がファイル名になります（Pavlovich 030）。
• ZBrush では 2026.1 以降、インストール先は読み取り専用のため、書き込みはその外部に限り、必ず絶対パスを使います。相対パスはアプリフォルダーに保存されます。エクスポートでは、置き換えるファイルの .bak が保持されます。
• オリジナルを保持します。ZRemesher または Decimation の前に複製します（スカルプトを投影元として維持します）。Merge Visible は新しいツールを作成します。リスクのあるストローク作業の前に、モーフターゲットを保存します。
• 同意なしに、ユーザーの設定（Store Config、ホットキー、zbc.config()、zbc.reset()）を変更してはいけません。

5. ペルソナ別パイプライン

概要	スキルチェーン	成果物
リアルなキャラクターまたはクリーチャー	scenario-zbrush-sculpting, scenario-zbrush-character-creature, scenario-zbrush-retopology-export, scenario-zbrush-paint-render	ZTL スタック、マップ、レンダー
スタイライズされたキャラクターまたはコレクタブル	scenario-zbrush-sculpting, scenario-zbrush-stylized, then scenario-zbrush-pose-print or scenario-zbrush-paint-render	スカルプト、印刷パーツまたはレンダー
ハードサーフェスの小道具または武器	scenario-zbrush-hard-surface, scenario-zbrush-retopology-export	ハイポリ、ゲーム用ローポリ、ベイクデータ
スカルプトのリトポロジーとエクスポート	scenario-zbrush-retopology-export	クリーンなローポリ、UV、マップ、OBJ または GoZ
AI 生成メッシュのクリーンアップ	zb_audit で監査、scenario-zbrush-retopology-export（修復、リメッシュ、投影）、scenario-zbrush-sculpting（形状）	ディテールを加える価値のあるクリーンなスカルプト
ポージングと 3D プリント	scenario-zbrush-pose-print	mm 単位でポージング、内部をくり抜き、キーを付けたパーツ（STL または 3MF）
ポリペイント、レンダー、プレゼンテーション	scenario-zbrush-paint-render	BPR または Redshift のレンダー、ターンテーブル
バッチジョブ、GoZ の往復処理、レポート	scenario-zbrush-automation	スクリプト、-script ジョブ、レポート

チームのスキル間で受け渡すものは、バージョン管理された ZTL と、その stats() および最新のレビュ​​ーシートです。ZBrush の外部への受け渡しには、OBJ または GoZ と、マップおよび監査レポートを使用します。関連チーム：scenario-maya-expert（リギング、アニメーション、Arnold ルックデブ）、scenario-blender-expert（リトポロジー、ルックデブ、レンダリング、GoB の往復処理）、scenario-3d（AI メッシュ生成から仕上げまで）。

6. 共有ツールキット（scripts/）

• zb_launch.py（エージェント側）：start、ping、stop(save_to)、is_running、status、 screen_locked、diagnose、run(code, modules)、call(module, func, *args)、hygiene、 purge。CLI：python3 zb_launch.py start|ping|status|stop|run。
• zb_ops.py（ZBrush内）：チェック機能付きラッパー new_sphere、dynamesh、divide、del_levels、 zremesher、project_all（安全：チェックポイント、メッシュ、Dist、ゲート）、top_level、 store_morph_target、new_layer、set_layer_intensity、morph_repair、polish、deform、 mask、polygroups、visibility、uv_unwrap、decimate、export_obj、export_canvas、 save_ztl、select_brush、find_brush、set_draw、set_material、set_symmetry、 sculpt_stroke、stats、subtools、gate、require_gate、quiet、frozen、sequence。 PATHS には、エビデンスタグ付きで各項目のパスがすべて記載されています。
• zb_stroke.py（純粋なPython、両側）：V02文字列のencode／decode、line、polyline、 arc、zigzag、dab、resample、clip_to_canvas、Camera(transform, pivot).project(p)、 frame_transform、visible_mask、front_most_vertex、fit_convention、VIEWS。
• zb_review.py：review(out_dir, views, matcap)（エージェント側）、capture_viewsおよび snapshot(path)（ZBrush内）、contact_sheet、silhouette_bbox。
• zb_audit.py（エージェント側、numpy）：audit(obj)は、カウント、極、穴、非多様体、巻き方向、 シェル、対称性、バウンディングボックス、面積、体積、辺の長さを返します。 verdict(report, "sculpt"|"game"|"print", ...)、displaced(a, b)。

オフラインテストは合格します（python3 -m unittest discover -s tests/code/zbrush-expert -p "test_*.py"）。ZBrush側の関数は、まだ関数としてZBrush内で実行されていません。それらの下で、v01からv03で実証済みの呼び出しは、references/sdk-cookbook.mdに記載されています。 tests/code/zbrush-expert/run_live.shを実行すると、ライブチェックを1つのコマンドで実行できます。

# not yet run in ZBrush as a sequence
import sys; sys.path.insert(0, "<this skill>/scripts")
import zb_launch as zl, zb_review, zb_audit
zl.start()
zl.call("zb_ops", "new_sphere", 128)
zl.call("zb_ops", "sculpt_stroke", [[500, 380], [620, 380]], brush="ClayBuildup", size=40,
        z_intensity=25)
sheet = zb_review.review("/abs/out/stage1")["sheet"]          # look at it
obj = zl.call("zb_ops", "export_obj", "/abs/out/stage1.obj")
print(zb_audit.verdict(zb_audit.audit(obj["path"]), "sculpt"))
zl.call("zb_ops", "save_ztl", "/abs/out/head.ztl")            # head_v001.ztl
zl.stop()

7. 2026年の主な落とし穴

• 存在しないパスに対するset()は何もせず、エラーも発生しません。Transform:Frameと Brush:Dam_Standardは存在しません。代わりにTransform:Fitとzb_ops.select_brush("Dam_Standard")を使います。 PolyFrameはTransform:Pf（commands.xml id Transform: Pf）、パースペクティブは Draw:Perspectiveです。Transform:PolyFとTransform:PerspはIDではありません。
• query_mesh3d()はリストを返します：int(zbc.query_mesh3d(1)[0])。
• Decimation MasterまたはUVプラグインを実行したZScriptは、制御を取り戻せませんでした（ZBrushCentral 2013 および2014、cgside 2022）。各プラグインのボタンを一度だけ押してテストし、その後、短いタイムアウトを設定してpingを実行してください。
• レベルがあるSubToolでDynaMeshを実行すると、モーダル通知が表示されることが想定されています［要検証］。ラッパーは代わりに実行を拒否します。ディテール追加のためにDynaMeshをDivideしてはいけません。先にZRemesherを実行してください（Pablo、Logic Part 7）。
• ZRemesherの目標値は千単位で、おおよその値です。面数を読み戻してください。
• ZHomePageは起動後、キャンバスを覆います。macOSではCmd+WでZBrushが終了するため、絶対に送信しないでください。
• 項目パスでは、大文字小文字とスペースは区別されません（SDKドキュメント）。Activityログ（Asset Directory Logs/Activity）には、各ボタン押下と設定で使われた正規パスが記録されるため、無料でパスを調べられます（ストロークは記録されません）。

参考資料

• references/sdk-cookbook.md：タスク別の呼び出しとパス、v01からv03のエビデンス、ダイアログの予算を記載しています。ブリッジコードを書く前に読み込んでください。
• references/zbrush-2026-traps.md：自動化とモデリングの落とし穴、およびその解決策を記載しています。呼び出しが何も実行しない、ハングする、またはチュートリアルの手順が2026年の環境と一致しない場合に読み込んでください。
• references/sources.md：認証情報とURLを含む、すべてのソースを記載しています。