reverse-engineer-animation

反向工程动画

• 是： 测量录制中已有的运动（提取帧、逐帧跟踪、拟合曲线、标注编排），然后生成能够复现它的代码和交接规格。
• 不是： 从零设计新运动，或审查／调试运动代码。这两类需求都转交给 ui-animation。

目录

• 参考文件
• 依赖项
• 工作流（提取、视觉检查、跟踪、拟合、标注、生成、验证）
• 注意事项
• 验证
• 相关技能

参考文件

文件	阅读时机
references/measurement-guide.md	决定测量哪些内容、选择人工目测还是脚本、读取 metrics.json、选择 ROI
references/curve-fitting.md	阅读 fit_curves.py 的输出、选择弹簧还是贝塞尔曲线、判断拟合误差、处理非对称的打开／关闭运动
references/code-output.md	为 CSS、Motion/Framer Motion、SwiftUI、React Native 或 UIKit 生成代码
references/choreography.md	处理多元素／多阶段运动：错开、先模糊后移动、各边分别稳定

依赖项

• ffmpeg：提取帧（brew install ffmpeg）。步骤 1 必需。
• Python：安装 opencv-python numpy scipy（pip install opencv-python numpy scipy），用于跟踪和曲线拟合（步骤 4）。

即使依赖不齐全，提取过程也能正常运行：只有 ffmpeg 时，仍可提取帧并进行视觉分析。跟踪和拟合需要 Python 包。

工作流

复制此清单并跟踪进度：

Reverse-engineer progress:
- [ ] Step 1: Extract frames + contact sheet (per direction if open differs from close)
- [ ] Step 2: Vision pass: identify element, effects, phases
- [ ] Step 3: Decide precision (eye-only vs scripted)
- [ ] Step 4: Track motion and fit curves (if escalating)
- [ ] Step 5: Annotate choreography (delays, asymmetry)
- [ ] Step 6: Emit code for the target(s)
- [ ] Step 7: Validate against the recording

步骤 1：提取帧

运行 python3 scripts/extract_frames.py <video> <outdir>。如果录制时长达到数秒，请使用 --start SECONDS --duration SECONDS 将范围裁剪到过渡片段；提取整个片段会让联系表过于拥挤，也会降低跟踪效果。如果交互既有打开也有关闭过程，请裁剪出 两个时间窗口，并针对每个方向各运行一次完整流程。它们几乎从来不是镜像关系，因此一次测量无法同时适用于两者。

将 --fps 与源视频匹配：使用 ffprobe -v 0 -select_streams v -show_entries stream=avg_frame_rate <video> 探测帧率，采样率绝不能高于源视频的帧率（参见“注意事项”）。首先打开生成的 contact_sheet.png；它会一次展示完整时间线。

步骤 2：视觉检查

查看联系表，并按顺序列出：

• 移动的元素。
• 出现的每种效果：平移、缩放（通常各向异性）、不透明度、模糊、圆角、阴影、颜色。使用 references/measurement-guide.md 中的属性清单。
• 各个阶段（例如，背景模糊逐渐增强，元素缩入缺口下方，过度拉伸，然后各边分别稳定）。记录哪些属性先动，哪些后动。

步骤 3：决定精度

• 简单淡入淡出或线性滑动：从联系表读取时间，然后跳至步骤 5。
• 弹性、弹簧式或多属性运动：转至步骤 4。仅凭目测估算弹簧运动并不可靠。

步骤 4：跟踪并拟合

运行 python3 scripts/track_motion.py <outdir> 生成 metrics.json。如果有多个元素在动，可传入 --bbox X,Y,W,H 将检测范围限制在单个元素上（每个元素运行一次）。然后运行 python3 scripts/fit_curves.py <outdir>/metrics.json，获取弹簧参数、三次贝塞尔曲线，以及每个属性的拟合误差。如果提取时使用了非默认的 --fps，请向 fit_curves.py 传入相同的 --fps：其默认值为 30，帧率不匹配会重新缩放每个持续时间和刚度（参见“注意事项”）。阅读 references/curve-fitting.md，解读数值并选择模型。如果两种模型的误差都很高，说明运动分为多个阶段：拆分时间线，并对每个片段分别拟合。

步骤 5：标注编排

读取 references/choreography.md。创建时间偏移表（记录每个属性开始运动和稳定的时间）。这些先后延迟和过度拉伸比任何单条曲线都更能体现运动的感觉。

步骤 6：输出代码

将拟合出的参数代入 references/code-output.md 中适用于所需目标的模板。保持运动效果作用于 transform/opacity。如果打开和关闭的效果不同，则输出两段过渡。根据 references/code-output.md 生成完整的交接动效规范（时序表 + 曲线 + 代码片段），确保无需视频也能实现。

步骤 7：验证

运行以下验证检查。退出标准是对比证据，而不是“看起来没问题”。

注意事项

• fit_curves.py 默认使用 --fps 30。以 --fps 60 提取，再用默认值进行拟合，则每个 duration_ms 都会加倍（500 ms 的过渡会报告为 1000 ms），拟合出的刚度则会降至四分之一。拟合时始终传入提取时使用的 fps。
• 采样帧率高于源视频帧率会造成帧重复：以 --fps 60 提取 24 fps GIF 时，metrics.json 中会出现连续相同的数值，使进度曲线呈平台状，并增大两种拟合的误差。先确认源帧率，并与其匹配。
• 屏幕录制在负载较高时会丢帧，iOS/QuickTime 录制则采用可变帧率。metrics.json 中连续相同的行表示重复帧，而不是动画暂停。如果平台段占主导，应以更稳定的帧率重新录制，而不是一味调整拟合。
• 对多阶段运动拟合一条全局曲线会导致两种模型的误差都很高。应拆分阶段并组合关键帧（references/curve-fitting.md）。
• 只跟踪位置会漏掉模糊/不透明度变化，而这些变化通常会提前约 100 ms 开始。动效的精致感就在这段提前量中。
• 打开和关闭的运动从来不是镜像关系（打开较慢且弹性更强，关闭较快且更平缓）。应将每个方向分别作为独立片段进行测量；切勿反向复用打开曲线。
• 报告弹簧参数前不检查拟合 error：糟糕的拟合会给出看似可信但实际错误的数值；error > 0.08 时应视为可疑。
• 输出动画效果作用于布局属性（width、height、top、left）的代码：应使用 transform/opacity/filter 重现运动效果（遵循 ui-animation 规则）。
• 通过重读脚本来还原逻辑，而不是运行脚本：脚本是权威且确定的执行路径。

验证

• 重新推导：播放输出的动画，录制屏幕，再通过 extract_frames.py 处理，并将联系表与原始版本并排比较。
• 在 DevTools 中将速度降至 0.1x，确认阶段顺序（先行/滞后）和过度拉伸效果仍然存在。
• 确认输出代码只为 transform、opacity 和 filter 添加动画。
• 检查拟合出的弹簧 overshoot/zeta 是否符合观察结果；明显的弹跳不能拟合成平缓的缓动。

相关技能

• ui-animation：将提取出的规范转化为适用于生产环境且可中断的动效，并应用其缓动默认值和反模式规则。