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.pyindex 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 thatmatch move to their counterparts, and the others fade.diff --git a/src/manimgx/animation/transform.py b/src/manimgx/animation/transform.pyindex 7d001631..65ef93f0 100644--- a/src/manimgx/animation/transform.py+++ b/src/manimgx/animation/transform.py@@ -9,6 +9,7 @@ import functoolsimport inspectfrom collections.abc import Callable, Sequencefrom typing import TYPE_CHECKING, Never, Protocol, Self, Unpack, cast, overload+from warnings import deprecatedimport 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 Besidefrom manimgx.mobjects.numbers import DecimalNumberfrom 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 ownclass), 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 thestart 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 astraight 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 takesthe mobject's place when the animation finishes. Presets withoutsuch 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, orNone.@@ -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 (frameif 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 beforeit). 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 itscenter in a straight line; and the rest of the change (a scale, a color, a newshape) happens along the way. A `path_arc` or `path_func` of its own replaces thatmotion.@@ -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.pynew file mode 100644index 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 = nowdiff --git a/tests/unit/animation/test_updaters.py b/tests/unit/animation/test_updaters.pynew file mode 100644index 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()