reverse-engineer-animation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reverse Engineer Animation

逆向工程动画

Measure motion that already exists in a recording, then reproduce it. This is the forensic counterpart to the

ui-animation

skill (which prescribes how motion should be designed).

测量录制视频中已有的运动效果，然后进行重现。这是

ui-animation

技能的逆向分析对应技能（

ui-animation

技能规定了运动效果应该如何设计）。

Reference files

参考文件

File	Read when
references/measurement-guide.md	Deciding what to measure, eye vs script, reading `metrics.json` , choosing an ROI
references/curve-fitting.md	Reading `fit_curves.py` output, spring vs bezier, judging fit error, asymmetric open/close
references/code-output.md	Emitting code for CSS, Motion/Framer Motion, SwiftUI, React Native, or UIKit
references/choreography.md	Multi-element / multi-phase motion: staggers, blur-before-move, per-edge settling

文件	阅读时机
references/measurement-guide.md	决定测量内容、人工目测 vs 脚本分析、读取 `metrics.json` 、选择感兴趣区域(ROI)
references/curve-fitting.md	读取 `fit_curves.py` 输出结果、弹簧曲线 vs 贝塞尔曲线、判断拟合误差、非对称展开/收起动画
references/code-output.md	生成CSS、Motion/Framer Motion、SwiftUI、React Native或UIKit代码
references/choreography.md	多元素/多阶段运动：交错动画、移动前模糊、逐边缘稳定

Dependencies

依赖项

```
ffmpeg
```
— frame extraction (
```
brew install ffmpeg
```
). Required for step 1.
Python:
```
pip install opencv-python numpy scipy
```
— tracking + curve fitting (steps 4).

Extraction degrades gracefully: with only ffmpeg you can still extract frames and reason visually. Tracking and fitting need the Python packages.

```
ffmpeg
```
— 帧提取（执行
```
brew install ffmpeg
```
安装）。步骤1必需。
Python:
```
pip install opencv-python numpy scipy
```
— 运动跟踪 + 曲线拟合（步骤4）。

提取功能具备降级兼容性：仅安装ffmpeg时，仍可提取帧并进行视觉分析。跟踪与拟合功能需要上述Python包。

Workflow

工作流程

Copy and track this checklist:

text

Reverse-engineer progress:
- [ ] Step 1: Extract frames + contact sheet
- [ ] 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

复制并跟踪以下检查清单：

text

Reverse-engineer progress:
- [ ] Step 1: Extract frames + contact sheet
- [ ] 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

Step 1: Extract frames

步骤1：提取帧

Run

python3 scripts/extract_frames.py <video> <outdir>

(add

--fps N

for very slow clips). On a multi-second recording, trim to just the transition with

--start SECONDS --duration SECONDS

— extracting the whole clip floods the contact sheet and dilutes tracking. Open the generated

contact_sheet.png

first — it shows the whole window at once.

执行

python3 scripts/extract_frames.py <video> <outdir>

（针对极慢片段可添加

--fps N

参数）。对于时长较长的录制视频，使用

--start SECONDS --duration SECONDS

参数仅裁剪过渡部分——提取整个视频会导致联系表内容过多，降低跟踪效率。先打开生成的

contact_sheet.png

文件，它会一次性展示整个窗口的帧内容。

Step 2: Vision pass

步骤2：视觉分析

View the contact sheet and name, in order:

The element(s) that move.
Every effect present — translate, scale (often anisotropic), opacity, blur, corner radius, shadow, color. Use the property checklist in
```
references/measurement-guide.md
```
.
The phases — e.g. backdrop blurs in, element tucks under the notch, over-stretches, then settles per-edge. Note which property leads and which lags.

查看联系表，并按顺序确认：

运动的元素。
所有存在的效果——平移、缩放（通常为各向异性）、透明度、模糊、圆角、阴影、颜色。可参考
```
references/measurement-guide.md
```
中的属性检查清单。
动画阶段——例如背景模糊出现、元素隐藏至缺口下方、过度拉伸、然后逐边缘稳定。记录哪些属性先启动，哪些滞后。

Step 3: Decide precision

步骤3：确定精度等级

Simple fade or linear slide → read timing off the contact sheet and skip to step 5.
Elastic, springy, or multi-property motion → escalate to step 4. Eyeballing a spring is unreliable.

简单淡入淡出或线性滑动 → 从联系表读取时间，直接跳至步骤5。
弹性、弹簧效果或多属性运动 → 升级至步骤4。目测弹簧效果的误差较大。

Step 4: Track and fit

步骤4：跟踪与拟合

Run

python3 scripts/track_motion.py <outdir>

→

metrics.json

. Pass

--bbox X,Y,W,H

to isolate one element when several move (one bbox per element). Then run

python3 scripts/fit_curves.py <outdir>/metrics.json

→ spring params, cubic-bezier, and a fit error per property. Read

references/curve-fitting.md

to interpret the numbers and pick the model. High error on both models means multi-phase motion — split the timeline and fit each segment.

执行

python3 scripts/track_motion.py <outdir>

→ 生成

metrics.json

。当多个元素运动时，传递

--bbox X,Y,W,H

参数以隔离单个元素（每个元素对应一个bbox）。然后执行

python3 scripts/fit_curves.py <outdir>/metrics.json

→ 生成弹簧参数、三次贝塞尔曲线，以及每个属性的拟合误差。阅读

references/curve-fitting.md

以解读数值并选择模型。两种模型均出现高误差意味着存在多阶段运动——拆分时间轴并分别拟合每个片段。

Step 5: Annotate choreography

步骤5：标注动画编排逻辑

Load

references/choreography.md

. Build the timing-offset table (when each property starts and settles) — those lead/lag gaps and the over-stretch carry more of the feel than any single curve.

打开

references/choreography.md

。构建时间偏移表（每个属性的启动与稳定时间）——这些领先/滞后间隔以及过度拉伸效果对动画质感的影响，比单一曲线更大。

Step 6: Emit code

步骤6：生成代码

Substitute the fitted parameters into the templates in

references/code-output.md

for the requested target. Keep movement on

transform

opacity

. Emit two transitions when open and close differ. Produce the consolidated handoff motion spec (timing table + curves + snippet) from

references/code-output.md

so the result can be implemented without the video.

将拟合参数代入

references/code-output.md

中对应目标平台的模板。仅在

transform

opacity

属性上实现运动效果。当展开与收起动画不同时，生成两组过渡代码。根据

references/code-output.md

生成整合的移交运动规范（时间表 + 曲线 + 代码片段），以便无需原视频即可实现该动画。

Step 7: Validate

步骤7：验证

See Validation below.

参见下方验证部分。

Asymmetric open/close

非对称展开/收起动画

Open and close are almost never mirror images — open tends to be slower and springier, close faster and flatter. Measure each direction separately (record or trim two clips and run the pipeline on each). Report two curves; never reuse the open curve reversed.

展开与收起动画几乎不会是镜像效果——展开通常更慢、弹簧感更强，收起则更快、更平缓。分别测量两个方向（录制或裁剪两个片段，并对每个片段运行流程）。输出两组曲线；切勿直接复用反向的展开曲线。

Anti-patterns

反模式

Fitting one global curve to multi-phase motion — split into phases and compose keyframes.
Tracking only position and ignoring blur/opacity — those usually lead the move and are where the polish lives.
Assuming symmetric open/close — measure both directions.
Reporting spring params without checking the fit error — a bad fit gives confident-looking but wrong numbers.
Emitting code that animates layout props (
```
width
```
,
```
height
```
,
```
top
```
,
```
left
```
) — reproduce the motion on
```
transform
```
/
```
opacity
```
(defer to
```
ui-animation
```
rules).
Re-reading a script to reconstruct its logic instead of running it — the scripts are the canonical, deterministic path.

用单一全局曲线拟合多阶段运动——拆分为多个阶段并组合关键帧。
仅跟踪位置而忽略模糊/透明度——这些效果通常先于位置移动，是动画精致感的关键。
假设展开与收起动画对称——需测量两个方向。
未检查拟合误差就报告弹簧参数——拟合效果差会产生看似可信但错误的数值。
生成动画布局属性（
```
width
```
、
```
height
```
、
```
top
```
、
```
left
```
）的代码——应在
```
transform
```
/
```
opacity
```
上重现运动效果（遵循
```
ui-animation
```
规则）。
重新阅读脚本以重构逻辑而非直接运行脚本——脚本是标准化、确定性的执行路径。

Validation

验证

Re-derive: play the emitted animation, screen-record it, run it back through
```
extract_frames.py
```
, and compare contact sheets side-by-side with the original.
Slow to 0.1x in DevTools to confirm phase order (lead/lag) and the over-stretch survive.
Confirm the emitted code only animates
```
transform
```
,
```
opacity
```
, and
```
filter
```
.
Sanity-check fitted spring
```
overshoot
```
/
```
zeta
```
against what you saw — a clear bounce must not fit as a flat ease.

重新推导：播放生成的动画，录制屏幕，将其重新传入
```
extract_frames.py
```
，并将联系表与原视频的联系表并排对比。
在DevTools中将速度调至0.1x，确认阶段顺序（领先/滞后）和过度拉伸效果得以保留。
确认生成的代码仅对
```
transform
```
、
```
opacity
```
和
```
filter
```
属性执行动画。
对照视觉效果 sanity-check 拟合的弹簧
```
overshoot
```
/
```
zeta
```
参数——明显的弹跳效果不能拟合为平缓的缓动曲线。