scenario-maya-deformation

Maya 变形（角色 TD）

专家级变形在第一个权重确定之前就已决定：关节枢轴和边缘环决定蒙皮能做到什么。随后按区域构建权重，在极限姿势下通过运动、数值和渲染进行评估，并从源头修复每个缺陷。原则：先锁定姿势，进行诊断，再平滑并调整形状，修正权重无法解决的问题，并确保所有内容都能作为数据重新生成。如果此处提到的某项同级技能不在你可用的技能中，请让用户安装它 （npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具架构继续操作并标明这一缺口。

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

模块 scripts/mx_skin.py：权重 IO、区域锁定、遮罩、镜像、传递、ROM 生成器、变形指标、修正器、Skin Tools 封装。状态（2026-09-24）： 其纯 Python 部分已离线运行（test_mx_skin_offline.py，全部通过）；所有 Maya 调用尚未在 Maya 中运行（测试：tests/code/maya-deformation/run_all.sh，通过 mx_run.py）。 import sys; sys.path.insert(0, "<skills>/scenario-maya-deformation/scripts"); import mx_skin as S

立场（专家补充）

• 未平滑的权重是绑定测试。 将每个顶点 100% 分配给距离最近的关节并摆好姿势：它「看起来应该相对接近预期的最终效果」；否则，应先修复枢轴、位置或拓扑环。用平滑掩盖绑定问题：「不要在生产环境中这么做」（Makauskas）。沿手腕或脚踝走向的拓扑环是建模师的问题；肘部形变干净却丢失体积，则是绑定的问题（antCGi）。
• 填满区域，在蒙版中进行艺术指导。 每个决定单独放在一层：扭转关节均匀填充，耸肩、肩部和肘部的形状则由蒙版控制，因此重新平滑扭转权重不会破坏肘部（Jao）。「蒙版不是实际影响范围」，而是该层的 Alpha（Makauskas）。在无界面模式下，S.block_regions 会合成同一组图层，并只写入一次。
• 在运动中评估，每次只测试一种动作。 徒手体操测试：每 10 帧设一个关键帧，每隔一个关键帧摆一个姿势，中间回到绑定姿势；不要同时弯曲和下压（Makauskas）；极限和「奇怪」的姿势能暴露问题。ML 姿势数据：每次只动一个关节，每步约 30 度（Widup）。
• 平滑不是没有代价的。 手指拓扑稀疏时会丢失体积：先平滑中间的拓扑环，再使用 Sharpen（Makauskas）。此处的测量 [新增]：平滑将肘部弯曲 110 度时的拉伸从 3.9x 降至 1.5x，但导致肘部内侧塌陷（边缘比 0.19）。深度弯曲需要正确的修形，而不是更多平滑。
• Skin Tools 图层属于创作状态。 图层存在时，Maya 会禁用经典的绘制、镜像、复制、锤平、设置最大影响数量和归一化工具；Delete Skin Layers 会保留求值后的权重，是交接步骤（帮助文档）。「最终它仍然是普通的 Maya 蒙皮」（Jao）。
• 雕刻前先选择修形所用的空间。 变形前修形「就像修复角色的原始网格」，并且能在其他姿势中保持效果；变形后修形则修复某个摆姿结果：当一个关节负责该修形时使用 Transform Space（速度更快，但受该关节影响范围限制），或使用 Tangent Space，使修形能跨关节跟随表面（帮助文档；跨关节的解读为 [新增]）。先处理极限姿势，再处理过渡姿势（帮助文档）。引擎方案：由摆动-扭转姿势比例驱动次级关节，并为每个关节指定其 LOD（Rudy）。
• 读取绑定实际驱动的关节。 由 IK/FK 约束或 offsetParentMatrix 混合驱动的绑定关节，需要通过控制器来摆姿势。Pose Editor：不添加中性姿势，先创建插值器；在 Driver Settings 中添加驱动控制器的属性，然后再点击 Add Neutral Poses；手腕绕前臂扭转时使用 Euler Twist（帮助文档）。节点读取器使用 dagLocalMatrix，因为 OPM 驱动会使 rotate 保持为 0 [新增]。
• 面部：先规划预算，旋转交给关节。 先确认关节和形状预算；嘴唇微微分开的中性姿势能让蒙皮「容易得多」（Burton）。即便面部使用形状，眼睛、眼睑和下颌仍由关节驱动；拆分形状的权重之和必须与主形状完全一致（antCGi）。ML Deformer 学到什么取决于输入：在 Control Collector 中为关节蒙皮，先移除 Delta Mush，并优先保证姿势覆盖，而非网络规模（Widup）。

首先确定

输入	影响	简要说明未明确时的默认值
目标运行时	影响数上限、是否允许 DQ、校正器使用形状还是次级关节、面部形状还是关节	Maya 中的电影风格：制作时不设上限，最后修剪至 0.01 [新增]；游戏：使用引擎或负责人规定的上限（具体数值）
骨架（scenario-maya-rigging）	区域、扭转链、镜像规则、绑定关节的驱动方式（约束或 OPM）	仅使用绑定关节，旋转归零，采用 L_/R_ 命名，每个肢体部分都包含扭转关节（资料中为 3 到 5 个）
网格（scenario-maya-retopology-uv）	绑定方法、壳	对包含内部关节的封闭单壳使用 Heat Map；对于多部件或非流形网格，使用 Geodesic Voxel
变形需求	风格化挤压（两个簇）、服装、面部范围、主角还是背景角色（ML Deformer）	身体和服装分别作为蒙皮网格；面部 = 下颌、眼睛和眼睑由关节驱动
Skin Tools API（S.skin_tools_probe()）	分层或普通工作流	使用内存分层的普通簇；只有在有人会为其绘制权重时才使用实际分层

工作流

1. 验收门槛。 mx_validate.validate(profile="model")、mx_audit.verdict(r, symmetric=True)、 S.bind_precheck(mesh, joints, method)。门槛：无错误行、关节位于网格内、变换已冻结、 无非变形器历史记录、X 轴对称；面部：嘴唇分开，眼部关节位于眼球中心（Burton）。
2. 明确绑定。 S.bind(mesh, joints, method, skin_method=0, normalize=1)：传入所有 标志，因为 cmds 和 UI 的默认值不同，而且 Help 对 normalizeWeights 的说明自相矛盾。 门槛：S.weights_verdict(S.audit_weights(...)) 检查干净；使用 S.export_weights_json 备份（OpenMaya 写入不可撤销）。
3. 区块化并诊断。 使用最近骨骼区域调用 S.block_regions，不进行平滑；关键 动态活动（S.rom_schedule、S.key_rom）；S.deformation_test；先运行 S.pose_snapshots， 再以无头模式运行 mx_review.review 并查看结果。门槛：原始姿势读数接近目标；故障连同数值和图片 返回 scenario-maya-rigging（枢轴）或 scenario-maya-retopology-uv（边环）。
4. 区域、扭转、蒙版。 顺序：躯干、锁骨和肩部、上臂、前臂、手、拇指、 手指、头部和颈部、腿、脚（Makauskas）。扭转链使用均匀渐变，蒙版使用沿骨骼的范围；使用 API 时调用 S.st_add_region_layer 和 S.st_flood。 调整蒙版范围，而不是顶点。门槛：审核干净，警告逐个姿势减少，最差姿势已查看。
5. 镜像和外壳。 S.mirror_skin（或 Skin Tools 的 Mirror 选项卡）；服装和配饰 继承其下方身体的权重（S.copy_nearest、S.remap_by_closest，体积平滑仅限于 外壳）。门槛：镜像误差 < 0.01，无未匹配项，静止时无穿插。
6. 完整 ROM。 检查前臂中段和上臂中段的分段、骨骼体积、褶皱、串扰、刚性 鞋底、服装穿插；然后测试组合“怪异”姿势并模拟动画师风格的播放；会话存在时进行 GUI 播放预览。门槛：无 error:，每条 warn: 均已修复或说明， references/critique.md 评分至少为 2。
7. 修正体。 糖果包装效应：先调整扭转分布，再使用 DQ 或权重混合蒙皮。深度 弯曲：选择前置或后置，以及目标空间（姿态）；检查 S.joint_drive(joint)，若关节受驱动，则通过控制器摆姿势，然后 从摆好的雕刻结果调用 S.solve_pre_corrective 和 S.corrective_driver，或在 GUI 中使用 Pose Editor（按上述控制器驱动顺序；先处理极限姿势；Regularization 从 0.01 开始）。门槛：静止时为 0，通过控制器到达目标姿势时为 1， 残差 < 1e-3 cm；重新运行 ROM。
8. 面部（如适用）。 通过拆分生成器创建形状（S.split_targets、 S.add_split_targets），或使用静止姿势为零的关节面部（Burton）；将挤压变形放在两个簇下方（multi=True，UV Pin 读取簇 1，将组逆矩阵写入 bindPreMatrix）。门槛：拆分误差 < 1e-5，数量在预算范围内，双重变换测试通过。
9. 收尾。 S.delete_skin_layers、S.prune_and_limit 以符合目标上限，重新运行 ROM，导出权重 JSON（以及图层 JSON），运行 mx_validate.validate(profile="rig")，保存一个新版本。

数值

数值	相对于	来源
每 10 帧设置关键帧，每隔一个关键帧设置姿势	徒手体操的计时	Makauskas [00:03:01]
3（Makauskas）或 5（Jao）个扭转关节	每条上臂或前臂	[00:07:57]、[00:17:13]
权重总和在 1e-4 内为 1	每个顶点，按簇计算	归一化（Jao、Help）
剔除低于 0.01 的权重 [已添加]	每个权重；Help 指出 0.008 可忽略	Help、Prune
影响数上限为 4 [已添加]；Burton 的 Unreal 移动端项目中为 2	每个顶点，仅适用于游戏	Burton [00:51:55]
边长比 < 0.7 为挤压，> 1.3 为拉伸 [已添加]	姿势下的边长与绑定姿势下的边长之比	摘要阈值
截面面积 < 0.7、周长 < 0.8 [已添加]	肢体中段横截面与绑定姿势下的横截面之比	糖纸效应；LBS 在 50/50、90 度扭转时保留 0.5 的面积（实测）
体积变化 > 10% [已添加]	骨骼周围区域	Makauskas 凭目测判断体积
镜像差异 < 0.01 [已添加]	顶点权重与其镜像顶点权重之差
正则化 0.01 至 1.0；3 个中性姿势（中立、摆动、扭转）	Pose Editor	Help
每步 30 度；每个身体 1,500 至 2,000 个姿势；每条手臂 12 至 20 个姿势	ML Deformer 姿势数据	Widup [00:15:50] [00:37:08]
24 个面部关节	Burton 当前世代游戏的面部	[00:35:45]

质量门槛

可测量（无头模式，mx_run）：在目标上限下，S.weights_verdict 无问题；S.deformation_test 不含 error:（纯蒙皮不可能出现串扰）；修复或说明警告；镜像误差 < 0.01；服装的 penetration 增量为 0；通过控制器设置姿势时，修正器在静止姿势下为 0、目标姿势下为 1； 拆分误差 < 1e-5；交付前 S.skin_layers_node(sc) == []；重新导入的 JSON 能重现权重（差异 < 1e-4）。视觉检查：使用 mx_review.review 渲染每个 ROM 姿势的 S.pose_snapshots（黏土和线框、正面和四分之三视角，每次迭代使用相同的相机），或使用 GUI 录制 playblast。抬脚时检查耸肩和三角肌、肘窝、手腕扭转、手指、腹股沟和膝盖，以及双脚、颈部和服装；面部检查嘴角、脸颊挤压和眼睑。依据 references/critique.md 进行评判。

常见错误

错误	表现	修正
掩盖不良的枢轴	手腕鼓包、颈部凸起在每个姿势中都会重新出现	移动关节（scenario-maya-rigging），重新分块（Makauskas）
单独解读边数	刚性权重显示没有挤压，但部件相互穿插	查看褶皱、塌陷面和严重程度（critique.md）
在活动的簇上编辑 maximumInfluences	自定义权重被悄然重置	使用 S.prune_and_limit（帮助：在编辑模式下使用 -mi 会清除权重）
使用默认标志运行 copySkinWeights	采用 closestComponent 关联方式，镜像平面为 XY	传入 surfaceAssociation、influenceAssociation、mirrorMode="YZ"
在分层簇上使用传统工具	出现“blocked”错误，或权重之后被覆盖	先使用 S.delete_skin_layers，或使用对应的 Skin Tools 工具
网格外存在末端关节时使用 Heat Map	这些关节不会获得权重	将关节移入网格内，或在预检查后使用测地线方法
用组合动作测试动画	无法判断是哪个关节出现问题	每个部分只用一个动作（rom_schedule）
对稀疏的手指使用 Flood 平滑	手指变成香肠状，指关节消失	平滑中间环，使用 Sharpen（Makauskas）
将网格级错误雕刻成后置修正	修正只在某个姿势附近显现	使用变形前修正（S.solve_pre_corrective）：它在所有姿势中都有效（帮助）
在 IK 或受约束关节上创建中立姿势	Pose Editor 无法返回中立姿势或切换到某个姿势	创建时不添加中立姿势；依次选择 Driver Settings > Controllers，然后选择 Add Neutral Poses（帮助）
在 .matrix 上使用姿势读取器，或对受驱动关节使用 setAttr	修正卡在开启或关闭状态；姿势被拒绝或弹回	使用 S.corrective_driver（dagLocalMatrix）；通过控制器设置姿势
中立姿势时嘴唇闭合	镜像和包裹传递失败，嘴唇粘连	让嘴唇稍微分开（Burton）；拆分上、下代理（Jao）
拆分的形状重叠	嘴角出现双重运动	设置顶点归属，使用差异形状（抬起而非微笑），进行求和测试（antCGi）
在 ML Deformer 下保留 Delta Mush	ML 会学习到平滑效果	训练前将其删除（Widup）
固定控制器读取最终网格	依赖循环	使用来自 skinCluster1.outputGeometry 的 UV Pin（Maya LC）

交接

• 接收自 scenario-maya-rigging： 绑定骨架（仅关节，旋转为零，方向正确，单根，名称或标签为 L_/R_）、ROM 控制器、已放置的扭转关节，以及绑定关节是通过约束还是 offsetParentMatrix 混合；mx_validate(profile="rig") 检查通过。接收自 scenario-maya-retopology-uv：冻结在原点的网格、无历史记录、对称、每个关节处都有环线、UV、嘴唇分开的面部，以及已就位的眼睛。
• 交付给 scenario-maya-animation： 删除图层后的新版本 Rig、权重和图层 JSON、ROM 判定 JSON、查看过的表格或 playblast，以及尚未验证的内容；采用引用方式，绝不导入。
• 交付给 scenario-maya-pipeline-scripting（游戏蒙皮）： 为引擎封顶并精简后的权重、仅作为影响对象的绑定骨架、带有 LOD 分配的次级关节列表、引擎需要时作为关节的校正器；用于其 FBX 导出检查的审计 JSON。
• 退回： 将轴心和放置问题退回 scenario-maya-rigging，将环线问题退回 scenario-maya-retopology-uv，并附上姿势、数值和图像。

Maya 2027 说明

• 内置 Skin Tools（基于 ngSkinTools）：Skin > Skin Tools；仅在显式初始化后才有图层；Bind Skin 的 Initialize Skin Layers 默认关闭；绘制偏好设置默认为经典工具。
• 脚本：from ngSkinTools2 import api（Developer Help，获取于 2026-09-24；尚未导入）：init_layers、Layers、assign_from_closest_joint、flood_weights（作用于组件选择）、PaintModeSettings、NamedPaintTarget.MASK、export_json、import_json。
• Skin > Smooth Skin Weights 使用 Skin Tools 算法，并会在多图层集群上报错；Rigid Bind 菜单已移除（使用单个影响对象进行绑定）；performSkinCluster.mel 已移除。
• 每个网格有多个 skinClusters 时需要使用 skinCluster(multi=True)；工具列表会将最新的集群显示在最前面。
• mlDeformer 命令（2026）、用于拉伸分析的 dgaTension（2026.3）、Apply Mesh Compare（2026）；Bifrost 3.0 随 2027 一同发布；旧版实验性 Rigging 模块不兼容。

参考资料

• references/procedures.md：每个阶段（P1 至 P16）的代码、状态和测试；执行时查阅。
• references/expert-notes.md：按专家整理的原则及意见分歧；需要了解决策依据时查阅。
• references/critique.md：报告阅读、区域检查、0 至 3 评分标准；在确认阶段完成前查阅。
• references/gui-paths.md：Skin Tools、Shape Editor、Pose Editor、ML Deformer 菜单；在 GUI 中查阅。
• references/sources.md：来源、凭据、URL、时间戳；用于追溯说法。