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

Add timed mobject updaters

Sina Atalaya40a30b6dbbd
diff --git a/src/manimgx/animation/matching.py b/src/manimgx/animation/matching.py
index 46b5e317..be7749e8 100644
--- a/src/manimgx/animation/matching.py
+++ b/src/manimgx/animation/matching.py
@@ -7,6 +7,8 @@
from __future__ import annotations
+from warnings import deprecated
+
__all__ = [
"TransformMatchingAbstractBase",
"TransformMatchingShapes",
@@ -28,6 +30,10 @@ if TYPE_CHECKING:
from manimgx.scene import Scene
+@deprecated(
+ "the base of TransformMatchingShapes and TransformMatchingTex: use either",
+ category=None,
+)
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.
diff --git a/src/manimgx/animation/transform.py b/src/manimgx/animation/transform.py
index 7d001631..65ef93f0 100644
--- a/src/manimgx/animation/transform.py
+++ b/src/manimgx/animation/transform.py
@@ -9,6 +9,7 @@ import functools
import inspect
from collections.abc import Callable, Sequence
from typing import TYPE_CHECKING, Never, Protocol, Self, Unpack, cast, overload
+from warnings import deprecated
import numpy as np
@@ -42,6 +43,8 @@ from manimgx.typing import (
if TYPE_CHECKING:
from fractions import Fraction
+ from manimgx.constants import DEFAULT_MOBJECT_TO_MOBJECT_BUFFER, RIGHT
+ from manimgx.mobject import Beside
from manimgx.mobjects.numbers import DecimalNumber
from manimgx.scene import Scene
@@ -86,9 +89,12 @@ if TYPE_CHECKING:
def mobject(self) -> T: ...
class _Method[
- S1: Mobject, **P1,
- S2: Mobject = Never, **P2 = ...,
- S3: Mobject = Never, **P3 = ...,
+ 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.
@@ -135,7 +141,7 @@ class TransformOptions(AnimationOptions, total=False):
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
+ the end points and the progress (see [paths][manimgx.Path]); 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,
@@ -174,7 +180,7 @@ class Transform[M: Mobject = Mobject](Animation[M]):
`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`.
+ [paths][manimgx.Path]); 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.
@@ -185,10 +191,9 @@ class Transform[M: Mobject = Mobject](Animation[M]):
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.
+ keys: Two or more states to pass through, in order: None for the mobject as the
+ animation starts, a function of it, or a mobject, copied when the animation
+ starts. Without them, the states are the mobject and `target_mobject`.
Examples:
```python
@@ -294,6 +299,7 @@ class Transform[M: Mobject = Mobject](Animation[M]):
return None if self._scene is None else self._scene.compositor
@functools.cached_property
+ @deprecated("manimgx's machinery: the play calls it", category=None)
def motion(self) -> tuple[tuple[Step, ...], Floats] | None:
"""The motion that carries the mobject from its first keyframe to its last, or
None.
@@ -309,6 +315,7 @@ class Transform[M: Mobject = Mobject](Animation[M]):
steps = path.steps or ((moved,) if np.any(moved) else ())
return steps, np.linalg.inv(carried((step, 1.0) for step in steps))
+ @deprecated("Manim CE's machinery: manimgx calls it itself", category=None)
def moving_target(self) -> bool:
"""Whether the target moves while the animation plays.
@@ -355,7 +362,9 @@ class Transform[M: Mobject = Mobject](Animation[M]):
else (
frame
if model is None
- else model.copy() if key is None else key(model.copy())
+ else model.copy()
+ if key is None
+ else key(model.copy())
)
)
for key, frame in zip(self.keys, self.frames, strict=True)
@@ -566,7 +575,16 @@ class _Methods:
)
arrange = recorded(_on(Mobject).arrange)
arrange_in_grid = recorded(_on(Mobject).arrange_in_grid)
- arrange_submobjects = recorded(_on(Mobject).arrange_submobjects)
+
+ @deprecated("arrange_submobjects is arrange: use it", category=None)
+ def arrange_submobjects(
+ self,
+ direction: Vector3DLike = RIGHT,
+ buff: float = DEFAULT_MOBJECT_TO_MOBJECT_BUFFER,
+ center: bool = True,
+ **kwargs: Unpack[Beside],
+ ) -> Self: ...
+
become = recorded(_on(Mobject).become)
center = recorded(_on(Mobject).center)
clear_updaters = recorded(_on(Mobject).clear_updaters)
@@ -607,7 +625,15 @@ class _Methods:
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)
+
+ @deprecated(
+ "rotate_about_origin(angle, axis) is rotate(angle, axis, about_point=ORIGIN)",
+ category=None,
+ )
+ def rotate_about_origin(
+ self, angle: float, axis: Vector3DLike = OUT
+ ) -> Self: ...
+
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)
@@ -762,9 +788,9 @@ class Animate[M: Mobject](Transform[M], _Methods):
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
+ The mobject moves as the calls do: a turn among them (`rotate`, `flip`) 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.
@@ -773,9 +799,7 @@ class Animate[M: Mobject](Transform[M], _Methods):
[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.
+ `square.animate(lambda mob: mob.shift(RIGHT))`.
Args:
mobject: The mobject whose method calls are animated.
diff --git a/src/manimgx/animation/updaters.py b/src/manimgx/animation/updaters.py
new file mode 100644
index 00000000..a56b94be
--- /dev/null
+++ b/src/manimgx/animation/updaters.py
@@ -0,0 +1,607 @@
+# SPDX-FileCopyrightText: 2026 Academa, Inc.
+# SPDX-FileCopyrightText: 2024 the Manim Community Developers
+# SPDX-FileCopyrightText: 2018 3Blue1Brown LLC
+# SPDX-License-Identifier: MIT
+
+"""Continuous motion: updater tools, animated outlines and recorded paths."""
+
+from __future__ import annotations
+
+__all__ = [
+ "AnimatedBoundary",
+ "TracedPath",
+ "always",
+ "always_redraw",
+ "always_rotate",
+ "always_shift",
+ "assert_is_mobject_method",
+ "cycle_animation",
+ "f_always",
+ "turn_animation_into_updater",
+]
+import inspect
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Self, Unpack
+
+import numpy as np
+
+from manimgx.animation import clock
+from manimgx.animation.easing import RateFunction, smooth
+from manimgx.constants import DEGREES, OUT, RIGHT
+from manimgx.drawing.geometry import normalize
+from manimgx.drawing.paint import (
+ BLUE_B,
+ BLUE_D,
+ BLUE_E,
+ GREY_BROWN,
+ WHITE,
+ ParsableManimColor,
+ Style,
+)
+from manimgx.mobject import Mobject, Pivot, VGroup, VMobject, flow, record
+from manimgx.typing import Point3DLike, Vector3DLike
+
+if TYPE_CHECKING:
+ from manimgx.animation.timeline import Animation
+
+
+def _owner(method: Callable[..., object]) -> tuple[Mobject, Callable[..., object]]:
+ """The mobject a bound method belongs to, and its plain function."""
+ if not inspect.ismethod(method) or not isinstance(method.__self__, Mobject):
+ raise TypeError("expected a method of a mobject, such as `square.move_to`")
+ return method.__self__, method.__func__
+
+
+def assert_is_mobject_method(method: Callable[..., object]) -> None:
+ """Check that `method` is a method of a mobject, bound to it (as `square.move_to`):
+ anything else raises a TypeError.
+
+ Args:
+ method: The method to check.
+ """
+ _owner(method)
+
+
+def always[**P](
+ method: Callable[P, object], *args: P.args, **kwargs: P.kwargs
+) -> Mobject:
+ """Call a method of a mobject every frame, with the same arguments: the relation it
+ sets is kept.
+
+ `always(label.next_to, dot, UP)` keeps the label above the dot, wherever the dot
+ goes. It adds a per-frame updater to the mobject the method belongs to (see
+ [`add_updater`][manimgx.Mobject.add_updater]), which first runs at the next frame,
+ not now. The arguments are taken once, as written: pass the mobject to follow
+ (`dot`), not its position (`dot.get_center()`), which would stay where it was.
+ [`Mobject.always`][manimgx.Mobject.always] does the same, as
+ `label.always.next_to(dot, UP)`.
+
+ Args:
+ method: A method of a mobject, bound to it (`label.next_to`).
+ *args: Its positional arguments.
+ **kwargs: Its keyword arguments.
+
+ Returns:
+ The mobject the method belongs to.
+ """
+ mobject, func = _owner(method)
+ mobject.add_updater(lambda m: func(m, *args, **kwargs))
+ return mobject
+
+
+def f_always(
+ method: Callable[..., object],
+ *arg_generators: Callable[[], object],
+ **kwargs: object,
+) -> Mobject:
+ """Call a method of a mobject every frame, with arguments computed anew each time.
+
+ Each positional argument is given as a function of no arguments, called every frame
+ for the value to pass: `f_always(dot.set_x, tracker.get_value)` keeps the dot at the
+ x the tracker holds. It adds a per-frame updater to the mobject the method belongs
+ to (see [`add_updater`][manimgx.Mobject.add_updater]), which first runs at the next
+ frame, not now.
+
+ Args:
+ method: A method of a mobject, bound to it (`dot.set_x`).
+ *arg_generators: For each positional argument, a function of no arguments that
+ gives its value.
+ **kwargs: Keyword arguments, passed as they are.
+
+ Returns:
+ The mobject the method belongs to.
+ """
+ mobject, func = _owner(method)
+ mobject.add_updater(
+ lambda m: func(m, *(generate() for generate in arg_generators), **kwargs)
+ )
+ return mobject
+
+
+def always_redraw[M: Mobject](func: Callable[[], M]) -> M:
+ """Make a mobject that is built anew every frame, by a function.
+
+ `func` builds the mobject now, and every frame the mobject becomes what `func`
+ builds then (see [`become`][manimgx.Mobject.become]): it stays one object in the
+ scene, and follows whatever `func` reads — value trackers, other mobjects. Use it
+ for a shape that depends on others in a way no motion follows: a brace that fits a
+ growing shape, a line between two moving dots, the area under a graph.
+
+ Args:
+ func: A function of no arguments that builds the mobject.
+
+ Returns:
+ The mobject, with its updater: add it to the scene.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class AlwaysRedrawExample(m.Scene):
+ def construct(self) -> None:
+ width = m.ValueTracker(2)
+ box = m.always_redraw(
+ lambda: m.Rectangle(width=width.get_value(), height=3, color=m.BLUE)
+ )
+ brace = m.always_redraw(lambda: m.Brace(box, m.DOWN, color=m.YELLOW))
+ self.add(box, brace)
+ self.play(width.animate.set_value(11), run_time=2)
+ self.play(width.animate.set_value(5))
+ ```
+ """
+ mob = func()
+ mob.add_updater(lambda m: m.become(func()))
+ return mob
+
+
+def always_shift[M: Mobject](
+ mobject: M, direction: Vector3DLike = RIGHT, rate: float = 0.1
+) -> M:
+ """Keep a mobject moving in a direction, at a steady speed.
+
+ It adds a time-based updater, a [flow][manimgx.mobject.flow], so at every frame
+ the mobject is exactly where its speed has brought it, through plays and waits
+ alike.
+
+ Args:
+ mobject: The mobject to move.
+ direction: The direction to move in; only its direction counts, not its length.
+ rate: The speed, in scene units per second.
+
+ Returns:
+ The mobject, with its updater.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class AlwaysShiftExample(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(side_length=2, color=m.BLUE, fill_opacity=0.8)
+ square.shift(5 * m.LEFT)
+ m.always_shift(square, m.RIGHT, rate=2.5)
+ self.add(square)
+ self.play(square.animate.set_color(m.YELLOW), run_time=2)
+ self.wait(2)
+ ```
+ """
+ unit = normalize(direction)
+ mobject.add_updater(flow(lambda m, dt: m.shift(dt * rate * unit)))
+ return mobject
+
+
+def always_rotate[M: Mobject](
+ mobject: M,
+ rate: float = 20 * DEGREES,
+ axis: Vector3DLike = OUT,
+ **kwargs: Unpack[Pivot],
+) -> M:
+ """Keep a mobject turning, at a steady speed.
+
+ It adds a time-based updater, a [flow][manimgx.mobject.flow], so at every frame
+ the mobject is at exactly the angle its speed has brought it to, through plays and
+ waits alike.
+
+ Args:
+ mobject: The mobject to turn.
+ rate: The speed, in radians per second; a positive one turns counterclockwise.
+ axis: The axis it turns about.
+ **kwargs: [Pivot keywords][manimgx.mobject.Pivot]: the point it turns
+ about, its center unless given.
+
+ Returns:
+ The mobject, with its updater.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class AlwaysRotateExample(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(side_length=3, color=m.BLUE, fill_opacity=0.5)
+ square.shift(3.5 * m.LEFT)
+ m.always_rotate(square, rate=m.PI / 2) # a quarter turn a second
+ center = m.Dot(3.5 * m.RIGHT, color=m.YELLOW)
+ moon = m.Dot(3.5 * m.RIGHT + 2 * m.UP, radius=0.25, color=m.TEAL)
+ m.always_rotate(moon, rate=-m.PI, about_point=center.get_center())
+ self.add(square, center, moon)
+ self.wait(4)
+ ```
+ """
+ mobject.add_updater(flow(lambda m, dt: m.rotate(dt * rate, axis, **kwargs)))
+ return mobject
+
+
+def turn_animation_into_updater(
+ animation: Animation, cycle: bool = False, delay: float = 0
+) -> Mobject:
+ """Play an animation from an updater of its mobject, on the mobject's own time,
+ instead of in a play.
+
+ The animation begins at once: it takes its mobject as it is now, and shows its
+ start. Its time then runs with the scene's, from now or from when the mobject joins
+ the scene; after `delay` seconds it plays, at its run time and rate function. When
+ it ends, it finishes and its updater is removed; with `cycle`, it starts over from
+ its beginning instead, again and again. Nothing is added to the scene or taken out
+ of it: add the mobject yourself.
+
+ Args:
+ cycle: Whether it repeats forever.
+ delay: How long it waits before it starts, in seconds.
+
+ Returns:
+ The animation's mobject, with its updater.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class TurnAnimationIntoUpdaterExample(m.Scene):
+ def construct(self) -> None:
+ shape = m.Square(side_length=2, color=m.BLUE, fill_opacity=0.5)
+ squares = m.VGroup(*(shape.copy() for _ in range(3))).arrange(buff=1.5)
+ self.add(squares)
+ for i, square in enumerate(squares): # half a second apart
+ m.turn_animation_into_updater(
+ m.Rotate(square, m.PI / 2, run_time=1), delay=0.5 * i
+ )
+ self.wait(2.5)
+ ```
+ """
+ mobject = animation.mobject
+ animation.suspend_mobject_updating = False
+ animation.begin()
+ animation.interpolate(
+ 0
+ ) # the object is the animation's from now: at its start, until then
+ elapsed = -delay
+
+ def update(m: Mobject, dt: float) -> None:
+ nonlocal elapsed
+ elapsed += dt # its time now: what this frame shows
+ if elapsed < 0:
+ return
+ run_time = animation.get_run_time()
+ if run_time > 0 and (cycle or elapsed < run_time):
+ animation.interpolate(
+ (elapsed / run_time) % 1 if cycle else elapsed / run_time
+ )
+ animation.advance(clock.now)
+ else:
+ animation.finish()
+ m.remove_updater(update)
+
+ mobject.add_updater(flow(update)) # the animation at the time it has run
+ return mobject
+
+
+def cycle_animation(animation: Animation, delay: float = 0) -> Mobject:
+ """Play an animation over and over, from an updater of its mobject:
+ [`turn_animation_into_updater`][manimgx.turn_animation_into_updater] with `cycle`.
+
+ Each cycle starts the animation over from its beginning: an animation that does not
+ end where it began jumps back at every cycle.
+
+ Args:
+ delay: How long it waits before its first cycle, in seconds.
+
+ Returns:
+ The animation's mobject, with its updater.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class CycleAnimationExample(m.Scene):
+ def construct(self) -> None:
+ orbit = m.Circle(radius=3, color=m.BLUE)
+ planet = m.Dot(orbit.get_start(), radius=0.25, color=m.YELLOW)
+ m.cycle_animation(
+ m.MoveAlongPath(planet, orbit, rate_func=m.linear, run_time=2)
+ )
+ self.add(orbit, planet)
+ self.wait(4)
+ ```
+ """
+ return turn_animation_into_updater(animation, cycle=True, delay=delay)
+
+
+class AnimatedBoundary(VGroup):
+ """An outline that keeps drawing itself around a mobject, cycling through colors.
+
+ Each cycle draws the mobject's outline in the next color, while the outline the
+ cycle before drew thins away; with `back_and_forth`, every other cycle draws it the
+ other way around. It follows the mobject: every frame, it takes the mobject's
+ outline as it is then. It draws only the outline: add it to the scene with the
+ mobject.
+
+ Args:
+ vmobject: The mobject to outline.
+ colors: The colors, one per cycle, in turn.
+ max_stroke_width: The outline's stroke width, in hundredths of a scene unit.
+ cycle_rate: How many cycles a second.
+ back_and_forth: Whether every other cycle draws the outline from its end back to
+ its start.
+ draw_rate_func: How each drawing is paced: a rate function.
+ fade_rate_func: How each thinning away is paced: a rate function.
+ **kwargs: [Style keywords][manimgx.drawing.paint.Style] of the group itself.
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class AnimatedBoundaryExample(m.Scene):
+ def construct(self) -> None:
+ word = m.Text("So shiny!", font_size=144)
+ boundary = m.AnimatedBoundary(
+ word,
+ colors=[m.RED, m.YELLOW, m.BLUE],
+ max_stroke_width=8,
+ cycle_rate=1, # a color a second
+ )
+ self.add(word, boundary)
+ self.wait(3)
+ ```
+ """
+
+ def __init__(
+ self,
+ vmobject: Mobject,
+ colors: Sequence[ParsableManimColor] = [BLUE_D, BLUE_B, BLUE_E, GREY_BROWN],
+ max_stroke_width: float = 3,
+ cycle_rate: float = 0.5,
+ back_and_forth: bool = True,
+ draw_rate_func: RateFunction = smooth,
+ fade_rate_func: RateFunction = smooth,
+ **kwargs: Unpack[Style],
+ ):
+ super().__init__(**kwargs)
+ self.colors = colors
+ self.max_stroke_width = max_stroke_width
+ self.cycle_rate = cycle_rate
+ self.back_and_forth = back_and_forth
+ self.draw_rate_func = draw_rate_func
+ self.fade_rate_func = fade_rate_func
+ self.vmobject = vmobject
+ self.boundary_copies = [
+ vmobject.copy().set_style(stroke_width=0, fill_opacity=0) for x in range(2)
+ ]
+ self.add(*self.boundary_copies)
+ self.total_time = 0.0
+ self.add_updater(flow(lambda m, dt: m.update_boundary_copies(dt)))
+
+ def update_boundary_copies(self, dt: float) -> None:
+ """Move the outline on by some time: its updater calls it every frame.
+
+ Args:
+ dt: The time since it last moved on, in seconds.
+ """
+ self.total_time += dt # its time now: what this frame shows
+ time = self.total_time * self.cycle_rate
+ growing, fading = self.boundary_copies
+ colors = self.colors
+ msw = self.max_stroke_width
+ vmobject = self.vmobject
+ index = int(time % len(colors))
+ alpha = time % 1
+ draw_alpha = self.draw_rate_func(alpha)
+ fade_alpha = self.fade_rate_func(alpha)
+ if self.back_and_forth and int(time) % 2 == 1:
+ bounds = (1.0 - draw_alpha, 1.0)
+ else:
+ bounds = (0.0, draw_alpha)
+ self.full_family_become_partial(growing, vmobject, *bounds)
+ growing.set_stroke(colors[index], width=msw)
+ if time >= 1:
+ self.full_family_become_partial(fading, vmobject, 0, 1)
+ fading.set_stroke(color=colors[index - 1], width=(1 - fade_alpha) * msw)
+
+ def full_family_become_partial(
+ self, mob1: Mobject, mob2: Mobject, a: float, b: float
+ ) -> Self:
+ """Make each drawn member of one mobject a stretch of its counterpart in
+ another.
+
+ The members with points are paired in family order; each member of `mob1` takes
+ the stretch of its counterpart from proportion `a` to proportion `b` of its
+ curves.
+
+ Args:
+ mob1: The mobject whose members change.
+ mob2: The mobject whose members they take stretches of.
+ a: Where each stretch starts, from 0 to 1.
+ b: Where it ends, from `a` to 1.
+
+ Returns:
+ This boundary, for chaining.
+ """
+ family1 = mob1.family_members_with_points()
+ family2 = mob2.family_members_with_points()
+ for sm1, sm2 in zip(family1, family2, strict=False):
+ sm1.pointwise_become_partial(sm2, a, b)
+ return self
+
+
+class TracedPath(VMobject):
+ """The path a moving point traces: a line through everywhere it has been.
+
+ `traced_point_func` gives the point. The path records where it is at every tick of
+ the simulation clock
+ ([`config.simulation_rate`][manimgx.config.Config.simulation_rate] times a second)
+ and at the end of each play and wait, so it is the same path at any frame rate; at a
+ frame between two ticks, it runs on to where the point is then. It traces while it
+ is in the scene, from when it joins it, and at each instant once everything else
+ has moved: its updater is a [recorder][manimgx.mobject.record].
+
+ A per-frame updater moves the point at frames only, so what it moves the point by
+ at a frame is its change over the frame that ends there: the path spreads that move
+ over the frame, in proportion to time. A point that a play carries while a
+ per-frame updater turns it traces one smooth curve, not stairs. With
+ `dissipating_time`, only the stretch traced in the last that many seconds remains.
+
+ Args:
+ traced_point_func: A function of no arguments that gives the point to trace
+ (`dot.get_center`).
+ dissipating_time: How long each stretch of the path remains, in seconds; None:
+ all of it remains.
+ **kwargs: [Style keywords][manimgx.drawing.paint.Style] (by default a white stroke,
+ 2 wide).
+
+ Examples:
+ ```python
+ import manimgx as m
+
+
+ class TracedPathExample(m.Scene):
+ def construct(self) -> None:
+ wheel = m.Circle(radius=1, color=m.BLUE).shift(5 * m.LEFT)
+ dot = m.Dot(wheel.get_bottom(), radius=0.12, color=m.YELLOW)
+ rolling = m.VGroup(wheel, dot)
+ path = m.TracedPath(
+ dot.get_center, stroke_color=m.YELLOW, stroke_width=4
+ )
+
+ def roll(mob: m.Mobject, dt: float) -> None: # 2.5 radians a second
+ mob.rotate(-2.5 * dt, about_point=mob[0].get_center())
+
+ rolling.add_updater(roll)
+ self.add(path, rolling)
+ # 2.5 units a second: the wheel rolls without slipping
+ self.play(
+ rolling.animate.shift(10 * m.RIGHT), run_time=4, rate_func=m.linear
+ )
+ ```
+ """
+
+ def __init__(
+ self,
+ traced_point_func: Callable[[], Point3DLike],
+ dissipating_time: float | None = None,
+ **kwargs: Unpack[Style],
+ ) -> None:
+ if kwargs.get("stroke_color") is None: # not given, None too
+ kwargs["stroke_color"] = WHITE
+ if kwargs.get("stroke_width") is None: # not given, None too
+ kwargs["stroke_width"] = 2
+ super().__init__(**kwargs)
+ self.traced_point_func = traced_point_func
+ self.dissipating_time = dissipating_time
+ self.time = 0.0 # the path's own time
+ self._traced: list[float] = (
+ []
+ ) # when each curve's end was traced (its own time)
+ self._open: list[float] = (
+ []
+ ) # the scene time of each curve's end since the last frame
+ self._framed: float | None = None # the scene time of the last frame (or event)
+ self._last = np.zeros(3) # the point as last traced
+ self._loose = (
+ False # its last curve runs on to the point at a frame between two ticks
+ )
+ self.add_updater(self.update_path)
+
+ @record
+ def update_path(self, mob: Mobject, dt: float) -> None:
+ """Trace the point where it is now: the path's updater, a
+ [recorder][manimgx.mobject.record].
+
+ At a tick of the simulation clock or at the end of a play or wait, the point is
+ traced for good; at a frame between two ticks, the path runs on to it, a
+ stretch the next instant takes back. A frame or an end runs it a second time
+ once the per-frame updaters have run: what they moved the point by is spread
+ over the frame that ends there, each stretch traced since the frame before
+ moved by its share of the frame's time. A dissipating path then drops what it
+ traced more than `dissipating_time` seconds ago.
+
+ Args:
+ mob: The path the updater runs on.
+ dt: The time since it last ran, in seconds.
+ """
+ # the second run is the instant's second pass (`clock.framing`, see
+ # `Scene._instant`): `_settle` spreads the move
+ point = np.asarray(self.traced_point_func(), dtype=float)
+ now = float(clock.now)
+ if clock.framing:
+ self._settle(point, now)
+ return
+ if self._loose:
+ self._loose = False
+ self.set_points(self.points[: -self.n_points_per_curve])
+ self._open.pop()
+ if self.has_points():
+ self._last = self.points[-1].copy()
+ self.time += dt
+ if not clock.stepping: # a frame between two ticks: loose, if the point moved
+ if not self.has_points() or not np.array_equal(point, self._last):
+ self._trace(point, now)
+ self._loose = True
+ return
+ self._trace(point, now)
+ if self.dissipating_time:
+ self._traced.append(self.time)
+ old = 0
+ while self._traced[old] < self.time - self.dissipating_time:
+ old += 1
+ if old:
+ del self._traced[:old]
+ self.set_points(self.points[old * self.n_points_per_curve :])
+ del self._open[: max(0, len(self._open) - len(self._traced))]
+
+ def _trace(self, point: np.ndarray, now: float) -> None:
+ if not self.has_points():
+ self.start_new_path(point)
+ self.add_line_to(point)
+ self._open.append(now)
+ self._last = point
+
+ def _settle(self, point: np.ndarray, now: float) -> None:
+ """The frame (or event) ending `now` moved the point on to `point`: each curve traced
+ since the last one takes its share of that move, by when it was traced. A curve's
+ handles move with its anchors, so it stays straight."""
+ jump = point - self._last
+ if jump.any():
+ if not self._open or self._open[-1] != now: # nothing traced here yet
+ self._trace(self._last, now)
+ self._loose = True
+ start = self._open[0] if self._framed is None else self._framed
+ span = now - start
+ ends = np.array(
+ [(t - start) / span if span > 0 else 1.0 for t in self._open]
+ )
+ first = ends[0] if self._framed is None else 0.0
+ starts = np.concatenate(([first], ends[:-1]))
+ weights = np.stack(
+ (starts, (2 * starts + ends) / 3, (starts + 2 * ends) / 3, ends), axis=1
+ ).reshape(-1, 1)
+ points = self.points.copy()
+ points[-len(weights) :] += weights * jump
+ self.set_points(points)
+ self._last = point
+ self._open = [now] if self._loose else []
+ self._framed = now
diff --git a/tests/unit/animation/test_updaters.py b/tests/unit/animation/test_updaters.py
new file mode 100644
index 00000000..97969a71
--- /dev/null
+++ b/tests/unit/animation/test_updaters.py
@@ -0,0 +1,115 @@
+"""An updater acts on the mobject it runs on: a replica of an updating mobject is a mobject of
+its own.
+
+- For every built-in updater (`always_redraw`, `always`, `f_always`, `always_shift`,
+ `always_rotate`, `turn_animation_into_updater`, an `AnimatedBoundary`'s, a `TracedPath`'s) and
+ a method of the mobject's own: a replica (a copy, a target, a saved state, or a mobject that
+ took the updaters over with `match_updaters`) runs them on itself, and leaves its original
+ as it was.
+- A replica does not keep its original alive.
+"""
+
+import gc
+import weakref
+from collections.abc import Callable
+
+import numpy as np
+import pytest
+from tests.oracles import look
+
+import manimgx as m
+
+type Updating = tuple[m.Mobject, Callable[[], object]]
+
+
+def redrawn() -> Updating:
+ x = m.ValueTracker(0.0)
+ return m.always_redraw(lambda: m.Dot([x.get_value(), 0, 0])), lambda: x.set_value(1)
+
+
+def following() -> Updating:
+ dot = m.Dot(m.RIGHT)
+ return m.always(m.Square().next_to, dot, m.UP), lambda: dot.shift(m.RIGHT)
+
+
+def tracking() -> Updating:
+ x = m.ValueTracker(0.0)
+ return m.f_always(m.Square().set_x, x.get_value), lambda: x.set_value(1)
+
+
+def traced() -> Updating:
+ dot = m.Dot()
+ return m.TracedPath(lambda: dot.get_center()), lambda: dot.shift(m.RIGHT)
+
+
+class Stepping(m.Square):
+ """A square whose updater is a method of its own, acting on itself."""
+
+ def step(self, mob: m.Mobject, dt: float) -> None:
+ self.shift(dt * m.RIGHT)
+
+
+def stepping() -> Updating:
+ square = Stepping()
+ return square.add_updater(square.step), lambda: None
+
+
+# an updating mobject, and a change of what its updaters read
+UPDATING: dict[str, Callable[[], Updating]] = {
+ "always_redraw": redrawn,
+ "always": following,
+ "f_always": tracking,
+ "always_shift": lambda: (m.always_shift(m.Square(), m.RIGHT, 1.0), lambda: None),
+ "always_rotate": lambda: (m.always_rotate(m.Square()), lambda: None),
+ "turn_animation_into_updater": lambda: (
+ m.turn_animation_into_updater(m.Rotate(m.Square(), 1.0)),
+ lambda: None,
+ ),
+ "AnimatedBoundary": lambda: (m.AnimatedBoundary(m.Square()), lambda: None),
+ "TracedPath": traced,
+ "a method of its own": stepping,
+}
+REPLICAS: dict[str, Callable[[m.Mobject], m.Mobject | None]] = {
+ "copy": lambda mob: mob.copy(),
+ "target": lambda mob: mob.generate_target(),
+ "saved state": lambda mob: mob.save_state().saved_state,
+ "match_updaters": lambda mob: mob.copy().clear_updaters().match_updaters(mob),
+}
+
+
+def cases(replicas: list[str]) -> list[tuple[str, str]]:
+ return [
+ (name, replica)
+ for name in UPDATING
+ for replica in replicas
+ # match_updaters gives the same functions: a user's method stays its mobject's
+ if not (name == "a method of its own" and replica == "match_updaters")
+ ]
+
+
[email protected](("name", "replica"), cases(list(REPLICAS)))
+def test_a_replica_updates_itself_and_leaves_its_original(
+ name: str, replica: str
+) -> None:
+ original, change = UPDATING[name]()
+ clone = REPLICAS[replica](original)
+ assert clone is not None
+ before, start = look(original), look(clone)
+ change()
+ clone.update(0.5)
+ assert look(clone) != start, "the replica's updaters did not run on it"
+ assert look(original) == before
+
+
[email protected](("name", "replica"), cases(["copy", "match_updaters"]))
+def test_a_replica_does_not_keep_its_original_alive(name: str, replica: str) -> None:
+ original, change = UPDATING[name]()
+ clone = REPLICAS[replica](original)
+ assert clone is not None
+ alive = weakref.ref(original)
+ del original
+ gc.collect()
+ assert alive() is None
+ change()
+ clone.update(0.25)
+ assert np.isfinite(clone.get_center()).all()