scenario-zbrush-automation

ZBrush 自动化（工具与流程技术指导）

专业的 ZBrush 技术指导会通过约定和验证来实现自动化：每个文件都是独立的工具，每个步骤都是带时限的独立调用，每个输出都会从磁盘读回，而插件卡死只会影响一个文件，绝不会拖垮整个批次。ZBrush 没有超时机制，无法通过 Python 控制撤销，也有代码无法应答的对话框，因此安全保障在 Agent 这一侧：运行器、检查点和报告。如果你可用的技能中缺少此处提到的同级技能，请让用户安装它 （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），包括读写器，其 GoZ 文件与 ZBrush 自带的 ZResources/DXFStar.GoZ 逐字节一致。实时测试套件：tests/code/zbrush-automation/run_live.sh。

立场（专家补充）

• 每次调用只处理一个文件、一个工具和一个步骤。“一次只能有一个 zscript/插件处于活动状态，因此如果你的 zscript 调用了类似 UV Mapper 的功能，控制权就会交给 UV Mapper，之后不会再运行任何命令”（marcus_civis，ZBrushCentral，2014）；按下 Decimation Master's Pre-process 后，ijacobs 的脚本停止运行（2013），并迫使 cgside 改用两次运行的辅助程序（2022，[00:06:56]）。因此，批处理应由 Agent 端循环执行（zb_batch.run_folder）：每个步骤都作为独立的桥接调用发送，并设置各自的超时；超时后发送 ping，发生卡死时重启 ZBrush。一个在 ZBrush 内运行的长脚本，会在第一个卡住的插件处停止。[新增设计]
• 插件最后运行，先保存检查点。 cgside 在 ProjectAll 之前保存，因为“它可能会导致程序崩溃”[00:02:19]。zb_ops.project_all 要求先保存带版本号的文件才能运行，配方中的项目步骤也会传入该文件（{stem}_preproject.ztl），即使 save_ztl 已关闭也是如此。Decimation Master 最后运行，等所有有价值的输出都已写入磁盘后再执行，这样即使它卡住，也只会留下一个 partial 文件，而不会丢失文件。[新增]
• 保持解释器原样。 ZBrush 在整个会话中只使用一个 Python，且脚本文件夹不在 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 文档）；Decimation Master 会缓存数据，UV Master 控制映射也以工具名称为键，因此新工具沿用旧名称时会继承过期数据（插件文档）。导入前，将每个输入文件都暂存为唯一且经过清理的名称（stage_input）；在这台大小写不敏感的 Mac 磁盘上，rock.obj 和 Rock.OBJ 是同一个文件。[新增]
• 从 ZBrush 获取路径，不要猜。 录制内容展示了精确路径和隐藏的前置条件（Maxon ZScript 手册；MadPony DnLlDJxfxHs [00:02:16]）；按住 Ctrl 并悬停可查看路径。对 Agent 来说，成本最低的查询工具是 ZBrush 自带的 Activity log，它会记录每次按下按钮和设置参数的规范路径（zb_batch.ActivityWatch；05:20 的日志已验证）。然后用 zb_plugin_ops.probe() 确认 exists、范围和标题。
• 录制一次，应用到全部对象。 Pavlovich 使用 ZRepeat It，将一次录制的操作重放到每个可见的 SubTool 上 [00:37:30]；ZRepeat It 未随 2026.2.1 版本提供，Python 对应实现是 for_each_subtool。
• 应用之间传递文件，不传递实时链接。 GoZ 会发送最低细分级别（GoZ 文档；FlippedNormals [00:04:02]），按名称更新，并在拓扑发生变化时弹出重新投射提示。Agent 应通过 .GoZ 或 OBJ 文件以及清单交接，再由另一应用的 Agent 导入。

先明确

输入	变更	未说明时的默认值
输入：数量、格式、每个文件的面数	超时、DynaMesh 分辨率、重启频率	OBJ，先用 zb_audit 审核
输出：低模数量、贴图尺寸和空间、预览数量	配方参数	brief 中的数字；否则使用 DEFAULT_PARAMS [已添加]
每个文件的部件数量、有意义的多边形组	ZRemesher 分组	cgside：先自动分组，再对副本启用 ZRemesher 的 Keep Groups，让低模遵循部件划分（MyhwQvkcnwI [00:08:38]）；当输入中的组很重要时，设为 zr_auto_groups=False
目标应用：Maya、Blender、Unreal、Unity	翻转 V、绿色通道、轴、格式	Maya：OBJ + 翻转 V 的切线 PNG，OpenGL 绿色通道 [已添加]
使用谁的 ZBrush	重启权限	绝不重启或退出批处理未启动的 ZBrush
有人看管还是无人值守	试运行规模、截图使用情况	试运行一个文件，有人看管
是否允许共享配置（GoZ 文件夹、Macro 调色板）	GoZ 推送、按键回答宏	不允许：先询问

工作流

1. 会话与探测。 使用 zb_launch.start() 或复用正在运行的桥接；对配方使用的每个路径调用 zb_plugin_ops.probe()；调用 memory()。GATE：ping 返回 2026.2，每个配方路径均存在， 插件均已就绪。
2. 先做计划，不执行。 zb_batch.plan(files, out, params) 无需启动 ZBrush，即可解析每个文件的步骤、路径和超时设置。GATE：输出位于安装目录之外（自 2026.1 起为只读），文件名主体唯一，且不包含 FBX 或 USD 步骤。
3. 监控单个文件试运行。 执行 run_folder([f], out, params)；打开 sheet.png 和法线贴图； 在目标应用中导入低模和贴图（使用 scenario-maya-pipeline-scripting 或 Blender 技能）。 GATE：文件状态为 ok，已记录步骤耗时，并在目标应用中确认贴图方向（在此之前，翻转 V 和 绿色通道均标记为 [verify]）。
4. 运行批处理。 默认使用 Bridge 模式；待 live_a05 显示 ZBrush 如何退出后，再使用 mode="script"（每个文件启动一个 ZBrush -script 进程）。在输出文件夹中放入 STOP 文件，即可在文件之间停止；重新运行即可续跑（依据 sha1 和配方哈希）。GATE：每处理完一个 文件后都会写入 report.json。
5. 恢复。 对每个 failed 或 partial 文件：读取 steps[].outcome（error、 timeout_recovered、hang）、挂起证据（屏幕未锁定时的截图；ZBrush Notes 会绘制在画布上， 只有截图能显示它们）以及 batch.blocked。修正参数或路径后重新运行：已完成的文件会跳过。GATE：报告中为每个非 ok 文件注明了原因。
6. 审核并交付。 打开联系表；检查 low_audit、preview_audit、 normal_stats；编写交接清单。GATE：数值通过审核，已查看联系表，并已交付报告和清单。

数值

数值	相对于	来源
UV Master：最多 100k 到 150k 个面；3k 个面时耗时数秒，150k 个面时最长 5 分钟	SubTool 展开后的面数	UV Master 文档
Divide 会将面数乘以 4；层级数 = 满足 low x 4^n >= source faces 的最小 n，顶层上限为 8M	投影堆栈	Pablo Logic Part 7；上限 [added]
Decimation 的 % of decimation 表示保留的点百分比；100 表示不简化，0.01 表示最大程度简化	点数；约每 2 个点对应 1 个三角形，因此 % = 100 x target_faces / 2 / points	DM 文档；ijacobs 2013；欧拉 [added]
DM 质量：40 到 100 % 看起来相同，2 % 仍然效果不错，1 % 会出现劣化	原始模型	DM 文档
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 存根
宏文件名至少 8 个字符，且需位于子文件夹中；新建文件夹后需重启	<Asset Dir>/ZStartup/Macros/	Maxon 接口文档
步骤超时为 30 到 1,800 s，设为观测到的最慢耗时的 4 倍，且最多为基础值的 10 倍；每处理 10 个文件重启	每个步骤、每个会话	[added]
切线贴图检查：90 % 的像素中蓝色值 >= 128	最终 PNG	[added]
Maya GoZ 会双向翻转 Y 和 Z，并垂直翻转法线贴图	GoZ_Info.txt	本地文件 2026-09-24
从 ZBrush 导入 FBX 到 Blender：缩放比例 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 收缩或膨胀都会导致文件失败。
• 每个文件（代码）： 低模 OBJ 通过 zb_audit.verdict(..., "game")（UV、无多边形面）；低模边界框与输入边界框的误差在 2 % 以内（OBJ 导入会设置 Export Scale: Outgang [00:24:03]）[已添加容差]；法线贴图尺寸符合要求、非纯色、类似切线空间；预览面数接近目标值。
• 每批： report.json 中包含 counts、restarts、blocked、aborted；面向人工查看的 report.csv。
• 视觉检查： sheet.png（每个文件一张画布快照，MatCap Gray）：低模 DynaMesh 导致的薄部位融化、投影尖刺、部件缺失。将法线贴图应用于目标应用，并从侧面打光：检查接缝、细节是否上下颠倒或反转。

常见错误

错误	表现	修复
在 ZBrush 中用一个循环处理所有文件	第一个卡住的插件会冻结所有操作，也不生成报告	run_folder：每个步骤调用一次，每个文件生成一份报告
调用没有超时限制的插件	桥接静默数分钟	插件步骤分开调用；先 wait_recovery，再重启
导入到当前活动工具	当前活动的 SubTool 被替换	import_mesh：先创建 PolyMesh3D 星形工具（usd-portal）
输入文件或工具同名	Decimation 缓存过期，GoZ 更新了错误的 SubTool	unique_stems + stage_input
在无人值守的运行中使用 FBX 或 USD	出现选项窗口，批处理卡住	按路径使用 OBJ 或 .GoZ
对主模型进行 Decimation	雕刻丢失，无法从 Python 撤销	保存 ZTL 检查点，最后进行 Decimation，或在副本上操作
从两个 SubTool 生成法线贴图	贴图中没有细节	贴图会比较同一个 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 和坐标轴说明。
• **交给人工或计算机操作 Agent：**所有需要操作对话框的事项（FBX 选项、SubTool Rename 和 New Folder 提示、End Macro 保存对话框、GoZ 应用选择器、重投影提示）。

ZBrush 2026 说明

• Python（2026.0）与 ZScript 并行运行；press_key“不起作用”，而 merge_undo“尚未实现”（2026.1 存根）：按住按键的操作和单次撤销序列需要通过 Python 按下 ZScript 宏 [verify]。
• 长时间、确定性的序列：通过 zb_ops.sequence、frozen、quiet 或 for_each_subtool(..., freeze=True) 使用 freeze(fn) 和 show_actions(0)（SDK GUI 参考）；切勿在插件按下或画布导出时使用 [added]。
• 自 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：通过面板和快捷键执行相同操作，供人工或计算机操作 Agent 使用。某个步骤需要 GUI 时应加载。
• references/sources.md：所有来源及其凭据和 URL。
• scripts/zb_batch.py（Agent 侧：运行器、会话、报告、-script、Activity oracle、ZScript 生成器）、scripts/zb_plugin_ops.py（ZBrush 内部：单文件步骤和插件）、scripts/zb_batch_job.py（-script 入口）、scripts/zb_goz.py（GoZ 文件和文件夹，任意 Python）。