scenario-blender-rigging

Blender 绑定

专业绑定意味着用骨骼摆放来定义绑定，通过受力姿势下的变形来验证，并围绕动画师实际会用到的内容来塑形。所有源专家的共同立场是：精确摆放关节，生成或构建可用的最简单机制，然后摆姿势、测量、渲染并修复，之后再称其完成。如果这里提到的某个同级技能不在你的可用技能中，请用户安装它（npx skills add scenario-labs/skills --skill <name>）；如果是无人值守运行，则根据工具模式继续操作，并标明这一缺失。

必备背景： scenario-blender-expert（执行渠道、审查循环、5.2 API 变更）。

模块：scripts/bx_rig.py（已在 5.2.1 上测试，支持无头和 GUI）。 import sys; sys.path.append("<skills>/scenario-blender-rigging/scripts"); import bx_rig as R

立场（专家实践的差异点）

• 摆放位置就是规范。 关节应位于其驱动体积的中心，而非解剖学骨骼的位置（“骨骼模拟骨、肌肉和组织”）；膝盖和肘部要略微预弯，因为链条的弯曲方向就是 IK 平面；滚转要让每个铰链都落在同一局部轴上，这样动画师只需使用一条曲线（CGDive；Demeter：决定控制柄位置的是弯曲方向，而非滚转）。
• 元骨架是源文件，生成的绑定可随时丢弃。 所有修复都应写入元骨架骨骼、Rigify 参数或生成后脚本；重新生成会保留控制器名称，因此权重和动画也会保留（CGDive、Demeter、Ivan Cappiello）。
• 自动权重会静默失败。 parent_set 返回 FINISHED 时，可能同时出现骨骼热权重失败的警告；要测量未加权顶点和空的变形组，并回退到体素代理加 Data Transfer（CGDive；已验证）。权重也会泄漏到裆部和腋下：从右半边移除 .L 权重。
• 权重应在运动中评估，宁硬勿软。 在姿势模式下或对照测试动画绘制；每条接缝限制在 2 或 3 根骨骼以内（避免“骨骼争抢影响力”）；轻微穿插优于橡皮般的过渡；刚性部分应以 1.0 权重分配，绝不绘制（CGDive、Demeter、Dikko）。
• 一起变形的所有对象都应从同一个源获取权重， 再传递并应用权重，这样服装在动画过程中才不会偏移（Dikko、CGDive）。
• 导出方式决定采用哪些变形工具。 每个节段使用四根扭转骨骼，而不是 Preserve Volume；Preserve Volume、Corrective Smooth 和 B-bones 仅限 Blender 使用，因此 Rigify 会将 DEF 骨骼分段（CGDive、Ivan）。
• 动画师是客户端。 删掉没人会用的功能，只限制会破坏绑定的内容；确保自动化骨骼仍可手动制作动画（用约束加子级、Mix Add、Transformation 代替驱动器）；达到用途要求后就停下（Wayne Dixon、Demeter、CGDive）。
• 面部绑定应按角色混合搭配。 不存在通用的风格化面部绑定（Demeter）；制作级面部绑定会混合使用关节、带状结构、形状键和晶格（Rik Schutte）。

首先确认

输入	变更	未说明时的默认值
目标：Blender 渲染，还是游戏/FBX	分段 DEF 骨骼，最多 4 个影响，不使用 Preserve Volume / Corrective Smooth / B-bone 变形	仅用于 Blender 的关键帧动画
角色：双足、四足、机械、道具	metarig 预设或自定义样例；刚性岛	双足，Rigify
面部需求和风格	无 / Rigify 面部 / 骨骼 + 形状键 + 面部控制器	身体绑定 + 仅眼部和下颌骨
手指	Rigify Human（手指 + 面部）还是 Basic Human	Basic Human（CGDive：首个绑定）
姿势、部件、比例	T 姿或 A 姿、分离的眼睛/牙齿/衣物、真实比例	测量；在模型检查中修正
动画师约定	FK/IK 默认值、侧边颜色、手指控制	腿部 IK、手臂 FK、跟随值为 0；左侧蓝色，右侧红色（询问）

选择路径

Rigify	手动 / 脚本绑定
解剖结构标准的人类和动物、多个角色共用控制器、快速实现可用于生产的成果	解剖结构特殊、机械部件、严格的游戏引擎层级、必须保持精简的绑定，或需求明确要求自定义控制方案
add_metarig 然后 fit_metarig、generate	new_bone、twist_chain、fk_ik_switch、ik_chain、foot_roll、make_def_layer、organize
Metarig 类型：手臂正好 3 根骨骼，腿部 4 根 + 脚跟，脊柱 3 根以上，super_copy 1 根骨骼	DEF / MCH / CTRL：只有 DEF 会变形，MCH 从不制作动画，其余全部为控制器

工作流

1. 模型检查。 R.model_check([body, *parts], fix=True)：应用变换（包括形状键），双脚位于 Z=0，模型在 X 轴上居中，面朝 -Y；成人身高约为 1.8 m。应用 Mirror 修改器，或保留其镜像对象。GATE：model_check(...)["problems"] == []。
2. 标志点。 lm = R.landmarks(body, eyes=eyes)：通过横截面找到胯部、臀部、脚踝、颈部、腋窝和手腕；从眼部网格获取眼球中心；根据面部轮廓获取鼻尖和下巴。使用 overrides={...} 覆盖任意关节。GATE：关节顺序合理，且 lm["notes"] 为空或已说明原因。
3. 拟合。 Rigify：meta = R.add_metarig("basic"|"human")，R.fit_metarig(meta, lm)（关节作为共享点，预弯曲、铰链滚转、左侧对称；手部和面部按相似度粗略拟合）。手动方式：使用相同的标志点，通过 new_bone 构建变形骨架。GATE：R.check_metarig(meta, body) == []，并查看 R.placement_sheet([body, eyes], out, arm_obj=meta, views=("front","right","top"))；使用 center=、size= 放大头部。
4. 面部（Rigify Human）。 拟合后运行 R.upgrade_face(meta)（不可逆；眼睑跟随 Z 为 0.3，下唇为 0.9，启用 Overwrite Widget Meshes）。风格化英雄面部：改用下颌、眼睛、舌头骨骼和形状键（阶段 7）。
5. 生成或构建。 rig, err = R.generate(meta)；err 是 Rigify 第一行错误信息，其中会指出骨骼名称（"Cannot connect chain - bone position is disjoint"、"Expected 2 eye corners"）：修复元骨架并重新生成。手动方式：扭转骨骼链，使用设置属性创建 FK/IK 层，添加已求解极角的 IK、脚部滚转、对称化、mirror_drivers、make_def_layer、organize 和控件形状。GATE（手动）：static_cycles == []、cycle_check() == []、root_test < 1e-4、静止姿势下 FK 和 IK 重合、极点误差 < 1e-3。
6. 绑定。 rep = R.bind(rig, body, garments=[shirt, pants], rigid={eyes: None, teeth: "DEF-teeth.T"})： 自动权重、验证、代理回退、跨侧条带、服装权重转移（已应用）、刚性岛、清理和归一化；Armature 位于 Mirror 之后、Subdivision 之前。GATE：rep["ok"]、unweighted == 0、没有非变形顶点组；导出时设置 max_influences=4。
7. 运动范围。 dr = R.deformation_report(rig, [body, *garments], R.RIGIFY_POSES)，运行 R.flag_report(dr)，然后生成 R.pose_sheet(...) 和 R.joint_sheet(...) 特写并查看。GATE：没有穿模，没有无法解释的塌陷；腋窝、肘部、手腕扭转、胯部、膝盖和锁骨处的渲染效果均可接受。
8. 按以下顺序修复。 放置或滚转问题：返回元骨架进行修复并重新生成。权重问题：定向编辑数据（使用顶点蒙版运行 strip_opposite_side、assign_rigid、smooth_weights、clean_weights）。深度弯曲处的体积问题：使用修正形状键（volume_restore_targets、corrective_from_targets、corrective_driver）。仅限 Blender 的糖果包装纸：preserve_volume_mask。每次修复后重新运行阶段 7；重新检查较早的姿势（CGDive）。
9. 可用性与交付。 In Front 关闭时控件仍清晰可见，包含控件形状和侧边颜色，MCH/DEF 隐藏，至少有一行 Rigify UI；rig_ui.py 需要在 GUI 中启用 Auto Run；切换值必须恰好为 0 或 1；静止姿势干净，移除测试动作。报告数值、渲染结果以及未验证的内容。

数值

数值	相对于	来源
膝盖／肘部预弯 1 至 3 度（拟合值：肢体长度的 1.2%，2.7 度）；检查范围 1 至 15	弯曲视图中的链	CGDive；检查 [added]
4 根扭转骨骼，Copy Rotation 1.0 / 0.66 / 0.33 / 0.1（大腿 0.05）	从驱动端开始	CGDive
IK 链长度 2；IK Stretch 0.1；在小腿和前臂上锁定 IK Y/Z	IK 骨骼	Wayne、CGDive
脚部滚动：脚跟 X [-90, 0]，脚趾 X [0, 90]，内侧／外侧 Z 单向	枢轴局部空间，滚动 0，朝上	CGDive（已验证）
权重绘制笔刷 Add，强度 0.1 至 0.2，Auto Normalize；接缝处 Mix 0.5，强度 1	Weight Paint	CGDive
模糊前清理接近零的权重（Demeter）；限制值 0.001（CGDive），bind 中为 0.01 [added]；游戏用 4 个影响骨骼	每个顶点	Demeter、CGDive
眼睑跟随 0.15（面部骨骼）；Rigify 眼睑跟随 Z 0.3（默认 0.7）；下颌带动下唇 0.9；嘴角跟随下颌 0.5	面部	CGDive
手掌 0.5 / 0.25；肘部护板为前臂旋转的 0.2	Copy Rotation Local，Mix Add	CGDive
手指卷曲：Transformation 将 Scale Z 0..1 映射到 Rot Z 90..0 度，Extrapolate	手指控制器	CGDive
Action 约束：第 1 和第 10 帧设关键帧，LINEAR，最大值 = 测得的控制器行程	控制器局部 Y	CGDive、Demeter
肩部测试范围约为锁骨抬升 20 至 30 度	解剖结构	CGDive
面部：约 16 个 Stop Staring 形状；用于动作捕捉的 52 个 ARKit	形状键	CGDive
代理模型体素尺寸 H/180，然后 H/90、H/45	角色高度	[added, verified]
塌陷 < 0.85，鼓起 > 1.25（关节带），穿漏 > 0.001 H，形变 0.5 至 1.6	静止姿势	[added]

质量门槛

代码（全部位于 bx_rig）：check_metarig、weight_report（unweighted、empty_major、 non_deform_groups、over4、sum_dev、mirror_err）、deformation_report + flag_report（strain、关节 体积区间、跨侧穿漏、通过 bx_audit 检测新的自相交）、static_cycles、cycle_check、 root_test、twist_angles、solve_pole_angle、rigid_check。

视觉检查：生成前制作摆放表（正面、右侧、顶部；头部放大）；为 RIGIFY_POSES 制作姿势表（正面、右侧、四分之三视角）；在每个标记姿势下拍摄关节特写（手臂关节拍正面／顶部／四分之三视角， 其他关节拍正面／右侧／四分之三视角）。检查腋下塌陷、肘部和膝盖尖突或挤压、手腕糖果纸效应、腹股沟和臀部体积、衣领穿插、衣物滑动或相交、牙齿和眼睛跟随滞后、控件隐藏在网格内部。测试时，即使数值检查通过，渲染结果仍可能显示手臂损坏或出现尖锐褶皱：务必打开渲染图。评分标准： references/critique.md。

面部形状：引擎与捕捉

面部捕捉应用、引擎和口型同步工具会按精确名称查找形状键。名称大小写错误（JawOpen）或仍与 Basis 相同的键都不会产生任何动画。这两种情况在导出 FBX 和 glTF 后仍会保留［已验证］，因此文件看起来是完整的。

• R.SHAPE_SETS："arkit"（Apple 的 52 个名称）和 "visemes"（Meta Lipsync 的 15 个名称，从 sil 到 U）。列表、来源和 Roblox 的 50 个 FACS 姿势见： references/face-shapes.md。
• R.shape_set(face, "arkit", rename={"JawOpen": "jawOpen"}) 会重命名，然后将每个缺失的键以值 0 添加为 Basis 的副本，并返回它创建的名称。已有键会保留其值：导出前将每个键设为 0，否则面部会在静止状态下变形。
• 雕刻 Left 键，然后对每个以 Left 结尾的 n，使用 R.mirror_shape_key(face, n, n[:-4] + "Right") 创建对应的 Right 键。
• 导出前，运行 R.shape_report(face, "arkit")。GATE：missing、wrong_case 和 side_conflicts 均为空，且 left_is == "+X"。
• empty 是仍需雕刻的键列表：交付占位内容时报告该列表，制作最终头部时将其清空。sil 口型是中性面部，因此始终保留在 empty 中。
• 侧别：Apple 的页面只写“左眼”，没有说明是谁的左眼，而且其面部坐标空间将 +X 定义为面部自身的左侧。在角色自身左侧（+X，即 .L 侧）制作 Left 键，并在雕刻整套键之前检查一次捕捉结果。
• Roblox 动态头部使用关节姿势，而非形状键；从第 1 帧开始每帧一个姿势，第 0 帧为中性面部。

常见错误

错误	表现	修复
未应用 Metarig 的缩放或姿势	生成的骨架大小或姿势不符	应用缩放；将姿势应用为静止姿势
移动颈部时未移动脊柱末端	“骨骼位置不连续”	将关节作为整体移动（move_points）
膝盖或肘部伸直	IK 向侧面或后方弯曲	在弯曲视图中预先弯曲
将网格设为 Metarig 的子级	网格不跟随任何有用对象	绑定到生成的骨架
未发现热量计算失败	网格不动	weight_report；使用代理方案
Armature 位于 Subdivision 下方，或在 Mirror 之前	速度慢；镜像的一侧会复制已摆姿势的一侧	armature_first
右腿上有左大腿的权重	对侧发生移动	strip_opposite_side
眼睛和牙齿被自动赋权	漂移、穿出	assign_rigid
衣物上有实时 Data Transfer	动画过程中权重发生变化	应用它
可制作动画的骨骼上有驱动器	通道无法添加关键帧	使用 Transformation 或 Copy Rotation Mix Add
为隔离而关闭 Inherit Rotation	根骨骼旋转会破坏肢体	使用跟随骨骼（World Copy Loc/Rot/Scale）
IK 目标设为其自身链内的父级	抖动、翻转	清除父级；使用 static_cycles
重新设置已连接骨骼的父级	骨骼头部跳到新父级的尾部	reparent 会先清除 use_connect
以为 Symmetrize 会复制驱动器；名称为 .L.001	右侧失效	mirror_drivers；side_of
IK/FK 保持在 0.86	变形混杂、难以辨认	必须设为 0 或 1
ARKit 键拼写错误，或仍处于 Basis	捕捉应用或引擎中没有任何动作	使用 shape_set，然后运行 shape_report

Blender 5.2 说明

• Rigify 在出厂启动时处于禁用状态（enable_rigify）；Human metarig 仍使用旧版面部（请升级）；Overwrite Widget Meshes 仍默认关闭。
• 骨骼集合和逐骨骼颜色取代了图层和骨骼组；edit_bones.new() 不会加入任何集合；姿势选择使用 pose.bones[n].select。
• parent_set 会将 Armature 修改器追加到最后；权重操作符（vertex_group_smooth、_clean）在无头模式下需要 Weight Paint 模式；bx_rig 则直接对数据进行清理、规范化和限制。
• 在 5.2.1 中，shape_key_add 会将新键的值设为 1.0：驱动前请设为 0 [已验证]。VertexGroup.remove 使用超出范围的索引会导致 5.2.1 崩溃 [已验证]。
• 设置父级的 tail 会移动已连接子级的 head；对已连接的组使用 EditBone.transform 会使共享端点移动两次 [已验证]：请使用 transform_bones。
• Python 驱动器的初始键为 (0,0)、(1,1)；请重新映射（remap_driver）。Action 约束会自动选择动作槽。默认只启用 Insert Available；不影响从 Python 调用 keyframe_insert。
• 自定义形状：Affect Gizmo（use_transform_at_custom_shape）、Use As Pivot（use_transform_around_custom_shape）。5.2 新增了 Duplicate 和 Rename，以及 Add Bone align Axes。

参考资料

• references/procedures.md：每个阶段的完整测试代码及其背后的测试脚本；编写绑定代码前先加载。
• references/expert-notes.md：专家的判断（放置、Rigify 内部机制、权重、机制、面部），附有时间戳；遇到上述内容未涵盖的决策时加载。
• references/critique.md：审查标准；每个关卡都要加载。
• references/face-shapes.md：ARKit、viseme 和 Roblox FACS 名称及其来源；为引擎或捕捉应用命名面部形状时加载。
• references/sources.md：视频、专家及最佳时间戳。