MBehtemam/montagent-skills

Pre-renderizado: imágenes generadas y metraje estabilizado

Cinco rutas, un conjunto de reglas comunes. Una pieza dibujada por código se convierte en metraje, colocado como un video: léalo primero. Una imagen SVG estática se convierte en un solo PNG, colocado como una image: salte a la ruta SVG. Una animación Lottie también se convierte en metraje, dibujando un reproductor fresco por cada fotograma: salte a la ruta Lottie. Una escena 3D se convierte en metraje transparente o un PNG estático: salte a la ruta de escena 3D. La estabilización de video fuente hornea un nuevo clip: salte a la ruta de estabilización. Todas se ejecutan fuera del render, por lo que cada pintor decodifica los mismos píxeles.

Montagent no tiene archivos de shader o script (ADR-0017). Un efecto fuera de la lista effects se dibuja en su propio código, se codifica una vez como metraje y se coloca como un video normal. El formato, el esquema y el pintor se mantienen como están (ADR-0156 §7, ADR-0233).

Cuándo usarlo

Tome la ruta nombrada primero. Lea la lista effects en montagent://schema/index.json: cuando un miembro compone el efecto (desenfoque, sombra, tinte, un blend, una mask con clave), úselo. Pre-renderice solo cuando ningún miembro, pintura o mezcla componga el efecto: distorsiones, mosaico, destello de lente, partículas, un patrón procedural, o un modelo/escena 3D externa.

Recurra a la ruta SVG cuando tenga un dibujo vectorial (un logotipo, un icono, una ilustración) como archivo SVG, o cuando una imagen estática sea más fácil de dibujar como SVG. Ningún elemento acepta un archivo SVG (ADR-0171). Un SVG que se anima (SMIL o CSS) no es de esta ruta: rasteriza como un solo fotograma estático y el movimiento se pierde. En su lugar, clave el scale, rotation y opacity propios de la imagen colocada.

Recurra a la ruta de escena 3D cuando tenga un activo 3D (.glb, .gltf, .obj, .fbx, .blend, .c4d) o una escena 3D. Ningún elemento acepta un modelo 3D o pase multicanal (ADR-0167, ADR-0233). El renderizado sin cabeza produce metraje ProRes 4444 / PNG transparente fuera del render, listo para la colocación 2D directa.

Recurra a la ruta Lottie cuando tenga un archivo Lottie JSON (una exportación de After Effects, una animación de LottieFiles), o cuando un movimiento sea más fácil de tomar de uno. Ningún elemento acepta un archivo Lottie (ADR-0171). Cuesta tres cosas. Una resolución fija: el metraje es raster al tamaño en que lo renderice. Una cadena de herramientas de receta: un reproductor Lottie instalado para reproducir la pieza (nunca para renderizar el proyecto). Tamaño del metraje: PNG en un MOV va desde aproximadamente 6 MB por segundo para arte suave hasta 141 MB por segundo para arte con ruido, a 1080p y 25 fps, así que renderice al tamaño mostrado y no más grande. Si el movimiento son algunas formas, clave los elementos rect, ellipse y path nativos es más pequeño y se mantiene nítido.

Una pieza pre-renderizada es metraje fijo. Su tamaño, fps y duración se establecen cuando la renderiza. Cambiar el efecto significa renderizar de nuevo, así que primero fije el tamaño, fps y duración del brief, y haga coincidir el fps del proyecto.

Reglas comunes

Cada ruta las lee. Están escritas una vez.

• Tamaño. Rasterice o dibuje al tamaño más grande en que la pieza se muestre, después de fit, scale y cualquier zoom con clave, como width y height literales en píxeles. Nunca lo derive del viewBox de un SVG: un viewBox establece las proporciones del dibujo, no sus píxeles, y las herramientas discrepan sobre un archivo sin él. Escriba el tamaño en la receta. Un zoom posterior que lo supere remuestrea un raster, así que re-ejecute la receta más grande en lugar de escalar hacia arriba.
• Texto. Solo fuentes incluidas, o texto convertido a contornos. Nunca una fuente del sistema: una máquina sin ella dibuja otra cosa. Una fuente que no se puede encontrar es un fallo de compilación, no un intervalo omitido. usvg, por ejemplo, registra la falta y omite el texto, así que build lee los valores font-family del SVG contra los archivos de fuente que usted liste en fonts, y falla también en la propia advertencia de fuente del rasterizador.
• Receta. Copia de la fuente, comandos exactos, versiones de herramientas, tamaño y un hash de los píxeles decodificados, tomados a través de la misma lectura que usa el decodificador. La reconstrucción informa una coincidencia o la primera diferencia, y nunca compara bytes de archivo. La receta dice dónde vive.

Los pasos

Ejecute cada paso, en orden. La pieza está colocada cuando el paso 5 pase.

1. Dibujar. Escriba código, en cualquier herramienta, que produzca fotogramas RGBA de un width, height y un conteo frames fijos: transparente donde no se dibuje nada. Escribe RGBA sin procesar a stdout, o archivos PNG f00000.png, f00001.png y así sucesivamente en la carpeta nombrada por PRERENDER_FRAMES_DIR. Lea su tamaño de PRERENDER_WIDTH, PRERENDER_HEIGHT, PRERENDER_FPS y PRERENDER_FRAMES. Use aritmética de enteros o una semilla fija, para que una segunda ejecución dibuje los mismos bytes. La pieza de ejemplo es la más pequeña que funciona.
2. Especificar. Escriba una especificación de compilación junto al código: name, out (la carpeta de medios del proyecto), width, height, fps, frames, render (el argv que ejecuta su código), files (cada archivo que el código necesita), e input de "png" cuando escriba PNGs. Ejecute python3 scripts/prerender.py --help para cada clave. Agregue versions para cualquier biblioteca cuya versión cambie los píxeles (una biblioteca de canvas, un navegador sin cabeza).
3. Compilar. python3 scripts/prerender.py build <spec>. Ejecuta el código, codifica un <name>.mov, lo decodifica y falla en el primer fotograma que difiera de lo que su código dibujó. Lea su última línea: N frames, decoded = drawn.
4. Colocar. Agregue el metraje al proyecto como un elemento video simple (abajo), o ejecute python3 scripts/prerender.py place <project> <placing>, donde <placing> es un archivo JSON {"source": "media/<name>.mov"} más cualquiera de id, at, x, y, origin, width, height, fit, track, layer. Imprime el proyecto con el elemento agregado, así que redirija eso a un nuevo archivo.
5. Verificar. validate el proyecto y corrija cada error. Luego montagent probe el metraje y confirme que informa alfa (carries: true). Solo entonces frame un mosaico donde la pieza esté activa y verifique que las partes transparentes muestren lo que está detrás.

{
  "frame": {"width": 640, "height": 360}, "fps": 25, "background": "#101418", "duration": 480, "output": "out/pulse.mp4",
  "tracks": [
    {"name": "prerender", "layer": 10, "elements": [
      {"id": "pulse", "type": "video", "start": 0, "end": 480, "source": "media/pulse.mov", "source_start": 0, "source_end": 480, "volume": 0, "x": 320, "y": 180, "origin": "center", "width": 320, "height": 240, "fit": "contain"}
    ]}
  ]
}

El elemento es un video normal: clave opacity, scale y position, agregue effects y un blend, y colóquelo en una pista como cualquier clip. El metraje no tiene sonido, así que volume es 0. Su end menos start es la duración del metraje; source_end es la misma duración.

La ruta SVG

Entrada: un archivo SVG, y el tamaño en píxeles de las reglas comunes.

1. Incluya las fuentes que usa el texto del SVG, con montagent fonts vendor, y establezca cada <text> en esa familia con un atributo font-family. O convierta el texto a contornos en su herramienta de dibujo y no use ninguna fuente.
2. Especificar. Escriba una especificación de compilación junto al SVG con "input": "svg": name, out, svg, el width y height literales, render (el argv del rasterizador, con {width}, {height} y {out} donde vayan), files, fonts y versions. No hay fps ni conteo de fotogramas.
3. Rasterizar. python3 scripts/prerender.py build <spec> ejecuta el rasterizador una vez, fuera del render. Cualquier herramienta que escriba un solo PNG RGBA servirá: la línea de comandos resvg, un navegador sin cabeza, Inkscape. Omita las fuentes del sistema y entréguele las incluidas, como en la especificación a continuación. Escribe <name>.png y su receta, y falla en una fuente faltante.
4. Colocar el PNG como un elemento image simple (abajo), o ejecute python3 scripts/prerender.py place <project> <placing> con {"source": "media/<name>.png", "duration": <ms>} más cualquiera de id, at, x, y, origin, width, height, fit, track, layer.
5. Verificar. Ejecute validate y corrija cada error, luego frame un mosaico donde la imagen esté activa y verifique que las partes transparentes muestren lo que está detrás.

La especificación de ejemplo, para el SVG de ejemplo (formas, un degradado y texto configurado en una fuente incluida), rasterizado a tres veces su viewBox:

{
  "name": "mark", "out": "media", "input": "svg", "svg": "sample_art.svg", "width": 480, "height": 270,
  "render": ["resvg", "--skip-system-fonts", "--use-font-file", "Inter-Bold.ttf", "-w", "{width}", "-h", "{height}", "sample_art.svg", "{out}"],
  "files": ["sample_art.svg"], "fonts": ["Inter-Bold.ttf"],
  "versions": {"resvg": ["resvg", "--version"]}
}

El PNG tiene dimensiones de píxeles intrínsecas, por lo que entra como una image normal, y las reglas fit de ADR-0015 se aplican como para cualquier PNG: contain con la relación de aspecto propia del cuadro, o literal. Colocarlo a su propio tamaño, con fit de contain, es un dibujo 1:1. Muéstrelo más grande que el tamaño al que lo rasterizó y el raster se remuestrea: ejecute la receta de nuevo al tamaño más grande.

{
  "frame": {"width": 640, "height": 360}, "fps": 25, "background": "#101418", "duration": 2000, "output": "out/mark.mp4",
  "tracks": [
    {"name": "art", "layer": 10, "elements": [
      {"id": "mark", "type": "image", "start": 0, "end": 2000, "source": "media/mark.png", "x": 320, "y": 180, "origin": "center", "width": 480, "height": 270, "fit": "contain"}
    ]}
  ]
}

Ejecute validate. La imagen es una normal: clave opacity, scale y position, agregue effects, colóquela en una pista.

La ruta Lottie

Entrada: un archivo Lottie JSON, un tamaño, un fps y un rango de fotogramas. Los propios w, h y fr del Lottie son entradas para elegir, no reglas: el tamaño sigue las reglas comunes (el tamaño más grande mostrado, como literales), y usted escribe el fps y el conteo de fotogramas en la especificación.

1. Elija un reproductor que pueda escribir fotogramas RGBA, y registre su nombre y versión en versions. El skill no elige uno: el pre-renderizado se ejecuta una vez fuera del render y los pintores nunca ven el reproductor. El reproductor de ejemplo es ThorVG a través de pip install thorvg-python==1.1.3.
2. Especificar. Escriba una especificación de compilación junto al Lottie con "input": "lottie": name, out, lottie, el width y height literales, fps, frames, render, files, fonts y versions. render es el argv del reproductor, con {width}, {height}, {frame} y {out} donde vayan: dibuja un fotograma como RGBA sin procesar en {out}. Opcionalmente, start y step establecen qué fotograma del Lottie corresponde a cada fotograma del metraje (el fotograma i es start + i * step; step por defecto es el fr del Lottie dividido por fps). Ejecute python3 scripts/prerender.py --help para cada clave.
3. Compilar. python3 scripts/prerender.py build <spec> primero lee el Lottie y lo rechaza, nombrando cada caso, si usa una expresión, un efecto de capa que el reproductor no esté registrado para dibujar (liste aquellos que sí lo estén en allow_effects), o texto cuya fuente no tenga ni rutas de glifo incrustadas ni un archivo incluido en fonts. Un reproductor omite todos estos sin sonido, por lo que una compilación que continuara enviaría una animación diferente. Luego ejecuta render una vez por fotograma, un nuevo proceso cada vez, lee el propio informe del reproductor sobre lo que omitió (cualquier línea que diga omitido (skipped), ignorado (ignored) o no soportado (unsupported) es un fallo de compilación: trátelo como tal), codifica un <name>.mov como el codec dice, y falla en el primer fotograma que difiera de lo que el reproductor dibujó.
4. Colocar el metraje como un elemento video normal, o con place como en los pasos. Ejecute validate y montagent probe el MOV: confirme que informa alfa (carries: true). Luego frame un mosaico donde la pieza esté activa y verifique que las partes transparentes muestren lo que está detrás.

Por qué un reproductor fresco por fotograma. El armazón nunca busca avanzar un reproductor. ThorVG ignora un cambio de fotograma por debajo de 0.001, por lo que dónde aterriza una búsqueda depende de la búsqueda anterior, y la búsqueda de Skottie muta su objeto de animación. Un fotograma dibujado después de otros puede diferir del mismo fotograma dibujado primero, y la reconstrucción no coincidiría.

...

[truncado para traducción]