Recursos
Carpeta de recursos, precarga y recarga, y qué admiten los importadores de SVG y Lottie
Imágenes, SVG, vídeo, audio, Lottie, WGSL y archivos Typst se cargan desde rutas locales. Las fábricas que los crean están en Medios y Audio esta página explica cómo se resuelven las rutas, cómo precargar y recargar archivos, y qué partes de cada formato se importan.
from gaanim import Scene
scene = Scene(frame=(16, 9), background="#0f172a")
scene.assets.load_project() # usa assets_dir del gaanim.toml del proyecto
logo = scene.media.svg("logo.svg")
cover = scene.media.image("cover.png")
pulse = scene.media.lottie("pulse.json")Una ruta relativa se resuelve desde la carpeta de recursos de la escena. Sin ella, se busca en el directorio de trabajo del proceso, después en la carpeta assets/ junto al script que creó la escena y por último en la carpeta del script, así que scene.media.svg("logo.svg") encuentra assets/logo.svg sin configurar nada. Una ruta absoluta se usa tal cual. Todas las fábricas usan archivos locales: no descargan URLs ni aceptan bytes o arrays.
Carpeta de recursos
assets_dir del manifiesto ("assets" si falta, como en la CLI) y la resuelve respecto de la carpeta del manifiesto, así que funciona igual se lance Gaanim desde donde se lance. Una ruta explícita relativa, en cambio, se resuelve desde el directorio de trabajo del proceso; sin argumento se busca el gaanim.toml en la carpeta del script que llama y después en sus carpetas superiores, así que un módulo como capitulo4/estilo.py usa el manifiesto del proyecto. Si no hay ninguno, lanza RuntimeError con la carpeta de partida. Es la forma recomendada en un proyecto. Un manifiesto ilegible lanza RuntimeError; un assets_dir que no es una cadena entre comillas o que apunta a una carpeta inexistente, ValueError. Consulta gaanim.toml.| Nombre | Tipo | Predeterminado | Descripción |
|---|---|---|---|
path | str | None | None | Ruta del manifiesto; sin ella, el gaanim.toml más cercano, buscando desde la carpeta del script que llama hacia arriba. |
None — Fija la carpeta de recursos.scene = Scene(frame=(16, 9), background="#0f172a")
scene.assets.load_project()
scene.assets.load_project("gaanim.toml") # ruta explícitaload_project() o construye la ruta desde __file__. Una carpeta inexistente lanza ValueError.| Nombre | Tipo | Predeterminado | Descripción |
|---|---|---|---|
path | str | obligatorio | Carpeta existente. |
None — Fija la carpeta de recursos.from pathlib import Path
scene = Scene(frame=(16, 9), background="#0f172a")
scene.assets.assets_dir(str(Path(__file__).parent / "assets"))
hero = scene.media.image("cover.png", width=8).lottie antes de reproducir la escena. Las imágenes se decodifican en la misma caché que usa scene.media.image, y las composiciones Lottie en la de scene.media.lottie; de un paquete dotLottie se precarga su animación o máquina de estados inicial. Un archivo que no se puede resolver o decodificar lanza RuntimeError con su ruta.| Nombre | Tipo | Predeterminado | Descripción |
|---|---|---|---|
paths | Sequence[str] | obligatorio | Rutas que se validan, relativas a la carpeta de recursos. |
None — Valida y guarda en caché los archivos.scene.assets.preload(["logo.svg", "cover.png", "pulse.json", "button.lottie"])scene.media.svg(...) crea un objeto.None — Vacía las cachés de archivos.scene.assets.reload_assets()
cover = scene.media.image("cover.png")Para crear un proyecto con esta estructura, usa gaanim init.
Lottie JSON y dotLottie
scene.media.lottie acepta archivos Lottie JSON y paquetes .lottie v1 y v2, y los dibuja como vectores con Velato dentro de la misma escena. La reproducción sigue el tiempo absoluto de la escena, también al saltar hacia atrás. Las opciones de la fábrica y los métodos set_theme, set_input, fire_event, warnings y los identificadores del paquete están en Medios.
int — Ancho de la composición original, en sus unidades.int — Alto de la composición original.float — Fotogramas por segundo de la composición.float — Duración de la composición, en segundos.200 200 30.0 2.0Qué se importa. Formas vectoriales, transformaciones, rellenos, trazos y máscaras. Las capas sólidas se dibujan con su color y tamaño, también dentro de precomposiciones. Las imágenes externas (como las que exporta Cavalry) se resuelven respecto del archivo JSON, incluida su carpeta images/, y conservan el orden de capa, las transformaciones, la opacidad, el tiempo local de la precomposición y las máscaras simples. Los gradientes lineales y radiales conservan sus paradas de color y de opacidad, estáticas o animadas. Una transformación que omite posición o escala usa traslación cero y escala del 100 %, y las posiciones X/Y separadas se reproducen. El texto, las imágenes incrustadas y los efectos pueden omitirse o aproximarse: consulta clip.warnings. Si Velato encuentra algo que no puede convertir con seguridad, la carga lanza un error en lugar de cerrar el proceso.
Paquetes .lottie. Se leen en memoria, incluidas sus imágenes PNG, JPEG y WebP; no se extraen al disco ni se buscan recursos fuera del ZIP. La caché comparte recursos entre clips, pero cada clip tiene sus propias entradas y órdenes. animation_id y state_machine_id son excluyentes; sin ninguno se usa el contenido inicial del manifiesto o, si no hay, la primera animación. Los controles de reproducción del manifiesto v1 no se aplican: se usan los de Gaanim.
Máquinas de estados. Activar una máquina no alarga la escena: usa scene.wait u otras animaciones. El estado controla velocidad, dirección, bucles, segmento por marcador y fondo, así que offset, duration, loop y speed deben quedarse en sus valores predeterminados. Un estado final detiene las transiciones y un marcador ausente usa la animación completa. Se admiten PlaybackState, GlobalState, transiciones inmediatas y condiciones numéricas, booleanas, de cadena y de evento; los temas admiten valores estáticos de color, escalar, posición, vector y gradiente. No se admiten acciones, interacciones de ratón, entradas automáticas reservadas, transiciones suavizadas, temas con keyframes o expresiones, ni sustituciones temáticas de imágenes o texto: seleccionar un tema o una máquina que los use lanza ValueError, y el resto del paquete sigue disponible. Los ciclos de transiciones instantáneas también se rechazan.
clip = scene.media.lottie("assets/button.lottie", state_machine_id="main", width=4)
clip.set_input("active", False)
scene.play([clip])
scene.wait(1)
clip.set_input("active", True).set_theme("gold")
scene.wait(1)
clip.fire_event("reset").set_theme(None)
scene.wait(1)write y create presentan el primer fotograma trazando los contornos en paralelo y fundiendo después los rellenos y las imágenes; no inician la animación interna. Encadena el clip después para reproducirlo:
from gaanim import Scene, sequence
scene = Scene(frame=(16, 9), background="#0f172a")
clip = scene.media.lottie("assets/pulse.json")
scene.play(sequence(clip.animate.create().duration(1.0), clip))
scene.render()SVG
scene.media.svg(path) conserva el documento como geometría vectorial: una jerarquía real de caminos y grupos a la que se llega con part(id). Por eso un SVG sirve también como máscara o como operando de operaciones booleanas. Se importa a 100 píxeles del documento por unidad lógica, centrado en el origen: un SVG de 300 px de ancho mide 3 unidades, y scale_to(factor) lo agranda o lo reduce (consulta MediaLibrary.svg).
Qué se importa. Grupos anidados, CSS, transformaciones, viewBox y <use>; rellenos y trazos sólidos, lineales y radiales con sus modos de extensión; geometría clipPath, sin rasterizar el documento; texto convertido en contornos con las fuentes instaladas; y los filtros feGaussianBlur y feDropShadow, como efectos vectoriales de Gaanim.
Qué no. Patrones de pintura, máscaras <mask> de alfa o luminancia, imágenes ráster incrustadas y grafos de filtros arbitrarios. Para una máscara, usa una silueta vectorial explícita. Para que el texto salga igual en cualquier equipo, instala la fuente en cada máquina que renderiza o convierte el texto en caminos en el SVG de origen.
Los identificadores de las partes distinguen mayúsculas; un identificador repetido en el archivo falla al importar y uno desconocido lanza KeyError con los nombres disponibles. El grosor aplicado al objeto raíz con stroke(...) está en unidades lógicas de escena y no cambia al escalar el SVG con scale_to; los trazos propios del archivo sí escalan con él.
diagram = scene.media.svg("assets/architecture.svg")
scene.play(diagram.part("database").animate.indicate().duration(0.6))