manim 0.18.0.post0__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/animation/animation.py

@@ -1,6 +1,5 @@
 """Animate mobjects."""
 
-
 from __future__ import annotations
 
 from manim.mobject.opengl.opengl_mobject import OpenGLMobject
@@ -8,15 +7,19 @@ from manim.mobject.opengl.opengl_mobject import OpenGLMobject
 from .. import config, logger
 from ..constants import RendererType
 from ..mobject import mobject
-from ..mobject.mobject import Mobject
+from ..mobject.mobject import Group, Mobject
 from ..mobject.opengl import opengl_mobject
 from ..utils.rate_functions import linear, smooth
 
-__all__ = ["Animation", "Wait", "override_animation"]
+__all__ = ["Animation", "Wait", "Add", "override_animation"]
 
 
+from collections.abc import Iterable, Sequence
 from copy import deepcopy
-from typing import TYPE_CHECKING, Callable, Iterable, Sequence
+from functools import partialmethod
+from typing import TYPE_CHECKING, Any, Callable
+
+from typing_extensions import Self
 
 if TYPE_CHECKING:
     from manim.scene.scene import Scene
@@ -112,7 +115,7 @@ class Animation:
         *args,
         use_override=True,
         **kwargs,
-    ):
+    ) -> Self:
         if isinstance(mobject, Mobject) and use_override:
             func = mobject.animation_override_for(cls)
             if func is not None:
@@ -169,6 +172,19 @@ class Animation:
                 ),
             )
 
+    @property
+    def run_time(self) -> float:
+        return self._run_time
+
+    @run_time.setter
+    def run_time(self, value: float) -> None:
+        if value < 0:
+            raise ValueError(
+                f"The run_time of {self.__class__.__name__} cannot be "
+                f"negative. The given value was {value}."
+            )
+        self._run_time = value
+
     def _typecheck_input(self, mobject: Mobject | None) -> None:
         if mobject is None:
             logger.debug("Animation with empty mobject")
@@ -398,6 +414,7 @@ class Animation:
         self.run_time = run_time
         return self
 
+    # TODO: is this getter even necessary?
     def get_run_time(self) -> float:
         """Get the run time of the animation.
 
@@ -476,6 +493,52 @@ class Animation:
         """
         return self.introducer
 
+    @classmethod
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+
+        cls._original__init__ = cls.__init__
+
+    @classmethod
+    def set_default(cls, **kwargs) -> None:
+        """Sets the default values of keyword arguments.
+
+        If this method is called without any additional keyword
+        arguments, the original default values of the initialization
+        method of this class are restored.
+
+        Parameters
+        ----------
+
+        kwargs
+            Passing any keyword argument will update the default
+            values of the keyword arguments of the initialization
+            function of this class.
+
+        Examples
+        --------
+
+        .. manim:: ChangeDefaultAnimation
+
+            class ChangeDefaultAnimation(Scene):
+                def construct(self):
+                    Rotate.set_default(run_time=2, rate_func=rate_functions.linear)
+                    Indicate.set_default(color=None)
+
+                    S = Square(color=BLUE, fill_color=BLUE, fill_opacity=0.25)
+                    self.add(S)
+                    self.play(Rotate(S, PI))
+                    self.play(Indicate(S))
+
+                    Rotate.set_default()
+                    Indicate.set_default()
+
+        """
+        if kwargs:
+            cls.__init__ = partialmethod(cls.__init__, **kwargs)
+        else:
+            cls.__init__ = cls._original__init__
+
 
 def prepare_animation(
     anim: Animation | mobject._AnimationBuilder,
@@ -575,6 +638,90 @@ class Wait(Animation):
         pass
 
 
+class Add(Animation):
+    """Add Mobjects to a scene, without animating them in any other way. This
+    is similar to the :meth:`.Scene.add` method, but :class:`Add` is an
+    animation which can be grouped into other animations.
+
+    Parameters
+    ----------
+    mobjects
+        One :class:`~.Mobject` or more to add to a scene.
+    run_time
+        The duration of the animation after adding the ``mobjects``. Defaults
+        to 0, which means this is an instant animation without extra wait time
+        after adding them.
+    **kwargs
+        Additional arguments to pass to the parent :class:`Animation` class.
+
+    Examples
+    --------
+
+    .. manim:: DefaultAddScene
+
+        class DefaultAddScene(Scene):
+            def construct(self):
+                text_1 = Text("I was added with Add!")
+                text_2 = Text("Me too!")
+                text_3 = Text("And me!")
+                texts = VGroup(text_1, text_2, text_3).arrange(DOWN)
+                rect = SurroundingRectangle(texts, buff=0.5)
+
+                self.play(
+                    Create(rect, run_time=3.0),
+                    Succession(
+                        Wait(1.0),
+                        # You can Add a Mobject in the middle of an animation...
+                        Add(text_1),
+                        Wait(1.0),
+                        # ...or multiple Mobjects at once!
+                        Add(text_2, text_3),
+                    ),
+                )
+                self.wait()
+
+    .. manim:: AddWithRunTimeScene
+
+        class AddWithRunTimeScene(Scene):
+            def construct(self):
+                # A 5x5 grid of circles
+                circles = VGroup(
+                    *[Circle(radius=0.5) for _ in range(25)]
+                ).arrange_in_grid(5, 5)
+
+                self.play(
+                    Succession(
+                        # Add a run_time of 0.2 to wait for 0.2 seconds after
+                        # adding the circle, instead of using Wait(0.2) after Add!
+                        *[Add(circle, run_time=0.2) for circle in circles],
+                        rate_func=smooth,
+                    )
+                )
+                self.wait()
+    """
+
+    def __init__(
+        self, *mobjects: Mobject, run_time: float = 0.0, **kwargs: Any
+    ) -> None:
+        mobject = mobjects[0] if len(mobjects) == 1 else Group(*mobjects)
+        super().__init__(mobject, run_time=run_time, introducer=True, **kwargs)
+
+    def begin(self) -> None:
+        pass
+
+    def finish(self) -> None:
+        pass
+
+    def clean_up_from_scene(self, scene: Scene) -> None:
+        pass
+
+    def update_mobjects(self, dt: float) -> None:
+        pass
+
+    def interpolate(self, alpha: float) -> None:
+        pass
+
+
 def override_animation(
     animation_class: type[Animation],
 ) -> Callable[[Callable], Callable]:

manim/animation/composition.py

@@ -1,26 +1,26 @@
 """Tools for displaying multiple animations at once."""
 
-
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Callable, Sequence
+import types
+from collections.abc import Iterable, Sequence
+from typing import TYPE_CHECKING, Callable
 
 import numpy as np
 
+from manim._config import config
+from manim.animation.animation import Animation, prepare_animation
+from manim.constants import RendererType
+from manim.mobject.mobject import Group, Mobject
 from manim.mobject.opengl.opengl_mobject import OpenGLGroup
-
-from .._config import config
-from ..animation.animation import Animation, prepare_animation
-from ..constants import RendererType
-from ..mobject.mobject import Group, Mobject
-from ..scene.scene import Scene
-from ..utils.iterables import remove_list_redundancies
-from ..utils.rate_functions import linear
+from manim.scene.scene import Scene
+from manim.utils.iterables import remove_list_redundancies
+from manim.utils.parameter_parsing import flatten_iterable_parameters
+from manim.utils.rate_functions import linear
 
 if TYPE_CHECKING:
     from manim.mobject.opengl.opengl_vectorized_mobject import OpenGLVGroup
-
-    from ..mobject.types.vectorized_mobject import VGroup
+    from manim.mobject.types.vectorized_mobject import VGroup
 
 __all__ = ["AnimationGroup", "Succession", "LaggedStart", "LaggedStartMap"]
 
@@ -54,14 +54,15 @@ class AnimationGroup(Animation):
 
     def __init__(
         self,
-        *animations: Animation,
+        *animations: Animation | Iterable[Animation] | types.GeneratorType[Animation],
         group: Group | VGroup | OpenGLGroup | OpenGLVGroup = None,
         run_time: float | None = None,
         rate_func: Callable[[float], float] = linear,
         lag_ratio: float = 0,
         **kwargs,
     ) -> None:
-        self.animations = [prepare_animation(anim) for anim in animations]
+        arg_anim = flatten_iterable_parameters(animations)
+        self.animations = [prepare_animation(anim) for anim in arg_anim]
         self.rate_func = rate_func
         self.group = group
         if self.group is None:
@@ -81,6 +82,12 @@ class AnimationGroup(Animation):
         return list(self.group)
 
     def begin(self) -> None:
+        if not self.animations:
+            raise ValueError(
+                f"Trying to play {self} without animations, this is not supported. "
+                "Please add at least one subanimation."
+            )
+        self.anim_group_time = 0.0
         if self.suspend_mobject_updating:
             self.group.suspend_updating()
         for anim in self.animations:
@@ -93,6 +100,8 @@ class AnimationGroup(Animation):
     def finish(self) -> None:
         for anim in self.animations:
             anim.finish()
+        self.anims_begun[:] = True
+        self.anims_finished[:] = True
         if self.suspend_mobject_updating:
             self.group.resume_updating()
 
@@ -104,7 +113,9 @@ class AnimationGroup(Animation):
             anim.clean_up_from_scene(scene)
 
     def update_mobjects(self, dt: float) -> None:
-        for anim in self.animations:
+        for anim in self.anims_with_timings["anim"][
+            self.anims_begun & ~self.anims_finished
+        ]:
             anim.update_mobjects(dt)
 
     def init_run_time(self, run_time) -> float:
@@ -121,22 +132,30 @@ class AnimationGroup(Animation):
             The duration of the animation in seconds.
         """
         self.build_animations_with_timings()
-        if self.anims_with_timings:
-            self.max_end_time = np.max([awt[2] for awt in self.anims_with_timings])
-        else:
-            self.max_end_time = 0
+        # Note: if lag_ratio < 1, then not necessarily the final animation's
+        # end time will be the max end time! Therefore we must calculate the
+        # maximum over all the end times, and not just take the last one.
+        # Example: if you want to play 2 animations of 10s and 1s with a
+        # lag_ratio of 0.1, the 1st one will end at t=10 and the 2nd one will
+        # end at t=2, so the AnimationGroup will end at t=10.
+        self.max_end_time = max(self.anims_with_timings["end"], default=0)
         return self.max_end_time if run_time is None else run_time
 
     def build_animations_with_timings(self) -> None:
         """Creates a list of triplets of the form (anim, start_time, end_time)."""
-        self.anims_with_timings = []
-        curr_time: float = 0
-        for anim in self.animations:
-            start_time: float = curr_time
-            end_time: float = start_time + anim.get_run_time()
-            self.anims_with_timings.append((anim, start_time, end_time))
-            # Start time of next animation is based on the lag_ratio
-            curr_time = (1 - self.lag_ratio) * start_time + self.lag_ratio * end_time
+        run_times = np.array([anim.run_time for anim in self.animations])
+        num_animations = run_times.shape[0]
+        dtype = [("anim", "O"), ("start", "f8"), ("end", "f8")]
+        self.anims_with_timings = np.zeros(num_animations, dtype=dtype)
+        self.anims_begun = np.zeros(num_animations, dtype=bool)
+        self.anims_finished = np.zeros(num_animations, dtype=bool)
+        if num_animations == 0:
+            return
+
+        lags = run_times[:-1] * self.lag_ratio
+        self.anims_with_timings["anim"] = self.animations
+        self.anims_with_timings["start"][1:] = np.add.accumulate(lags)
+        self.anims_with_timings["end"] = self.anims_with_timings["start"] + run_times
 
     def interpolate(self, alpha: float) -> None:
         # Note, if the run_time of AnimationGroup has been
@@ -144,14 +163,32 @@ class AnimationGroup(Animation):
         # times might not correspond to actual times,
         # e.g. of the surrounding scene.  Instead they'd
         # be a rescaled version.  But that's okay!
-        time = self.rate_func(alpha) * self.max_end_time
-        for anim, start_time, end_time in self.anims_with_timings:
-            anim_time = end_time - start_time
-            if anim_time == 0:
-                sub_alpha = 0
-            else:
-                sub_alpha = np.clip((time - start_time) / anim_time, 0, 1)
-            anim.interpolate(sub_alpha)
+        anim_group_time = self.rate_func(alpha) * self.max_end_time
+        time_goes_back = anim_group_time < self.anim_group_time
+
+        # Only update ongoing animations
+        awt = self.anims_with_timings
+        new_begun = anim_group_time >= awt["start"]
+        new_finished = anim_group_time > awt["end"]
+        to_update = awt[
+            (self.anims_begun | new_begun) & (~self.anims_finished | ~new_finished)
+        ]
+
+        run_times = to_update["end"] - to_update["start"]
+        with_zero_run_time = run_times == 0
+        run_times[with_zero_run_time] = 1
+        sub_alphas = (anim_group_time - to_update["start"]) / run_times
+        if time_goes_back:
+            sub_alphas[(sub_alphas < 0) | with_zero_run_time] = 0
+        else:
+            sub_alphas[(sub_alphas > 1) | with_zero_run_time] = 1
+
+        for anim_to_update, sub_alpha in zip(to_update["anim"], sub_alphas):
+            anim_to_update.interpolate(sub_alpha)
+
+        self.anim_group_time = anim_group_time
+        self.anims_begun = new_begun
+        self.anims_finished = new_finished
 
 
 class Succession(AnimationGroup):
@@ -195,7 +232,11 @@ class Succession(AnimationGroup):
         super().__init__(*animations, lag_ratio=lag_ratio, **kwargs)
 
     def begin(self) -> None:
-        assert len(self.animations) > 0
+        if not self.animations:
+            raise ValueError(
+                f"Trying to play {self} without animations, this is not supported. "
+                "Please add at least one subanimation."
+            )
         self.update_active_animation(0)
 
     def finish(self) -> None:
@@ -226,8 +267,8 @@ class Succession(AnimationGroup):
             self.active_animation = self.animations[index]
             self.active_animation._setup_scene(self.scene)
             self.active_animation.begin()
-            self.active_start_time = self.anims_with_timings[index][1]
-            self.active_end_time = self.anims_with_timings[index][2]
+            self.active_start_time = self.anims_with_timings[index]["start"]
+            self.active_end_time = self.anims_with_timings[index]["end"]
 
     def next_animation(self) -> None:
         """Proceeds to the next animation.
@@ -244,7 +285,7 @@ class Succession(AnimationGroup):
             self.next_animation()
         if self.active_animation is not None and self.active_start_time is not None:
             elapsed = current_time - self.active_start_time
-            active_run_time = self.active_animation.get_run_time()
+            active_run_time = self.active_animation.run_time
             subalpha = elapsed / active_run_time if active_run_time != 0.0 else 1.0
             self.active_animation.interpolate(subalpha)
 

manim/animation/creation.py

@@ -70,17 +70,22 @@ __all__ = [
     "RemoveTextLetterByLetter",
     "ShowSubmobjectsOneByOne",
     "AddTextWordByWord",
+    "TypeWithCursor",
+    "UntypeWithCursor",
 ]
 
 
 import itertools as it
-from typing import TYPE_CHECKING, Callable, Iterable, Sequence
+from collections.abc import Iterable, Sequence
+from typing import TYPE_CHECKING, Callable
 
 import numpy as np
 
 if TYPE_CHECKING:
     from manim.mobject.text.text_mobject import Text
+    from manim.scene.scene import Scene
 
+from manim.constants import RIGHT, TAU
 from manim.mobject.opengl.opengl_surface import OpenGLSurface
 from manim.mobject.opengl.opengl_vectorized_mobject import OpenGLVMobject
 from manim.utils.color import ManimColor
@@ -88,7 +93,6 @@ from manim.utils.color import ManimColor
 from .. import config
 from ..animation.animation import Animation
 from ..animation.composition import Succession
-from ..constants import TAU
 from ..mobject.mobject import Group, Mobject
 from ..mobject.types.vectorized_mobject import VMobject
 from ..utils.bezier import integer_interpolate
@@ -246,7 +250,9 @@ class DrawBorderThenFill(Animation):
 
     def _typecheck_input(self, vmobject: VMobject | OpenGLVMobject) -> None:
         if not isinstance(vmobject, (VMobject, OpenGLVMobject)):
-            raise TypeError("DrawBorderThenFill only works for vectorized Mobjects")
+            raise TypeError(
+                f"{self.__class__.__name__} only works for vectorized Mobjects"
+            )
 
     def begin(self) -> None:
         self.outline = self.get_outline()
@@ -277,7 +283,7 @@ class DrawBorderThenFill(Animation):
         alpha: float,
     ) -> None:  # Fixme: not matching the parent class? What is outline doing here?
         index: int
-        subalpha: int
+        subalpha: float
         index, subalpha = integer_interpolate(0, 2, alpha)
         if index == 0:
             submobject.pointwise_become_partial(outline, 0, subalpha)
@@ -347,10 +353,7 @@ class Write(DrawBorderThenFill):
     ) -> tuple[float, float]:
         length = len(vmobject.family_members_with_points())
         if run_time is None:
-            if length < 15:
-                run_time = 1
-            else:
-                run_time = 2
+            run_time = 1 if length < 15 else 2
         if lag_ratio is None:
             lag_ratio = min(4.0 / max(1.0, length), 0.2)
         return run_time, lag_ratio
@@ -456,7 +459,7 @@ class SpiralIn(Animation):
         fade_in_fraction=0.3,
         **kwargs,
     ) -> None:
-        self.shapes = shapes
+        self.shapes = shapes.copy()
         self.scale_factor = scale_factor
         self.shape_center = shapes.get_center()
         self.fade_in_fraction = fade_in_fraction
@@ -473,15 +476,21 @@ class SpiralIn(Animation):
 
     def interpolate_mobject(self, alpha: float) -> None:
         alpha = self.rate_func(alpha)
-        for shape in self.shapes:
+        for original_shape, shape in zip(self.shapes, self.mobject):
             shape.restore()
-            shape.save_state()
-            opacity = shape.get_fill_opacity()
-            new_opacity = min(opacity, alpha * opacity / self.fade_in_fraction)
+            fill_opacity = original_shape.get_fill_opacity()
+            stroke_opacity = original_shape.get_stroke_opacity()
+            new_fill_opacity = min(
+                fill_opacity, alpha * fill_opacity / self.fade_in_fraction
+            )
+            new_stroke_opacity = min(
+                stroke_opacity, alpha * stroke_opacity / self.fade_in_fraction
+            )
             shape.shift((shape.final_position - shape.initial_position) * alpha)
             shape.rotate(TAU * alpha, about_point=self.shape_center)
             shape.rotate(-TAU * alpha, about_point=shape.get_center_of_mass())
-            shape.set_opacity(new_opacity)
+            shape.set_fill(opacity=new_fill_opacity)
+            shape.set_stroke(opacity=new_stroke_opacity)
 
 
 class ShowIncreasingSubsets(Animation):
@@ -668,3 +677,176 @@ class AddTextWordByWord(Succession):
             )
         )
         super().__init__(*anims, **kwargs)
+
+
+class TypeWithCursor(AddTextLetterByLetter):
+    """Similar to :class:`~.AddTextLetterByLetter` , but with an additional cursor mobject at the end.
+
+    Parameters
+    ----------
+    time_per_char
+        Frequency of appearance of the letters.
+    cursor
+        :class:`~.Mobject` shown after the last added letter.
+    buff
+        Controls how far away the cursor is to the right of the last added letter.
+    keep_cursor_y
+        If ``True``, the cursor's y-coordinate is set to the center of the ``Text`` and remains the same throughout the animation. Otherwise, it is set to the center of the last added letter.
+    leave_cursor_on
+        Whether to show the cursor after the animation.
+
+    .. tip::
+        This is currently only possible for class:`~.Text` and not for class:`~.MathTex`.
+
+
+    Examples
+    --------
+
+    .. manim:: InsertingTextExample
+        :ref_classes: Blink
+
+        class InsertingTextExample(Scene):
+            def construct(self):
+                text = Text("Inserting", color=PURPLE).scale(1.5).to_edge(LEFT)
+                cursor = Rectangle(
+                    color = GREY_A,
+                    fill_color = GREY_A,
+                    fill_opacity = 1.0,
+                    height = 1.1,
+                    width = 0.5,
+                ).move_to(text[0]) # Position the cursor
+
+                self.play(TypeWithCursor(text, cursor))
+                self.play(Blink(cursor, blinks=2))
+
+    """
+
+    def __init__(
+        self,
+        text: Text,
+        cursor: Mobject,
+        buff: float = 0.1,
+        keep_cursor_y: bool = True,
+        leave_cursor_on: bool = True,
+        time_per_char: float = 0.1,
+        reverse_rate_function=False,
+        introducer=True,
+        **kwargs,
+    ) -> None:
+        self.cursor = cursor
+        self.buff = buff
+        self.keep_cursor_y = keep_cursor_y
+        self.leave_cursor_on = leave_cursor_on
+        super().__init__(
+            text,
+            time_per_char=time_per_char,
+            reverse_rate_function=reverse_rate_function,
+            introducer=introducer,
+            **kwargs,
+        )
+
+    def begin(self) -> None:
+        self.y_cursor = self.cursor.get_y()
+        self.cursor.initial_position = self.mobject.get_center()
+        if self.keep_cursor_y:
+            self.cursor.set_y(self.y_cursor)
+
+        self.cursor.set_opacity(0)
+        self.mobject.add(self.cursor)
+        super().begin()
+
+    def finish(self) -> None:
+        if self.leave_cursor_on:
+            self.cursor.set_opacity(1)
+        else:
+            self.cursor.set_opacity(0)
+            self.mobject.remove(self.cursor)
+        super().finish()
+
+    def clean_up_from_scene(self, scene: Scene) -> None:
+        if not self.leave_cursor_on:
+            scene.remove(self.cursor)
+        super().clean_up_from_scene(scene)
+
+    def update_submobject_list(self, index: int) -> None:
+        for mobj in self.all_submobs[:index]:
+            mobj.set_opacity(1)
+
+        for mobj in self.all_submobs[index:]:
+            mobj.set_opacity(0)
+
+        if index != 0:
+            self.cursor.next_to(
+                self.all_submobs[index - 1], RIGHT, buff=self.buff
+            ).set_y(self.cursor.initial_position[1])
+        else:
+            self.cursor.move_to(self.all_submobs[0]).set_y(
+                self.cursor.initial_position[1]
+            )
+
+        if self.keep_cursor_y:
+            self.cursor.set_y(self.y_cursor)
+        self.cursor.set_opacity(1)
+
+
+class UntypeWithCursor(TypeWithCursor):
+    """Similar to :class:`~.RemoveTextLetterByLetter` , but with an additional cursor mobject at the end.
+
+    Parameters
+    ----------
+    time_per_char
+        Frequency of appearance of the letters.
+    cursor
+        :class:`~.Mobject` shown after the last added letter.
+    buff
+        Controls how far away the cursor is to the right of the last added letter.
+    keep_cursor_y
+        If ``True``, the cursor's y-coordinate is set to the center of the ``Text`` and remains the same throughout the animation. Otherwise, it is set to the center of the last added letter.
+    leave_cursor_on
+        Whether to show the cursor after the animation.
+
+    .. tip::
+        This is currently only possible for class:`~.Text` and not for class:`~.MathTex`.
+
+
+    Examples
+    --------
+
+    .. manim:: DeletingTextExample
+        :ref_classes: Blink
+
+        class DeletingTextExample(Scene):
+            def construct(self):
+                text = Text("Deleting", color=PURPLE).scale(1.5).to_edge(LEFT)
+                cursor = Rectangle(
+                    color = GREY_A,
+                    fill_color = GREY_A,
+                    fill_opacity = 1.0,
+                    height = 1.1,
+                    width = 0.5,
+                ).move_to(text[0]) # Position the cursor
+
+                self.play(UntypeWithCursor(text, cursor))
+                self.play(Blink(cursor, blinks=2))
+
+    """
+
+    def __init__(
+        self,
+        text: Text,
+        cursor: VMobject | None = None,
+        time_per_char: float = 0.1,
+        reverse_rate_function=True,
+        introducer=False,
+        remover=True,
+        **kwargs,
+    ) -> None:
+        super().__init__(
+            text,
+            cursor=cursor,
+            time_per_char=time_per_char,
+            reverse_rate_function=reverse_rate_function,
+            introducer=introducer,
+            remover=remover,
+            **kwargs,
+        )