CozyClay motion3编译器原理：浏览器内的FK/IK数学，150毫秒烤出730帧

CozyClay 是一款开源的浏览器预演（previs）软件，它的 motion3 模块是一个完全运行在浏览器里的确定性动画编译器：你（或 AI Agent）写一份纯 JSON 的 motion spec 动作描述，它就在真实骨架上把每一帧的骨骼姿态"烤"出来，再自动做碰撞、滑步、可达性 QA 检查。官方验收测试里，一段730 帧、24 fps 的下车抽烟场景，编译只需约 150 毫秒，QA 约 80 毫秒——快到可以随意反复迭代。这篇文章用通俗的方式讲清楚这套浏览器内 FK/IK 数学是怎么工作的。

1. 从动作规格到730帧：motion3的完整流水线

motion3 的入口是 src/motion3/pipeline.js，一次编译（motion.compile）按固定顺序走：

1. 规格修正：自动补齐帧数（frames: "auto"）、修正明显笔误（src/motion3/correct.js）
2. 技能展开：spec.use里的walkTo、sitInSeat、smokeCigarette等技能被展开成具体关键帧（src/motion3/skills/index.js）
3. 参数搜索：写成{ range: [lo, hi] }的开放参数被确定性搜索求解（src/motion3/search.js）
4. 严格校验：未知通道、错误帧号、非法骨骼名全部逐条报错
5. 烘焙帧 + 自动修复（编译器核心，见下两节）
6. QA 测量：每帧逐条检查，输出"原因 + 修改建议"

整个流程是确定性且无副作用的——同样的 spec 和场景永远烤出同样的帧，这正是 AI Agent 敢反复试错的前提。

2. 自带数学工具箱：向量、矩阵、四元数

编译器不依赖任何第三方数学库。src/motion3/compiler/math.js 只用纯 JS 实现了它需要的一切：

• 向量：加减、点积、叉积、归一化（向量就是[x, y, z]数组）
• 3×3 矩阵：行列主序，作用在列向量上；绕任意轴的旋转用Rodrigues 公式直接生成
• 四元数 ↔ 矩阵互转：骨骼姿态最终以局部四元数输出，但求解过程全程用世界坐标矩阵，算完再转回去

这套约定的好处是：所有中间计算都在"世界空间"进行，最后 src/motion3/compiler/skeleton.js 里的toLocal()一步把世界姿态精确映射回每根骨骼的局部四元数，直接驱动渲染用的 rig（X Bot / Y Bot，绑定数据来自 src/motion3/rigs/）。

3. FK与双骨IK：一条手臂如何"弯得对"

这是 motion3 的核心数学。姿态求解在 src/motion3/compiler/pose.js，单条肢体求解在 src/motion3/compiler/limbs.js：

FK（正向运动学）：每个关键帧的通道值（root髋部位置、yaw转身、spine_pitch弯腰、aswing摆臂……）沿骨骼链逐级旋转子树，得到整具身体姿态。

双骨 IK（逆向运动学）：当你给出手腕或脚踝的世界坐标目标，twoBone()用经典的两段杆几何（余弦定理解出中间关节位置）反解肘/膝。但 naive 的 IK 会让手臂"穿模式"地拉直，motion3 加了两层人体约束：

• 弯曲折点：肘部自由弯折到 145°（接近临床主动屈曲极限），之后渐近地贴在 150° 的"停点"上，手腕速度连续地慢下来——手臂永远不会"啪"地拉直
• FK/IK 混合：armw_l通道从 0 到 1 淡入 IK，FK 姿态和目标姿态按权重混合，所以"抬手去开门把手"是一个平滑过渡

软可达修复（soft reach）：手腕目标超出臂展 5 厘米以内时，沿指数缓动曲线拉回可达球面上，超出部分留作 QA 报告——而不是直接报错或硬拉。

腿部同理：膝盖自由弯折到 150°，贴向 160° 的被动极限（深蹲时大腿压到小腿），脚踝目标比髋还近时如实记录"够不到"。

4. 关键帧烘焙：PCHIP插值与"流动感"

关键帧之间不是线性插值。src/motion3/compiler/channels.js 用了动画行业验证过的两条曲线策略：

• 身体定位类通道（脚、髋部、手目标、权重）用单调三次 PCHIP插值：值绝不越过关键帧（接触永远精确落在关键帧上），但过渡依然平滑
• 身体摆动类通道（脊柱、头、摆臂）用Catmull-Rom并带几帧"拖尾"：头滞后身体 2 帧、手臂再滞后 3 帧，加上重叠（overlap）机制让脊柱、胸、头逐级接力转动——这就是角色动作"有活气"而不是机械的根源

步行生成器（src/motion3/compiler/walk.js）更是把步态生物力学做进了关键帧：脚跟先着地、脚绕脚跟滚平、绕前脚掌推离地面——完整实现了人步行的"三个摇杆"（three rockers）；每一步的周期、步幅、抬腿高都是平均值加随机变化量，保证没有两步完全一样。

5. 自动修复与QA：编译器还负责批改作业

烤完帧不是终点。编译器先过一遍自动修复（src/motion3/fix/）：

然后 src/motion3/qa/ 的 30 多个检查模块逐帧测量：身体胶囊 vs 场景碰撞、IK 可达、落地脚滑动、骨骼长度、速度突变（pop）、膝盖/肘反折、手进头部或躯干、双手互穿、铰链物体穿墙、平衡、自接触……

关键设计：每个 QA 问题组都带cause（谁造成的）和hint（怎么改），比如"root 在 f315 需要移动 [+0.049, 0, +0.122] m（撞出了车门），请改那段步行的 heading/step 或给一个{ range }"。AI Agent 拿着这个提示改 spec、重新编译，通常一次script调用内就收敛到qa.ok。

6. 开放参数搜索：编译器替你"找答案"

不确定转弯半径该给 0.4 还是 1.5？把它写成{ range: [0.2, 2.0] }就行。src/motion3/search.js 的搜索策略很有讲究：先试中点，再单参数网格 / 多参数Halton 序列采样，然后围绕最优解做收缩的图案搜索；最多编译 32 次（上限 64），遇到 QA 为 0 立即停止。而且每次试验只重编译参数能影响的帧窗口——官方例子里，一个手工试 93 帧都撞门的转弯半径，搜索 5 次编译（0.8 秒）就找到 1.55。

7. 为什么150毫秒如此重要

因为 motion3 的消费者是AI Agent 的紧密循环：写 spec → 编译 → 读 QA → 改 → 再编译。150ms 编译 + 80ms QA 意味着每轮迭代不到 1/5 秒，Agent 能在一次对话回合内完成"下车、走路、抽烟"整段 30 秒动画的打磨。

这个性能被测试锁死：验收测试 test/motion3/verify-motion3-exitcar.mjs 用主线程 CPU 时间（而非挂钟）计时，要求 730 帧编译 + QA 总计不超过 3 秒预算，并逐帧验证"手指扣在门把手上""烟嘴贴着嘴唇"等接触在每一帧都成立。CI 上预算放宽 5 倍，但性能退化一个数量级照样会被抓出来。

8. 上手体验motion3动画编译

npx cozyclay

浏览器打开http://127.0.0.1:5180/app/，按Cmd/Ctrl+B调出 Agent 面板，对它说"让人物走到车旁下车"即可——Agent 会调用motion.compile走上面整条流水线，你看着角色在灰色方块场景里一步步把动作改对。完整的 spec 字段、通道表和 QA 语义见官方文档 docs/motion3-agent-guide.md。

核心文件速查