Escena

Scene es el punto de entrada de toda animación: crea los objetos, programa la línea de tiempo, organiza los segmentos y entrega el resultado al ejecutable de Gaanim. Cada script crea una escena, la llena y termina con scene.render().

from gaanim import BLUE, Scene

scene = Scene(frame=(16, 9), background="#0f172a")
dot = scene.geometry.circle(0.6).fill(BLUE)
scene.play([dot.animate.create().duration(0.8)])
scene.wait(0.5)
scene.render()

Esta página documenta la escena, su lienzo (scene.canvas), su cámara (scene.camera) y las secciones. Los métodos comunes de los objetos están en Drawable, las animaciones en Animaciones y los temas en Temas y colores. Para ejecutar, validar y exportar un script, consulta la línea de comandos.

Constructor

from gaanim import Scene

scene = Scene(frame=(16, 9), background="#0f172a", margin=0.5, theme="presentation")
print(scene.canvas.frame_width, scene.canvas.safe_width)  # 16.0 15.0

16.0 15.0

Sin theme, la escena usa el tema technical: fondo gris casi negro (#121212), texto y ejes claros y formas rellenas con el color de acento. Un background explícito gana al fondo del tema, y los colores de cada objeto ganan a los del tema. theme=None deja un lienzo sin tema: fondo blanco (si no pasas background) y objetos sin estilo también blancos, así que tendrás que darles color. Consulta Canvas.set_theme.

Capacidades

Las fábricas viven en handles que pertenecen a la escena. Un objeto de una escena no puede usarse en otra: pasarlo lanza ValueError.

shape = scene.geometry.circle(1)
title = scene.text("Resultado", role="title")
page = scene.layout.column([title, shape])
value = scene.viz.parameter(0.0)

dot.move_to(computed(lambda t: -4 + t, inputs=[scene.time]), 0)
scene.wait(3)

Las narraciones (Scene.voiceover, Scene.narration_script y Scene.live_take) están en Audio.

Marco lógico y área segura

El marco es el rectángulo que se ve, en unidades lógicas y centrado en el origen: con el predeterminado de 16 × 9, x va de -8 a 8 e y de -4.5 a 4.5. El área segura es el marco menos los márgenes; la usan el layout (within="safe") y las colocaciones en bordes y esquinas.

scene.canvas.set_margin(0.4)
print(scene.canvas.safe_width, scene.canvas.safe_height)  # 15.2 8.2

15.2 8.2

scene.canvas.set_safe_area(top=0.5, bottom=1.0)
print(scene.canvas.safe_height)  # 7.5

7.5

scene.canvas.set_preset("vertical")
page = scene.layout.column([scene.text("Vídeo vertical", role="title")], within="safe")

Línea de tiempo

Cada llamada a play o wait avanza el cursor de autoría. Las animaciones de una misma lista empiezan juntas; llamadas sucesivas van una detrás de otra. scene.launch(...) (o play(..., advance=False)) empieza en el cursor sin moverlo, para una animación larga que sigue mientras programas lo demás.

from gaanim import BLUE, GOLD, Easing, Scene

scene = Scene(frame=(16, 9), theme="technical")
circle = scene.geometry.circle(0.8).fill(BLUE).move_to(-1.6, 0)
rect = scene.geometry.rect(1.8, 1.0).fill(GOLD).move_to(1.6, 0)
scene.play([circle.animate.create(), rect.animate.grow_from_center()], duration=0.8)
scene.play(circle.animate.shift_by(1.2, 0), easing=Easing.SNAPPY)
scene.render()

import math
rueda = scene.geometry.regular_polygon(6, 1.5).fill("#38bdf8")
puntos = [scene.geometry.dot(0.2).move_to(x, -3) for x in (-4, -2, 0, 2, 4)]
scene.launch(rueda.animate.rotate_by(math.tau).duration(5.0))
for punto in puntos:
    scene.play(punto.animate.fade_in().duration(1.0))

scene.tempo(128, offset=0.0)
logo = scene.geometry.star(5, 1.2, 0.5).fill("#fbbf24")
scene.play(logo.animate.grow_from_center().duration(scene.beats(2)))
scene.wait_until(bar=1)
scene.play(logo.animate.rotate_by(1.0).duration(scene.beats(4)))
scene.wait_until(bar=2)

scene.wait(1.0)

from gaanim import Scene

scene = Scene(frame=(16, 9), theme="technical")
title = scene.text("Fin", role="title")
scene.play(title.animate.write())
scene.fade_out_all(0.6)
scene.render()

scene.play([title.animate.write().duration(0.8)])
reveal_time = scene.cursor  # 0.8

scene.play(intro)
scene.marker("climax")
scene.play(outro)
scene.marker("fin")

gaanim export escena.py --output climax.mp4 --from climax --to fin

scene.wait(1.5)
scene.marker("climax")
print([(m.name, m.time) for m in scene.markers])  # [('climax', 1.5)]

[('climax', 1.5)]

Segmentos

Un segmento es la unidad estructural de la escena: agrupa objetos, define la transición de entrada, las notas para Presenter View, la plantilla y un fondo propio. Los límites entre segmentos son continuos; stop() marca dónde la reproducción interactiva espera al presentador.

intro = scene.segment("Introducción", notes="Presenta el objetivo.", template=title_slide)
intro.bind(title=scene.text("Una idea clara", role="title"))
scene.wait(0.5)
details = scene.segment(
    "Detalles",
    Transition.cross_fade(0.4),
    background=Brush.linear(["#172554", "#0f172a"], start=(-8, 0), end=(8, 0)),
)
scene.wait(0.5)

results = scene.segment("Resultados", template=comparison, notes="Compara los dos modelos.")
results.bind(title=scene.text("Resultados", role="title"), left=baseline, right=proposed)
scene.stop("comparación")

scene.canvas.motion_blur(180)
scene.segment("normal")
scene.wait(1)
scene.segment("amplio").motion_blur(360, samples=16)
scene.wait(1)
scene.segment("nítido").motion_blur(None)
scene.wait(1)

overview = scene.segment("Resumen")
card = scene.geometry.rect(3, 2).fill(BLUE).move_to(-4, 0)
scene.wait(0.5)
detail = scene.segment("Detalle")
panel = scene.geometry.rect(12, 6).fill(BLUE)
scene.wait(0.5)
scene.link(overview, detail, Transition.morph(0.8, pairs=[(card, panel)]))

scene.play([result.animate.write().duration(0.6)])
scene.stop("resultado")
scene.wait(0.5)
# Las flechas siguen moviéndose mientras se explica la pausa.
scene.stop("dos-placas", loop=sequence(
    arrow.animate.shift_by(0.5, 0).duration(0.75),
    arrow.animate.shift_by(-0.5, 0).duration(0.75),
))

scene.rehearsal(24, seed=3, skill=0.7)
audience = scene.audience()

>>>from gaanim import *
>>>scene = Scene(frame=(16, 9))
for q in load_questions("preguntas.md"):
    poll = scene.question(q)

scene.roster("Código de alumno")
audience = scene.audience()

teams = scene.teams(["Rojo", "Azul"])
for team, x in [(0, -4), (1, 4)]:
    scene.viz.readout(teams.score(team), format=".0f").move_to(x, 0)

poll = scene.poll("¿Qué crece más rápido?", ["x²", "2ˣ"], rehearse=[1, 2])
card = scene.geometry.rounded_rect(3.4, 3.4, 0.2).fill(WHITE).no_stroke().move_to(-4, 0)
qr = poll.qr(3.0).move_to(-4, 0)
bar = poll.bar(1, length=6).fill(GOLD).no_stroke().move_to(2, 0)
votes = scene.viz.readout(poll.votes(1), format=".0f").move_to(5.6, 0)
scene.stop()

quiz = scene.quiz("¿Derivada de x²?", ["x", "2x", "x²/2"], correct=1, time=20, rehearse=0.6)
clock = scene.viz.readout(quiz.remaining(), format=".0f").move_to(-5, 3)
scene.wait(1)
scene.stop()
quiz.reveal()
scene.wait(1)
scene.stop()

board = scene.leaderboard()
for rank in range(2):
    board.name(rank, size=0.5).move_to(-3, 1 - rank)
    scene.viz.readout(board.points(rank), format=".0f").move_to(3, 1 - rank)

from gaanim.live import pose
audience = scene.audience()

def en_fila(p):
    return pose(-6 + p.index * 1.2, -3, express="happy")

zone = scene.live_zone(audience, en_fila, names=True)

hero = scene.character([1, 0, 4, 2, 1], name="Ana").move_to(-3, 0)
scene.wait(1)
hero.express("winner", loop=True)
scene.wait(2)

audience = scene.audience()
for slot in range(6):
    audience.name(slot, size=0.4).move_to((slot - 2.5) * 2, 0)

if snapshots := os.environ.get("GAANIM_SNAPSHOTS"):
    scene.snapshots(snapshots, [stop.time for stop in scene.stops])

Al empezar un segmento, los objetos de los anteriores dejan de verse. Estos tres métodos cambian a qué segmento pertenece un objeto, en el cursor actual y sin alterar su estado visual. Un objeto de otra escena lanza ValueError.

scene.z_layers("fondo", "contenido", "overlay", default="contenido")
rejilla = scene.geometry.rect(14, 8).fill(GRAY).z_layer("fondo")
cursor = scene.geometry.dot(0.1).fill(GOLD).z_layer("overlay")

MÉTODOScene.releaserelease(object: Drawable, *others: Drawable) -> None

Termina la persistencia y devuelve los objetos al segmento activo. Al inicio de un segmento, el objeto queda quieto durante la transición de entrada y después pasa a ser local. Nunca oculta ni elimina el objeto: la siguiente transición lo trata como contenido saliente normal.

Parámetros

Nombre	Tipo	Predeterminado	Descripción
object	Drawable	obligatorio	Primer objeto.
others	Drawable	()	Más objetos de la misma escena.

Devuelve: None

Ejemplo

from gaanim import BLUE, GOLD, Scene, Transition

scene = Scene(frame=(16, 9), background="#0f172a")
title = scene.text("Contexto compartido", role="title").fill(GOLD).move_to(0, 0.875)
scene.play([title.animate.write().duration(0.5)])

scene.segment("contenido", Transition.cross_fade(0.35))
scene.reuse(title)
dot = scene.geometry.dot(0.225).fill(BLUE).move_to(0, -0.375)
scene.play([dot.animate.grow_from_center().duration(0.4)])
scene.persist(title)

scene.segment("cierre", Transition.slide(0.35, "left"))
scene.release(title)
scene.wait(0.5)
scene.render()

La identidad de una presentación (logo, pie, número de diapositiva) se configura una vez con scene.slides.brand(...); consulta Presentaciones.

Secciones

Section agrupa pasos de contenido que se construyen con funciones de Python. Cada paso abre su propio segmento; la función recibe la escena y crea contenido y pausas sin volver a llamar a segment. Estas clases se importan desde gaanim.

from gaanim import Scene, Section, SectionStep

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

def contexto(scene):
    title = scene.text("Contexto", size=0.5)
    scene.play(title.animate.write())
    scene.stop()

def propuesta(scene):
    title = scene.text("Propuesta", size=0.5)
    scene.play(title.animate.write())
    scene.stop()

section = Section("introduccion", [
    SectionStep(name="Contexto", build=contexto, notes="Presenta el problema."),
    SectionStep(name="Propuesta", build=propuesta),
])

def al_entrar(scene, progress):
    print(progress.key, progress.index, progress.total, progress.fraction)

segments = section.build(scene, on_enter=al_entrar)
scene.render()

introduccion 1 2 0.5
introduccion 2 2 1.0

agenda = scene.sections.agenda(sections, pitch=0.66)
agenda.root.move_to(-2, 1.4, Anchor.TOP_LEFT)
rail = scene.sections.progress_rail(sections, segmented=True, captions=True)
rail.root.move_to(0, -4.3).hud()
scene.persist(rail.root)

for section in sections:
    scene.play([agenda.animate.focus(section), rail.animate.enter(section)])
    section.build(scene, on_enter=lambda scene, p: scene.play(rail.animate.to(p)))

Agenda. scene.sections.agenda(sections, current=None, *, direction="column",
pitch=0.5, styles=None, item=None, marker=None, marker_gap=0.3) devuelve un Agenda. Cada entrada está en uno de tres estados, done, current o upcoming, y se coloca por su punto izquierdo-central a pitch unidades de la anterior, en columna o en fila. Cada entrada guarda un drawable por estado y solo muestra el suyo, así que un estado puede cambiar peso, color o contenido: focus hace un fundido cruzado entre ellos. Por defecto done usa foreground, current usa accent con peso 700 y upcoming usa muted; styles={"current": TextStyle(...)} sustituye cualquiera de ellos e item=lambda scene, entry, state: ... sustituye el texto por cualquier drawable. marker=lambda scene: ... añade un indicador a marker_gap de la entrada actual que se desliza con focus. Para anotar esas funciones, NavigationEntry y NavigationState se importan desde gaanim.

• agenda.item(key) es el grupo de una entrada, agenda.items("done") las entradas en un estado y agenda.variant(key, "current") el drawable de ese estado.
• agenda.focus(key) y agenda.advance(steps) cambian el estado de inmediato; agenda.animate.focus(key) y agenda.animate.advance() devuelven composiciones para scene.play, con easing= opcional. Los destinos aceptan una clave, un índice desde 0, un Section o un SectionProgress.

Barra de progreso. scene.sections.progress_rail(sections=None, *,
length=12.0, thickness=0.08, orientation="horizontal", segmented=False, ...) devuelve un ProgressRail. Una barra continua es una sola pista con una marca en cada límite de sección; segmented=True da a cada sección su propia pista, separadas por gap. rail.animate.to(progress) llena las secciones anteriores a un SectionProgress y su parte de pasos; un número en [0, 1] fija la fracción de toda la barra. rail.animate.enter(section) marca una sección como actual sin llenar nada, como en una diapositiva divisoria. captions=True nombra cada sección sobre su tramo y la colorea por estado. Las partes son track, fills, marks, captions y label, y los argumentos track=, mark= y caption= sustituyen sus formas. Las barras se llenan de izquierda a derecha, o hacia arriba con orientation="vertical".

Salida

from gaanim import Scene

scene = Scene(frame=(16, 9))
scene.wait(0.5)
scene.render()

import os

if snapshots := os.environ.get("GAANIM_SNAPSHOTS"):
    scene.snapshots(snapshots, [0.0, 1.0])

titulo = scene.text("Resultados").scale_by(2)
scene.play(titulo.animate.write())
scene.thumbnail()

Variación reproducible

rng = scene.random(seed=42)
stars = [scene.geometry.dot(0.04).move_to(rng.uniform(-7, 7), rng.uniform(-4, 4)) for _ in range(60)]

rng = scene.random(seed=7)
colors = [BLUE, GOLD, CYAN]
rng.shuffle(colors)
size = rng.gauss(1.0, 0.1)
count = rng.integer(3, 8)
accent = rng.choice(colors)

drift = scene.noise(frequency=0.6, amplitude=0.3, octaves=3, seed=5)
title.rotate_to(computed(lambda v: 0.1 * v, inputs=[drift]))
scene.wait(2)

Cámara

scene.camera controla qué parte del mundo se ve. Sus métodos directos aplican un corte en el cursor, sin avanzar el tiempo, y devuelven la cámara para encadenar. Los mismos métodos bajo scene.camera.animate devuelven un Anim que se programa con scene.play junto a cualquier otra animación y admite .duration(), .delay() y .easing().

from gaanim import BLUE, GOLD, Scene

scene = Scene(frame=(16, 9), background="#0f172a")
circle = scene.geometry.circle(0.8).fill(BLUE).move_to(-4, 1)
square = scene.geometry.square(1.2).fill(GOLD).move_to(4, -1)
scene.play([scene.camera.animate.frame_to(circle, margin=0.6).duration(0.8)])
scene.play([scene.camera.animate.frame_to(square, margin=0.6).duration(0.8)])
scene.play([scene.camera.animate.reset().duration(0.6)])
scene.render()

Los destinos de posición (pan_to, follow, look_at, bind_*) aceptan un Drawable, un AnchorPoint, un PointRef o una tupla 2D o 3D. El zoom y la rotación aceptan también Parameter, Variable y Computed. Las APIs de cámara rechazan valores no finitos, zooms, campos de visión y planos de recorte inválidos, poses de look_at degeneradas e influencias fuera de [0, 1] con ValueError, sin recortar valores en silencio.

Poses guardadas

detail = scene.camera.state_2d(center=(-1.6, 0.4), zoom=1.5)
scene.play([scene.camera.animate.to(detail).duration(0.8)])

scene.camera.save("general")
scene.camera.zoom_to(2.0)
scene.wait(0.5)
scene.camera.restore("general")

Encuadre

scene.camera.pan_to(circle).zoom_to(1.5).rotate_to(0.1)
scene.wait(0.5)
scene.camera.frame_to(circle, margin=0.4)
scene.wait(0.5)
scene.camera.reset()

Movimientos animados

scene.camera.save("general")
scene.play([scene.camera.animate.zoom_to(2.0).duration(0.6)])
scene.play([scene.camera.animate.restore("general").duration(0.6)])

scene.play([scene.camera.animate.pan_to(-1.6, 0.4).duration(0.8)])

scene.play([scene.camera.animate.zoom_to(8.0).duration(1.5)])
scene.play([scene.camera.animate.zoom_to(1.0, interpolation="linear").duration(0.8)])

scene.play([scene.camera.animate.frame_to([circle, label], margin=(0.32, 0.48), dynamic=True).duration(0.9)])

scene.play([scene.camera.animate.rotate_to(0.15).duration(0.5)])

scene.play([
    circle.animate.move_to(4, 0).duration(2.0),
    scene.camera.animate.follow(circle.anchor_point(Anchor.TOP), offset=(0, 0.24), lag=0.2).duration(2.0),
])

scene.play([scene.camera.animate.shake(trauma=0.8, decay=1.5, frequency=12, rotation=0.02, seed=0)])
scene.play([scene.camera.animate.shake(trauma=0.4, seed=3)])  # un golpe más leve

route = scene.geometry.path([(-6, -2), (-2, 2), (2, -2), (6, 2)])
scene.play([scene.camera.animate.follow_path(route, orient=True).duration(4)])

section_b = scene.text("B", role="title").move_to(16, 0)
scene.play([scene.camera.animate.whip_pan(section_b)])
scene.play([scene.camera.animate.whip_pan(0, 0, blur=False).duration(0.3)])

cube = scene.geometry.cube(2.0)
scene.camera.look_at(eye=(7, 5, 10), target=(0, 0, 0)).perspective(0.7)
scene.play([scene.camera.animate.orthographic(1.5)], duration=1.0)

scene.play([scene.camera.animate.zoom_to(2.0).duration(0.5)])
scene.play([scene.camera.animate.reset().duration(0.5)])

Capas de parallax

Una capa de parallax agrupa drawables que están más lejos o más cerca de la cámara que el plano de la escena. Con la cámara ortográfica, sus miembros se desplazan 1 / depth del paneo de cámara: el fondo lejano se mueve despacio y el primer plano pasa rápido, sin 3D real. No confundir con Scene.z_layers (orden de dibujo con nombre), Drawable.view_layer (filtro de vistas de cámara) ni con .layer(nombre) de gráficos y ejes (una parte del objeto).

MÉTODOScene.layerlayer(depth: float) -> ParallaxLayer

La capa ve una cámara centrada en posición / depth y con zoom zoom ** (1 / depth); la rotación afecta a todas por igual. depth=1 se comporta como el resto de la escena, depth=3 se mueve a un tercio de la velocidad de la cámara, depth=0.6 pasa más rápido y math.inf no se desplaza ni hace zoom, como Drawable.hud salvo por la rotación. Sacudida, seguimiento y bindings también mueven las capas; un miembro convertido en HUD con Drawable.hud sigue fijo en pantalla. Las capas lejanas se dibujan detrás de las cercanas: su z_index por defecto es round(-100 * ln(depth)), limitado a ±900, y cada miembro suma el suyo. Con cámara en perspectiva las capas no se mueven, porque la profundidad real ya produce parallax. Una profundidad no positiva lanza ValueError.

Parámetros

Nombre	Tipo	Predeterminado	Descripción
depth	float	obligatorio	Distancia a la cámara en unidades de la distancia del plano de la escena; positiva, math.inf permitido.

Devuelve: ParallaxLayer — Capa vacía; es un Drawable cuyos miembros se añaden con add.

Ejemplo

import math
from gaanim import *

scene = Scene(frame=(16, 9), background="#1d2b53")
sky = scene.layer(depth=math.inf).add(scene.geometry.circle(0.9).fill(GOLD).move_to(4.5, 2.6))
far = scene.layer(depth=3.0)
for i in range(6):
    far.add(scene.geometry.polygon([(-2.4, 0), (0, 2.6), (2.4, 0)]).fill("#3b4a7a").move_to(-8 + i * 4.2, -1.4))
for i in range(8):
    scene.geometry.rect(0.5, 1.2).fill("#8a5a3b").move_to(-6 + i * 3, -2.0)
near = scene.layer(depth=0.6)
for i in range(5):
    near.add(scene.geometry.circle(0.9).fill("#1f4d33").move_to(-7 + i * 5, -3.3))
scene.play([scene.camera.animate.pan_to(6, 0).duration(3)])
scene.render()

far = scene.layer(depth=3.0)
far.add(scene.geometry.circle(1.0).move_to(4, 2), scene.geometry.square(1.0).move_to(-4, 2))
print(far.depth)  # 3.0

3.0

Profundidad de campo

Las capas de parallax pueden desenfocarse según su distancia al foco, como con una lente real: cada capa se desenfoca aperture * |1 - focus / depth| unidades de escena, como máximo max_blur. Las capas a la profundidad focus quedan nítidas y el desenfoque crece al alejarse de ella hacia delante o hacia atrás; una capa en math.inf se desenfoca aperture. Los drawables fuera de capas, y los HUD dentro de ellas, nunca se desenfocan. Cada capa se desenfoca como una sola imagen, con un efecto de shader en su raíz que reemplaza cualquier shader_effect puesto en la propia capa; una capa desenfocada se dibuja fuera de pantalla y cuesta más.

MÉTODOCamera.depth_of_fielddepth_of_field(focus: Optional[float] = None, *, aperture: Optional[float] = None, max_blur: Optional[float] = None) -> Camera

Fija la profundidad de campo en el cursor. Los valores omitidos se conservan; al principio el foco es 1, la apertura 0 (sin desenfoque) y max_blur 0.5. Un foco no finito o no positivo, o una aperture o max_blur negativos o no finitos lanzan ValueError.

Parámetros

Nombre	Tipo	Predeterminado	Descripción
focus	float | None	None	Profundidad nítida, finita y positiva; 1 es el plano de la escena.
aperture	float | None	None	Escala del desenfoque, en unidades de escena; 0 lo apaga.
max_blur	float | None	None	Desenfoque máximo, en unidades de escena.

Devuelve: Camera — La cámara.

Ejemplo

import math
from gaanim import *

scene = Scene(frame=(16, 9), background="#1d2b53")
far = scene.layer(depth=3.0)
for i in range(5):
    far.add(scene.geometry.polygon([(-2.4, 0), (0, 2.6), (2.4, 0)]).fill("#3b4a7a").move_to(-8 + i * 4.2, -1.2))
for i in range(6):
    scene.geometry.rect(0.5, 1.2).fill("#8a5a3b").move_to(-6.5 + i * 2.6, -2.0)
near = scene.layer(depth=0.5)
for i in range(4):
    near.add(scene.geometry.circle(0.9).fill("#1f4d33").move_to(-6 + i * 4.4, -3.4))
scene.camera.depth_of_field(focus=1.0, aperture=0.12)
scene.wait(0.5)
scene.play([scene.camera.animate.focus_to(3.0).duration(1.5)])
scene.render()

scene.camera.depth_of_field(focus=0.6, aperture=0.12)
scene.play([scene.camera.animate.focus_to(3.0).duration(1.5)])
scene.play([scene.camera.animate.depth_of_field(aperture=0.0).duration(0.5)])

Bindings persistentes

Un binding es una restricción de cámara que no se dibuja: desde que se crea (salvo con enabled=False) escribe los canales que declara en cada fotograma, también a través de segmentos. influence es un escalar en [0, 1] que mezcla el binding con la pose anterior, y los bindings posteriores se componen sobre los anteriores. follow y el encuadre dinámico actúan después, y el shake se suma al final.

import math

theta = scene.viz.parameter(0.0)
focus = scene.geometry.point_ref(
    computed(lambda t: t * 2.25, inputs=[theta]),
    computed(lambda t: math.sin(t * 2), inputs=[theta]),
)
rig = scene.camera.bind_2d(center=focus, zoom=computed(lambda t: 1 + t * 0.3, inputs=[theta]))
scene.play([theta.animate.set(1.0).duration(2.0)])
rig.disable()

Vistas de cámara

Una vista de cámara muestra dentro de una figura lo que ve una segunda cámara. Drawable.camera_view (en Drawable) convierte cualquier figura cerrada en pantalla; scene.camera.inset monta de una vez la pantalla, el marco y los conectores. Ambos devuelven un CameraView.

MÉTODOCamera.insetinset(target: Endpoint, *, zoom: float | Parameter = 2.0, at: Anchor | tuple[float, float] = Anchor.TOP_RIGHT, size: float | tuple[float, float] | None = None, aspect: Optional[float] = None, shape: Literal["rect", "rounded", "circle"] = "rounded", follow: bool = False, connectors: bool = True, color: Optional[ColorLike] = None, fixed: bool = False, background: Paint | Literal["canvas"] | None = "canvas", exclude: Sequence[Drawable] = (), layers: Sequence[str] = ()) -> CameraView

Muestra un detalle ampliado en una pantalla aparte. El marco sigue el zoom, así que siempre recuadra lo que la pantalla muestra en reposo. Lanza ValueError con un zoom o tamaño no positivo, un shape o at desconocido, o un target reactivo sin follow.

Parámetros

Nombre	Tipo	Predeterminado	Descripción
target	Endpoint	obligatorio	Qué ampliar: un punto, un objeto o un punto de anclaje. Con follow=True, cualquier extremo reactivo.
zoom	float | Parameter	2.0	Aumento de la pantalla en reposo.
at	Anchor | tuple[float, float]	Anchor.TOP_RIGHT	Esquina o borde del fotograma donde va la pantalla (Anchor.CENTER la centra), o punto donde se centra.
size	float | tuple[float, float] | None	None	Ancho de la pantalla, o diámetro si es un círculo; por defecto, el 30 % del ancho de la escena (20 % para un círculo). size=(ancho, alto) fija ambos lados de un rectángulo.
aspect	float | None	None	Proporción ancho / alto de un rectángulo y su marco; por defecto, la del fotograma. Úsala para encuadrar entero un panel alto o una barra de herramientas. Un círculo no admite aspect.
shape	str	"rounded"	"rect", "rounded" o "circle".
follow	bool	False	El marco sigue a target mientras se mueve.
connectors	bool	True	Dos líneas que unen las esquinas enfrentadas del marco y la pantalla.
color	Color | None	None	Trazo de la pantalla, el marco y los conectores; por defecto, el acento del tema.
fixed	bool	False	Fija la pantalla a la imagen como un HUD, para que no se mueva con scene.camera.
background / exclude / layers		obligatorio	Como en Drawable.camera_view. Los conectores nunca aparecen en la vista.

Devuelve: CameraView — La vista, con sus connectors.

Ejemplo

from gaanim import Anchor, CYAN, GOLD, Scene
scene = Scene(frame=(16, 9), background="#0f172a")
for i in range(24):
    scene.geometry.dot(0.05).fill(CYAN if i % 2 else GOLD).move_to(-6 + 0.25 * i, -1 + 0.15 * (i % 5))
view = scene.camera.inset((-4, -0.7), zoom=4, at=Anchor.TOP_RIGHT)
scene.play([view.animate.pop_out().duration(0.8)])
scene.play([view.animate.pan_to(-1.5, -0.7).duration(1.2), view.animate.zoom_to(8).duration(1.2)])
scene.render()

label = scene.viz.readout(view.zoom, format=".1f", prefix="x")

Cámara 3D

La cámara 3D usa coordenadas de mundo (x, y, z) y ángulos en radianes. Las primitivas 3D están en Geometría. Para una introducción, consulta la guía Cámara y 3D.

scene.camera.perspective(fov_y=0.785, near=0.1, far=1000.0)

scene.camera.look_at(eye=(7, 5, 6), target=(0, 0, 0))

rig = scene.camera.bind_3d(eye=(6, 4, 8), target=(0, 0, 0), fov_y=0.8, influence=0.75)
scene.wait(1)
rig.disable()

scene.play([scene.camera.animate.orbit(delta_yaw=0.5, delta_pitch=0.1).duration(1.0)])

scene.play([scene.camera.animate.dolly(factor=0.85).duration(0.6)])

scene.camera.perspective(fov_y=0.6)
scene.camera.look_at(eye=(0, 1, 8), target=(0, 0, 0))
scene.play([scene.camera.animate.dolly_zoom(1.8).duration(2.0)])

Cámara de inspección del editor

El editor tiene una cámara de inspección separada de scene.camera, que nunca cambia las capturas, Presenter View ni la exportación. Empieza desactivada; cada vez que se activa con I (o con el botón Interactive de la barra de overlays, O) parte de una copia de la cámara de la escena en ese instante.

• Num0: alterna entre Free 3D y Camera View (la cámara de la escena).
• En 3D, arrastrar con el botón derecho: orbitar; con el central o Mayús + izquierdo: desplazar. En 2D, arrastrar con cualquier botón desplaza la vista y la escena sigue al cursor; un clic sin arrastrar selecciona el objeto.
• Rueda: hacia arriba acerca y hacia abajo aleja. En 2D acerca hacia el punto bajo el cursor, que se queda quieto.
• W, A, S, D: desplazan la cámara. Las flechas siguen navegando entre paradas y escenas.
• Mientras la inspección está activa, un clic en la vista previa no avanza a la siguiente parada; Enter y las flechas sí. Arrastrar o usar la rueda sobre los paneles del editor no mueve la cámara.
• F: encuadra la selección, o toda la escena si no hay nada seleccionado.
• R: restablece y encuadra; I: activa o desactiva la inspección.

El marco de salida visible conserva el marco lógico y su proporción, y la selección con el ratón se limita a ese marco. Mientras la escena tiene contenido 3D, la barra de tiempo desactiva el ajuste magnético.

Overlays del editor

O muestra una barra con guías que se dibujan solo en el editor, nunca en las capturas ni en la exportación. O o Esc la ocultan.

• Bounds (B): el marco de salida y su tamaño en unidades lógicas.
• Coordinates (C): los ejes con sus marcas y el punto bajo el cursor en unidades de la escena. Mantén Mayús para ajustarlo a la grilla y pulsa Ctrl+C (Cmd+C en macOS) para copiarlo como tupla, lista para pegar en move_to((x, y)). La etiqueta se oculta sobre los paneles del editor.
• Grid (G): líneas cada 1, 2 o 5 unidades (o sus potencias de diez), según el zoom. Durante la inspección cubren toda la vista, no solo el marco. En 3D es una grilla sobre el plano XZ alrededor del punto que mira la cámara, con el eje X en rojo y el Z en azul.
• Guides (M): márgenes seguros de acción (90 %) y de títulos (80 %), y los tercios del marco.
• Layout (K): inspecciona las cajas como las herramientas de desarrollo de un navegador. Cada caja lleva un contorno discontinuo y las zonas del segmento actual un contorno turquesa con su nombre. Al pasar el cursor por una caja se colorean su padding (verde), las celdas de sus hijos (azul), sus márgenes (naranja) y los gaps entre ellos (morado), con una etiqueta de su tipo, tamaño, padding y gap en px de diseño. Sigue la caja en cada momento de la línea de tiempo, también mientras se reorganiza.
• El objeto seleccionado se enmarca con su centro y su tamaño en unidades, y el Inspector muestra sus propiedades (ver más abajo).
• Con la inspección activa, la barra muestra el zoom de la vista (o Free 3D) en azul cuando ya no coincide con la cámara de la escena, y un botón para restablecerla (R). El botón de captura guarda el fotograma actual como PNG, sin overlays (Ctrl+Mayús+S). El icono de teclado lista todos los atajos.

El editor recuerda qué overlays dejaste activados entre sesiones; el modo en sí siempre empieza oculto.

Inspector, consola y animaciones

Con los overlays visibles, un clic en la vista previa selecciona un objeto y el Inspector (botón de la barra) muestra:

• su tipo con el vocabulario del script (circle, rounded_rect, text…) y el nombre que le diste con named;
• la línea del script que lo creó, con Open para ir a ella en tu editor de código y Copy para llevarte archivo:línea. Si lo creó una función tuya, debajo aparecen las líneas que la llamaron (called from main.py · line 11), cada una también se abre con un clic;
• su posición, rotación (en radianes, como rotate_to, y en grados), escala, tamaño y centro en unidades de la escena; su relleno y su trazo con el color en hexadecimal, y su opacidad;
• su z_index, su capa, su profundidad de parallax o si es HUD, si es visible, el texto que dibuja y cuántos hijos tiene.

Sin nada seleccionado, el inspector muestra la cámara de la escena: su posición, rotación, zoom (o campo de visión, recorte y objetivo en perspectiva), el encuadre y, si está activa, la profundidad de campo. Los valores son los del instante de la línea de tiempo, así que cambian al reproducir o recorrer la escena. Un clic sobre una letra selecciona el texto entero y, a igual z_index, gana la caja más pequeña bajo el cursor: la etiqueta sobre su tarjeta, el miembro dentro de su grupo. Inside … sube al grupo que lo contiene. Las líneas siguen siendo correctas tras cada recarga, aunque la recarga reutilice segmentos ya compilados.

La Console (J, o el botón de la barra) reúne lo que antes solo llegaba a la terminal: los avisos de Gaanim y de Python (warnings.warn), lo que escribe print, los errores del script con su traceback y las líneas de estado de cada recarga. Cada mensaje ocupa una fila y enlaza con la línea del script que lo produjo; un clic en la fila muestra debajo el mensaje completo y, si lo tiene, su traceback. Filtra por errores, avisos y mensajes, busca por texto o archivo, copia lo listado como en la terminal y limpia la lista. Por defecto muestra solo la última ejecución del script; History conserva las anteriores. Mientras está oculta, una insignia arriba a la izquierda cuenta los errores y avisos de la última ejecución y la abre con un clic.

Animations (T, o el botón de la barra) abre sobre la barra de reproducción una línea de tiempo de la escena: una fila por objeto animado, más la de la cámara, y un bloque por cada play que lo anima, coloreado por tipo (movimiento, transformación, aparición, estilo, trazo o cámara). Las animaciones de las letras de un texto aparecen en la fila del texto. Muestra el segmento bajo el cabezal; Whole scene muestra toda la escena, y la búsqueda filtra por objeto o por animación. Un clic o un arrastre en la regla mueve el cabezal. Un clic en un bloque pausa, lleva el cabezal a su inicio y selecciona el objeto para verlo en el inspector; un doble clic abre la línea del play. Al pasar el cursor, el bloque muestra su duración, su curva, la línea del play y las líneas desde las que se llamó. Un clic en el nombre de la fila selecciona el objeto y un doble clic abre la línea que lo creó. Mientras está oculto, el panel no cuesta nada por fotograma.

El inspector aparece arriba a la derecha y el panel de animaciones sobre la barra de reproducción. Arrastra cualquiera de los dos por su cabecera (la fila con los puntos) para llevarlo a otro sitio de la ventana; se queda ahí al cambiar de selección y nunca sale de la pantalla. Un doble clic en la cabecera lo devuelve a su sitio. Mientras el panel de animaciones está en su sitio, la consola se coloca encima de él.

Open usa el comando de GAANIM_EDITOR (por ejemplo code --goto {file}:{line}); sin ella, el primero que encuentre en el PATH entre VS Code (code), Cursor, VSCodium, Zed y Sublime Text, y si no hay ninguno abre el archivo con la aplicación predeterminada, que no salta a la línea. El panel de error del script también ofrece Open in the editor.

Recorte y máscaras

Cualquier objeto vectorial puede recortar a otro con una máscara viva que se recalcula en cada fotograma: consulta Drawable.clip y Drawable.no_clip.