De una ilustración a un avatar vectorial animado
Este es el procedimiento para agregar un nuevo personaje a este repositorio (vector-avator). A partir de una sola ilustración del personaje, se crea una vista frontal de pie y una hoja de personaje con el estilo unificado, Fable 5.2 dibuja las piezas vectoriales (rellenas, con regiones ocultas completadas), se verifican y luego se animan en el visor.
El ejemplo es el conejo temporal (ID del personaje usagi, imagen original en inputs/kariusagi/). Los productos terminados de cada etapa se encuentran en public/characters/usagi/vector/ y tools/vector/sheets/characters/usagi.*; si tienes dudas, compáralos.
0. Requisitos previos
El directorio de trabajo es la raíz de este repositorio. Todos los comandos siguientes son rutas relativas desde la raíz.
| Herramienta | Importancia | Etapa de uso | Cómo verificar |
|---|---|---|---|
| Claude Code + Fable 5.2 | Obligatorio | 5. División en piezas (subagente) | El modelo del subagente debe poder especificar Fable 5.2 |
| Codex CLI (imagegen) | Obligatorio | 2. Transformación de estilo, 4. Hojas | codex --version, codex login (funciona con el plan de ChatGPT, no requiere clave de API) |
| Node 22, npm | Obligatorio | 7. Visor, 8. Video | npm install completado |
| Python 3.10+ | Obligatorio | 2 a 6 | python3 -m venv .venv && .venv/bin/pip install -r requirements.txt |
| resvg | Obligatorio | 6. Imagen de verificación | resvg --version (por ejemplo, cargo install resvg) |
| Playwright Chromium, ffmpeg | Obligatorio | 7 a 8. Captura/Video | npx playwright install chromium, ffmpeg -version |
| MiniMax H3 (ComfyUI) | Opcional | 3. Muestras de ángulos | API de ComfyUI (por defecto http://127.0.0.1:8188). Si no está, saltar etapa 3 |
| TTS | Opcional | 8. Voz para lip-sync | Si no está, usar lip-sync de texto |
Si Fable 5.2 o Codex imagegen no están disponibles, informa al usuario y detente. Sustituir la división en piezas con otro modelo resulta en calidad insuficiente.
Puerto del servidor de desarrollo: por defecto 5280 (npm run dev). Si está ocupado, inicia con npx vite --port <puerto> --strictPort y agrega VIEWER_URL=http://127.0.0.1:<puerto>/ a los comandos de captura y video (viewer_shots.mjs, record.mjs). También escribe esa URL en la solicitud que se envía a Fable.
Coste y tiempo estimado (medido)
Mediciones cuando se hizo el conejo temporal (47 piezas). Para personajes a partir del segundo, incluyendo tiempos de espera, 1 a 1.5 horas por personaje. El trabajo humano es solo escribir las características del personaje en viñetas y revisar.
| Etapa | Responsable | Tiempo | Intentos |
|---|---|---|---|
| 1. Descripción del personaje | Claude (principal) | ~10 min | — |
| 2. Vista frontal de pie | Codex imagegen | ~4.7 min | 2 generaciones, 1 adoptada |
| 3. Muestras de ángulos (opcional) | MiniMax H3 | ~7 min | 1 |
| 4. Dos hojas de personaje | Codex imagegen | ~5 min | 1 cada una |
| 5. División en piezas | Fable 5.2 | ~16 min + correcciones ~2.5 min | 1 + 1 corrección |
| 6 a 7. Verificación, ajuste | Claude (principal) | ~20 min | — |
- Codex imagegen tarda ~2 a 2.5 min por imagen. Si se alcanza el límite de uso del plan de ChatGPT, puede haber esperas de varias horas. Por personaje se necesitan 1 a 2 frontales y 2 hojas.
- La división en piezas de Fable 5.2 para otros dos personajes fue de ~22 min (49 piezas) y ~24 min (61 piezas).
- Cuando un agente sin conocimiento previo usó solo esta habilidad para crear un personaje (63 piezas), saltando las muestras de ángulos, totalizó ~43 min (4 imagegen, 1 Fable con ~24 min y ~280k tokens, sin correcciones).
- No se midieron tokens ni costes.
Flujo general
| Etapa | Contenido | Herramienta | Salida |
|---|---|---|---|
| 1 | Escribir las características a conservar (notas del personaje) | Manuscrito | tools/vector/sheets/characters/<id>.md · .json |
| 2 | Transformar el arte original al estilo común y crear vista frontal en pose A | make.py gen <id> restyle | ref/front.png |
| 3 | Extraer fotogramas de un video de rotación 360° (opcional) | turntable.sh <id> | ref/turntable.mp4, ref/angle_*.png |
| 4 | Dos hojas: 4 vistas + manos, y variaciones faciales | make.py gen <id> sheet_turnaround · sheet_face | ref/sheet_turnaround.png, ref/sheet_face.png |
| 5 | Dibujar piezas rellenas (rellenando partes ocultas) | Fable 5.2 + references/fable-brief.md | vector.json |
| 6 | Verificar estructura e inspeccionar visualmente | check_parts.py <id> | 0 errores |
| 7 | Animar en el visor y ajustar | npm run dev, viewer_shots.mjs | vector.json ajustado |
| 8 | Exportar video y lip-sync | record.mjs, lipsync.py | MP4 |
ref/ es public/characters/<id>/vector/ref/. El ID del personaje debe ser alfanumérico en minúsculas (ej. usagi). Las imágenes de prueba y archivos de trabajo de Fable se acumulan en var/vector/<id>/ (no se incluyen en el commit).
1. Escribir las notas del personaje
En tools/vector/sheets/characters/<id>.md, escribe en viñetas las características que deben conservarse incluso al cambiar el estilo. En <id>.json escribe la ruta de la imagen original y su función. La imagen original se coloca en inputs/<id>/.
- Formato y ejemplo en
references/character-notes.md. Ejemplo del conejo temporal:tools/vector/sheets/characters/usagi.md·usagi.json. - Los colores se escriben con valores aproximados (
#RRGGBB). - El estilo común (
tools/vector/sheets/style_base.md) dibuja al personaje como "animal/ser vivo". Si esto cambia al personaje (pelo en personajes sin pelo, dibujar animal a un no animal), anúlelo escribiendo específicamente "no dibujar ~" o "no aplicar ~" en las notas. No modifique el archivo de estilo común. - Incluso si la ilustración original está en una pose dinámica (giro de torso, brazo doblado),
layouts/restyle.mdse encarga de redibujar la pose A frontal. No es necesario escribirlo en las notas; en<id>.jsonse puede añadir "no tomar la pose como referencia" enrolespara mayor estabilidad.
Además, registra el personaje en el visor. Necesario para que Fable lo verifique en la etapa 5. data/characters/<id>.json:
{ "id": "<id>", "label": "<Nombre del personaje>", "vector": { "url": "characters/<id>/vector/vector.json" } }
2. Vista frontal de pie (Codex imagegen)
.venv/bin/python tools/vector/sheets/make.py gen <id> restyle --count 2
.venv/bin/python tools/vector/sheets/make.py log <id>
.venv/bin/python tools/vector/sheets/make.py adopt <id> restyle <número>
- El prompt se construye combinando "estilo común + notas del personaje + qué dibujar (
layouts/restyle.md)" y se envía a imagegen a través decodex exec. Los intentos quedan envar/vector/<id>/gen/junto con el prompt y el tiempo. - Mira siempre las imágenes generadas y compáralas con la original. Verifica: ¿se reconoce al personaje?, ¿es de 2 a 2.5 cabezas de alto?, ¿pose A frontal con espacio bajo los brazos?, ¿sin reflejos en los ojos?, ¿no está bizco?.
- Si no encaja, corrige con
--note "instrucción adicional"o reescribe las notas del personaje (ejemplo: el conejo temporal se veía como otro personaje con el "volumen de pelo" común, así que se anuló en las notas). Deja constancia de la corrección en las notas. adoptcoloca la imagen adoptada enref/front.png(1024×1536).
3. Muestras de ángulos (opcional: MiniMax H3)
bash tools/vector/sheets/turntable.sh <id> # COMFY_SERVER cambia la URL de ComfyUI
- Primero escribe
tools/vector/sheets/h3/<id>.txt(prompt del video de rotación) usandoh3/usagi.txtcomo plantilla. Solo cambia la parte de la descripción del personaje. - Las salidas
angle_045.png,angle_090.png,angle_180.pngse agregan automáticamente como imágenes de referencia en la generación de las hojas (etapa 4). La rotación de H3 no es uniforme; los ángulos son aproximados. - Si no tienes ComfyUI ni H3, salta esta etapa. La división en piezas aún es posible solo con las hojas.
4. Dos hojas de personaje (Codex imagegen)
.venv/bin/python tools/vector/sheets/make.py gen <id> sheet_turnaround
.venv/bin/python tools/vector/sheets/make.py adopt <id> sheet_turnaround 1
.venv/bin/python tools/vector/sheets/make.py gen <id> sheet_face
.venv/bin/python tools/vector/sheets/make.py adopt <id> sheet_face 1
- La primera hoja contiene 4 vistas (frontal, oblicua, lateral, trasera) y 4 formas de mano (abierta, señalando, puño, palma). La segunda hoja contiene variaciones faciales (ojos: abiertos, medio cerrados, cerrados; boca: cerrada, a, i, u, e, o; expresiones: normal, sonrisa, sorpresa, preocupación).
- Las vistas oblicua y lateral dibujan al personaje mirando hacia la izquierda de la pantalla (misma dirección que la rotación de H3).
- Verifica visualmente que sean el mismo personaje que la vista frontal, y que las variaciones sean consistentes (p. ej., ojo medio cerrado sin que el iris se aplaste). Si no encaja, corrige con
--notey regenera.
5. División en piezas (subagente Fable 5.2)
- Toma la plantilla de
references/fable-brief.md, inserta el ID del personaje, nombre, notas específicas del personaje, y la URL del visor (por defectohttp://127.0.0.1:5280/), y guarda envar/vector/<id>/fable/brief.md. El formato y ejemplo (conejo temporal) de las notas específicas están enreferences/character-notes.md. - Inicia un subagente con Fable 5.2 especificado y pásale el contenido completo de
brief.md. Fable, siguiendoreferences/parts-spec.md, creapublic/characters/<id>/vector/vector.jsonmediante un script de dibujo, se verifica a sí mismo y reporta. - Lee el reporte, realiza la verificación de la etapa 6 y la inspección de la etapa 7. Si hay que corregir algo, continúa pidiendo al mismo subagente (no inicies uno nuevo, perderías el contexto).
Lo que debe cumplir (escrito en la plantilla):
- Las piezas se dibujan desde cero como unidades con significado. No se usan recortes de píxeles ni auto-trazado para definir formas.
- Dibujar solo con relleno. Las líneas se agregan automáticamente al renderizar.
- Completar las regiones ocultas (frente debajo del flequillo, cabeza debajo de la base de las orejas, torso sin brazos, cuello, base de la cola, etc.).
- No dibujar imágenes de brazos (se generan al renderizar). En su lugar, medir y escribir las marcas del esqueleto y el grosor/color del brazo.
_Ly_Rson la izquierda y derecha del personaje (en vista frontal,_Lestá a la derecha de la pantalla).
6. Verificación
.venv/bin/python tools/vector/check_parts.py <id>
- Aprueba si hay 0 errores. Las advertencias se evalúan según su contenido.
- Mira visualmente las imágenes de verificación (
var/vector/<id>/check/). Los puntos a revisar están enreferences/visual-qa.md. En particular, en las imágenes con piezas frontales ocultas (qa_*.png) verifica que no haya agujeros ni cortes, que las variaciones (variants.png,expressions.png) coincidan con las hojas, y que las articulaciones del esqueleto (skeleton.png) coincidan con el dibujo. - Las imágenes de verificación no incluyen contornos automáticos ni brazos generados. La apariencia final se verifica en la etapa 7.
7. Animar en el visor
-
Asegúrate de que existe
data/characters/<id>.json(creado en la etapa 1). -
Inicia el servidor de desarrollo con
npm run devy abrehttp://localhost:5280/?char=<id>(si hay más de un personaje, aparece un selector). -
Captura y verifica (mientras el servidor de desarrollo esté corriendo):
DSF=2 node tools/capture/viewer_shots.mjs var/vector/<id>/check/viewer \ neutral="char=<id>" face30="char=<id>&framing=face&yaw=30&blink=0" faceM30="char=<id>&framing=face&yaw=-30&blink=0" \ explain="char=<id>&motion=explain&t=1.0" spread="char=<id>&motion=spread&t=1.2" \ half="char=<id>&framing=face&eye=half&blink=0" point="char=<id>&motion=point&t=1.5" -
Puntos a verificar: ¿aparecen líneas no deseadas en los bordes de las piezas del personaje blanco?, al girar la cabeza ±30°, ¿los ojos salen del contorno facial?, ¿las orejas/cabello se separan de la cabeza?, ¿el grosor y color de brazos y manos son correctos?, ¿los objetos colgantes se balancean adecuadamente?.
-
Los ajustes se hacen modificando valores en
vector.json. Primero prueba con parámetros en la URL y luego escribe los valores. La lista de valores ajustables está enreferences/tuning.md; problemas comunes y soluciones enreferences/troubleshooting.md.
8. Exportación de video y lip-sync
# Video (con el servidor de desarrollo corriendo)
node tools/vector/record.mjs --out out/<id>_explain --motion explain --query "char=<id>"
# Lip-sync: desde wav y lectura (japonés en kana). El tipo de TTS no importa
.venv/bin/python tools/lipsync/lipsync.py line.wav --text "こんにちは、よろしくおねがいします。" -o line.json
node tools/vector/record.mjs --out out/<id>_hello --motion talk_demo --lipsync line.json --audio line.wav --query "char=<id>"
- Si no hay TTS, se puede crear video con lip-sync de texto:
node tools/vector/record.mjs --out out/<id>_hello --motion talk_demo --seconds 6 --query "char=<id>&say=こんにちは、よろしくね。". El diálogo se repite en sincronía con el reloj, y la duración del video se determina por la duración del movimiento (con--secondspara movimientos no en bucle). Para detener según la duración del diálogo, especifica--seconds(aproximación: 0.15 segundos por mora, 0.3 segundos por pausa). - Para diálogo en inglés usa
--lang en, solo volumen sin texto--method rms, con tiempos de palabras de Whisper--whisper whisper.json. - Color de fondo:
--query "bg=ffd3e0", línea estilo dibujo a mano:vHand=0~4(ninguno, suave, medio, fuerte, dibujo a mano +; por defecto fuerte). - En el visor también se puede cargar el JSON de lip-sync y el archivo de audio para reproducir.
Al terminar
Informa al usuario lo siguiente:
- Los archivos creados (imágenes en
ref/,vector.json,data/characters/<id>.json) y la ubicación de las imágenes/video de verificación. - El tiempo de cada etapa y el número de generaciones/correcciones.
- Los resultados de la verificación y los problemas restantes (piezas de las que no se está seguro, apariencias que no se pudieron corregir por completo).