SPEC-PIEZAS · el estándar de pieza, marioneta, personaje y collage

Estado: v1, 15-10-2026. Rama piezas. Código: manim_saorin/estudio/. Lo pidió José Luis: «Toda la forma de hacer dibujos, hacer marionetas, etc. debe ser estándar y ser especialmente útil» y «se deben poder hacer vídeos de mixed media como si fuera un collage en movimiento muy fácilmente». La vara de calidad es el bestiario de Radiointermisión (~/Movies/radiointermision), del que sube a la librería todo lo genérico.

Este documento es normativo para lo que entra en un pliego por PIEZAS/PYTHON, python:, MARIONETA, foto: y clip:. Lo que no está aquí no está garantizado. La gramática del pliego sigue en SPEC-MESA-2.md.

§1. La idea en una tabla

Cada nivel es un superconjunto del anterior. Un personaje es también una marioneta, una pieza con partes y un dibujo: todo lo que el pliego puede pedir a un nivel lo puede pedir a los de arriba.

§2. El contrato

§2.1 Nivel 0 · dibujo

Una función (no un objeto) que devuelve un mobject de ManimGX, con:

• firma: sus argumentos propios por posición o por nombre (lo que el pliego escribe tras python: nombre), más los extras con valor por defecto: alto=None (unidades de escena: la pantalla mide 8), hervor=None (0, 1 o 2 fija una pose del hervor; None, la mesa la hace hervir), mundo=None (el modelo de color, §3.3), espejo=None, id=None;
• la ficha fn.PIEZA (un dict, §3);
• el hervor: dibujada con la Hoja del estudio (estudio/pluma.py), las tres poses tienen la misma estructura y otro pulso. La regla de siempre (aviva_constructor) sigue valiendo: la función termina en return pulso(h) y la mesa sustituye pulso para sacar las tres poses;
• el apoyo: h.pies (la cota de la hoja donde se apoya) para que se pose por los pies y no por el centro.

Una foto recortada (recortable, §7) es una pieza de nivel 0 con registro foto: no hierve el papel, hierve lo que la sujeta (la cinta, la chincheta).

§2.2 Nivel 1 · partes

Además: pieza.partes (dict nombre → submobject) y pieza.pivote(nombre). Las partes se abren en el orden de la mano con with h.parte("nombre", pivote=(x, y), dentro="madre"). Las partes esenciales (§3.2) se declaran siempre que existan.

§2.3 Nivel 2 · marioneta

Además:

• firma de la ficha: vista="frente", pose="reposo", expresion="neutra", boca="reposo", mano_i="reposo", mano_d="reposo", hervor=None + los extras. Con vista y boca en la firma la mesa la trata como ficha viva (gx/ficha.py): la redibuja cuando cambian su pose, su boca o su hervor;
• POSES (tupla de nombres), ACCIONES (dict acción → lista de poses, se hacen «en dos») y CICLOS (dict ciclo → lista de poses que se repite; corre y anda los lanza el verbo de movimiento);
• pivote y madre en cada parte articulada (la hija viaja con la madre);
• si una parte se llama mandibula, se abre con los visemas: la boca sigue a la voz sola, como la de un personaje.

Las acciones de una marioneta son su vocabulario cerrado: X saluda vale si saluda está en sus ACCIONES (o es una de sus POSES); si no, la mesa lo dice con la lista de las que tiene.

§2.4 Nivel 3 · personaje

El contrato de gx/ficha.py y de §39 de dirigir-saorin, entero:

Partes (anidadas, con pivote): tronco (pelvis) · cuello · cabeza (nuca) → ojos, cejas, nariz, boca, orejas, gafas… · pelo (melena, acción secundaria) · bufanda · brazo_* (hombro) → antebrazo_* (codo) → mano_* (muñeca) · muslo_* (cadera) → pierna_* (rodilla) → pie_* (tobillo) · falda si la lleva.

§3. La ficha de la pieza (fn.PIEZA)

meta_de(fn) la lee y, para los bestiarios anteriores al estándar, la deduce de la firma y los atributos (y mesa pieza comprueba avisa).

§3.2 Las partes esenciales

Lo que la lengua protege al cortar por el borde (SPEC-MESA-2 §3.11.3c): cara (los rasgos) · boca · cabeza · mano (la que actúa) · objeto (lo que importa). Un personaje declara las cuatro primeras; una marioneta, al menos cabeza u objeto; un dibujo, objeto. Ninguna esencial puede salirse del contorno de la pieza (comprueba lo mide).

§3.3 Los modelos de color por mundo

mundo=: natural · tinta (crema y tinta) · sepia (el recuerdo) · noche (ámbar y crema sobre azul) · hielo · silueta o silueta:#RRGGBB · riso:TAMBOR+TAMBOR (dos tambores del canon) · y los de Radiointermisión (radio, recuerdo, var, patio, estadio, anuncio). Un proyecto añade los suyos con registra_mundo(nombre, fn). Vale igual para dibujos (recolorea cada tinta) y fotos (lleva el gris a las dos tintas del mundo).

§4. El personaje con palabras

Un personaje nuevo no necesita código: x.personaje.toml (o personaje(...) en Python) con estas secciones, todas de vocabulario cerrado (una palabra que no está es error, con la lista de las que valen):

• [cuerpo] alto (muy bajo … muy alto) · complexion (menuda, flaca, media, fuerte, robusta, ancha) · edad (niña/niño, joven, adulta/adulto, vieja/viejo: la edad trae proporciones, encorvadura, arrugas y piel);
• [cabeza] craneo (medio, alargado, ancho, cuadrado, redondo, ovalado, viejo, fino, infantil) · nariz (recta, chata, aguileña, bulbo, rota) · ojos · iris · cejas · orejas · piel · gafas · bigote · barba · coloretes · pecas · venda;
• [pelo] estilo (corto, rapado, melena, media melena, moño, coleta, calvo, corona) · color;
• [ropa] arriba (camiseta, camisa, jersey, chaqueta, batín, rebeca, abrigo, sudadera, uniforme, vestido) · color · franjas · abajo (pantalón largo/corto, falda, falda larga/corta) · color_abajo · medias · calzado · color_calzado · bufanda · cuello · escudo · dorsal · cinturon · guantes · brazalete;
• [poses.NOMBRE] por articulación, en palabras: brazo_d/brazo_i (cae, arriba, al frente, señala, atrás, en jarras, cruzado, a la boca, saluda, abierto, en cruz, en alto, doblado, ofrece, a la cadera), pierna_* (firme, adelante, atrás, rodilla arriba, abierta, sentada, doblada), cabeza (recta, baja, alta, ladeada, a la derecha, a la izquierda, hundida, atrás), cuerpo (erguido, inclinado, agachado, echado atrás, encogido, sentado, girado, de lado; se combinan con « y »), base (una pose común de partida), mano_d, mano_i, expresion;
• [acciones] nombre → lista de poses.

Los colores son los del canon por nombre (tinta, minio, azurita, ultramar, granate, ocre, mostaza, verde oscuro, beis, crema…) o #RRGGBB.

Cuándo bajar a la ficha en bruto: cuando el carácter de la cara pide rasgos escritos a mano (rasgos=[dict(p=[(acimut, altura, sale)…], g=…)]), un cráneo propio por secciones o una prenda que no está. ficha_de_datos produce el dict que entiende dibuja; se edita y se pasa a ficha_publica. Así están hechos los de Radiointermisión.

§5. Las herramientas

mesa pieza nueva «nombre» [--tipo dibujo|marioneta|personaje|recorte] [--foto x.jpg] [-d carpeta]
mesa pieza comprueba fichero.py|fichero.toml|carpeta [--solo a,b]
mesa pieza hoja fichero[:nombre] [-o carpeta]
mesa bestiario fichero|carpeta [-o carpeta]

• nueva escribe la plantilla del tipo (con el vocabulario al lado) y dice el siguiente paso. --tipo marioneta --foto x.jpg es la marioneta de foto; --tipo recorte --foto x.jpg, la foto recortada.
• comprueba llama a la pieza como la llamará la mesa y mira lo que sale: que se dibuja; que hierve (tres poses, misma estructura, distinto pulso); que trae sus partes y sus esenciales y que ninguna esencial se sale del contorno; que cada parte articulada tiene pivote y que ningún pivote cae fuera; que cada acción y cada ciclo usan poses que existen y se dibujan; en un personaje, las cinco vistas, la cara de frente y de tres cuartos, que la boca cambia con los visemas, los ciclos de andar y correr y los mundos. Cada línea dice ✓, ⚠ o ✗ y qué hacer. Sale con 1 si hay algún ✗.
• hoja hornea las hojas de presentación de su nivel (§6).
• bestiario escribe BESTIARIO.md (la ficha, la firma, las partes, las poses, las acciones y las líneas de pliego que se le pueden pedir a cada pieza) y hoja_contactos.png, generados del código.

Todas corren en el Python de ManimGX (MESA_GX_PYTHON) y todo lo pesado pasa por ~/Developer/torculo/tools/pesado.

§6. Las hojas de presentación (model sheets)

Papel del canon, letra de mano con tildes, filas rotuladas y cada fila a la misma escala (la de la hoja de dibujo):

• personaje: _1_giro (cinco vistas con las alturas en cabezas, y en acción) · _2_caras (expresiones; diez visemas en frente, tres cuartos y perfil) · _3_manos_y_poses · _4_ciclos · _5_hervor_color_partes (hervor, mundos, pivotes en cruces rojas y lo esencial en recuadros);
• marioneta: poses, acciones, bocas, hervor, mundos, partes y pivotes;
• dibujo: la pieza con lo esencial, el hervor y los mundos.

Se le mandan a José Luis antes de escribir el pliego (dirigir-saorin §39).

§7. El collage en movimiento

§7.1 La foto recortada

foto: medios/abuela.jpg · sin fondo · canto de tijera · sombra levantada · con cinta
recorte: medios/maquina.jpg · canto rasgado · con chincheta
foto: medios/carta.jpg · con fondo · canto rasgado · con celo

• sin fondo (lo de siempre en recorte:): Vision del Mac en local (estudio/swift/recorte.swift, el gemelo de escritorio de SubjectLifter del sticker-engine; se compila solo), si no ONNX (onnxruntime + ~/.u2net/isnet-general-use.onnx) y si no la inundación de los bordes;
• canto: de tijera (cortes rectos alrededor, margen desigual), de troquel (blanco puro: el único que la casa permite), rasgado, limpio;
• sombra: pegada (por defecto), levantada, sin sombra; dura, de la luz de la casa, nunca negra (#4A4032);
• con cinta · celo · chincheta: dibujadas a pluma, hierven.

Sin ·, foto: es la de siempre (semitono, Polaroid). Las materias por pieza siguen valiendo: en risografía rosa: foto: … · sin fondo, en pincel: foto: …. Fuera del pliego: estudio.collage.recortable(...).

§7.2 La marioneta de foto (Terry Gilliam)

MARIONETA charlot · de la foto medios/chaplin.jpg · mira a la derecha
MARIONETA bailarina · de la foto medios/isadora.jpg · mira a la izquierda · canto de troquel
REPARTO CHARLOT: minio, elevenlabs A, alias: charlot
…
python: charlot
CHARLOT: —¿estás viendo lo que yo estoy viendo?
BAILARINA baila

Vision encuentra las articulaciones de la persona (cuello, hombros, codos, muñecas, caderas, rodillas, tobillos) y la cara. La foto se corta con un solo canto de tijera alrededor y se parte por las articulaciones: cabeza, tronco, brazo_*, antebrazo_*, muslo_*, pierna_* (las piernas solo si se ven enteras: una falda larga no se parte), cada una con su pivote, solapada un poco con su madre para que al girar no se abra el hueco. De la cara sale la mandíbula (lo que queda bajo el labio), que baja con la voz dejando ver el hueco oscuro con los dientes. Sin persona ni cara, la foto es una sola pieza que tiembla.

Poses de serie (en palabras, para un recortable plano: el brazo se orienta «hacia fuera», «arriba», «en cruz»…): saluda, celebra, señala, baila, se inclina, duda, grita, aplaude, en jarras, y el ciclo anda. Las propias, en x.marioneta.toml con las palabras de PALABRAS_FOTO (§4 para el formato) o en grados por parte. Su hervor es el temblor del stop-motion: cada pose del hervor mueve un pelo cada parte.

Si el corte automático no sirve, las partes se escriben a mano en el .marioneta.toml ([partes.NOMBRE] poligono = [[x, y]…] normalizado, pivote, madre).

§7.3 El clip recortado

clip: medios/annabelle.mp4 de 0:01 a 0:07 · sin fondo
clip: medios/annabelle.mp4 de 0:01 a 0:07 · sin fondo · canto de troquel · a 24
clip de fondo: medios/annabelle.mp4

Cada fotograma se recorta (Vision) y se vuelve a cortar a tijera: el canto hierve solo, como el de un recortable animado. En dos por defecto (12 imágenes por segundo, como los recortes); a 24 o en uno lo deja a la cadencia del cine; en cuatro, a 6. Es pesado la primera vez y se cachea. El clip de fondo, a pantalla completa, sigue siendo la película a 24: la mezcla de cadencias (el vídeo real a 24, lo recortado en dos, la pluma hirviendo a 8) sale sola y se ajusta con CADENCIA (SPEC-MESA-2 §3.13).

§7.4 Lo que funciona igual con piezas de foto y de vídeo

Cartel (CARTEL, LETRA, · gigante · cortado por …, la salvaguarda de lo esencial), cámara (> la cámara se acerca a «charlot», capas por distancia, foco), la imagen que oye (LUZ, SOPORTE, INTENSIDAD) y Lasseter (los verbos de movimiento con su anticipación y asiento): una pieza de foto tiene partes y esenciales como cualquier dibujo, y un clip recortado es un actor más (sin marco ni celo).

§8. En el pliego

• PIEZAS ruta (preámbulo): un .py, un .toml (personaje, marioneta de foto o recorte) o una carpeta entera. Es PYTHON ampliado; PYTHON sigue valiendo para un .py.
• MARIONETA nombre · de la foto ruta [· mira a la izquierda|derecha] [· canto …] (preámbulo): la marioneta de foto sin fichero.
• python: nombre [args] pone cualquier pieza (§1). Con nombre (python: abuela pose=recuerda vista=perfil) fija la pose y la vista de partida de una ficha.
• QUIEN acción (clip): para un nombre del REPARTO (con alias: al nombre de la pieza) o de una MARIONETA, cualquier acción que la pieza declare (CAPITAN muerde, TIJERAS corta, ABUELA recuerda). Las de la lengua (celebra, grita, anda, señala…) siguen valiendo para todas. Una acción que la pieza no tiene es aviso en el rodaje, con la lista de las que tiene.
• mesa lee conoce los nombres de los .toml, las carpetas y las MARIONETA, y avisa si la foto de una marioneta no existe.

§9. Lo que la librería trae (y lo que se queda en el proyecto)

De la casa (manim_saorin/estudio/): la pluma (pluma.py: Hoja, cera, sombra, aguada, rotulo Hershey, fusión de hojas, láminas), el muñeco de estudio (muneco.py: esqueleto 3D con giro, cráneo por secciones, caras, visemas, manos y objetos en mano, pelo, ropa, ciclos de andar y correr), el personaje (personaje.py: el dibujante por profundidad, el contrato, la declaración con palabras, la disolución entre dos fichas), los mundos, las esenciales, la marioneta (dibujada y de foto), el collage, el horno de hojas, la comprobación y el bestiario.

Del proyecto: quién es cada uno (su ficha o su .toml), sus poses y acciones propias, sus objetos y sus mundos si no son los de serie. El corte es el de dirigir-saorin §10: si un proyecto tiene que copiar código de otro para hacer un personaje, eso estaba en el lado equivocado.

Radiointermisión sigue con su copia (muneco.py, pluma_ri.py, personajes.py) y su contrato es idéntico: la librería dibuja lo mismo, trazo a trazo (comprobado lado a lado con el delantero). Pasarlo a la librería es cambiar sus import cuando su agente lo decida.

§10. Trampas

• El estudio vive en ManimGX: todo esto rueda con --motor gx (en Cairo, foto: … · sin fondo avisa y sale la foto de siempre).
• Los id en ASCII (son semillas: una tilde cambia el pulso).
• Las piernas de una foto con falda larga no se parten (Vision ve las rodillas con poca confianza): es lo correcto, no un fallo.
• Una foto sin persona ni cara es una marioneta de una sola pieza: para articularla, escribe sus partes en el .toml.
• Una acción con nombre propio solo se entiende si quien la hace está en el REPARTO (con su alias:) o es una MARIONETA; si no, la línea es prosa.
• El clip recortado es pesado la primera vez (Vision en cada fotograma): córtalo a lo que se ve (de … a …).