Skip to content

The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.

Python

Implement transforms and shape matching

Sina Atalay0ae3ced89a8b
diff --git a/src/manimgx/animation/matching.py b/src/manimgx/animation/matching.py
new file mode 100644
index 00000000..46b5e317
--- /dev/null
+++ b/src/manimgx/animation/matching.py
@@ -0,0 +1,274 @@
+# SPDX-FileCopyrightText: 2026 Academa, Inc.
+# SPDX-FileCopyrightText: 2024 the Manim Community Developers
+# SPDX-FileCopyrightText: 2018 3Blue1Brown LLC
+# SPDX-License-Identifier: MIT
+
+"""Ported from Manim CE 0.21 (MIT)."""
+
+from __future__ import annotations
+
+__all__ = [
+ "TransformMatchingAbstractBase",
+ "TransformMatchingShapes",
+ "TransformMatchingTex",
+]
+from collections.abc import Hashable, Mapping
+from typing import TYPE_CHECKING, Unpack
+
+import numpy as np
+
+from manimgx.animation.motion import FadeIn, FadeOut, FadeTransformPieces
+from manimgx.animation.transform import Transform, TransformOptions
+from manimgx.mobject import Group, Mobject
+from manimgx.mobjects.text import MathTexPart
+
+from .timeline import AnimationGroup
+
+if TYPE_CHECKING:
+ from manimgx.scene import Scene
+
+
+class TransformMatchingAbstractBase(AnimationGroup):
+ """The base of the transforms that match the parts of two mobjects: the parts that
+ match move to their counterparts, and the others fade.
+
+ Each part of `mobject` and of `target_mobject` has a key
+ ([`get_mobject_key`][manimgx.TransformMatchingAbstractBase.get_mobject_key]). The
+ parts of `mobject` whose key a part of the target has transform into the target's
+ parts with that key; the others fade out, moving to where the target's unmatched
+ parts are, as those fade in in their places (unless `transform_mismatches` or
+ `fade_transform_mismatches` has them transform). Parts are matched in their own
+ order, so the result is the same in every run. When the animation finishes,
+ `target_mobject` is in the scene in the place of `mobject`, which is left out of it
+ as it was. A subclass says what the parts are
+ ([`get_mobject_parts`][manimgx.TransformMatchingAbstractBase.get_mobject_parts]) and
+ what their keys are.
+
+ Args:
+ mobject: The mobject to transform.
+ target_mobject: The mobject it becomes.
+ transform_mismatches: Whether the unmatched parts transform into the target's
+ unmatched parts, rather than fade.
+ fade_transform_mismatches: Whether they cross-fade into the target's unmatched
+ parts (see [`FadeTransformPieces`][manimgx.FadeTransformPieces]), rather
+ than fade.
+ key_map: Pairs of keys to match although they differ: the parts of `mobject`
+ with the first key cross-fade into the target's parts with the second.
+ **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
+ each of the animations it plays.
+ """
+
+ # the parts are matched in their own order, so the result is the same in every run
+ # (CE matched through salted hashes, in set order)
+
+ def __init__(
+ self,
+ mobject: Mobject,
+ target_mobject: Mobject,
+ transform_mismatches: bool = False,
+ fade_transform_mismatches: bool = False,
+ key_map: Mapping[Hashable, Hashable] | None = None,
+ **kwargs: Unpack[TransformOptions],
+ ):
+ source_map = self.get_shape_map(mobject)
+ target_map = self.get_shape_map(target_mobject)
+ matched = [key for key in source_map if key in target_map]
+ anims: list[AnimationGroup | Transform] = [
+ Transform(
+ Group(*(source_map[k] for k in matched)),
+ Group(*(target_map[k] for k in matched)),
+ **kwargs,
+ )
+ ]
+ key_mapped_source, key_mapped_target = Group(), Group()
+ for key1, key2 in (key_map or {}).items():
+ if key1 in source_map and key2 in target_map:
+ key_mapped_source.add(source_map.pop(key1))
+ key_mapped_target.add(target_map.pop(key2))
+ if len(key_mapped_source) > 0:
+ anims.append(
+ FadeTransformPieces(key_mapped_source, key_mapped_target, **kwargs)
+ )
+ fade_source = Group(
+ *(part for key, part in source_map.items() if key not in target_map)
+ )
+ fade_target = Group(
+ *(part for key, part in target_map.items() if key not in source_map)
+ )
+ fade_target_copy = fade_target.copy()
+ if transform_mismatches:
+ kwargs.setdefault("replace_mobject_with_target_in_scene", True)
+ anims.append(Transform(fade_source, fade_target, **kwargs))
+ elif fade_transform_mismatches:
+ anims.append(FadeTransformPieces(fade_source, fade_target, **kwargs))
+ else:
+ anims.append(FadeOut(fade_source, target_position=fade_target, **kwargs))
+ anims.append(
+ FadeIn(fade_target_copy, target_position=fade_target, **kwargs)
+ )
+ super().__init__(*anims)
+ self.to_remove = [mobject, fade_target_copy]
+ self.to_add = target_mobject
+
+ def get_shape_map(self, mobject: Mobject) -> dict[Hashable, Group]:
+ """Gather the parts of a mobject by their keys.
+
+ Returns:
+ For each key, in the order its first part comes, a group of the parts with
+ that key, in order.
+ """
+ groups: dict[Hashable, tuple[Group, list[Mobject]]] = {}
+ for part in self.get_mobject_parts(mobject):
+ key = self.get_mobject_key(part)
+ if (bucket := groups.get(key)) is None:
+ groups[key] = bucket = Group(), []
+ bucket[1].append(part)
+ return {key: group.add(*parts) for key, (group, parts) in groups.items()}
+
+ def _end(self, i: int) -> None:
+ # its parts leave the scene with the whole, as it finishes (`clean_up_from_scene`)
+ self.done.add(i)
+ self.animations[i].finish()
+
+ def clean_up_from_scene(self, scene: Scene) -> None:
+ for anim in self.animations:
+ anim.interpolate(0)
+ # what its parts brought into the scene, and every part of the mobject it
+ # transformed, wherever the parts brought them
+ scene.remove(
+ *(anim.mobject for anim in self.animations),
+ *(part for mob in self.to_remove for part in mob.get_family()),
+ )
+ scene.add(self.to_add)
+
+ @staticmethod
+ def get_mobject_parts(mobject: Mobject) -> list[Mobject]:
+ """The parts of a mobject that are matched: a subclass says what they are.
+
+ Returns:
+ Its parts, in order.
+ """
+ raise NotImplementedError("To be implemented in subclass.")
+
+ @staticmethod
+ def get_mobject_key(mobject: Mobject) -> Hashable:
+ """The key a part is matched by: a subclass says what it is.
+
+ Args:
+ mobject: A part.
+
+ Returns:
+ Its key: parts with equal keys match.
+ """
+ raise NotImplementedError("To be implemented in subclass.")
+
+
+class TransformMatchingShapes(TransformMatchingAbstractBase):
+ """Transform a mobject into another by matching their shapes: each part moves to a
+ part of the same shape, and the others fade.
+
+ The parts are the members with points (the letters of a text); two match when they
+ have the same shape, whatever their size and place (their points, centered and
+ scaled to a height of 1, agree to 3 decimals). So a text becomes its anagram letter
+ by letter. When the animation finishes, `target_mobject` is in the scene in the
+ place of `mobject`.
+
+ Args:
+ mobject: The mobject to transform.
+ target_mobject: The mobject it becomes.
+ transform_mismatches: Whether the unmatched parts transform into the target's
+ unmatched parts, rather than fade.
+ fade_transform_mismatches: Whether they cross-fade into the target's unmatched
+ parts (see [`FadeTransformPieces`][manimgx.FadeTransformPieces]), rather
+ than fade.
+ key_map: Pairs of keys to match although they differ: the parts of `mobject`
+ with the first key cross-fade into the target's parts with the second.
+ **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
+ each of the animations it plays.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class TransformMatchingShapesExample(m.Scene):
+ def construct(self) -> None:
+ source = m.Text("the morse code", font_size=96)
+ target = m.Text("here come dots", font_size=96, color=m.YELLOW)
+ self.add(source)
+ self.play(
+ m.TransformMatchingShapes(source, target, path_arc=m.PI / 2),
+ run_time=2,
+ )
+ self.wait(0.5)
+ ```
+ """
+
+ @staticmethod
+ def get_mobject_parts(mobject: Mobject) -> list[Mobject]:
+ return mobject.family_members_with_points()
+
+ @staticmethod
+ def get_mobject_key(mobject: Mobject) -> Hashable:
+ # the shape itself (centered, unit height, to 3 decimals): its bytes, not their
+ # hash
+ shape = mobject.copy().center().set(height=1)
+ return (np.round(shape.points, 3) + 0.0).tobytes()
+
+
+class TransformMatchingTex(TransformMatchingAbstractBase):
+ """Transform a formula into another by matching their parts: each part moves to a
+ part written the same way, and the others fade.
+
+ The parts of a [`MathTex`][manimgx.MathTex] are the strings it is made of: the
+ arguments it is given and what `{{…}}` sets apart in them, split further at its
+ `substrings_to_isolate` and at the strings of its `tex_to_color_map` (a group's
+ parts are its members'). Two parts
+ match when their strings are the same, so give each term that should travel as an
+ argument of its own. When the animation finishes, `target_mobject` is in the scene
+ in the place of `mobject`.
+
+ Args:
+ mobject: The formula to transform: a `MathTex`, or a group of them.
+ target_mobject: The formula it becomes.
+ transform_mismatches: Whether the unmatched parts transform into the target's
+ unmatched parts, rather than fade.
+ fade_transform_mismatches: Whether they cross-fade into the target's unmatched
+ parts (see [`FadeTransformPieces`][manimgx.FadeTransformPieces]), rather
+ than fade.
+ key_map: Pairs of strings to match although they differ: the parts of `mobject`
+ written the first way cross-fade into the target's parts written the second.
+ **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
+ each of the animations it plays.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class TransformMatchingTexExample(m.Scene):
+ def construct(self) -> None:
+ before = m.MathTex("a^2", "+", "b^2", "=", "c^2", font_size=120)
+ after = m.MathTex("a^2", "=", "c^2", "-", "b^2", font_size=120)
+ self.add(before)
+ self.play(
+ m.TransformMatchingTex(before, after, path_arc=m.PI / 2), run_time=2
+ )
+ self.wait(0.5)
+ ```
+ """
+
+ @staticmethod
+ def get_mobject_parts(mobject: Mobject) -> list[Mobject]:
+ if isinstance(mobject, Group):
+ return [
+ p
+ for s in mobject.submobjects
+ for p in TransformMatchingTex.get_mobject_parts(s)
+ ]
+ return mobject.submobjects
+
+ @staticmethod
+ def get_mobject_key(mobject: Mobject) -> Hashable:
+ assert isinstance(mobject, MathTexPart)
+ return mobject.tex_string
diff --git a/src/manimgx/animation/transform.py b/src/manimgx/animation/transform.py
new file mode 100644
index 00000000..7d001631
--- /dev/null
+++ b/src/manimgx/animation/transform.py
@@ -0,0 +1,964 @@
+"""Transforms: keyframe evaluation, recorded method calls, and concurrent leaf composition.
+
+A Transform moves geometry and paint between states; Animate derives those states
+from recorded calls. The play's compositor combines transforms sharing a leaf."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Never, Protocol, Self, Unpack, cast, overload
+
+import numpy as np
+
+from manimgx.animation import clock
+from manimgx.animation.timeline import (
+ Animation,
+ AnimationOptions,
+ Key,
+ _updating,
+ keyframe_at,
+)
+from manimgx.constants import ORIGIN, OUT, PI
+from manimgx.drawing.geometry import (
+ Blend,
+ Floats,
+ Path,
+ Step,
+ carried,
+ path_along_arc,
+ path_along_circles,
+)
+from manimgx.mobject import Group, Mobject, VMobject, _animate_plays
+from manimgx.typing import (
+ PathFunc,
+ Point3D,
+ Point3DLike,
+ Point3DLike_Array,
+ Vector3DLike,
+)
+
+if TYPE_CHECKING:
+ from fractions import Fraction
+
+ from manimgx.mobjects.numbers import DecimalNumber
+ from manimgx.scene import Scene
+
+if TYPE_CHECKING:
+ from manimgx.animation.updaters import AnimatedBoundary
+ from manimgx.mobject import (
+ ComplexValueTracker,
+ Mobject1D,
+ PMobject,
+ ValueTracker,
+ VDict,
+ VectorizedPoint,
+ )
+ from manimgx.mobjects.annotations import Brace, BraceLabel
+ from manimgx.mobjects.graph import GenericGraph
+ from manimgx.mobjects.grid import Matrix, Table
+ from manimgx.mobjects.images import ImageMobject, ImageMobjectFromCamera
+ from manimgx.mobjects.plotting import (
+ BarChart,
+ ComplexPlane,
+ NumberLine,
+ PolarPlane,
+ SampleSpace,
+ _Plane,
+ )
+ from manimgx.mobjects.shapes import (
+ Arc,
+ Arrow,
+ Circle,
+ Line,
+ Polygram,
+ TipableVMobject,
+ )
+ from manimgx.mobjects.text import BulletedList, MathTex
+ from manimgx.mobjects.three_d import Cone, Cylinder, Line3D, Polyhedron, Surface
+ from manimgx.mobjects.vector_field import StreamLines, VectorField
+
+ class _Of[T](Protocol):
+ """A proxy of a T (covariant: `_Of[Circle]` is an `_Of[VMobject]`)."""
+
+ @property
+ def mobject(self) -> T: ...
+
+ class _Method[
+ S1: Mobject, **P1,
+ S2: Mobject = Never, **P2 = ...,
+ S3: Mobject = Never, **P3 = ...,
+ ]:
+ """A mobject method as a proxy records it: for mobjects of kind S (the method's own
+ class), the method's parameters P, returning the proxy — per kind, first match.
+ """
+
+ @overload
+ def __get__(self, proxy: None, owner: type) -> Self: ...
+ @overload
+ def __get__[R](self, proxy: R, owner: type[_Of[S1]]) -> Callable[P1, R]: ...
+ @overload
+ def __get__[R](self, proxy: R, owner: type[_Of[S2]]) -> Callable[P2, R]: ...
+ @overload
+ def __get__[R](self, proxy: R, owner: type[_Of[S3]]) -> Callable[P3, R]: ...
+ def __get__(self, proxy: object, owner: type) -> object:
+ raise NotImplementedError # typing only
+
+ def _on[K](kind: type[K], /) -> K:
+ """A K, for its bound methods: their parameters without `self`, returning K."""
+ raise NotImplementedError # typing only
+
+ @overload
+ def recorded[A: Mobject, **PA](m1: Callable[PA, A], /) -> _Method[A, PA]: ...
+
+ @overload
+ def recorded[A: Mobject, **PA, B: Mobject, **PB](
+ m1: Callable[PA, A], m2: Callable[PB, B], /
+ ) -> _Method[A, PA, B, PB]: ...
+
+ @overload
+ def recorded[A: Mobject, **PA, B: Mobject, **PB, C: Mobject, **PC](
+ m1: Callable[PA, A], m2: Callable[PB, B], m3: Callable[PC, C], /
+ ) -> _Method[A, PA, B, PB, C, PC]: ...
+
+ def recorded(*methods: object) -> object:
+ """A method a proxy records, from each kind's bound method (its kind is what it returns)."""
+ raise NotImplementedError # typing only
+
+
+__all__ = ["Animate", "Transform"]
+
+
+class TransformOptions(AnimationOptions, total=False):
+ """The options a transform takes, by keyword: the animation options and its path."""
+
+ path_func: PathFunc | None
+ """How each point travels from its start to its end: a function of the start points,
+ the end points and the progress (see [paths][manimgx.drawing.geometry]); it replaces
+ `path_arc` and `path_arc_centers` (default None: a straight path)."""
+ path_arc: float
+ """The angle each point turns through on its way, in radians: 0 is a straight path,
+ and a positive angle turns counterclockwise about `path_arc_axis` (default 0)."""
+ path_arc_axis: Vector3DLike
+ """The axis the arcs of `path_arc` turn about (default [`OUT`][manimgx.OUT]: in the
+ plane of the screen)."""
+ path_arc_centers: Point3DLike | Point3DLike_Array | None
+ """A point the mobject turns about by `path_arc` on its way, or one for each of its
+ points (default None: each point turns about the center of its own arc)."""
+ replace_mobject_with_target_in_scene: bool
+ """Whether the target takes the mobject's place in the scene when the animation
+ finishes, as with [`ReplacementTransform`][manimgx.ReplacementTransform]
+ (default False)."""
+
+
+class Transform[M: Mobject = Mobject](Animation[M]):
+ """Transform a mobject into the shape and style of another.
+
+ The mobject stays in the scene and ends looking like `target_mobject`, which is not
+ added (with [`ReplacementTransform`][manimgx.ReplacementTransform], the target takes
+ the mobject's place). Their parts are matched up one to one (the side with fewer
+ parts gains some, and so do the points of each pair), so the mobject may end with
+ more parts than it had. Each point travels from its start to its end in a straight
+ line, or along an arc with `path_arc`.
+
+ Transforms that begin together on one mobject compose: `square.animate.shift(RIGHT)`
+ and `Rotate(square)` played together move the square and turn it. One that begins
+ later takes the mobject over from where the others have brought it. A target that
+ has updaters and is not in the scene moves while the animation plays (the animation
+ runs its updaters), and the mobject follows it.
+
+ Args:
+ mobject: The mobject to transform.
+ target_mobject: The mobject it turns into; None creates an empty target when
+ `keys` is omitted. Passing only `keys` leaves `target_mobject` as None.
+ path_func: How each point travels from its start to its end: a function of the
+ start points, the end points and the progress (see
+ [paths][manimgx.drawing.geometry]); it replaces `path_arc` and `path_arc_centers`.
+ None: a straight path.
+ path_arc: The angle each point turns through on its way, in radians: 0 is a
+ straight path, and a positive angle turns counterclockwise.
+ path_arc_axis: The axis the arcs of `path_arc` turn about.
+ path_arc_centers: A point the mobject turns about by `path_arc` on its way, or
+ one for each of its points; None: each point turns about the center of its
+ own arc.
+ replace_mobject_with_target_in_scene: Whether an independent target takes
+ the mobject's place when the animation finishes. Presets without
+ such a target retain their usual removal or restoration behavior.
+ keys: Two or more states to tween through, in the existing keyframe form: None
+ for a copy of the source, a function of that copy, or a mobject
+ copied when the animation begins. When omitted, the states are the
+ source and target_mobject; presets supply their own sequence.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class TransformExample(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(side_length=3, color=m.BLUE, fill_opacity=0.5)
+ circle = m.Circle(radius=1.5, color=m.YELLOW, fill_opacity=0.5)
+ square.shift(3 * m.LEFT)
+ circle.shift(3 * m.RIGHT)
+ self.add(square)
+ self.play(m.Transform(square, circle, path_arc=m.PI / 2, run_time=2))
+ ```
+ """
+
+ # each leaf moves between its keyframes along `path_func`: from the object to a target
+ # of its own, or between states a preset derives (`keys`)
+ _moving: bool | None = None # `moving_target`, once decided
+
+ def __init__(
+ self,
+ mobject: M | None,
+ target_mobject: Mobject | None = None,
+ path_func: PathFunc | None = None,
+ path_arc: float = 0,
+ path_arc_axis: Vector3DLike = OUT,
+ path_arc_centers: Point3DLike | Point3DLike_Array | None = None,
+ replace_mobject_with_target_in_scene: bool = False,
+ *,
+ keys: Sequence[Key] | None = None,
+ **kwargs: Unpack[AnimationOptions],
+ ) -> None:
+ self.path_arc_axis, self.path_arc_centers = path_arc_axis, path_arc_centers
+ self.path_arc = path_arc
+ if path_func is not None:
+ self._path_func = path_func
+ elif path_arc_centers is not None:
+ self._path_func = path_along_circles(
+ path_arc, path_arc_centers, path_arc_axis
+ )
+ self.replace_mobject_with_target_in_scene = replace_mobject_with_target_in_scene
+ self.target_mobject = target_mobject
+ if keys is None:
+ if self.target_mobject is None:
+ self.target_mobject = Mobject()
+ keys = (None, self.target_mobject)
+ self.keys: Sequence[Key] = keys
+ self.shared: set[int] = set() # its leaves other tweens drive too (`compose`)
+ super().__init__(mobject, **kwargs)
+
+ @property
+ def path_arc(self) -> float:
+ """The angle each point turns through on its way, in radians.
+
+ Setting it makes the path an arc of that angle about `path_arc_axis`.
+ """
+ return self._path_arc
+
+ @path_arc.setter
+ def path_arc(self, value: float) -> None:
+ self._path_arc = value
+ self._path_func = path_along_arc(arc_angle=value, axis=self.path_arc_axis)
+
+ @property
+ def path_func(self) -> PathFunc:
+ """How each point travels from its start to its end.
+
+ A function of the start points, the end points and the progress; setting None
+ keeps the current one.
+ """
+ return self._path_func
+
+ @path_func.setter
+ def path_func(self, value: PathFunc | None) -> None:
+ if value is not None:
+ self._path_func = value
+
+ def begin(self) -> None:
+ # the base begin (the keyframes and the object; a tween acts only when
+ # interpolated), whether the target moves decided afresh: a target that moves runs
+ # from now, its updaters live from when the animation begins to run them
+ self._moving = None
+ super().begin()
+ if self.moving_target():
+ cast("Mobject", self.keys[-1])._stamp(clock.now)
+
+ def take(self) -> None:
+ # take the object; in a play, join the tweens driving its leaves
+ super().take()
+ self.__dict__.pop("motion", None)
+ self.shared = set()
+ if (compositor := self._compositor()) is not None:
+ compositor.join(self)
+
+ def finish(self) -> None:
+ super().finish()
+ if (compositor := self._compositor()) is not None:
+ compositor.finished.add(id(self))
+
+ def _compositor(self) -> Compositor | None:
+ return None if self._scene is None else self._scene.compositor
+
+ @functools.cached_property
+ def motion(self) -> tuple[tuple[Step, ...], Floats] | None:
+ """The motion that carries the mobject from its first keyframe to its last, or
+ None.
+
+ For transforms that compose: its steps (turns about points of the mobject as it
+ began, and moves; a straight path's is the move of its center) and the whole
+ motion undone. None when the path is not a motion.
+ """
+ path, frames = self.path_func, self.frames
+ if not (isinstance(path, Path) and path.kind == "motion" and len(frames) == 2):
+ return None
+ moved = frames[1].get_center() - frames[0].get_center()
+ steps = path.steps or ((moved,) if np.any(moved) else ())
+ return steps, np.linalg.inv(carried((step, 1.0) for step in steps))
+
+ def moving_target(self) -> bool:
+ """Whether the target moves while the animation plays.
+
+ It does when it is a mobject of its own with updaters that the scene does not
+ run: the animation runs them (`advance`), and the keyframes follow it. Decided
+ once, when first asked.
+ """
+ # decided once: not a walk of the scene per animation, nor of the target per
+ # frame
+ if self._moving is None:
+ target = self.keys[-1]
+ self._moving = (
+ isinstance(target, Mobject)
+ and _updating(target)
+ and (
+ self._scene is None
+ or not any(
+ target is m for m in self._scene.get_mobject_family_members()
+ )
+ )
+ )
+ return self._moving
+
+ def advance(self, t: Fraction) -> None:
+ # the object's updaters, brought to scene time `t` on its model, a moving target's
+ # too; then the keyframes follow
+ moving = self.moving_target()
+ if self.model is None and not moving:
+ return
+ if self.model is not None:
+ self.model.advance(t)
+ if moving:
+ cast("Mobject", self.keys[-1]).advance(t)
+ self.rederive()
+
+ def rederive(self) -> None:
+ # the keyframes again (from the model, if the object updates; own objects copied
+ # afresh), aligned with the object
+ model = self.model
+ self.frames = [
+ (
+ key.copy()
+ if isinstance(key, Mobject)
+ else (
+ frame
+ if model is None
+ else model.copy() if key is None else key(model.copy())
+ )
+ )
+ for key, frame in zip(self.keys, self.frames, strict=True)
+ ]
+ for _ in range(2):
+ for frame in self.frames:
+ self.mobject.align_data(frame)
+
+ def interpolate_keyframes(
+ self, submobject: Mobject, keys: Sequence[Mobject], alpha: float
+ ) -> None:
+ i, t = keyframe_at(len(keys) - 1, alpha) # past its ends, it runs on
+ a, b = keys[i], keys[i + 1]
+ shared = self.shared and id(submobject) in self.shared
+ compositor = self._compositor() if shared else None
+ if compositor is None or not compositor.write(submobject, self, a, b, t):
+ submobject.interpolate(a, b, t, self.path_func)
+
+ def clean_up_from_scene(self, scene: Scene) -> None:
+ super().clean_up_from_scene(scene)
+ if (
+ self.replace_mobject_with_target_in_scene
+ and self.target_mobject is not None
+ ):
+ scene.replace(self.mobject, self.target_mobject)
+
+
+class _Call:
+ """A method call, with mobject arguments captured when it is written."""
+
+ __slots__ = ("args", "function", "kwargs")
+
+ def __init__(
+ self,
+ function: Callable[..., object],
+ args: tuple[object, ...],
+ kwargs: dict[str, object],
+ own: set[int],
+ ) -> None:
+ def written(value: object) -> object:
+ return (
+ value.copy()
+ if isinstance(value, Mobject) and id(value) not in own
+ else value
+ )
+
+ self.function = function
+ self.args = tuple(written(value) for value in args)
+ self.kwargs = {key: written(value) for key, value in kwargs.items()}
+
+ def __call__(self, target: Mobject) -> Mobject:
+ self.function(target, *self.args, **self.kwargs)
+ return target
+
+
+_EYE = np.eye(3)
+
+
+_ZERO = np.zeros(3)
+
+
+_BRUSHES = ("fill", "stroke", "background")
+
+
+_FIELDS = ( # every paint field a tween changes but the sheen's direction
+ "fill",
+ "stroke",
+ "background",
+ "stroke_width",
+ "background_width",
+ "sheen_factor",
+ "trim",
+ "pace",
+ "dash",
+)
+
+
+class Compositor:
+ """A play's leaves, and the tweens driving each (`Scene.play` makes one per play)."""
+
+ def __init__(self) -> None:
+ self.leaves: dict[int, _Leaf] = {}
+ self.finished: set[int] = set() # the tweens that have finished
+
+ def join(self, tween: Transform) -> None:
+ """`tween` begins: it joins the tweens on a leaf they have not moved since they began (the leaf
+ is then shared), and takes over any other leaf."""
+ for leaf in tween.mobject.family_members_with_points():
+ entry = self.leaves.get(id(leaf))
+ if entry is not None and entry.found(leaf):
+ entry.parts.append(_Part(tween))
+ for part in entry.parts:
+ part.tween.shared.add(id(leaf))
+ continue
+ for part in entry.parts if entry is not None else ():
+ if id(part.tween) not in self.finished:
+ part.tween.shared.add(id(leaf))
+ self.leaves[id(leaf)] = _Leaf(leaf, tween)
+
+ def write(
+ self, leaf: Mobject, tween: Transform, a: Mobject, b: Mobject, t: float
+ ) -> bool:
+ """Write a shared `leaf` as `tween` has it — between keyframes a and b, at t — with
+ the other tweens driving it. False: the tween writes it itself."""
+ entry = self.leaves[id(leaf)]
+ part = next((p for p in entry.parts if p.tween is tween), None)
+ if part is None: # the leaf was taken over from it
+ return True
+ part.keys, part.t = (a, b), t
+ return entry.compose()
+
+
+class _Part:
+ def __init__(self, tween: Transform) -> None:
+ self.tween = tween
+ self.keys: tuple[Mobject, Mobject] | None = None # once it has written
+ self.t = 0.0
+
+
+class _Leaf:
+ """A leaf as its tweens found it when they began, and those tweens."""
+
+ def __init__(self, leaf: Mobject, tween: Transform) -> None:
+ self.leaf, self.geometry, self.paint = leaf, leaf._geometry, leaf.paint
+ self.parts = [_Part(tween)]
+
+ def found(self, leaf: Mobject) -> bool:
+ """Is the leaf as its tweens found it (none of them has moved it)?"""
+ return leaf._geometry is self.geometry and leaf.paint is self.paint
+
+ def compose(self) -> bool:
+ parts = [(p.tween, p.keys, p.t) for p in self.parts if p.keys is not None]
+ n = self.geometry.n
+ if any(k._geometry.n != n for _, keys, _ in parts for k in keys):
+ return False
+ steps: list[tuple[Step, float]] = []
+ body, paint = self.geometry, self.paint
+ changed: dict[str, object] = {}
+ for tween, (a, b), t in parts:
+ if tween.motion is None: # not a motion: the leaf as the tween has it
+ path = tween.path_func
+ rest = (
+ Blend.mix(a._geometry, b._geometry, path.coefficients(t))
+ if isinstance(path, Path)
+ else Blend.of(path(a.points, b.points, t))
+ )
+ else: # its chord in the frame its motion carries
+ own, undo = tween.motion
+ steps += [(step, t) for step in own]
+ coefficients = ((1 - t) * _EYE, t * undo[:3, :3], t * undo[:3, 3])
+ rest = Blend.mix(a._geometry, b._geometry, coefficients)
+ body = Blend.mix(body, rest, (_EYE, _EYE, _ZERO))
+ body = Blend.mix(body, self.geometry, (_EYE, -_EYE, _ZERO))
+ mixed = paint.mixed(a.paint, b.paint, t)
+ for name in _FIELDS:
+ if (value := getattr(mixed, name)) is getattr(paint, name):
+ continue
+ if name in _BRUSHES and name in changed:
+ value = _channels(changed[name], value, getattr(paint, name))
+ changed[name] = value
+ motion = carried(steps)
+ changed["sheen_direction"] = motion[:3, :3] @ paint.sheen_direction
+ self.leaf._geometry = body.transformed(motion[:3])
+ self.leaf.paint = paint.but(**changed)
+ return True
+
+
+def _channels(before: object, value: np.ndarray, own: np.ndarray) -> np.ndarray:
+ """A brush that two tweens change: its colors the last changer's, and its opacities (a
+ brush of other rows: the last changer's whole)."""
+ if not (
+ isinstance(before, np.ndarray) and before.shape == value.shape == own.shape
+ ):
+ return value
+ out = np.array(before)
+ if not np.array_equal(value[:, :3], own[:, :3]):
+ out[:, :3] = value[:, :3]
+ if not np.array_equal(value[:, 3], own[:, 3]):
+ out[:, 3] = value[:, 3]
+ return out
+
+
+class _Methods:
+ """Every `-> Self` method of the library, by the class that defines it (see the module doc)."""
+
+ if TYPE_CHECKING:
+ # Mobject
+ add = recorded(_on(VDict).add, _on(Group).add, _on(Mobject).add)
+ add_background_rectangle = recorded(_on(Mobject).add_background_rectangle)
+ add_n_more_submobjects = recorded(_on(Mobject).add_n_more_submobjects)
+ add_to_back = recorded(_on(Mobject).add_to_back)
+ add_updater = recorded(_on(Mobject).add_updater)
+ align_data = recorded(_on(Mobject).align_data)
+ align_on_border = recorded(_on(Mobject).align_on_border)
+ align_points = recorded(_on(Mobject).align_points)
+ align_points_with_larger = recorded(_on(Mobject).align_points_with_larger)
+ align_submobjects = recorded(_on(Mobject).align_submobjects)
+ align_to = recorded(_on(Mobject).align_to)
+ apply_complex_function = recorded(_on(Mobject).apply_complex_function)
+ apply_function = recorded(_on(Mobject).apply_function)
+ apply_function_to_position = recorded(_on(Mobject).apply_function_to_position)
+ apply_function_to_submobject_positions = recorded(
+ _on(Mobject).apply_function_to_submobject_positions
+ )
+ apply_matrix = recorded(_on(Mobject).apply_matrix)
+ apply_points_function_about_point = recorded(
+ _on(Mobject).apply_points_function_about_point
+ )
+ arrange = recorded(_on(Mobject).arrange)
+ arrange_in_grid = recorded(_on(Mobject).arrange_in_grid)
+ arrange_submobjects = recorded(_on(Mobject).arrange_submobjects)
+ become = recorded(_on(Mobject).become)
+ center = recorded(_on(Mobject).center)
+ clear_updaters = recorded(_on(Mobject).clear_updaters)
+ fade = recorded(_on(Mobject).fade)
+ fade_to = recorded(_on(Mobject).fade_to)
+ flip = recorded(_on(Mobject).flip)
+ generate_points = recorded(_on(Mobject).generate_points)
+ generate_target = recorded(_on(Mobject).generate_target)
+ init_colors = recorded(_on(Mobject).init_colors)
+ init_points = recorded(_on(Mobject).init_points)
+ insert = recorded(_on(Mobject).insert)
+ interpolate_color = recorded(_on(Mobject).interpolate_color)
+ invert = recorded(_on(Mobject).invert)
+ match_color = recorded(_on(Mobject).match_color)
+ match_coord = recorded(_on(Mobject).match_coord)
+ match_depth = recorded(_on(Mobject).match_depth)
+ match_dim_size = recorded(_on(Mobject).match_dim_size)
+ match_height = recorded(_on(Mobject).match_height)
+ match_points = recorded(_on(Mobject).match_points)
+ match_style = recorded(_on(Mobject).match_style)
+ match_updaters = recorded(_on(Mobject).match_updaters)
+ match_width = recorded(_on(Mobject).match_width)
+ match_x = recorded(_on(Mobject).match_x)
+ match_y = recorded(_on(Mobject).match_y)
+ match_z = recorded(_on(Mobject).match_z)
+ move_to = recorded(_on(Mobject).move_to)
+ next_to = recorded(_on(Mobject).next_to)
+ null_point_align = recorded(_on(Mobject).null_point_align)
+ pointwise_become_partial = recorded(_on(Mobject).pointwise_become_partial)
+ push_self_into_submobjects = recorded(_on(Mobject).push_self_into_submobjects)
+ put_start_and_end_on = recorded(_on(Mobject).put_start_and_end_on)
+ remove = recorded(_on(VDict).remove, _on(Mobject).remove)
+ remove_updater = recorded(_on(Mobject).remove_updater)
+ replace = recorded(_on(Mobject).replace)
+ rescale_to_fit = recorded(_on(Mobject).rescale_to_fit)
+ reset_points = recorded(_on(Mobject).reset_points)
+ restore = recorded(_on(Mobject).restore)
+ resume_updating = recorded(_on(Mobject).resume_updating)
+ reverse_points = recorded(_on(Mobject).reverse_points)
+ rotate = recorded(_on(Mobject).rotate)
+ rotate_about_origin = recorded(_on(Mobject).rotate_about_origin)
+ save_state = recorded(_on(Mobject).save_state)
+ scale = recorded(_on(Arrow).scale, _on(Mobject).scale)
+ scale_to_fit_height = recorded(_on(Mobject).scale_to_fit_height)
+ scale_to_fit_width = recorded(_on(Mobject).scale_to_fit_width)
+ set = recorded(_on(Mobject).set)
+ set_color = recorded(_on(ImageMobject).set_color, _on(Mobject).set_color)
+ set_color_by_gradient = recorded(_on(Mobject).set_color_by_gradient)
+ set_colors_by_radial_gradient = recorded(
+ _on(Mobject).set_colors_by_radial_gradient
+ )
+ set_coord = recorded(_on(Mobject).set_coord)
+ set_fill = recorded(_on(Mobject).set_fill)
+ set_opacity = recorded(_on(ImageMobject).set_opacity, _on(Mobject).set_opacity)
+ set_points = recorded(_on(Mobject).set_points)
+ set_sheen = recorded(_on(Mobject).set_sheen)
+ set_sheen_direction = recorded(_on(Mobject).set_sheen_direction)
+ set_stroke = recorded(_on(Mobject).set_stroke)
+ set_style = recorded(_on(Mobject).set_style)
+ set_submobject_colors_by_gradient = recorded(
+ _on(Mobject).set_submobject_colors_by_gradient
+ )
+ set_submobject_colors_by_radial_gradient = recorded(
+ _on(Mobject).set_submobject_colors_by_radial_gradient
+ )
+ set_x = recorded(_on(Mobject).set_x)
+ set_y = recorded(_on(Mobject).set_y)
+ set_z = recorded(_on(Mobject).set_z)
+ set_z_index = recorded(_on(Mobject).set_z_index)
+ shift = recorded(_on(Mobject).shift)
+ shift_onto_screen = recorded(_on(Mobject).shift_onto_screen)
+ shuffle = recorded(_on(Mobject).shuffle)
+ sort = recorded(_on(Mobject).sort)
+ sort_submobjects = recorded(_on(Mobject).sort_submobjects)
+ space_out_submobjects = recorded(_on(Mobject).space_out_submobjects)
+ stretch = recorded(_on(Mobject).stretch)
+ stretch_about_point = recorded(_on(Mobject).stretch_about_point)
+ stretch_to_fit_height = recorded(_on(Mobject).stretch_to_fit_height)
+ stretch_to_fit_width = recorded(_on(Mobject).stretch_to_fit_width)
+ surround = recorded(_on(Circle).surround)
+ suspend_updating = recorded(_on(Mobject).suspend_updating)
+ to_corner = recorded(_on(Mobject).to_corner)
+ to_edge = recorded(_on(Mobject).to_edge)
+ to_original_color = recorded(_on(Mobject).to_original_color)
+ update = recorded(_on(Mobject).update)
+ # VMobject
+ add_cubic_bezier_curve = recorded(_on(VMobject).add_cubic_bezier_curve)
+ add_cubic_bezier_curve_to = recorded(_on(VMobject).add_cubic_bezier_curve_to)
+ add_line_to = recorded(_on(VMobject).add_line_to)
+ add_points_as_corners = recorded(_on(VMobject).add_points_as_corners)
+ add_quadratic_bezier_curve_to = recorded(
+ _on(VMobject).add_quadratic_bezier_curve_to
+ )
+ add_smooth_curve_to = recorded(_on(VMobject).add_smooth_curve_to)
+ append_points = recorded(_on(VMobject).append_points)
+ change_anchor_mode = recorded(_on(VMobject).change_anchor_mode)
+ clear_points = recorded(_on(VMobject).clear_points)
+ force_direction = recorded(_on(VMobject).force_direction)
+ get_subcurve = recorded(_on(VMobject).get_subcurve)
+ insert_n_curves = recorded(_on(VMobject).insert_n_curves)
+ make_smooth = recorded(_on(VMobject).make_smooth)
+ reverse_direction = recorded(_on(VMobject).reverse_direction)
+ scale_handle_to_anchor_distances = recorded(
+ _on(VMobject).scale_handle_to_anchor_distances
+ )
+ set_anchors_and_handles = recorded(_on(VMobject).set_anchors_and_handles)
+ set_cap_style = recorded(_on(VMobject).set_cap_style)
+ set_points_as_corners = recorded(_on(VMobject).set_points_as_corners)
+ set_points_smoothly = recorded(_on(VMobject).set_points_smoothly)
+ set_shade_in_3d = recorded(_on(VMobject).set_shade_in_3d)
+ start_new_path = recorded(_on(VMobject).start_new_path)
+ # the kinds' own
+ add_bases = recorded(_on(Cylinder).add_bases)
+ add_coordinates = recorded(
+ _on(PolarPlane).add_coordinates, _on(ComplexPlane).add_coordinates
+ )
+ add_display_frame = recorded(_on(ImageMobjectFromCamera).add_display_frame)
+ add_highlighted_cell = recorded(_on(Table).add_highlighted_cell)
+ add_key_value_pair = recorded(_on(VDict).add_key_value_pair)
+ add_labels = recorded(_on(NumberLine).add_labels)
+ add_line = recorded(_on(Mobject1D).add_line)
+ add_numbers = recorded(_on(NumberLine).add_numbers)
+ add_points = recorded(_on(PMobject).add_points)
+ add_ticks = recorded(_on(NumberLine).add_ticks)
+ add_tip = recorded(_on(TipableVMobject).add_tip)
+ assign_tip_attr = recorded(_on(TipableVMobject).assign_tip_attr)
+ change_bar_values = recorded(_on(BarChart).change_bar_values)
+ change_label = recorded(_on(BraceLabel).change_label)
+ change_layout = recorded(_on(GenericGraph).change_layout)
+ divide_vertically = recorded(_on(SampleSpace).divide_vertically)
+ fade_all_but = recorded(_on(BulletedList).fade_all_but)
+ fit_to_coordinate_system = recorded(_on(VectorField).fit_to_coordinate_system)
+ full_family_become_partial = recorded(
+ _on(AnimatedBoundary).full_family_become_partial
+ )
+ increment_value = recorded(
+ _on(ValueTracker[complex]).increment_value,
+ _on(ValueTracker).increment_value,
+ )
+ match_colors = recorded(_on(PMobject).match_colors)
+ move_arc_center_to = recorded(_on(Arc).move_arc_center_to)
+ nudge = recorded(_on(VectorField).nudge)
+ nudge_submobjects = recorded(_on(VectorField).nudge_submobjects)
+ prepare_for_nonlinear_transform = recorded(
+ _on(_Plane).prepare_for_nonlinear_transform
+ )
+ put_at_tip = recorded(_on(Brace).put_at_tip)
+ reset_endpoints_based_on_tip = recorded(
+ _on(TipableVMobject).reset_endpoints_based_on_tip
+ )
+ reset_normal_vector = recorded(_on(Arrow).reset_normal_vector)
+ rotate_about_number = recorded(_on(NumberLine).rotate_about_number)
+ rotate_about_zero = recorded(_on(NumberLine).rotate_about_zero)
+ round_corners = recorded(_on(Polygram).round_corners)
+ set_angle = recorded(_on(Line).set_angle)
+ set_color_by_tex = recorded(_on(MathTex).set_color_by_tex)
+ set_color_by_tex_to_color_map = recorded(
+ _on(MathTex).set_color_by_tex_to_color_map
+ )
+ set_column_colors = recorded(
+ _on(Matrix).set_column_colors, _on(Table).set_column_colors
+ )
+ set_direction = recorded(_on(Cone).set_direction, _on(Cylinder).set_direction)
+ set_fill_by_checkerboard = recorded(_on(Surface).set_fill_by_checkerboard)
+ set_fill_by_value = recorded(_on(Surface).set_fill_by_value)
+ set_length = recorded(_on(Line).set_length)
+ set_location = recorded(_on(VectorizedPoint).set_location)
+ set_path_arc = recorded(_on(Line).set_path_arc)
+ set_points_by_ends = recorded(_on(Line).set_points_by_ends)
+ set_resampling_algorithm = recorded(_on(ImageMobject).set_resampling_algorithm)
+ set_row_colors = recorded(_on(Matrix).set_row_colors, _on(Table).set_row_colors)
+ set_start_and_end_attrs = recorded(_on(Line3D).set_start_and_end_attrs)
+ set_value = recorded(
+ _on(ComplexValueTracker).set_value,
+ _on(ValueTracker).set_value,
+ _on(DecimalNumber).set_value,
+ )
+ start_animation = recorded(_on(StreamLines).start_animation)
+ start_submobject_movement = recorded(_on(VectorField).start_submobject_movement)
+ stop_submobject_movement = recorded(_on(VectorField).stop_submobject_movement)
+ thin_out = recorded(_on(PMobject).thin_out)
+ update_edges = recorded(_on(GenericGraph).update_edges)
+ update_faces = recorded(_on(Polyhedron).update_faces)
+
+
+class Animate[M: Mobject](Transform[M], _Methods):
+ """An animation of a mobject's method calls.
+
+ It is what [`mobject.animate`][manimgx.Mobject.animate] returns. Call methods on it
+ as on the mobject, `square.animate.shift(RIGHT).scale(2)`, and play it: it is the
+ animation. Each call is recorded and tried at once on a copy, so a wrong call fails
+ where it is written, and the calls are carried out on the mobject as it is when the
+ animation begins (in a [`Succession`][manimgx.Succession], after the parts before
+ it). When it finishes, the mobject is exactly what the calls make of it.
+
+ The mobject moves as the calls do: a turn among them (`rotate`, `flip`,
+ `rotate_about_origin`) turns it rigidly, through its whole angle (`rotate(TAU)` is a
+ full turn), about its pivot as the motion carries it; any other call moves its
+ center in a straight line; and the rest of the change (a scale, a color, a new
+ shape) happens along the way. A `path_arc` or `path_func` of its own replaces that
+ motion.
+
+ Called before any method, it takes the animation's
+ [options][manimgx.animation.transform.TransformOptions]:
+ `square.animate(run_time=2, rate_func=linear).shift(RIGHT)`. It also takes an edit,
+ a function applied to the mobject as a method would be:
+ `square.animate(lambda mob: mob.shift(RIGHT))`. A method that the mobject's class
+ overrides with [`override_animate`][manimgx.override_animate] plays the animation it
+ returns instead, and cannot be chained.
+
+ Args:
+ mobject: The mobject whose method calls are animated.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class AnimateExample(m.Scene):
+ def construct(self) -> None:
+ bar = m.Rectangle(width=3, height=1, color=m.BLUE, fill_opacity=0.5)
+ self.add(bar.shift(4 * m.LEFT))
+ self.play(
+ bar.animate(run_time=2)
+ .shift(8 * m.RIGHT)
+ .rotate(m.PI / 2)
+ .set_color(m.YELLOW)
+ )
+ ```
+ """
+
+ def __init__(self, mobject: M) -> None:
+ self._target = mobject.generate_target()
+ self._override: Animation | None = None
+ self._chaining = False
+ self._anim_args: TransformOptions = {}
+ self.methods: list[_Call] = []
+ super().__init__(mobject, self._target)
+ self._chosen: PathFunc | None = self._path_func
+ self.keys = (None, self._replay)
+
+ def __call__(self, **anim_args: Unpack[TransformOptions]) -> Self:
+ """Set the animation's options, before any method is recorded.
+
+ Args:
+ **anim_args: [Transform options][manimgx.animation.transform.TransformOptions].
+
+ Returns:
+ This animation, for chaining.
+ """
+ if self._chaining and anim_args:
+ raise ValueError(
+ "Animation arguments must be passed before accessing methods and can"
+ " only be passed once"
+ )
+ if (
+ anim_args
+ ): # the animation, constructed with them (an override gets them too)
+ self._anim_args = anim_args
+ super().__init__(self.mobject, self.mobject.target, **anim_args)
+ self._chosen = (
+ None
+ if any(
+ k in anim_args
+ for k in ("path_func", "path_arc", "path_arc_centers")
+ )
+ else self._path_func
+ )
+ self.keys = (None, self._replay)
+ return self
+
+ def __getattr__(self, name: str) -> Callable[..., Animation]:
+ if name.startswith("_") or "_target" not in self.__dict__:
+ raise AttributeError(name)
+ method = getattr(self._target, name)
+ override = (
+ _animate_plays.get(method.__func__) if inspect.ismethod(method) else None
+ )
+ if (self._chaining and override is not None) or self._override is not None:
+ raise NotImplementedError(
+ "Method chaining is currently not supported for overridden animations"
+ )
+
+ def record(*args: object, **kwargs: object) -> Animation:
+ if override is not None:
+ animation: Animation = override(
+ self.mobject, *args, anim_args=self._anim_args, **kwargs
+ )
+ self._override = animation
+ return animation
+ method(*args, **kwargs) # tried on the target: a wrong call fails here
+ own = {
+ id(m) for mob in (self.mobject, self._target) for m in mob.get_family()
+ }
+ self.methods.append(_Call(method.__func__, args, kwargs, own))
+ return self
+
+ self._chaining = True
+ return record
+
+ def _replay(self, target: Mobject) -> Mobject:
+ """The recorded calls, carried out on (a copy of) the object as it is when the animation
+ begins, on their arguments as written."""
+ turns = [_turn(item) for item in self.methods]
+ if self._path_func is not self._chosen or not any(turns):
+ for item in self.methods:
+ item(target)
+ return target
+ steps: list[Step] = []
+ for item, turn in zip(self.methods, turns, strict=True):
+ if turn is not None:
+ angle, axis, pivot = turn
+ # its pivot as a point of the object as it began: where the steps so far took it
+ whole = carried((step, 1.0) for step in steps)
+ point = np.linalg.solve(whole, np.append(pivot(target), 1.0))[:3]
+ steps.append((angle, axis, point))
+ item(target)
+ continue
+ before = target.get_center()
+ item(target)
+ moved = target.get_center() - before
+ if np.any(moved):
+ steps.append(moved)
+ self._path_func = self._chosen = Path(steps=tuple(steps))
+ return target
+
+ def finish(self) -> None:
+ for item in self.methods:
+ item(self.mobject)
+ super().finish()
+
+ def build(self) -> Animation:
+ return self if self._override is None else self._override
+
+
+def _turn(
+ item: _Call,
+) -> tuple[float, Floats, Callable[[Mobject], Floats]] | None:
+ """(angle, axis, pivot) of a recorded call that turns the object (`rotate`, `flip`,
+ `rotate_about_origin`), the pivot as the call finds it; None for any other call."""
+ func = item.function
+ name = getattr(func, "__name__", "")
+ if name not in ("rotate", "flip", "rotate_about_origin"):
+ return None
+ try:
+ bound = inspect.signature(func).bind(None, *item.args, **item.kwargs)
+ bound.apply_defaults()
+ given = bound.arguments
+ angle = PI if name == "flip" else float(cast("float", given["angle"]))
+ axis = np.asarray(given["axis"], dtype=np.float64)
+ except (TypeError, KeyError, ValueError):
+ return None
+ point = ORIGIN if name == "rotate_about_origin" else given.get("about_point")
+ edge = given.get("about_edge")
+
+ def pivot(mob: Mobject) -> Floats:
+ if point is not None:
+ return np.asarray(point, dtype=np.float64)
+ return mob.get_critical_point(ORIGIN if edge is None else cast("Point3D", edge))
+
+ return angle, axis, pivot
+
+
+class Always[M: Mobject](_Methods):
+ """A mobject's method calls, each made again at every frame.
+
+ It is what [`mobject.always`][manimgx.Mobject.always] returns. Each call, as
+ `label.always.next_to(dot, UP)`, is made at once and then at every frame, as an
+ updater of the mobject; calls chain. Their arguments are taken as they are written:
+ pass mobjects (`dot`), which the call reads anew at every frame, not values computed
+ from them (`dot.get_center()`), which stay as they were.
+
+ Args:
+ mobject: The mobject whose method calls become updaters.
+ """
+
+ def __init__(self, mobject: M) -> None:
+ self._mobject = mobject
+
+ @property
+ def mobject(self) -> M: # (typing: the proxy of a mobject of this kind)
+ """The mobject whose method calls become updaters."""
+ return self._mobject
+
+ def __getattr__(self, name: str) -> Callable[..., Self]:
+ if name.startswith("_"):
+ raise AttributeError(name)
+
+ def add_updater(*args: object, **kwargs: object) -> Self:
+ self._mobject.add_updater(
+ lambda m: getattr(m, name)(*args, **kwargs), call_updater=True
+ )
+ return self
+
+ return add_updater
diff --git a/src/manimgx/mobjects/images.py b/src/manimgx/mobjects/images.py
index 3f648740..31be0d84 100644
--- a/src/manimgx/mobjects/images.py
+++ b/src/manimgx/mobjects/images.py
@@ -2,6 +2,7 @@
from pathlib import Path
from typing import TYPE_CHECKING, Self, Unpack
+from warnings import deprecated
import numpy as np
@@ -30,18 +31,18 @@ class ImageMobject(MeshMobject):
pixels make it.
An image `scale_to_resolution` pixels tall (1080 unless given) is as tall as the
- frame, 8 scene units, and any other in proportion. Shown larger than its pixels, the
- picture is reconstructed from them by `resampling_algorithm`: by default a smooth
- cubic through every pixel; linear blends neighboring pixels; nearest shows each
- pixel as a square of its color. Shown smaller, it is sampled, not averaged. The
+ frame's short side, 8 scene units, and any other in proportion. Shown larger than its
+ pixels, the picture is reconstructed from them by `resampling_algorithm`: by default
+ a smooth cubic through every pixel; linear blends neighboring pixels; nearest shows
+ each pixel as a square of its color. Shown smaller, it is sampled, not averaged. The
mobject's opacity multiplies its pixels' own.
Args:
filename_or_array: The picture: an image file's path, the file's contents
(bytes), or an array of pixel values from 0 to 255: (h, w) gray, (h, w, 3)
RGB or (h, w, 4) RGBA.
- scale_to_resolution: How many pixels tall an image as tall as the frame is; 0
- for an image 3 units tall, whatever its size.
+ scale_to_resolution: How many pixels tall an image as tall as the frame's
+ short side is; 0 for an image 3 units tall, whatever its size.
invert: Whether its colors are inverted (not its transparency).
image_mode: The mode, as the Pillow library names them, a file is read in:
"RGBA", or "L" for gray.
@@ -161,11 +162,9 @@ class ImageMobject(MeshMobject):
texture = self._texture
assert isinstance(texture, np.ndarray)
h, w = texture.shape[:2]
- height = (
- h / self.scale_to_resolution * config.frame_height
- if self.scale_to_resolution
- else 3
- )
+ # an image `scale_to_resolution` pixels high spans the frame's short side
+ short = min(config.frame_width, config.frame_height)
+ height = h / self.scale_to_resolution * short if self.scale_to_resolution else 3
return self.stretch_to_fit_height(height).stretch_to_fit_width(height * w / h)
def set_color( # pyright: ignore[reportIncompatibleMethodOverride] # ty: ignore[invalid-method-override] # CE's: an image's tint, then its alpha
@@ -218,6 +217,7 @@ class ImageMobject(MeshMobject):
self.resampling_algorithm = resampling_algorithm
return self
+ @deprecated("Manim CE's machinery: manimgx calls it itself", category=None)
def get_style(self) -> Fill:
"""The picture's style, as fill keywords: its color and its opacity.
@@ -238,9 +238,8 @@ def _to_rgba(pixels: np.ndarray) -> np.ndarray:
class ImageCameraOptions(Style, total=False):
- """A camera picture's keywords, those of an
- [ImageMobjectFromCamera][manimgx.ImageMobjectFromCamera], for the scenes that pass
- them on: a [ZoomedScene][manimgx.ZoomedScene]'s display.
+ """A camera picture's keywords, for the scenes that pass them on: a
+ [ZoomedScene][manimgx.ZoomedScene]'s display.
Beyond these, they take the [style keywords][manimgx.drawing.paint.Style].
"""
@@ -251,6 +250,7 @@ class ImageCameraOptions(Style, total=False):
outline, over a white outline 3 wide with no margin (default None)."""
+@deprecated("Manim CE's machinery for ZoomedScene: use ZoomedScene", category=None)
class ImageMobjectFromCamera(MeshMobject):
"""What a camera sees, as a picture: a rectangle showing the camera's view, drawn
anew every frame.
diff --git a/tests/unit/animation/test_matching.py b/tests/unit/animation/test_matching.py
new file mode 100644
index 00000000..b23f1495
--- /dev/null
+++ b/tests/unit/animation/test_matching.py
@@ -0,0 +1,48 @@
+"""Parts are matched in their own order, so a matching is the same in every run.
+
+- `get_shape_map` gathers a mobject's parts by their keys: the keys in the order each first
+ comes, and under each key its parts, each once, at its last place.
+
+(That making a matching changes none of the mobjects it is given, their saved states included,
+is a law of every animation: `test_timeline.py`'s registry laws.)
+"""
+
+from collections.abc import Hashable
+
+from hypothesis import given
+from hypothesis import strategies as st
+
+import manimgx as m
+from manimgx.animation.matching import TransformMatchingAbstractBase
+
+
+class Token(m.Mobject):
+ def __init__(self, value: int) -> None:
+ super().__init__()
+ self.value = value
+
+
+class Matcher(TransformMatchingAbstractBase):
+ """Matches tokens by their values, modulo 3."""
+
+ @staticmethod
+ def get_mobject_parts(mobject: m.Mobject) -> list[m.Mobject]:
+ return mobject.submobjects
+
+ @staticmethod
+ def get_mobject_key(mobject: m.Mobject) -> Hashable:
+ assert isinstance(mobject, Token)
+ return mobject.value % 3
+
+
+@given(indices=st.lists(st.integers(0, 8), max_size=50))
+def test_parts_are_gathered_by_key_in_their_own_order(indices: list[int]) -> None:
+ tokens = [Token(i) for i in range(9)]
+ source = m.Mobject()
+ source.submobjects = [tokens[i] for i in indices]
+ groups = Matcher(m.Mobject(), m.Mobject()).get_shape_map(source)
+ assert list(groups) == list(dict.fromkeys(i % 3 for i in indices))
+ for key, group in groups.items():
+ last = {i: p for p, i in enumerate(indices)} # each token's last place
+ expected = sorted({i for i in indices if i % 3 == key}, key=last.__getitem__)
+ assert [id(x) for x in group.submobjects] == [id(tokens[i]) for i in expected]
diff --git a/tests/unit/animation/test_transform.py b/tests/unit/animation/test_transform.py
new file mode 100644
index 00000000..784b18c3
--- /dev/null
+++ b/tests/unit/animation/test_transform.py
@@ -0,0 +1,189 @@
+"""Recorded methods keep their arguments as written and start when played; tweens that begin
+together on one mobject compose; a replacement leaves its target in its mobject's place.
+
+- `.animate` and `ApplyMethod` take their arguments as written, and carry the calls out on the
+ mobject as it is when the animation begins.
+- An animation's `keys` (functions of the mobject) are applied when it begins, to a copy.
+- A mobject's override (`override_animation`) plays in place of the animation it overrides,
+ the animation given in a list or a generator too.
+- Moves compose: shifts and turns, and a scaling about the mobject's center, played together
+ end where applying them one after another puts it, whatever their order. (Changes of shape
+ add: two scalings played together add their changes, as two morphs do; a scaling is not a
+ step of a motion, as a turn is.)
+- Paint composes channel by channel: a fade and a recolor played together both happen, the
+ same in either order.
+- Played, a transform made to replace its mobject (`replace_mobject_with_target_in_scene`, as
+ a scene gives it) leaves the scene holding its target where the mobject was; one with no
+ target of its own leaves the mobject (a remover, nothing): never an object of its own making.
+"""
+
+from collections.abc import Callable, Iterator
+
+import numpy as np
+import pytest
+from hypothesis import given
+from hypothesis import strategies as st
+from tests.scenes import Recorder, assert_same_frames, record, scene
+from tests.strategies import vectors
+
+import manimgx as m
+from manimgx.animation import easing as rf
+from manimgx.animation.transform import TransformOptions
+from manimgx.drawing.paint import mix_rgba
+
+
[email protected]("form", ["animate", "positional", "keyword"])
+def test_recorded_calls_snapshot_arguments_but_replay_on_the_current_mobject(
+ form: str,
+) -> None:
+ square = m.Square()
+ destination = m.Dot(2 * m.RIGHT + m.UP)
+ wanted = destination.get_center().copy()
+ animation: m.Animation
+ if form == "animate":
+ animation = square.animate.move_to(destination)
+ elif form == "positional":
+ animation = m.ApplyMethod(square.move_to, destination)
+ else:
+ animation = m.ApplyMethod(square.move_to, {"point_or_mobject": destination})
+ destination.shift(3 * m.UP)
+ square.shift(2 * m.LEFT)
+ start = square.get_center().copy()
+
+ animation.begin()
+ animation.interpolate(0)
+ np.testing.assert_allclose(square.get_center(), start, atol=1e-12)
+ animation.finish()
+ np.testing.assert_allclose(square.get_center(), wanted, atol=1e-12)
+
+
+def test_keys_are_applied_as_the_animation_begins_to_a_copy() -> None:
+ square = m.Square()
+ copies: list[m.Mobject] = []
+
+ def moved(copy: m.Mobject) -> m.Mobject:
+ copies.append(copy)
+ return copy.shift(2 * m.RIGHT)
+
+ animation = m.Transform(square, keys=(None, moved), rate_func=rf.linear)
+ assert copies == []
+ animation.begin()
+ assert len(copies) == 1
+ assert copies[0] is not square
+ animation.interpolate(0.5)
+ np.testing.assert_allclose(square.get_center(), m.RIGHT)
+ animation.finish()
+ np.testing.assert_allclose(square.get_center(), 2 * m.RIGHT)
+
+
+def test_an_override_plays_in_place_of_its_animation_given_in_iterables() -> None:
+ class Waiting(m.Square):
+ @m.override_animation(m.FadeIn)
+ def _fade_in(self) -> m.Animation:
+ return m.Wait(0.25)
+
+ def given() -> Iterator[m.Animation]:
+ yield m.FadeIn(Waiting())
+
+ group = m.AnimationGroup(given(), [m.FadeIn(Waiting())], m.FadeIn(m.Square()))
+ kinds = [type(part) for part in group.animations]
+ assert kinds == [m.Wait, m.Wait, m.FadeIn]
+
+
+moves = st.lists(
+ st.one_of(
+ st.tuples(st.just("shift"), vectors(bound=3).map(lambda v: v * [1, 1, 0])),
+ st.tuples(st.just("rotate"), st.floats(-3, 3)),
+ st.tuples(st.just("scale"), st.floats(0.3, 3)),
+ ),
+ min_size=1,
+ max_size=3,
+).filter(lambda calls: sum(name == "scale" for name, _ in calls) <= 1)
+
+
+def played(calls: list[tuple[str, object]], reverse: bool) -> np.ndarray:
+ def tell(s: Recorder) -> None:
+ square = m.Square(1.5).shift(0.3 * m.LEFT)
+ s.stage = [square]
+ s.add(square)
+ anims = [getattr(square.animate, name)(arg) for name, arg in calls]
+ s.play(*(anims[::-1] if reverse else anims))
+
+ return record(tell).stage[0].points
+
+
+@given(calls=moves, reverse=st.booleans())
+def test_moves_played_together_end_as_applied_in_turn(
+ calls: list[tuple[str, object]], reverse: bool
+) -> None:
+ square = m.Square(1.5).shift(0.3 * m.LEFT)
+ for name, arg in calls:
+ getattr(square, name)(arg)
+ np.testing.assert_allclose(played(calls, reverse), square.points, atol=1e-9)
+
+
+def faded_and_recolored(recolor_first: bool) -> Recorder:
+ def tell(s: Recorder) -> None:
+ square = m.Square(color=m.BLUE, fill_opacity=1)
+ s.stage = [square]
+ anims = [m.FadeIn(square), square.animate.set_color(m.RED)]
+ s.play(*(anims[::-1] if recolor_first else anims), rate_func=rf.linear)
+
+ return record(tell)
+
+
+def test_a_fade_and_a_recolor_both_happen_in_either_order() -> None:
+ first, other = faded_and_recolored(False), faded_and_recolored(True)
+ assert_same_frames(first.frames, other.frames)
+ halfway = first.frames[5][0]
+ fill = np.frombuffer(halfway.brushes[0], dtype=float).reshape(-1, 4)
+ color = mix_rgba(m.ManimColor(m.BLUE).to_rgba(), m.ManimColor(m.RED).to_rgba(), 0.5)
+ np.testing.assert_allclose(fill[0, :3], color[:3], atol=1e-9)
+ assert fill[0, 3] == pytest.approx(0.5)
+
+
+REPLACE: TransformOptions = {"replace_mobject_with_target_in_scene": True}
+# each: a transform of a square made to replace it (given the circle it may turn into)
+REPLACING: dict[str, Callable[[m.Square, m.Circle], m.Transform]] = {
+ "Transform": lambda sq, c: m.Transform(sq, c, **REPLACE),
+ "ReplacementTransform": lambda sq, c: m.ReplacementTransform(sq, c),
+ "Transform through keys": lambda sq, c: m.Transform(
+ sq, c, keys=(None, lambda copy: copy.shift(m.RIGHT)), **REPLACE
+ ),
+ ".animate": lambda sq, c: sq.animate(**REPLACE).shift(m.RIGHT),
+ "Rotate": lambda sq, c: m.Rotate(sq, 1.0, **REPLACE),
+ "FadeIn": lambda sq, c: m.FadeIn(sq, **REPLACE),
+ "FadeOut": lambda sq, c: m.FadeOut(sq, **REPLACE),
+ "Indicate": lambda sq, c: m.Indicate(sq, **REPLACE),
+ "GrowFromPoint": lambda sq, c: m.GrowFromPoint(sq, m.LEFT, **REPLACE),
+ "ApplyMethod": lambda sq, c: m.ApplyMethod(sq.shift, m.RIGHT, **REPLACE),
+ "ApplyFunction": lambda sq, c: m.ApplyFunction(
+ lambda copy: copy.shift(m.RIGHT), sq, **REPLACE
+ ),
+ "MoveAlongPath": lambda sq, c: m.MoveAlongPath(
+ sq, m.Line(m.LEFT, m.RIGHT), **REPLACE
+ ),
+ "Create": lambda sq, c: m.Create(sq, **REPLACE),
+ "DrawBorderThenFill": lambda sq, c: m.DrawBorderThenFill(sq, **REPLACE),
+ "CyclicReplace": lambda sq, c: m.CyclicReplace(sq, **REPLACE),
+}
+
+
[email protected]("name", sorted(REPLACING))
+def test_a_replacement_leaves_its_target_in_its_mobjects_place(name: str) -> None:
+ square, circle = m.Square(), m.Circle().shift(m.RIGHT)
+ before, after = m.Dot(m.UP), m.Dot(m.DOWN)
+ animation = REPLACING[name](square, circle)
+ target = animation.target_mobject # its own, if it has one
+
+ def construct(s: m.Scene) -> None:
+ s.add(before, square, after)
+ s.play(animation)
+
+ told = scene(construct)
+ told.render()
+ if target is not None:
+ middle = [target]
+ else:
+ middle = [] if animation.is_remover() else [square]
+ assert [id(x) for x in told.mobjects] == [id(x) for x in (before, *middle, after)]