Layout

scene.layout compone la escena con cajas, igual que CSS compone una página con divs: cada caja mide su contenido, reparte el espacio entre sus hijos y los coloca, con padding, gap, borde, radio, sombra y recorte. Las zonas dividen el fotograma en regiones con nombre para colocar objetos que siguen siendo libres. La guía Layout enseña a usarlas paso a paso; esta página es la referencia de cada pieza.

from gaanim import BoxStyle, Scene

scene = Scene(frame=(16, 9), theme="paper", background="#f1f5f9", margin=0.6)
L = scene.layout
L.classes(
    card=BoxStyle(padding="26px", gap="12px", radius="22px", background="white",
                  shadow={"color": "#0f172a22", "y": "-8px", "blur": "26px"}),
    tag=BoxStyle(padding=("4px", "12px"), radius="full", font_size="18px",
                 background="#e0e7ff", color="#3730a3"),
)
article = L.box(
    L.row(L.box("Layout", class_="tag"), L.box("CSS", class_="tag"), gap="8px"),
    L.box("Cajas que se colocan solas", font_size="40px", weight=700),
    L.box("Padding, gap, grids, estilos y zonas: la escena se compone sin coordenadas "
          "y se reorganiza al animar.", font_size="24px", color="#475569", line_spacing=1.4),
    class_="card", max_width="760px",
)
scene.play([article.animate.fade_in().duration(0.6)])
scene.render()

El modelo tiene tres capas, como en CSS:

1. La caja decide el flujo (direction), su tamaño, el espacio interior (padding, gap) y cómo reparte y alinea a sus hijos (justify, align).
2. Cada hijo declara con .item(...) cómo consume la caja que recibe: crecer, alinearse, ocupar celdas, márgenes, ajuste.
3. El contenido se mide dentro de esa caja: el texto recompone sus líneas y las imágenes se ajustan con fit.

Unidades

Todas las propiedades aceptan las mismas unidades:

• Números: unidades de escena (el fotograma por defecto mide 16 × 9).
• "Npx": píxeles de diseño. El fotograma mide design_resolution (1080 por defecto) píxeles de alto, así que "24px" se ve igual en cualquier resolución de salida: Scene(design_resolution=1920) cambia la referencia.
• Tokens del tema: cualquier otro nombre, como "space_md" o "page_padding", se lee de theme.layout.
• Tamaños (width, height, basis): además "N%" del padre, "hug" (o "auto", el tamaño del contenido) y "fill" (el espacio libre).
• Pistas de grid: además "auto" y fracciones "Nfr".
• Relleno y margen: uno, dos, tres o cuatro valores, como el atajo de CSS.

Una unidad desconocida, un tamaño negativo o un valor no finito lanzan ValueError.

Cajas

pill = scene.layout.box("Nuevo", padding=("6px", "16px"), radius="full",
                        background="#4f46e5", color="white", font_size="24px")

tags = scene.layout.row(*[scene.layout.box(t, padding="6px", background="#e0e7ff") for t in
                          ("rust", "gpu", "vello", "taffy", "python")],
                        gap="8px", wrap=True, max_width="300px")

bento = scene.layout.grid(
    scene.layout.box("A", style=cell).item(row_span=2),
    scene.layout.box("B", style=cell).item(column_span=2),
    scene.layout.box("C", style=cell),
    scene.layout.box("D", style=cell),
    columns=["160px", "1fr", "2fr"], gap="12px", within="safe", width="fill",
)

cover = scene.layout.stack(
    photo.item(fit="cover"),
    scene.layout.box("Portada", padding="8px", background="white").item(anchor="bottom_left",
                                                                         offset=("16px", "16px")),
    width="420px", height="260px", radius="16px", clip=True,
)

Propiedades

Las mismas propiedades valen para box, row, column, grid, stack, BoxStyle y Box.set. Un nombre desconocido lanza TypeError.

Contenedor

• direction: "column", "row", "grid" o "stack".
• width, height, min_width, max_width, min_height, max_height, aspect_ratio.
• padding, gap, row_gap, column_gap.
• align (eje transversal): start, center, end, stretch, baseline. justify (eje principal): start, center, end, between, around, evenly.
• wrap (filas y columnas), columns, rows, auto_flow (grids).
• within: solo en la raíz; "safe" (el fotograma menos el margen, por defecto) o "frame" (a sangre).

Hijo (también en Drawable.item)

• grow, shrink, basis: reparto del eje principal. width="fill" en una fila equivale a grow=1. En una caja que se ajusta a su contenido no hay espacio libre que repartir: un hijo que crece mide su contenido aunque tenga basis, y un texto se ajusta al ancho que le deje el padre.
• align_self: alineación propia en el eje transversal (en un grid, la vertical dentro de la celda).
• margin: longitudes o "auto", que se queda con el espacio libre.
• row, column, row_span, column_span: celda en un grid.
• fit: none, contain, cover, stretch, scale_down. cover recorta siempre lo que sale de la celda, sin clip=True, como object-fit: cover en CSS, también si después se mueve la caja.
• anchor, offset: posición en una capa o en su celda.
• absolute: fuera del flujo; no ocupa espacio.

Decoración

• background, border, border_width, radius ("full": píldora), shadow (True o {"color", "x", "y", "blur"}), clip. shadow=True usa el color shadow del tema, que también es el color por defecto del diccionario: negro suave sobre fondos claros y casi opaco sobre fondos oscuros, donde uno suave no se vería.

Tipografía (la heredan las cadenas hijas)

• color, font, font_size, weight, italic, role, text_align, line_spacing, letter_spacing, max_lines, overflow, markup, text_box. markup es False por defecto: $ y * se escriben tal cual.
• text_box elige la caja con que se mide y coloca el texto, como text-box en CSS: "line" (por defecto) ocupa líneas completas, de la ascendente a la descendente, así que textos del mismo estilo comparten altura; "cap" va de la altura de las mayúsculas a la línea base (de un texto de una línea), para que las mayúsculas toquen el borde de la caja como en un diseño calcado; "ink" se ajusta a la tinta de los glifos. Las fórmulas $…$ usan siempre su tinta.

Estilos y clases

pill = BoxStyle(padding=("4px", "12px"), radius="full", background="#4f46e5", color="white")
badge = scene.layout.box("v2", style=pill)

ghost = pill.but(background="#e0e7ff", color="#3730a3")

scene.layout.classes(card=BoxStyle(padding="20px", radius="16px", background="white"))
panel = scene.layout.box("Hola", class_="card")

Reglas por hijo

row = scene.layout.row("Carga", bar.item(grow=1, height="12px"), "72%", gap="16px",
                       align="center", width="fill")

Cajas vivas

Una Box es un Drawable: move_to, scale_by, animate.fade_in() o place actúan sobre la caja entera, y su escala y su giro se aplican a los hijos sobre los suyos, como una transformación CSS. Decide la posición de reposo de sus hijos, que siguen aceptando cualquier animación de .animate: parten de ese sitio, no mueven a sus hermanos y conservan su desplazamiento cuando la caja se reorganiza. Los cambios de estructura se registran en la línea de tiempo; con duration= se animan (los hijos se deslizan, lo que entra aparece con un fundido y lo que sale se desvanece) y avanzan el cursor como scene.play. Con advance=False el siguiente cambio empieza a la vez.

board.add(scene.layout.box("Nueva", style=chip), at=1, duration=0.6)
board.remove(board[3], duration=0.6)
board.replace(board[0], scene.layout.box("Otra", style=chip), duration=0.6)

grid.set(columns=2, gap="30px", duration=0.8)

for piece in card.walk():
    scene.play(piece.animate.fade_in().duration(0.1))
scene.render()

scene.play(card.stagger(lambda piece: piece.animate.fade_in(), each=0.08))
scene.render()

title = card.find(text="Título")
letters = card.find_all(type=Text, where=lambda piece: piece is not title)
scene.play(title.animate.fade_in())
scene.render()

card.each(lambda piece: piece.fill("#0f172a"), type=Text)
scene.render()

scene.play(card.reveal())
scene.render()

scene.play(card.cascade(each=0.08).fade_in())
scene.render()

row.move_child(row[2], 0, duration=0.6)
row.swap(row[0], row[2], duration=0.6)
row.reverse(duration=0.6)
scene.render()

Zonas

Las zonas dividen una región en rectángulos con nombre. No adoptan objetos: colocan una vez (o animan) objetos que siguen siendo libres, así que una misma plantilla sirve para el fotograma, para una zona o para el interior de un objeto.

page = Zones.rows(["90px", "1fr", "60px"], names=["cabecera", "cuerpo", "pie"], gap="16px")
split = Zones.columns(["1fr", "2fr"], names=["lateral", "principal"], gap="24px")

z = scene.layout.zones(page)
title = scene.text("Título", size=0.5).place(z["cabecera"], anchor="left")

dots = [scene.geometry.circle(0.3) for _ in range(4)]
scene.layout.safe.inset("80px").arrange(*dots, gap="24px")

logo = scene.geometry.circle(1).place(zone, anchor="top_right", fit="contain", padding="20px")
scene.play([logo.animate.place(zone, anchor="bottom_left").duration(0.8)])

MÉTODOLayoutBuilder.scatterscatter(items, region=None, *, avoid=(), gap=None, seed=0) -> None

Coloca los objetos en posiciones aleatorias deterministas, dentro de region y sin solaparse entre sí ni con avoid. Los más grandes se colocan primero y cada uno va donde tiene más sitio, así se reparten por toda la región. Si no caben (un objeto mayor que la región, o sin hueco con ese gap), lanza ValueError y no mueve nada.

Parámetros

Nombre	Tipo	Predeterminado	Descripción
items	Sequence[Drawable]	obligatorio	Los objetos que se reparten. Conservan su tamaño; solo se mueven, sin quedar adoptados.
region	"safe" | "frame" | Zone | Drawable | None	None	Dónde caben: el área segura por defecto, el encuadre, una zona o la caja de un objeto.
avoid	Sequence[Drawable | Zone]	()	Formas que hay que dejar libres, por su caja. Para no tapar una figura sin vaciar toda su caja, evita sus partes: avoid=[persona.part("cabeza"), ...].
gap	Length | None	0.2	Separación mínima entre objetos y respecto a cada forma de avoid.
seed	int	0	Semilla: la misma semilla da siempre el mismo reparto.

Ejemplo

from gaanim import WHITE, Scene, stagger

scene = Scene(frame=(16, 9), background="#0f172a")
persona = scene.media.svg("assets/personaje.svg").scale_to(2.0)
partes = [persona.part(p) for p in ("cabeza", "torso", "piernas", "brazo-izq", "brazo-der")]
formulas = [
    scene.text.equation(f).fill(WHITE).scale_to(0.75)
    for f in ["E = m c^2", "F = m a", "pi r^2", "sqrt(2)", "e^(i pi) + 1 = 0",
              "a^2 + b^2 = c^2", "Delta x", "nabla dot E", "x!", "lambda", "oo", "phi"]
]
scene.layout.scatter(formulas, avoid=partes, gap=0.25, seed=1)
scene.play([persona.animate.fade_in().duration(0.4)])
scene.play(stagger(*[f.animate.write().duration(0.6) for f in formulas], each=0.05))
scene.render()

Componentes

component convierte una función (scene, *, huecos...) -> Box en un componente reutilizable: comprueba sus argumentos con la firma (un hueco que falta o sobra lanza TypeError con el nombre del componente), expone slots y conserva los tipos para el editor. Cada llamada crea objetos nuevos. Las plantillas de presentación title_slide, lecture, comparison, vertical_short, minimal, lower_third y credits son componentes y se usan también con scene.segment(..., template=...) y Segment.bind (ver Escena).

from gaanim import Scene, component

scene = Scene(frame=(16, 9), theme="paper")

@component
def tag(scene, *, text: str, color: str = "#4f46e5"):
    return scene.layout.box(text, padding=("4px", "12px"), radius="full",
                            background=color, color="white")

row = scene.layout.row(tag(scene, text="Nuevo"), tag(scene, text="Beta", color="#0891b2"), gap="8px")

Las plantillas incluidas usan tokens de espaciado del tema. Léelos con scene.canvas.layout_token(name) y cámbialos con Theme(..., layout={"page_padding": 0.7, "column_gap": 0.6}).

Restricciones lineales

Relaciones entre la geometría de ramas distintas del árbol, como alinear una etiqueta externa con el centro de un gráfico. Cada objeto expone las expresiones left, right, top, bottom, center_x, center_y, width y height. Complementan a las cajas: para una cuadrícula, usa grid.

relations = scene.layout.constrain(
    (label.left == chart.right + 0.3).strong(),
    label.center_y == chart.center_y,
    (label.width <= page.width * 0.30).weak().named("etiqueta estrecha"),
)

for message in scene.layout.check_layout():
    print(message)

Errores frecuentes

• Mover un hijo con move_to(). Expresa la intención con align, justify, margin, anchor u offset, o usa una zona si el objeto debe ser libre.
• Poner "fill" en todos los niveles. Decide qué caja es dueña del espacio y deja que el resto use su tamaño natural.
• Confundir align con justify. Identifica primero el eje principal: en una fila es horizontal y en una columna, vertical.
• Medidas en unidades de escena para UI. "24px" y los tokens del tema mantienen la proporción en cualquier formato; los números sirven para geometría con significado.
• Construir una cuadrícula con restricciones. Usa grid y reserva las restricciones para relaciones entre ramas.