rn-human-motion-extractor

RN ヒューマンモーション抽出器

許可された参照動画から選択範囲を、再利用可能なモーションデータに変換します。モーションとタイミングを保持し、元の人物の外見、声、字幕、映像を再利用可能なアイデンティティアセットとしてパッケージ化しないでください。

境界

• ユーザーが分析を許可されている公開またはローカルの参照素材のみを使用してください。
• 元映像と、アイデンティティを保持するオーバーレイプレビューは、非公開のプロジェクトワークスペースに保管してください。純粋なスケルトン動画とキーポイントデータが、持ち運び可能なモーションアセットです。
• この Skill は根拠を抽出するものであり、生成動画モデルがすべてのキーポイントに従うことを保証するものではありません。
• 指が遮蔽されている、ぼやけている、フレーム外にある、または信頼度ゲートを下回る場合、結果を「正確な手の動き」と呼ばないでください。代わりにカバレッジを報告してください。
• デザインされたカード、コネクター、タイポグラフィ、UI モーションは rn-motion-replica に、全画面のレプリカに関する主張は rn-replica-qc に振り分けてください。

ワークフロー

1. 範囲とタイムベースを確定する

入力ファイルと対象範囲を確認します。ffprobe でソースを調べ、幅、高さ、fps、再生時間、フレーム数、音声の有無を記録します。範囲がすでに短く、明確な場合に限り、クリップ全体をデフォルトで対象にします。

2. ローカル実行環境を作成する

同梱の抽出器には、FFmpeg と Python 3.10–3.12 が必要です。分離された環境を使用し、システムの Python は変更しないでください。

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r \
  <skill-dir>/scripts/requirements.txt

3. 軌跡を抽出する

.venv/bin/python <skill-dir>/scripts/extract_motion.py \
  --input <reference.mp4> \
  --output <private-project-dir>/motion-extraction \
  --start 0 \
  --duration 10

--duration を省略すると、--start から末尾まで処理します。アイデンティティを保持する QC プレビューが不要な場合は、--no-overlay を使用してください。

抽出器は次の情報を記録します。

• MediaPipe のポーズランドマーク 33 個
• 検出された各手のランドマーク 21 個
• 生の座標と、信頼度を考慮して平滑化した座標
• 正規化された画像の x/y、相対 z、可視性、フレームインデックス、タイムスタンプ

短い欠損区間は補間される場合があります。長い欠損はそのまま欠損として残します。長い遮蔽を、作り上げた指の動きで埋めないでください。

4. 根拠を確認する

オーバーレイプレビューと純粋なスケルトンプレビューの両方を開きます。少なくとも冒頭、主なジェスチャーが変化するたび、および最終フレームを確認してください。再現性について説明する前に、qc/extraction-stats.json を読みます。

プレビューの色分けは次のとおりです。

• 黄色：身体
• 青／赤：左手／右手
• 細い灰色：信頼度の低い身体ノード

交差動作中も、肩、肘、手首、手のクラスターが正しい手足に対応していることを確認してください。手が左右入れ替わったり、位置が飛んだりした場合は、生データを保持し、該当する時間範囲を記録してから、ハード制御信号として使う前に手動キーフレームで修正してください。

5. 裏付けのある範囲で結果を報告する

想定される出力は次のとおりです。

motion-extraction/
├── data/
│   ├── motion-keypoints.json
│   └── motion-keypoints.npz
├── qc/
│   ├── extraction-stats.json
│   ├── media-probe.json
│   ├── motion-overlay.mp4
│   ├── motion-skeleton.mp4
│   └── contact-sheet.jpg
└── work/
    └── *.mp4

身体のカバレッジと左右の手のカバレッジを分けて報告してください。身体と手首の有用な軌跡が得られても、指のトラッキングが不完全な場合があります。その場合は、明確に伝えてください。JSON の仕様と左右の判定ルールについては、references/keypoint-schema.md を参照してください。

完了ゲート

• ソース範囲、fps、処理済みフレーム数が一致している。
• JSON を解析でき、処理したフレームごとにエントリーが 1 件含まれている。
• 最終 MP4 がどちらも FFmpeg エラーなくデコードでき、抽出した再生時間と一致している。
• コンタクトシートを目視で確認している。
• 信頼度の欠落や遮蔽は、平滑化で隠さず報告している。
• この抽出 Skill によって、有料の生成タスクが示唆または実行されていない。