scenario-zbrush-expert

ZBrush 专家（路由器与 Agent 协议）

Agent 通过循环执行 ZBrush 专家级操作：确定性的调色板操作、合成笔触，以及从固定视角渲染画布，每个阶段都设有门控。方法不是编写一个很长的脚本。此技能是每项 ZBrush 任务都要遵循的协议、scripts/ 中的共享工具包，以及团队技能的索引。目标：在 macOS 上通过项目的 Python 桥接使用 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_PLUGIN_PATH=scripts/zb_plugins 和 ZB_BRIDGE_AUTOSERVE=1 启动 ZBrush。它会等待“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）。
• 单一驱动程序。 同一时间只有一个 Agent 驱动 ZBrush。ZBrush 是单实例程序：start() 会拒绝启动第二个实例，且绝不会终止它未启动的 ZBrush 进程。
• 短时、可测量的调用。 每次调用都会返回数值（面数、体积、文件字节数）。ZRemesher、Decimation 或将模型细分至数百万面等长时间操作，都要设置分钟级超时。超时不会取消已排队的代码：主线程空闲后，代码仍会运行。发送其他内容前，请先 Ping 并读取状态。
• 不要阻塞 UI。 切勿调用 message_*、ask_* 或 show_note(..., 0)。要显示进度，请使用 set_notebar_text(text, progress)。
• 共享解释器。 ZBrush 在整个会话期间使用同一个嵌入式 Python：调用留下的内容会一直保留，直到重启。run 和 call 会将 sys.path、sys.modules、stdout 和工作目录恢复为原样，并移除所有工具包模块，即使发生错误也不例外（Maxon 风格指南；服务会运行恢复钩子）。切勿永久向 sys.path 添加文件夹，也切勿在 zb_launch.run 之外导入工具包代码。zb_launch.hygiene() 必须返回空列表；purge() 可清除泄漏。
• 长序列。 将确定性步骤合并到一次调用中： zb_ops.sequence([["divide", [2]], ["polish", [10]]]) 会在 freeze 中运行这些步骤，并调用 show_actions(0)；quiet() 和 frozen(fn) 是实现所需的组成部分（SDK GUI 参考）。 切勿冻结插件按钮操作或画布导出；截屏前请调用 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）；旋转和缩放 [doc]
canvas_click 拖动以雕刻	否（v01：无变化）	canvas_stroke
无需对话框即可将画布导出为 PNG 和 OBJ	是（v03：0.04 s、0.08 s）
按路径保存 ZTL	路径存在，无需对话框 [verify]
将笔画对准模型上的点	在 v03 OBJ 上测量了前视图；其他视图 [verify live_04]	zb_stroke.fit_convention
字符串中的笔压	未知 [verify 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；否则交给人工或计算机使用 Agent
文本提示词（SubTool Rename、New Folder）	否	创建时为部件命名；set_tool_path 仅重命名顶部 SubTool
FBX 导出选项对话框	否（“You cannot escape any GUI”，Maxon 论坛）	按路径导出 OBJ 或 .GoZ
press_key	否（存根中标注“Does not work”）	使用 IKeyPress 的 ZScript 宏 [verify]；从外部调用 System Events
merge_undo、撤销控制	否（“Not implemented”）	版本化 ZTL 保存、Tool:Morph Target:StoreMT
遮罩、图层、多边形组数据	无 API（Maxon 论坛，2026 年）	使用按钮并进行视觉检查；几何体可导出为 OBJ
UV Master 和 Decimation Master 按钮	路径存在；控制权返回情况 [verify 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. 先用确定性操作构建一个阶段；这些操作精确且成本低。只有在形体需要时才使用笔刷笔触。每次笔触前：开启 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）渲染正面、右侧、背面、四分之三角度和顶部视图，并拼成一张带标签的图（正面以外的三张图超出 [verify live_03] 的范围；上下颠倒或方向错误的图块会在图中显现）。用图像读取器打开图像，并按照该领域技能的评审标准进行判断。专家会不断旋转视图；这张图就是 Agent 的环绕视图。
5. 先修正，再做细节。 在初步构形阶段发现的比例错误只需一次调用即可修正；投影后才发现则会耗掉整个阶段。
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，绝不会覆盖文件。至少保留三个版本增量；仅靠 AutoSave 不够（Maxon，Saving Your Work）。QuickSave 用于崩溃恢复，不用于版本管理。
• 切勿在有未保存工具时打开项目。打开 .ZPR 会删除所有已加载的工具（Pavlovich 005）。先保存每个已更改的工具。Ctrl+S 保存的是项目，不是模型。
• 创建 SubTool 时就命名：之后重命名需要文本提示。保存时，顶部 SubTool 会使用文件名（Pavlovich 030）。
• 只在安装目录之外写入；自 2026.1 起，ZBrush 的安装目录为只读。始终使用绝对路径：相对路径会落在应用程序文件夹中。导出会为任何被替换的文件保留 .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）
Polypaint、渲染、展示	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（Agent 端）：start、ping、stop(save_to)、is_running、status、 screen_locked、diagnose、run(code, modules)、call(module, func, *args)、hygiene、 purge。命令行：python3 zb_launch.py start|ping|status|stop|run。
• zb_ops.py（ZBrush 内）：经过检查的封装函数：new_sphere、dynamesh、divide、del_levels、 zremesher、project_all（安全：检查点、nets、Dist、gate）、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)（Agent 端）、capture_views 和 snapshot(path)（ZBrush 内）、contact_sheet、silhouette_bbox。
• zb_audit.py（Agent 端，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 可通过一条命令运行实时检查。

# 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])。
• 曾有 ZScript 在按下 Decimation Master 或 UV 插件后无法收回控制权（ZBrushCentral 2013 和 2014、cgside 2022）。每个插件按钮只测试按下一次，设置较短的超时时间，并在之后执行 ping。
• 预期对带有细分级别的 SubTool 使用 DynaMesh 会弹出模态提示 [verify]；封装函数会拒绝此操作。 切勿为了增加细节而对 DynaMesh 执行 Divide；应先运行 ZRemesher（Pablo，Logic Part 7）。
• ZRemesher 的目标值以千为单位，且只是近似值：请读取实际面数。
• ZBrush 启动后，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。