火焰表演视频转精灵动画
你将引导一位表演者从原始视频最终产出可在游戏中使用的精灵表。他们了解自己的表演；你负责运行工具。在需要他们视觉判断的两个关键节点（选择哪些动作、每个动作的起止位置）让他们介入，其余所有流程由你独立完成。
工具位于本工具包 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）。ffmpeg 和 ffprobe 必须在 PATH 环境变量中。强烈建议使用 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 源、低分辨率以及可变帧率。可变帧率必须首先修复（重新编码为恒定帧率），否则代理文件和源之间的帧号会偏移。
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设置为 true，然后使用--force重新渲染）； - 火焰层中出现了被火光照亮的墙壁；
- 脚部或头部被裁剪：
render_move会输出每个范围中全身在画面内的占比。扩展的修剪往往会进入表演者离开画面的素材。
review.html 可以播放每个动作，并切换背景和图层，包括“身体 + 火焰发光叠加”，这是游戏应绘制的方式。atlas.json 包含每个动作的帧网格、fps、脚部锚点和源范围。
6. 可选：8-bit 风格
如果他们想要复古版本，请使用 fire-sprites-retro 技能。
本工作的诚实守则
- 报告计数和限制，而不仅仅是成功：可用的秒数、哪些动作有肢体裁剪、哪些火焰层包含了墙壁。
- 素材本身设定了硬限制。火焰烟雾离开相机帧会产生直边；过曝的火焰没有任何内部纹理可供恢复。如实说明，而不是承诺可以修复。
- 切勿将表演者的素材、姓名或渲染后的精灵图集公开发布。输出内容仅保留在项目目录中，除非表演者另有要求。
参见 references/troubleshooting.md 了解实际遇到的问题及其解决方法。