scenario-maya-rigging

Maya 绑定

专业绑定意味着每个数值都有解释、每种行为都经过测量：关节位于真实枢轴处，并根据计算得出朝向；控制器在零值时，其位置由 offsetParentMatrix 承载；IK/FK 和空间切换不会造成任何移动；绑定还经得起缩放、距离变化、镜头中出现多个角色，以及动画师为所有内容打关键帧。绑定是构建脚本和数据的产物。如果这里提到的同级技能未出现在你的可用技能中，请让用户安装它 （npx skills add scenario-labs/skills --skill <name>）；若需无人值守地继续，请依据工具模式操作，并标明这一缺口。

必备背景： scenario-maya-expert（执行通道、审查循环、2027 版陷阱）。

模块 scripts/mx_rig.py （sys.path.insert(0, "<skills>/scenario-maya-rigging/scripts"); import mx_rig as R）：尚未在 Maya 中运行；其纯数学部分已通过离线测试（test_rig_offline.py）。安装 Maya 后，运行 tests/code/maya-rigging/run_all.sh，并修复 test_rig_probe 指出的所有问题。

原则（专家级的关键差异）

• 数值整洁，每种值只存一处。 静止姿势下旋转值为零，朝向存于 jointOrient（或不存于任何地方：Fragapane），控制器位置存于 offsetParentMatrix（antCGi；Maya Learning Channel）。OPM 会进行复合，world = local * OPM * dagParentWorld（2027 transform node）：相对驱动时输入 .matrix；或者将 worldMatrix 乘以 DAG 父级的 worldInverseMatrix，再将 translate、rotate 和 jointOrient 归零，否则它们会被应用两次（Maya Learning Channel；antCGi 的腿部会反向旋转）。
• 计算，不凭目测。 如果关节已有旋转或没有子关节，-orientJoint 会静默跳过（2027 cmds.joint）；沿骨骼方向的次级世界轴没有明确定义（antCGi 的脚趾）。R.joint_chain 根据位置计算 jointOrient；极向量落在骨链所在平面上时，不会产生漂移（R.pole_vector_position）[新增]。
• 由动画师定义完成标准。 在中立姿势下切换 IK/FK 不跳动；只有当前模式可见；其余内容全部锁定，因为动画师会“选择层级并为所有内容打关键帧”；在会导致断裂的位置设置限制；肢体行为镜像对称；眼睛和面部朝向一致（antCGi）。
• 优先使用矩阵，再使用约束堆栈，并了解混合方式。 OPM、blendMatrix 和 pickMatrix 可让通道保持自由（Maya Learning Channel 将单只手的关节数从 20 个减少）。blendMatrix 是有序堆栈，每个目标都会覆盖前面的目标（三等分：1、1/2、1/3）；parentMatrix（2025）会归一化权重，并为每个目标存储偏移（2027 Help）。空间混合的是偏移目标，而不是空间本身，否则 IK 会翻转（antCGi）。
• 构建好的绑定是可丢弃的。 使用 Guides、构建脚本、序列化的权重和设置；修复应回写到数据中（Miquel Campos，mGear：“我们会序列化所有内容，并且每次都从干净状态开始构建”；Bungie）。用元数据和关节标签识别骨链，而非依赖名称（Bungie）。skinCluster 只读取影响对象的世界矩阵和 bindPreMatrix：重置绑定姿势，绝不要为此重建关节（Fragapane）。
• 结构决定速度。 Evaluation Graph 会将静态曲线排除在外，并在第一个键值不同时重新计算；没有曲线时，绑定“会陷入严重的瘫痪状态”（Fragapane；Using Parallel Maya 2027）。拆分组件，让开销小的全局运算尽早完成，即使需要重复执行开销小的数学运算也可以（Fragapane）；不要使用 Python 节点、查询场景的表达式或驱动的 frozen；将 hosts 放在肢体之外（Miquel Campos）；优化前先确认 DG、Serial 和 Parallel 的结果一致。
• 在极端情况下测试。 缩放至 1.24 和 1.6（antCGi）；移至一百万单位之外并倒置（Fragapane）；三个引用角色；构建时快速绑定（antCGi）。
• 变形骨架与控制绑定分离。 引擎只处理关节、蒙皮和混合变形：一个位于原点的根关节、引擎要求的名称，以及关节预算（antCGi、Unreal 和 Unity 文档、Bungie）。

优先确定

输入	影响	未说明时的默认值（[added] 除非注明来源）
目标	电影关键帧绑定 vs 引擎骨架（名称、轴向、影响数、单个根骨骼）	功能型关键帧绑定，自定义
摄影机距离、风格	自动绑定器或自定义；扭转和修正关节；风格化：先制作粗略比例绑定和美术指导绘制稿，从第一天起记录最终瞄准备注（Miquel Campos）	主角：自定义；群演：Quick Rig
骨架约定	重用引擎动画时，需要使用其名称和层级	X 轴沿骨骼向下，绕局部 Z 轴弯曲，正 Z 轴方向为屈曲
动画师约定	IK/FK 默认设置、空间、颜色、选择器	手臂 FK，腿部 IK；空间为 world、cog、chest、head；询问
镜头负载	每个镜头中的角色数、密集网格	三个引用角色
面部、动捕、预算	面部对应 scenario-maya-deformation；HumanIK；关节数和影响数	下颌、眼睛、瞄准控制；询问负责人（antCGi：“节俭有益”）

选择路径

Quick Rig + HumanIK	AdvancedSkeleton	mGear Shifter	自定义（mx_rig）
双足，面朝 +Z；游戏或背景角色，“不会被仔细观察”（Maya Learning Channel）；动画需要重定向时使用 HumanIK（2027 Help）；15 个节点，严格 T 姿	基于拟合骨架构建身体和面部，通过切换拟合状态重建；通过 Convert to BlendShapes Only 导出到引擎	角色较多、有团队、需要 Unreal 导出器；先确认是否有适用于该操作系统的 2027 版本 [verify]	主角绑定、严格遵循引擎骨架、需要 Agent 重建和验证的绑定：本工作流

工作流

1. 检查模型。 mx_validate.validate(profile="model") 检查通过；使用厘米；高度符合规格（约 180）；双脚位于 y = 0；以 X 轴为中心；冻结变换；双眼直视前方；指关节、肘部和膝盖处有环线； 面部有嘴部袋状结构（antCGi）。将问题列成清单退回；未经询问，绝不修改客户端模型。 检查关卡：无失败项；已查看线框图。
2. 放置关节，使其位于边缘环线的枢轴处：脊柱关节位于胸腔下方（antCGi）；手腕与手掌解耦（Fragapane）；肘部预先向后弯曲，膝盖向前；第一节上臂和大腿扭转关节与肩部或髋部一同置于顶端，中间扭转关节按位置放置，以保持父级关节的朝向（antCGi）。检查关卡：R.chain_plane 在任何肢体上都不会报错；已查看关节线框。
3. 构建并设置朝向。 肢体使用 R.joint_chain(spec, parent, up="plane")， 脊柱和颈部使用 up=(0, 0, 1), up_axis="y"，根部、重心、头部、眼睛和双脚使用 world=[...]（antCGi：动画师、引擎中的脚部放置），锁骨使用 end_aim=；现有骨架使用： R.orient_with_cmds（腿部和脊柱使用 'zup'）。R.mirror_chain：肢体的行为， 眼睛和面部的朝向；控制器上的旋转顺序（R.rotate_order(twist, main)； Fragapane）；R.set_preferred_angles(root)。检查关卡：R.rig_check(joints=bind) 检查通过；镜像误差在 1e-3 cm 以内；所有手指都沿同一轴、以相同方向弯曲，拇指固定，因此一个属性即可握拳 （antCGi）。
4. 将绑定骨架交给 scenario-maya-deformation（它会在构建控制器时进行绑定）： 仅关节、单一层级、标签、rig_check JSON。
5. 控制器绑定。 R.ikfk_limb(bind[:3], name, rig_parent, ctrl_parent, own_solver=char + "_ikRPsolver")：同一类型的控制器共用一个解算器节点，因此场景中有多个角色时会发生冲突（Fragapane：“可能会弄得一团糟”；2027 Help）。腿部：extra=[ball, toe], orient_end=False，然后使用 R.foot_pivots_from_mesh 调用 R.reverse_foot；P9 脊柱；R.space_switch(ctrl, [None, cog, chest], names=[...])；R.ikfk_match(meta, to="fk"|"ik", key=True) 使用存储的偏移（antCGi 则会在 FK 肘部下方添加一个极点定位器，并添加一个朝向与 IK 脚相同的脚踝定位器）。检查关卡： R.neutral_switch_test 通过，极点漂移低于 1e-3；R.space_test 符合预期；FK 和 IK 姿势分开，R.blend_sweep_test 未发现翻转；滚动扫掠时脚跟、脚掌、脚趾依次着地；没有共用解算器错误；控制器归零。
6. 缩放和拉伸。 仅在不继承缩放的组上设置根部缩放；拉伸基础长度乘以根部 scaleY；IK 脊柱关节置于世界枢轴缩放组下，因为 segmentScaleCompensate 会阻止缩放（antCGi）。检查关卡：在 1.24 和 1.6 的缩放下，测试中性和拉伸状态，误差低于 1e-3 cm。
7. 锁定。 R.lockdown；FK 铰链保持弯曲轴；限制；控制器标签；选择集。检查关卡：R.lockdown_audit 和 R.opm_audit(rig) 均无输出；绑定仍可正常工作。
8. 性能。 先添加关键帧（R.rom_keys，每个已用属性设置两个不同的值）：没有关键帧的绑定会显得很快，结果也不真实。使用 R.eval_census(rig)、R.eval_ab(bind, meshes, frames)； R.prepare_eval_graph(root=rig) 会标记每个控制器（动画师的 Preferences > Settings > Animation > Include controllers in evaluation graph 设置启用后，首批关键帧可避免重复重建图表），并为当前会话启用曲线管理器。运行 R.gpu_override_census(meshes)，然后 GUI 中的 Evaluation HUD 必须显示非零 k 数，否则 deformerEvaluator -meshes 会说明原因。针对 1 个和 3 个引用角色，对 DG、Serial、Parallel 和 GPU Override 进行性能分析；保存带日期的性能分析结果（Miquel Campos）。检查关卡：清点过程无错误；各模式结果相差不超过 1e-5；每个高密度网格都在 GPU 上运行，或已记录原因。
9. 审查。 运行 R.rom_keys，然后使用 mx_review.playblast（GUI）或 R.pose_review（无头模式）； 在镜头距离下运行 R.precision_test；references/critique.md。检查关卡： 已查看各帧；肘部、膝盖、肩部、手腕和双脚的动作都符合预期。
10. 交付。 新版本、validate(profile="rig") 检查通过、测试 JSON、playblast，以及未验证的内容。

数值

数值	相对于	来源
扭转关节：上臂 2 个（上部、中部），下臂 1 个，大腿 2 个，小腿 1 个，另加手腕和脚	骨骼	antCGi
极向定位器距手部 30 个单位；计算得出的极向距离 = 较长的线段	肘部	antCGi；[已添加]
切换、漂移、缩放误差低于 1e-3 cm；中间混合路径与直接角度的偏差不超过 max(1 deg, 5%)	绑定关节	[已添加] 门槛
脚部弯折角度 25 deg：脚掌 = roll 到 25，然后为 50 - roll；脚趾 = roll - 25；限制 footRoll -40..80、footBank -60..60	footRoll	antCGi
脊柱中部扭转衰减为 1、0.5、0.25	丝带关节	antCGi
精度：在 1e5 个单位处出现问题，在 1e6 处闪烁	装配顶层节点	Fragapane
肢体外的主机：每帧 20 到 17 ms	一个角色	Miquel Campos
GPU Override：NVIDIA 为超过 2000 个顶点，AMD 为 500 个顶点；MAYA_OPENCL_DEFORMER_MIN_VERTS，设为 0 会发送全部顶点	每个网格	Using Parallel Maya 2027
blendMatrix 等分：1、1/2、1/3……；计入 inputMatrix：1/2、1/3……	有序堆栈	2027 Help；[已添加]
HumanIK 15 个节点；Unity 4 个影响项；Unreal FBX 2020.2	引擎约定	文档

质量门槛

代码（mx_rig）：rig_check（静止旋转、朝向、控制器、极向定位器、共享求解器、OPM 双重变换、求值清单、锁定）、neutral_switch_test、blend_sweep_test、space_test、scale_test、precision_test、eval_ab、gpu_override_census、game_skeleton_check；scenario-maya-expert 的 validate(profile="rig")。

视觉检查：在线框前视图和侧视图中检查摆放；对每个控制器轴进行 ROM 播放预览，查看前视图、侧视图和四分之三视图；拖动检查脚部滚动；在极端姿势下缩放装配。留意膝盖弹跳、肘部翻转、糖纸状手腕、肩部塌陷、脚部滑动。

常见错误

错误	表现	修正
在带旋转的关节上执行 Orient Joint	没有变化，也没有错误	先冻结旋转，或使用 R.joint_chain
次级世界轴沿着骨骼方向（腿部使用“yup”，向前的脚趾使用世界 Z 轴）	大腿和小腿的轴不一致	选择横跨骨骼的轴；R.orient_with_cmds 会拒绝此设置
肘或膝伸直	IK 朝错误方向弯曲，甚至向后弯曲	预先弯曲，重建，再设置首选角度
极向量偏离链平面；极向量太近	约束后肘部漂移；手部移动时手臂翻转	使用 R.pole_vector_position；将极向量移到更靠后的位置
将 worldMatrix 接入移动父级下的 OPM，或 OPM 驱动后仍保留数值	双重变换、旋转反向	使用父级的 worldInverseMatrix 或 .matrix；使用 R.bake_to_opm；使用 R.opm_audit
用相同的 blendMatrix 权重计算平均值	最后一个目标生效	使用 1、1/2、1/3，或 parentMatrix 节点
混合到空间自身的矩阵	控件跳到目标上，IK 翻转	使用偏移目标（R.space_switch）
句柄使用场景共享求解器	引用的角色发生冲突；一次编辑会更改每个绑定	每个角色使用独立的 own_solver
设置宿主位于肢体内部	播放缓慢（节点级循环）	将宿主放在肢体的父级空间中
IK/FK 混合中途翻转	脚趾或手腕在中途旋转	约束混合：将 interpType 设为 Shortest（antCGi）；矩阵混合：使用 R.blend_sweep_test 测量
分析无关键帧的绑定	动画后数值会骤降；首批关键帧播放卡顿	先添加关键帧；使用控制器标签并预填充
GPU Override HUD 显示“Enabled (0 k)”	GPU 上没有任何变形	使用 R.gpu_override_census、deformerEvaluator -meshes
重复连接缩放，或拉伸未归一化	双重缩放；绑定缩放时肢体被拉伸	仅缩放不继承的组；基础长度乘以根节点 scaleY
组、句柄、定位器未锁定	“全部设为关键帧”会破坏绑定	使用 R.lockdown
样条曲线位于起始关节下方；辅助对象位于绑定关节下方	依赖循环；引擎导出报错	两者都放在绑定骨架之外

交接

• **接收自 scenario-maya-modeling 或 scenario-maya-retopology-uv：**通过 validate(profile="model") 的网格，单位为 cm，Y-up，朝向 +Z，脚位于 y = 0，居中、已冻结、 对称、肢体预弯、眼睛朝前。
• **交付给 scenario-maya-deformation：**绑定骨架（仅关节、一个根关节、已定向、 旋转值为零、带标签）、rig_check JSON，以及绑定关节是通过约束还是 OPM 混合（其姿势读取器依赖此设置）；接收权重数据和需要重新连接的修正器。
• **交付给 scenario-maya-animation：**供其引用的绑定，归零且带标签的控制器，通过检查的 validate(profile="rig")、切换列表、ROM 播放预览、已知限制。
• 游戏绑定交付给 scenario-maya-pipeline-scripting：game_skeleton_check 检查通过，绑定混合使用约束，除非已证明 OPM 导出可行；他们负责导出 FBX。

Maya 2027 备注

• 2026 年的重命名：addDL、multiplyDL、pointMatrixMultDL；普通数学节点名称会创建无单位节点； condition、multiplyDivide、reverse、blendMatrix 保持不变。
• parentMatrix（2025）提供 Snap 和 Initialize Target Offset；axisFromMatrix 取代逐轴节点。
• Orient Joint：负主轴已在 2027.1 修复；自 2025 起支持自动定向次轴。
• ikHandle 仅列出 RP、SC 和样条解算器；先加载弹簧和双骨骼解算器。FBIK 会强制使用 Serial： 请使用 HumanIK。
• GPU Override：已知的 2027.2 问题是在启用时拖动时间轴会崩溃（请禁用它或不可见性求值器）；论文仅涵盖 AMD 和 NVIDIA 上的 OpenCL，因此请查看 Apple GPU 上的 HUD [verify]。求值器设置按会话保存，不会保存到场景中。
• Skin Tools 图层会阻止经典权重工具运行，直到将其删除（scenario-maya-deformation）。仅支持 PySide6；不附带 PyMEL。

参考资料

• references/procedures.md：每个阶段的代码及其测试；编写绑定代码前阅读。
• references/expert-notes.md：专家判断和意见分歧；适用于此处未涵盖的决策。
• references/critique.md：评估标准；每个关卡都要查看。
• references/gui-paths.md：菜单、Profiler、HUD；操作 GUI 时参考。
• references/sources.md：来源、URL、时间戳。