Luan-vP/fire-sprites

De video de malabares de fuego a sprites

Estás guiando a un intérprete desde un video en bruto hasta hojas de sprites que pueda usar en un juego. Él conoce su actuación; tú ejecutas las herramientas. Mantenlo involucrado en los dos puntos donde su ojo importa (qué movimientos, y dónde empieza y termina cada uno) y haz todo lo demás tú mismo.

Las herramientas están en la carpeta tools/ de este kit (dos niveles arriba de este archivo). Llámala $KIT. Cada herramienta se ejecuta dentro de un directorio de proyecto que creas para este intérprete; los videos de origen se referencian, nunca se copian.

Lee references/how-it-works.md una vez antes de empezar. Explica las tres ideas en las que se basa todo el proceso: capas separadas de cuerpo y fuego, manejo de exposición y normalización anclada a los pies.

0. Configuración (una vez por máquina)

cd $KIT && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

Usa una compilación nativa de Python para la máquina (en Apple Silicon una versión x86 instala silenciosamente un PyTorch antiguo solo para CPU). ffmpeg y ffprobe deben estar en PATH. Se recomienda encarecidamente una GPU (Apple MPS o CUDA): el renderizado cuesta aproximadamente 3 s por cuadro de salida en un M2 Max. Los pesos del modelo se descargan en el primer uso.

A continuación, py significa $KIT/.venv/bin/python y los comandos se ejecutan desde el directorio del proyecto.

1. Solicita el metraje correcto

Pídele al intérprete los archivos originales de la cámara, no una edición o exportación para redes sociales. Busca en la carpeta que te indique: a menudo un original en 4K, 10 bits, 50 fps está junto a un corte final en 720p, y todo el proceso mejora a partir de él. También pregunta si hay metraje de él caminando o de pie antes de encender el fuego: las rutinas de fuego rara vez contienen un ciclo de caminata limpio, y los juegos necesitan uno.

mkdir -p ~/sprite-projects/NOMBRE && cd ~/sprite-projects/NOMBRE
py $KIT/tools/ingest.py main "/ruta/al/original.mov"      # repite con otros nombres para otros clips

Lee lo que imprime ingest. Mide el nivel de negro real (las etiquetas de rango de archivo no son fiables) y advierte sobre fuentes de 8 bits, baja resolución y frecuencia de cuadros variable. La frecuencia de cuadros variable debe corregirse primero (re-codificar a frecuencia constante), o los números de cuadro se desvían entre el proxy y la fuente.

2. Encuentra metraje utilizable

py $KIT/tools/pose_pass.py main                             # lento: aproximadamente 15 cuadros proxy por segundo
py $KIT/tools/find_segments.py main --strips                # añade --performer por piel si hay una multitud vestida en escena
py $KIT/tools/find_bursts.py main                           # respiraciones de fuego, detectadas por brillo

• find_segments conserva secuencias donde todo el cuerpo está en el encuadre y erguido. Espera que solo una fracción del metraje califique: las cámaras de mano cortan los pies constantemente. Eso es normal; informa al intérprete el número.
• Revisa un par de strips/*.jpg tú mismo. Si siguen a la persona equivocada, cambia al modo --performer.
• Revisa bursts/main.jpg. Conserva solo las respiraciones de fuego reales, luego py $KIT/tools/catalog.py add-bursts main (y elimina cualquier entrada incorrecta de catalog/selected.json). Las respiraciones de fuego se encuentran así porque la búsqueda basada en pose rechaza los cuadros sobreexpuestos.

3. Cataloga los movimientos (usa subagentes)

py $KIT/tools/catalog.py batches 5

Entrega cada lote a un subagente usando el prompt en references/catalog-prompt.md (completa el número de lote y describe al intérprete en una línea para que los revisores puedan rechazar a la persona equivocada). Leen las tiras de película numeradas y escriben catalog/outK.json. Este es el paso que más se beneficia de agentes en paralelo: es puramente visual, y cada lote es independiente. Luego:

py $KIT/tools/catalog.py select            # preselección: calidad >= 4, más caminatas/giros/giros impactantes en 3
py $KIT/tools/catalog.py list

Informa al intérprete claramente lo que se encontró y lo que no (por ejemplo: "13 inactivos, 8 giros, pero solo una caminata real, del clip antes de encender el fuego").

4. El intérprete recorta y elige

py $KIT/tools/make_trim.py                 # un clip de contexto por movimiento + trim.html
open trim.html

Los rangos de los revisores son deliberadamente ajustados; los movimientos reales necesitan respirar en lo que viene antes y después. En trim.html el intérprete arrastra el inicio y el final de cada movimiento sobre unos segundos de metraje circundante, marca Conservar o Descartar, y copia la lista del cuadro en la parte inferior. Pídele que te la pegue. La página almacena su estado en su navegador, por lo que no puedes leerla tú mismo. Guarda el texto pegado en un archivo y:

py $KIT/tools/catalog.py apply-trim kept.txt

5. Renderiza, empaqueta, revisa

py $KIT/tools/render_move.py --kept        # largo: ejecútalo en segundo plano
py $KIT/tools/pack.py --kept
open review.html

Antes de informar, revisa varios archivos moves/NOMBRE/preview.jpg tú mismo. Cosas a comprobar y mencionar en voz alta:

• otra persona fusionada en el recorte (establece "gate": true en ese movimiento en catalog/selected.json si el movimiento no tiene accesorio, luego vuelve a renderizar con --force);
• pared iluminada por fuego que aparece en la capa de fuego;
• pies o cabeza recortados: render_move imprime la proporción de cada rango con todo el cuerpo en el encuadre. Los recortes extendidos a menudo se topan con metraje donde el intérprete sale del cuadro.

review.html reproduce cada movimiento con cambios de fondo y capa, incluyendo "cuerpo + brillo de fuego aditivo", que es cómo debería dibujarlo un juego. atlas.json tiene la cuadrícula de cuadros, fps, ancla de pies y rango de origen por movimiento.

6. Opcional: aspecto de 8 bits

Si quieren una versión retro, usa el skill fire-sprites-retro.

Reglas de honestidad para este trabajo

• Informa recuentos y límites, no solo éxitos: cuántos segundos fueron utilizables, qué movimientos tienen extremidades recortadas, qué capas de fuego incluyen pared.
• El metraje impone límites estrictos. Una nube de fuego que sale del encuadre tiene un borde recto; una llama sobreexpuesta no tiene textura interna que recuperar. Dilo en lugar de prometer una solución.
• Nunca pongas el metraje, nombre o sprites renderizados del intérprete en ningún lugar público. Las salidas permanecen en el directorio del proyecto a menos que él solicite lo contrario.

Consulta references/troubleshooting.md para problemas encontrados en la práctica y qué los solucionó.