# Las piezas, las marionetas y el collage (SPEC-PIEZAS) > El estándar de pieza (estática, por partes, marioneta, personaje con ficha), su ficha, lo esencial que no se corta y el collage en movimiento. URL: https://torculo.joseluissaorin.com/referencia/piezas · Revisado: 2026-10-16 · English: https://torculo.joseluissaorin.com/en/reference.md Fuente: manim-saorín · SPEC-PIEZAS.md (generada al construir la web). > 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 | nivel | qué es | se declara con | el pliego puede | |---|---|---|---| | **0 · dibujo** | un dibujo a pluma, una foto, un recorte | `@pieza(...)` sobre una función · `x.recorte.toml` · `foto: x.jpg · sin fondo` | ponerla, moverla, filmarla, cortarla por el borde | | **1 · partes** | + partes con nombre y pivote | lo mismo, dibujando en `h.parte(...)` | además: `el pelo pasa de A a B`, proteger lo esencial al cortar | | **2 · marioneta** | + articulación (madres y pivotes), poses, acciones y ciclos | `marioneta(...)` · `marioneta_de_foto(...)` · `x.marioneta.toml` · `MARIONETA x · de la foto y.jpg` | además: `X saluda`, `X corre hasta…`, la boca sigue a la voz si hay mandíbula | | **3 · personaje** | + cinco vistas, expresiones, visemas, manos, ciclos de andar y correr, mundos | `personaje(...)` · `x.personaje.toml` | además: `X de espaldas`, la vista sale del plano, `al decir «…»: X se asombra` | **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: | | valores | |---|---| | `vista` | frente · tres cuartos · perfil · tres cuartos de espalda · espalda (o grados) | | `expresion` | neutra · euforia · rabia · angustia · duda · sorna · sueno · asombro, y las de la mesa: enfado · risa · sonrisa · miedo · tristeza · serio · alegria · tension · cansancio · picardia | | `boca` | reposo · a · e · i · o · u · m (b, p) · f (v) · l (d, t) · gol | | `mano_i`, `mano_d` | abierta · puno · senala · aplaude · pinza, o un objeto: microfono · libro · taza · carta · flor · pluma · boton · banderin · silbato · tarjeta_roja… (`registra_objeto_en_mano`) | | `pose` | las comunes (reposo, quieto, celebra_a/b, salta, grita, brazos_arriba, señala, aplaude_1/2, cae, se_levanta, chuta, regate, acodado, sentado, habla_1…4, corre_1…8, anda_1…8) y las propias | | `CICLOS` | corre (8 dibujos), anda (8), habla (6), y los propios | | `ACCIONES` | celebra, salta, grita, aplaude, cae, señala, se levanta, chuta, habla, gesticula, se sienta, gira el dial, y las propias | | `mundo` | §3.3 | | `encuadre` | cuerpo · cabeza (el primer plano de las hojas de caras) | **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`) | clave | qué | obligatoria | |---|---|---| | `nivel` | dibujo · partes · marioneta · personaje | sí | | `nombre` | ASCII, sin espacios: es la semilla y lo que escribe el pliego | sí | | `titulo` | con tildes, para las hojas | no | | `descripcion` | lo que se ve, para quien no lo ve: la usa la capa de sentido (`≈`, `sentido indexa`) y el BESTIARIO.md | sí (≥ 20 caracteres) | | `alto` | su alto natural en la escena | recomendado | | `mira` | derecha · izquierda · frente: para el espejo de los que se enfrentan y el eje | recomendado | | `tintas` | los colores que usa (para los modelos de color) | recomendado | | `registro` | dibujo · foto · recorte · clip · tipografia · materia · escaneo | no | | `partes` | las que trae | nivel ≥ 1 | | `esenciales` | {esencial: parte} | nivel ≥ 1 | `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 …`).