火舞表演影片轉為精靈動畫
您正在引導一位表演者，從原始影片一路製作成他們可以在遊戲中使用的精靈表。表演者熟悉自己的演出；您負責操作工具。請在兩個關鍵環節讓他們參與判斷（選擇哪些動作，以及每個動作的起點與終點），其餘部分由您自行完成。
所有工具都位於此工具包的 tools/ 資料夾中（相對於此檔案向上兩層）。稱之為 $KIT。每個工具都在您為此表演者建立的專案目錄內執行；原始影片會被引用，但絕不複製。
在開始之前，請先閱讀 references/how-it-works.md 一次。它說明了整個流程所依賴的三個核心概念：分離身體與火焰圖層、曝光處理、以及錨定腳部的標準化。
0. 環境設定（每台機器只需執行一次）
cd $KIT && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
請使用適用於該機器的原生 Python 版本（在 Apple Silicon 上，x86 的 Python 會靜默安裝僅支援 CPU 的舊版 PyTorch）。必須在 PATH 環境變數中包含 ffmpeg 和 ffprobe。強烈建議使用 GPU（Apple MPS 或 CUDA）：在 M2 Max 上，渲染成本約為每輸出幀 3 秒。模型權重將在首次使用時下載。
下文中的 py 代表 $KIT/.venv/bin/python，且命令皆從專案目錄下執行。
1. 要求正確的影片素材
請向表演者索取原始攝影機檔案，而非經剪輯或匯出至社交媒體的版本。檢查他們所指派的資料夾：一個 4K、10-bit、50 fps 的原始檔經常就放在一個 720p 的最終剪輯檔旁邊，而下游的所有處理都從原始檔開始效果更好。同時詢問是否有他們在點火前走路或站著的影片：火舞表演很少包含清晰的走路循環，而遊戲需要走路動畫。
mkdir -p ~/sprite-projects/NAME && cd ~/sprite-projects/NAME
py $KIT/tools/ingest.py main "/path/to/original.mov" # 對其他片段重複執行並使用不同名稱
閱讀 ingest 的輸出內容。它會測量真實的黑電平（檔案標籤的範圍標記不可靠），並對 8-bit 來源、低解析度和可變影格率（VFR）發出警告。可變影格率必須先修正（重新編碼為固定影格率），否則代理檔與原始檔之間的幀數會出現偏移。
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 中的提示（填入批次編號並用一句話描述表演者，以便審閱者能排除錯誤的人）。他們會讀取標有幀號的影片片段，並寫入 catalog/outK.json。這是藉助並行代理效益最大的步驟：它純粹是視覺辨識，而且每個批次之間相互獨立。然後執行：
py $KIT/tools/catalog.py select # 篩選出品質 >= 4 的項目，以及評分為 3 的走路/轉彎/旋轉/打擊動作
py $KIT/tools/catalog.py list
直接告訴表演者找到了什麼、沒找到什麼（例如：「13 個待機動作，8 個旋轉，但只有一個真正的走路動作，來自點火前的那段影片」）。
4. 表演者修剪與選擇
py $KIT/tools/make_trim.py # 為每個動作產生一段上下文片段 + trim.html
open trim.html
審閱者設定的範圍通常偏緊；實際的動作需要留出前後的緩衝空間。在 trim.html 中，表演者可以在前後幾秒的周圍素材上拖放每個動作的開始與結束點，標記為保留或刪除，並從頁面底部的方塊中複製清單。請他們將清單貼給您。該頁面會將狀態儲存在他們的瀏覽器中，因此您無法自行讀取。將貼上的文字儲存至檔案，然後執行：
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 以了解實務上常見的問題以及解決方法。