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：追跡と曲線フィッティングには 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 を指定してトランジション部分だけを切り出してください。クリップ全体を抽出するとコンタクトシートが大量のフレームで埋まり、追跡の精度も薄れます。インタラクションに開く動作と閉じる動作の両方がある場合は、2 つの区間を切り出し、方向ごとにパイプライン全体を 1 回ずつ実行してください。ほとんどの場合、これらは互いに鏡像ではないため、1 回の計測で両方に対応することはできません。

--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 を渡して検出範囲を 1 つの要素に限定してください（要素ごとに 1 回実行します）。次に、python3 scripts/fit_curves.py <outdir>/metrics.json を実行して、スプリングパラメーター、三次ベジェ曲線、およびプロパティごとのフィッティング誤差を取得します。既定値以外の --fps で抽出した場合は、同じ --fps を fit_curves.py に渡してください。既定値は 30 で、値が一致しないと、すべての時間と剛性が再スケーリングされます（「注意点」を参照）。数値の解釈とモデルの選び方については、references/curve-fitting.md を参照してください。どちらのモデルでも誤差が大きい場合は、複数フェーズの動きです。タイムラインを分割して、各セグメントをフィッティングしてください。

ステップ 5：振り付けの注釈付け

references/choreography.md を読み込みます。タイミングオフセット表（各プロパティがいつ開始し、いつ収束するか）を作成してください。先行／遅延の間隔と伸びすぎる動きのほうが、単一の曲線よりも動きの印象に大きく影響します。

Step 6: コードを出力する

要求されたターゲットに合わせて、フィッティングしたパラメーターを references/code-output.md のテンプレートに当てはめます。動きには transform／opacity を使用します。開く動きと閉じる動きが異なる場合は、2 つのトランジションを出力します。references/code-output.md のタイミング表＋カーブ＋スニペットから成る統合されたハンドオフ用モーション仕様を作成し、動画がなくても実装できるようにします。

Step 7: 検証する

以下の検証項目を実行します。合格基準は見た目の印象ではなく、比較による証拠です。

注意点

• fit_curves.py のデフォルトは --fps 30 です。--fps 60 で抽出し、デフォルト設定でフィッティングすると、すべての duration_ms が 2 倍になり（500 ms のトランジションが 1000 ms と表示されます）、フィッティングされた剛性は 4 分の 1 に低下します。フィッティング時には必ず抽出時の fps を指定してください。
• ソースのフレームレートを超えてサンプリングすると、フレームが重複します。24 fps の GIF を --fps 60 で抽出すると、metrics.json に同じ値が連続する区間が生じ、進行度カーブが平坦になり、両方のフィッティング誤差が増大します。まずソースのフレームレートを調べ、それに合わせてください。
• 画面録画は負荷がかかるとフレームが欠落します。また、iOS／QuickTime のキャプチャは可変フレームレートです。metrics.json で連続して同一の行がある場合、それはアニメーションの一時停止ではなく重複フレームです。平坦な区間が大半を占める場合は、フィッティングを調整するのではなく、より安定したフレームレートで録画し直してください。
• 複数フェーズの動きを 1 つのグローバルカーブでフィッティングすると、両方のモデルで誤差が大きくなります。フェーズに分割し、キーフレームを組み合わせてください（references/curve-fitting.md）。
• 位置だけをトラッキングすると、ぼかし／不透明度を見落とします。これらは通常、動きより約 100 ms先行します。この先行が、仕上がりの差を生みます。
• 開く動きと閉じる動きは、決して鏡像にはなりません（開く動きは遅く、ばね感が強く、閉じる動きは速く、平坦です）。それぞれの方向を個別のクリップとして計測し、開く動きのカーブを反転して使い回さないでください。
• フィッティングの error を確認せずにばねのパラメーターを報告しないでください。フィッティングが不適切だと、確信がありそうに見えても数値が誤っています。誤差が 0.08 を超える場合は疑わしい値として扱ってください。
• レイアウト用のプロパティ（width、height、top、left）をアニメーションするコードを出力しないでください。transform／opacity／filter で動きを再現してください（ui-animation のルールに従ってください）。
• スクリプトを読み直して処理を推測するのではなく、実行してください。スクリプトは正規の決定的な手順です。

検証

• 再導出します。出力したアニメーションを再生して画面録画し、extract_frames.py に再度通して、コンタクトシートを元のものと並べて比較します。
• DevTools で 0.1 倍速にし、フェーズの順序（先行／遅延）と伸びすぎの動きが維持されていることを確認します。
• 出力したコードが transform、opacity、filter のみをアニメーションしていることを確認します。
• フィッティングしたばねの overshoot／zeta が実際に見た動きと整合しているか、妥当性を確認します。明確なバウンスが、平坦なイーズとしてフィッティングされていてはいけません。

関連スキル

• ui-animation：抽出した仕様を、本番環境に適した割り込み可能なモーションに変換し、イージングのデフォルト設定とアンチパターンのルールを適用します。