gif-animado

GIF Animado

Tres herramientas, un núcleo de ensamblaje. Elige la ruta que coincida con la entrada.

Entrada	Herramienta	Movimiento
Fotogramas de texto con colores ANSI	bin/ascii_gif.py	secuencia de fotogramas
Carpeta de fotos o imágenes	bin/pics_gif.py	pausa, transición, Ken Burns
Animación SVG o HTML	bin/svg_gif.py	SMIL, CSS, o preset rotar/pulsar/desvanecer

Todas las rutas comparten bin/gifkit.py: una paleta para todo el bucle, cuadrícula de temporización de 10 ms, fotogramas consecutivos idénticos fusionados en retardos más largos, escritura atómica, verificación de lectura.

Dependencias

Pillow es necesario. SVG y HTML necesitan Node con Playwright y un shell headless de Chromium.

python -c "import PIL; print(PIL.__version__)"
node -e "require('playwright')"
npx playwright install chromium --only-shell

Cada herramienta imprime una línea FAIL ... en stderr y sale con código 1 cuando falta una dependencia o entrada. No reintentar con los mismos argumentos.

Flujo de trabajo

1. Elige la ruta de la tabla. Lee la sección correspondiente a continuación.
2. Ejecuta la herramienta con una ruta de salida explícita dentro del proyecto en el que se está trabajando. No escribir en un directorio temporal del sistema ni en el Escritorio.
3. Conserva el resumen impreso: número de fotogramas, duración, tamaño en píxeles. Una ruta impresa es un GIF verificado.
4. Para trabajo visual, abre el GIF o escribe --preview preview.png e inspecciona esa imagen fija antes de informar.
5. Informa la ruta absoluta junto con los ajustes importantes: fps, tamaño, duración, modo.

Ruta ASCII

La entrada es un archivo de texto. Los fotogramas se separan por una línea que contiene solo ---; un retardo opcional en ms sigue al separador: --- 250. Los colores SGR ANSI se respetan: 30-37, 90-97, 38;5;n y 38;2;r;g;b. Un directorio de archivos .txt se lee como un fotograma por archivo, ordenado por nombre.

python bin/ascii_gif.py frames.txt -o project/loader.gif --size 28 --delay 120
python bin/ascii_gif.py frames/ -o project/loader.gif --preview project/loader.png

• --font debe ser un TTF o TTC monoespaciado; las fuentes monoespaciadas comunes se detectan automáticamente cuando se omite.
• --width y --height fijan el lienzo y centran la cuadrícula de texto. Proporciona ambos, o ninguno. Úsalo para igualar un tamaño entre varias muestras.
• --fg y --bg por defecto son texto claro sobre un lienzo casi negro.
• --delay es el retardo de fotograma predeterminado; los retardos del separador lo anulan por fotograma.
• Mantén los fotogramas dentro de aproximadamente 120 columnas y 40 filas; los lienzos más grandes producen GIFs largos.

Ruta de carpeta de imágenes

Los archivos se ordenan naturalmente (pic-2 antes que pic-10), se rotan según EXIF y se ajustan a un lienzo.

python bin/pics_gif.py photos/ -o project/reel.gif --mode kenburns --fps 12 --hold 1.2 --transition 0.5 --width 800
python bin/pics_gif.py photos/ -o project/reel.gif --mode sequence --fps 10 --hold 0.8 --fit contain --bg "#101010"

• sequence mantiene cada imagen; crossfade mezcla entre imágenes; kenburns acerca lentamente cada imagen, alternando dirección.
• --width establece el lienzo; --height por defecto es la relación de aspecto de la primera imagen.
• --fit cover recorta para llenar, contain rellena con --bg.
• --hold son segundos por imagen, --transition segundos de mezcla, --zoom el zoom final de Ken Burns.
• Una carpeta de 100 fotos a 800 px y 12 fps produce un archivo grande; reduce primero el ancho o los fps.

Ruta SVG y HTML

La herramienta envuelve .svg en una página en la ventana solicitada, o abre .html directamente, luego pausa y busca cada animación en tiempos explícitos antes de cada captura de pantalla. Los fotogramas no dependen del tiempo de pared.

python bin/svg_gif.py logo.svg -o project/logo.gif --duration 3 --fps 15
python bin/svg_gif.py logo.svg -o project/logo.gif --animate rotate --selector "#mark" --duration 2 --background "#0b0d12"
python bin/svg_gif.py page.html -o project/page.gif --width 960 --height 540 --duration 4 --fps 12

• Sin --animate, el SVG o la página deben animarse ya sea mediante SMIL o CSS. Los dibujos estáticos necesitan un preset.
• Presets: rotate, pulse, fade, aplicados a la raíz del SVG o a --selector.
• --width y --height por defecto toman los valores de width/height del SVG o del viewBox.
• --dpr 2 captura al doble de la ventana, para texto más nítido; el GIF tendrá entonces el doble de tamaño en píxeles.
• Las páginas con canvas impulsadas por JS o WebGL no son manejadas por esta herramienta. Usa una página que exponga un hook de fotogramas, o renderiza previamente los fotogramas y ensámblalos con gifkit.

Opciones compartidas

• --colors hasta 255. Redúcelo solo cuando la paleta sea simple o el archivo deba encogerse.
• --dither none es correcto para arte plano y texto; floyd ayuda con degradados y fotos.
• --loop 0 se repite infinitamente; cualquier otro valor repite esa cantidad de veces.
• --preview PATH escribe un PNG del primer fotograma.
• La salida es determinista para la misma entrada, ajustes y cadena de herramientas.

Fotogramas personalizados

Cualquier secuencia de fotogramas puede usar el mismo núcleo. Los fotogramas deben ser RGB y del mismo tamaño; los retardos están en ms en la cuadrícula de 10 ms.

import sys
sys.path.insert(0, "bin")
import gifkit
from PIL import Image

frames = [Image.new("RGB", (320, 180), (n * 20, 40, 90)) for n in range(12)]
gifkit.write_gif(frames, "project/gradient.gif", [100] * 12)

write_gif construye una paleta, fusiona fotogramas consecutivos idénticos, escribe atómicamente y verifica el resultado. Usa esta ruta para animaciones de datos, diagramas generados o cualquier fotograma que estas rutas no cubran.

Contrato

• La herramienta escribe en <name>.tmp.gif en el directorio de salida, verifica el número de fotogramas, la suma de duración y el tamaño en píxeles leyendo el archivo de vuelta, luego lo renombra. Un fallo elimina el archivo temporal y no deja un objetivo parcial.
• El GIF usa una paleta para cada fotograma, por lo que los colores no pueden parpadear.
• Los fotogramas consecutivos idénticos se fusionan en un fotograma con un retardo más largo; el número de fotogramas impreso es el número almacenado.
• Los retardos se sitúan en la cuadrícula GIF de 10 ms y son de al menos 20 ms.

Verificación

Las comprobaciones de cada ruta residen en el repositorio fuente. Desde la raíz del repositorio:

python tools/check.py

Cada comprobación imprime una línea PASS, SKIP o FAIL. Las dependencias opcionales faltantes se saltan por defecto; --strict requiere cada ruta. Las comprobaciones generan fixtures bajo scratch/checks y también escanean el repositorio en busca de secretos, rutas absolutas, texto no ASCII y finales de línea CRLF.

Límites

• GIF es indexado de 8 bits y tiene un límite de 256 colores; las fotos muestran bandas sin tramado.
• Los visores recortan retardos cortos; mantén los retardos de fotograma en 20 ms o más.
• Las secuencias largas, de alta tasa de fotogramas y color verdadero son mejores como APNG o WebM. Dilo cuando te pidan calidad.
• La memoria crece con el número de fotogramas y el tamaño del lienzo; las herramientas mantienen todos los fotogramas mientras construyen una paleta.
• La cobertura de glifos ASCII depende de la fuente elegida; los glifos de caja o bloque faltantes caen en cuadros vacíos.

Consulta references/animated-gif-considerations.md para conocer las restricciones de formato y el razonamiento detrás de estos valores predeterminados.

Archivos

• bin/gifkit.py - paleta, temporización, fusión, escritura atómica, verificación.
• bin/ascii_gif.py - fotogramas de texto ANSI a GIF.
• bin/pics_gif.py - carpeta de imágenes a GIF.
• bin/svg_gif.py - animación SVG/HTML a GIF.
• bin/render_frames.cjs - helper de captura de fotogramas de Playwright.
• references/animated-gif-considerations.md - notas de formato.

Las comprobaciones del repositorio y la generación de muestras están en tools/, fuera del payload de la habilidad instalada.