火のパフォーマンス映像をスプライトに変換 は何をしますか？
あなたは、生の動画からパフォーマーがゲームで使えるスプライトシートを生成するまでのガイドをします。パフォーマーは自分のパフォーマンスを知っていますが、ツールを実行するのはあなたです。パフォーマーの目が重要な二つのポイント（どの動きを選ぶか、各動きの開始と終了位置）ではパフォーマーを関与させ、それ以外はすべて自分で行います。
ツールはこのキットの tools/ フォルダにあります（このファイルから2階層上）。これを $KIT とします。すべてのツールは、このパフォーマー用に作成した プロジェクトディレクトリ 内で実行されます。ソースビデオは参照のみで、コピーはされません。
開始前に references/how-it-works.md を一度読んでください。パイプライン全体の基礎となる3つのアイデア（身体と火のレイヤー分離、露出処理、足を基準にした正規化）について説明しています。
0. セットアップ（マシンごとに1回）
cd $KIT && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
マシンにネイティブなPythonビルドを使用してください（Apple Silicon上でx86 Pythonを使用すると、サイレントに古いCPU専用のPyTorchがインストールされます）。ffmpegとffprobeがPATHに含まれている必要があります。GPU（Apple MPSまたはCUDA）を強く推奨します。レンダリングにはM2 Maxで出力フレームあたり約3秒かかります。モデルの重みは初回使用時にダウンロードされます。
以下では、py は $KIT/.venv/bin/python を意味し、コマンドはプロジェクトディレクトリから実行します。
1. 適切な映像の依頼
パフォーマーに 元のカメラファイル（編集済みやSNS用に書き出したものではない）を依頼してください。パフォーマーが指定したフォルダを確認します。多くの場合、4K、10ビット、50fpsのオリジナルファイルが720pの最終カットの隣にあり、後続の処理はオリジナルから行ったほうがはるかに良くなります。また、火が点灯される前にパフォーマーが歩いたり立ったりしている映像があるかどうかも尋ねてください。火のルーティンにはきれいな歩行サイクルが含まれていることはほとんどなく、ゲームには歩行サイクルが必要です。
mkdir -p ~/sprite-projects/NAME && cd ~/sprite-projects/NAME
py $KIT/tools/ingest.py main "/path/to/original.mov" # 他のクリップについては名前を変えて繰り返す
ingest の出力を読んでください。実際の黒レベルを測定し（ファイルレンジタグは信頼できません）、8ビットソース、低解像度、可変フレームレートについて警告します。可変フレームレートは最初に修正する必要があります（定フレームレートに再エンコード）。そうしないと、プロキシとソースの間でフレーム番号がずれます。
2. 使用可能な映像を見つける
py $KIT/tools/pose_pass.py main # 低速：プロキシフレーム毎秒約15フレーム
py $KIT/tools/find_segments.py main --strips # 服を着た群衆が写っている場合は --performer skin を追加
py $KIT/tools/find_bursts.py main # 火の息、明るさで検出
find_segmentsは、全身がフレーム内に収まり直立している部分を保持します。映像の一部のみが条件を満たすことを想定してください。ハンディカメラでは常に足が切れます。これは正常です。パフォーマーにその数を伝えてください。- 自分で
strips/*.jpgをいくつか確認してください。間違った人物を追跡している場合は、--performerモードに切り替えてください。 bursts/main.jpgを確認してください。実際の火の息のみを保持し、その後py $KIT/tools/catalog.py add-bursts mainを実行します（そしてcatalog/selected.jsonから誤ったエントリを削除します）。火の息はこの方法で見つけられます。なぜなら、ポーズベースの検索は白飛びしたフレームを拒否するからです。
3. 動きをカタログ化する（サブエージェントを使用）
py $KIT/tools/catalog.py batches 5
各バッチをサブエージェントに渡し、references/catalog-prompt.md のプロンプトを使用します（バッチ番号を入力し、パフォーマーの説明を1行で記述して、レビューアが誤った人物を拒否できるようにします）。サブエージェントはフレーム番号付きのフィルムストリップを読み取り、catalog/outK.json を書き出します。これは並列エージェントの恩恵を最も受けるステップです。純粋な目視作業であり、各バッチは独立しています。その後：
py $KIT/tools/catalog.py select # ショートリスト：品質 >= 4、およびウォーク/ターン/スピン/ストライクは3以上
py $KIT/tools/catalog.py list
見つかったものと見つからなかったものをパフォーマーに率直に伝えてください（例：「13のアイドル、8のスピン、ただし実際のウォークは火が点灯される前のクリップから1つだけ」）。
4. パフォーマーによるトリミングと選択
py $KIT/tools/make_trim.py # 動きごとのコンテキストクリップ + trim.html
open trim.html
レビューアの範囲は意図的にタイトになっています。実際の動きは、前後の映像を呼吸するように取り込む必要があります。trim.html では、パフォーマーが各動きの開始と終了を数秒の周囲映像にわたってドラッグし、KeepまたはDropをマークし、下部のボックスからリストをコピーします。パフォーマーにそれを貼り付けてもらってください。ページはブラウザに状態を保存するため、あなた自身で読み取ることはできません。貼り付けられたテキストをファイルに保存し、次のコマンドを実行します：
py $KIT/tools/catalog.py apply-trim kept.txt
5. レンダリング、パッキング、レビュー
py $KIT/tools/render_move.py --kept # 長時間実行：バックグラウンドで実行
py $KIT/tools/pack.py --kept
open review.html
報告する前に、自分でいくつかの moves/NAME/preview.jpg ファイルを確認してください。確認して口に出して言うべきこと：
- カットアウトに別の人物が混入していないか（動きにプロップがない場合は、
catalog/selected.jsonでその動きに"gate": trueを設定し、--forceを付けて再レンダリング）； - 火のレイヤーに火に照らされた壁が表示されていないか；
- 足や頭が切れていないか：
render_moveは、全身がフレーム内に収まっている範囲の割合を出力します。トリミングを拡張すると、パフォーマーがフレームから外れる映像に出くわすことがよくあります。
review.html は、すべての動きを背景とレイヤー切り替え付きで再生します。これには「身体 + 加算的な火のグロー」も含まれ、これがゲームで描画すべき方法です。atlas.json には、動きごとのフレームグリッド、fps、足のアンカー、ソース範囲が含まれています。
6. オプション：8ビットルック
レトロなバージョンが必要な場合は、fire-sprites-retro スキルを使用します。
この作業における誠実ルール
- 成功だけでなく、数と限界も報告してください：使用可能な秒数、手足が切れている動き、火のレイヤーに壁が含まれていることなど。
- 映像は厳しい限界を設定します。カメラフレームからはみ出した火の雲にはまっすぐなエッジができます。白飛びした炎には回復可能な内部テクスチャがありません。修正を約束するのではなく、その旨を伝えてください。
- パフォーマーの映像、名前、またはレンダリングされたスプライトを決して公開しないでください。出力は、パフォーマーが別途依頼しない限り、プロジェクトディレクトリ内に留めてください。
実際に遭遇した問題とその修正については、references/troubleshooting.md を参照してください。