gaanim 0.17.0__py3-none-any.whl

gaanim/__init__.py

@@ -0,0 +1,428 @@
+"""Gaanim — GPU-accelerated vector animation engine."""
+
+import sys
+import warnings
+
+if f"{__name__}.gaanim_core" not in sys.modules:
+    raise RuntimeError(
+        "The `gaanim` wheel only provides authoring helpers and type information. "
+        "Run animation scripts with `gaanim <script.py>` or open them in the Gaanim editor."
+    )
+
+# The stub declares type aliases such as Paint on gaanim_core, but the native
+# module only defines classes: give it the aliases before anything imports them.
+from . import _type_aliases
+
+_type_aliases.install(sys.modules[f"{__name__}.gaanim_core"])
+
+from . import colors
+from .gaanim_core import (
+    Anchor,
+    AnchorPoint,
+    PointRef,
+    Direction,
+    Box,
+    BoxStyle,
+    Zone,
+    ZoneSet,
+    Zones,
+    LayoutExpression,
+    LayoutConstraint,
+    ConstraintSet,
+    LayoutOwnershipError,
+    BLACK,
+    BLUE,
+    CORAL,
+    CYAN,
+    GOLD,
+    GRAY,
+    GREEN,
+    NAVY,
+    ORANGE,
+    PINK,
+    PURPLE,
+    RED,
+    TEAL,
+    WHITE,
+    YELLOW,
+    Anim,
+    Easing,
+    EasingCurve,
+    Audio,
+    AudioData,
+    AudioTempo,
+    Voiceover,
+    Composition,
+    Schedule,
+    ScheduleEntry,
+    parallel,
+    sequence,
+    stagger,
+    quantity,
+    distribute,
+    label,
+    magic_move,
+    Color,
+    ColorMap,
+    Palette,
+    Brush,
+    Background,
+    ColorLike,
+    ColorMapLike,
+    PaletteLike,
+    Paint,
+    BackgroundLike,
+    Distribution,
+    Emitter,
+    PostProcess,
+    Camera,
+    CameraState,
+    CameraConstraint,
+    SceneStop,
+    Bounds,
+    SceneMarker,
+    Theme,
+    Style,
+    StrokeStyle,
+    AxesStyle,
+    Drawable,
+    Image,
+    Video,
+    VideoSegment,
+    Lottie,
+    Dimension,
+    AngleDimension,
+    ForceVector,
+    Support,
+    SurroundingRect,
+    ParallaxLayer,
+    Material3D,
+    Primitive3D,
+    Axonometric,
+    Text,
+    TextAnchor,
+    TextPart,
+    TextParts,
+    TextStyle,
+    TextFlow,
+    TextSelection,
+    TextSelectionAnimation,
+    TextQuery,
+    TextAnimator,
+    TextAnimatorAnimation,
+    PathModifiers,
+    Annotations,
+    PathModifier,
+    PathModifierAnimation,
+    part,
+    parts,
+    Transition,
+    Overlay,
+    Updater,
+    Falloff,
+    FalloffColor,
+    Axis,
+    Scale,
+    Field,
+    Value,
+    Guide,
+    ChartSpec,
+    Chart,
+    Parameter,
+    Poll,
+    Leaderboard,
+    Audience,
+    Teams,
+    Condition,
+    Character,
+    LiveZone,
+    Readout,
+    Variable,
+    RollingNumber,
+    ProgressRing,
+    BarRace,
+    BarRaceAnimation,
+    Computed,
+    Random,
+    TimeInput,
+    computed,
+    deg,
+    CoordinateRef,
+    CoordinateSpace,
+    CoordinateSpace3D,
+    VectorField,
+    ArrowVectorField,
+    StreamLines,
+    FlowParticles,
+    Cartesian2D,
+    Cartesian3D,
+    NumberLine,
+    PolarSpace,
+    DataTable,
+    DataSource,
+    Geometry,
+    Typography,
+    LayoutBuilder,
+    MediaLibrary,
+    UI,
+    Visualization,
+    SlideKit,
+    Mechanics,
+    Fx,
+    AssetManager,
+    Scene,
+    Segment,
+)
+
+# Keep the semantic complex-space name available even when an embedding host
+# has an older abi3 module already loaded in-process.
+ComplexSpace = CoordinateSpace
+from .sections import (
+    Agenda,
+    NavigationEntry,
+    NavigationState,
+    ProgressRail,
+    Section,
+    SectionLike,
+    SectionProgress,
+    SectionStep,
+    SectionTarget,
+    SegmentCamera,
+)
+from .templates import (
+    comparison,
+    credits,
+    component,
+    Component,
+    lecture,
+    lower_third,
+    minimal,
+    title_slide,
+    vertical_short,
+)
+from .animation_types import AnimationChannel, CustomAnimationValues, Playable, ScalarSource
+from .questions import Question, QuestionError, load_questions
+from .pointer import Pointer, PointerAnimator
+from .timeline import Timeline, TimelineEvent
+from .matrix import (
+    Matrix,
+    MatrixAlgebraError,
+    MatrixDerivation,
+    MatrixEntry,
+    MatrixSelection,
+    MatrixSelectionAnimation,
+    MatrixStep,
+)
+
+
+def Canvas(*args, **kwargs):
+    """Deprecated compatibility constructor; use :class:`Scene` instead."""
+    warnings.warn(
+        "Canvas is deprecated as the animation facade; use Scene instead. "
+        "Use scene.canvas for viewport configuration.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return Scene(*args, **kwargs)
+
+
+__all__ = [
+    "Section",
+    "SectionStep",
+    "SectionProgress",
+    "SectionLike",
+    "SectionTarget",
+    "SegmentCamera",
+    "Agenda",
+    "NavigationEntry",
+    "NavigationState",
+    "ProgressRail",
+    "AnimationChannel",
+    "CustomAnimationValues",
+    "Playable",
+    "ScalarSource",
+    "Scene",
+    "Geometry",
+    "Typography",
+    "LayoutBuilder",
+    "MediaLibrary",
+    "UI",
+    "Visualization",
+    "SlideKit",
+    "Mechanics",
+    "Fx",
+    "AssetManager",
+    "Segment",
+    "Canvas",
+    "Composition",
+    "Schedule",
+    "ScheduleEntry",
+    "parallel",
+    "sequence",
+    "stagger",
+    "quantity",
+    "distribute",
+    "label",
+    "magic_move",
+    "Matrix",
+    "Pointer",
+    "PointerAnimator",
+
+    "Timeline",
+    "TimelineEvent",
+    "MatrixEntry",
+    "MatrixSelection",
+    "MatrixSelectionAnimation",
+    "MatrixStep",
+    "MatrixDerivation",
+    "MatrixAlgebraError",
+    "Drawable",
+    "Image",
+    "Video",
+    "VideoSegment",
+    "Lottie",
+    "Dimension",
+    "AngleDimension",
+    "ForceVector",
+    "Support",
+    "SurroundingRect",
+    "ParallaxLayer",
+    "Material3D",
+    "Primitive3D",
+    "Axonometric",
+    "Text",
+    "TextAnchor",
+    "TextPart",
+    "TextParts",
+    "TextStyle",
+    "TextFlow",
+    "TextSelection",
+    "TextSelectionAnimation",
+    "TextAnimator",
+    "TextAnimatorAnimation",
+    "PathModifiers",
+    "Annotations",
+    "PathModifier",
+    "PathModifierAnimation",
+    "TextQuery",
+    "part",
+    "parts",
+    "Anim",
+    "Easing",
+    "EasingCurve",
+    "Audio",
+    "AudioData",
+    "AudioTempo",
+    "Voiceover",
+    "Transition",
+    "Overlay",
+    "Color",
+    "ColorMap",
+    "Palette",
+    "Brush",
+    "Background",
+    "ColorLike",
+    "ColorMapLike",
+    "PaletteLike",
+    "Paint",
+    "BackgroundLike",
+    "Distribution",
+    "Emitter",
+    "PostProcess",
+    "Camera",
+    "CameraState",
+    "CameraConstraint",
+    "SceneStop",
+    "Bounds",
+    "SceneMarker",
+    "Theme",
+    "Style",
+    "StrokeStyle",
+    "AxesStyle",
+    "colors",
+    "Anchor",
+    "AnchorPoint",
+    "PointRef",
+    "Direction",
+    "Box",
+    "BoxStyle",
+    "Zone",
+    "ZoneSet",
+    "Zones",
+    "LayoutExpression",
+    "LayoutConstraint",
+    "ConstraintSet",
+    "LayoutOwnershipError",
+    "component",
+    "Component",
+    "title_slide",
+    "lecture",
+    "comparison",
+    "vertical_short",
+    "minimal",
+    "lower_third",
+    "credits",
+    "Question",
+    "QuestionError",
+    "load_questions",
+    "Updater",
+    "Falloff",
+    "FalloffColor",
+    "Axis",
+    "Scale",
+    "Field",
+    "Value",
+    "Guide",
+    "ChartSpec",
+    "Chart",
+    "Parameter",
+    "Poll",
+    "Leaderboard",
+    "Audience",
+    "Teams",
+    "Condition",
+    "Character",
+    "LiveZone",
+    "Readout",
+    "Variable",
+    "RollingNumber",
+    "ProgressRing",
+    "BarRace",
+    "BarRaceAnimation",
+    "Computed",
+    "Random",
+    "TimeInput",
+    "computed",
+    "deg",
+    "CoordinateRef",
+    "CoordinateSpace",
+    "CoordinateSpace3D",
+    "VectorField",
+    "ArrowVectorField",
+    "StreamLines",
+    "FlowParticles",
+    "Cartesian2D",
+    "Cartesian3D",
+    "ComplexSpace",
+    "NumberLine",
+    "PolarSpace",
+    "DataTable",
+    "DataSource",
+    "GOLD",
+    "CORAL",
+    "BLUE",
+    "WHITE",
+    "BLACK",
+    "RED",
+    "GREEN",
+    "YELLOW",
+    "ORANGE",
+    "PURPLE",
+    "PINK",
+    "GRAY",
+    "CYAN",
+    "NAVY",
+    "TEAL",
+]
+
+__version__ = "0.17.0"

gaanim/_docs/apendices/glosario.typ

@@ -0,0 +1,153 @@
+#import "../../components/section.typ": docs-chapter
+
+#show: docs-chapter.with(
+  title: "Glosario",
+  description: "Los términos que usa esta documentación y el nombre que tienen en la API",
+  route: "/apendices/glosario/",
+)
+
+Esta documentación explica en español y conserva en inglés los nombres de la
+API. Aquí tienes cada término con el identificador que le corresponde en el
+código.
+
+/ Ancla (`Anchor`, `anchor_point`): uno de los nueve puntos de referencia de
+  la caja de un objeto (`Anchor.CENTER`, `Anchor.TOP_LEFT`…). Sirve para
+  colocar objetos (`move_to(x, y, anchor=...)`) y, con
+  `objeto.anchor_point(...)`, como extremo que acompaña al objeto cuando se
+  mueve.
+
+/ Animación (`Anim`): la descripción de un cambio en el tiempo, como
+  `circle.animate.move_to(2, 0)` con `.duration(1.0)`. No hace nada hasta que la
+  pasas a `scene.play([...])`.
+
+/ `.animate`: propiedad de solo lectura de cada handle que ofrece los mismos
+  métodos que los cambios inmediatos, pero devuelve animaciones.
+
+/ Área segura (`within="safe"`): el fotograma menos el margen de la escena
+  (`Scene(margin=...)`). Layout la usa para no pegar el contenido a los bordes.
+
+/ Binding (vínculo): relación por la que una propiedad copia la de otro
+  objeto, como `bind_x_from`, `bind_rotation_from` o `follow`. Ver
+  #link("/guias/reactividad/")[Reactividad].
+
+/ Capacidad: cada grupo de fábricas de una escena: `scene.geometry`,
+  `scene.text`, `scene.layout`, `scene.media`, `scene.viz`, `scene.slides`,
+  `scene.mechanics`, `scene.assets`, `scene.canvas` y `scene.camera`.
+
+/ Captura (`scene.snapshots`): imagen exacta de un instante de la escena, que
+  `gaanim --diff` compara con una versión aprobada. Ver
+  #link("/guias/capturas-y-comparacion/")[Capturas y comparación visual].
+
+/ Composición (`Composition`): grupo de animaciones ordenadas con
+  `parallel`, `sequence` o `stagger`, que se reproduce como una unidad.
+
+/ Corte: cambio inmediato, sin duración, que un método aplicado fuera de
+  `.animate` registra en el cursor actual (por ejemplo `circle.fill(RED)`
+  después de un `play`). Es reversible: al volver atrás en la línea de tiempo,
+  el objeto recupera su estado anterior.
+
+/ Cursor (`scene.cursor`): el instante de la línea de tiempo en el que se
+  añade lo siguiente que escribes. Avanza con cada `scene.play` y
+  `scene.wait`.
+
+/ Drawable: cualquier objeto visible de la escena (una figura, un texto, una
+  imagen, un gráfico, un layout). En español decimos también *objeto*.
+
+/ Easing (`Easing`): la curva que reparte el progreso de una animación en el
+  tiempo: `Easing.LINEAR`, `Easing.SMOOTH`, `Easing.spring(...)`… Se aplica
+  con `.easing(...)`.
+
+/ Escena (`Scene`): el documento que describes en Python. Contiene los
+  objetos, la línea de tiempo, el tema y la cámara, y termina con
+  `scene.render()`.
+
+/ Exportar (`gaanim export`): renderizar la escena a un archivo de video,
+  imagen animada o secuencia PNG. Ver
+  #link("/guias/proyectos/")[Proyectos y exportación].
+
+/ Fábrica: método que crea un drawable y devuelve su handle, como
+  `scene.geometry.circle(1)` o `scene.text("Hola")`.
+
+/ Fragmento: parte de un texto seleccionada por su contenido, como
+  `text["energía"]`, para colorearla o animarla por separado. Si el texto
+  tiene una parte con ese nombre, se usa la parte.
+
+/ Handle: el valor de Python que devuelve una fábrica y con el que manipulas
+  el objeto: `circle = scene.geometry.circle(1)`. Sus métodos son encadenables:
+  `circle.fill(BLUE).move_to(2, 0)`.
+
+/ Layout: sistema que coloca objetos en filas, columnas, rejillas y capas sin
+  coordenadas manuales (`scene.layout`). Ver #link("/guias/layout/")[Layout].
+
+/ Línea de tiempo: la secuencia de todo lo que ocurre en la escena, con su
+  instante exacto. Gaanim puede saltar a cualquier punto de ella y mostrar lo
+  mismo que al reproducir.
+
+/ Manifiesto (`gaanim.toml`): archivo que define un proyecto: nombre, tipo,
+  script de entrada y carpetas de recursos y exportación.
+
+/ Marcador (`scene.marker`): nombre de un instante de la línea de tiempo.
+  El editor lo muestra en la barra de reproducción y `gaanim export --from/--to`
+  lo acepta en lugar de segundos.
+
+/ Parada (`scene.stop`): punto donde el modo presentación espera a que
+  avances. La vista previa, las capturas y la exportación no se detienen en
+  ella. En la vista del presentador cada parada es un *paso*.
+
+/ Parámetro (`Parameter`, `scene.viz.parameter`): valor numérico invisible y
+  animable del que pueden depender otros objetos.
+
+/ Parte (`part`): fragmento de un texto o una ecuación con nombre propio,
+  como `part("masa", "m")`, que puedes seleccionar con `text["masa"]` y que
+  las transformaciones emparejan por nombre.
+
+/ Presenter View (vista del presentador): ventana con la diapositiva actual,
+  la siguiente, las notas y el tiempo, que se abre con `gaanim --present`. Ver
+  #link("/guias/presentaciones/")[Presentaciones].
+
+/ Proyecto: carpeta con un `gaanim.toml`, un script de entrada, recursos y
+  exportaciones. Se crea con `gaanim init video` o `gaanim init slides`.
+
+/ Punto de referencia (`PointRef`): punto lógico, sin dibujo, que otros
+  objetos pueden seguir o usar como extremo; lo crean `polar_point`,
+  `point_ref`, `offset_point` y `point_between`.
+
+/ Reactivo: se dice del objeto o valor que se recalcula a partir de otros en
+  cada fotograma, como una `tracking_line` o un `computed`.
+
+/ Recarga en caliente: la vista previa vuelve a ejecutar el script al guardar
+  y conserva lo que no cambió.
+
+/ Rol de texto (`role=`): estilo con nombre que el tema define para un texto:
+  `"title"`, `"subtitle"`, `"body"`, `"caption"`…
+
+/ Segmento (`scene.segment`): tramo con nombre de la línea de tiempo. En una
+  presentación, cada segmento es una diapositiva; entre segmentos puede haber
+  una transición.
+
+/ Stagger (`stagger`): composición que arranca varias animaciones con un
+  desfase entre ellas, por orden o por distancia a un origen.
+
+/ Tema (`theme=`, `Theme`): conjunto de colores, tipografías y estilos de
+  texto que la escena aplica por defecto, como `"presentation"` o
+  `"technical"`.
+
+/ Transición (`Transition`): el paso visual de un segmento al siguiente,
+  como `Transition.cross_fade(0.4)` o `Transition.wipe(...)`.
+
+/ Unidades lógicas: la medida de toda la escena. El fotograma mide 16 × 9
+  unidades con el origen en el centro; los píxeles solo se eligen al
+  previsualizar o exportar.
+
+/ Updater (`Updater`, `add_updater`): comportamiento continuo añadido a un
+  objeto, como `Updater.rotate(1.5)` o `Updater.wiggle(...)`. Ver
+  #link("/guias/reactividad/")[Reactividad].
+
+/ Valor calculado (`computed`): número derivado de parámetros, variables o
+  del tiempo mediante una función de Python pura con entradas explícitas.
+
+/ Versión aprobada (*baseline*): el conjunto de capturas aceptadas contra el
+  que `gaanim --diff` compara. Se actualiza con `--bless`.
+
+/ Vista previa: la ventana que abre `gaanim archivo.py` o `gaanim proyecto`,
+  con reproducción, saltos y recarga en caliente.