manim 0.17.0__py3-none-any.whl → 0.19.1__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 Callable, Iterable, Sequence
 from copy import deepcopy
-from typing import TYPE_CHECKING, Callable, Iterable, Sequence
+from functools import partialmethod
+from typing import TYPE_CHECKING, Any
+
+from typing_extensions import Self
 
 if TYPE_CHECKING:
     from manim.scene.scene import Scene
@@ -51,7 +54,6 @@ class Animation:
         For example ``rate_func(0.5)`` is the proportion of the animation that is done
         after half of the animations run time.
 
-
     reverse_rate_function
         Reverses the rate function of the animation. Setting ``reverse_rate_function``
         does not have any effect on ``remover`` or ``introducer``. These need to be
@@ -112,13 +114,13 @@ 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:
                 anim = func(mobject, *args, **kwargs)
                 logger.debug(
-                    f"The {cls.__name__} animation has been is overridden for "
+                    f"The {cls.__name__} animation has been overridden for "
                     f"{type(mobject).__name__} mobjects. use_override = False can "
                     f" be used as keyword argument to prevent animation overriding.",
                 )
@@ -127,7 +129,7 @@ class Animation:
 
     def __init__(
         self,
-        mobject: Mobject | None,
+        mobject: Mobject | OpenGLMobject | None,
         lag_ratio: float = DEFAULT_ANIMATION_LAG_RATIO,
         run_time: float = DEFAULT_ANIMATION_RUN_TIME,
         rate_func: Callable[[float], float] = smooth,
@@ -138,7 +140,7 @@ class Animation:
         introducer: bool = False,
         *,
         _on_finish: Callable[[], None] = lambda _: None,
-        **kwargs,
+        use_override: bool = True,  # included here to avoid TypeError if passed from a subclass' constructor
     ) -> None:
         self._typecheck_input(mobject)
         self.run_time: float = run_time
@@ -158,8 +160,6 @@ class Animation:
         else:
             self.starting_mobject: Mobject = Mobject()
             self.mobject: Mobject = mobject if mobject is not None else Mobject()
-        if kwargs:
-            logger.debug("Animation received extra kwargs: %s", kwargs)
 
         if hasattr(self, "CONFIG"):
             logger.error(
@@ -169,6 +169,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")
@@ -249,11 +262,11 @@ class Animation:
         ):
             scene.add(self.mobject)
 
-    def create_starting_mobject(self) -> Mobject:
+    def create_starting_mobject(self) -> Mobject | OpenGLMobject:
         # Keep track of where the mobject starts
         return self.mobject.copy()
 
-    def get_all_mobjects(self) -> Sequence[Mobject]:
+    def get_all_mobjects(self) -> Sequence[Mobject | OpenGLMobject]:
         """Get all mobjects involved in the animation.
 
         Ordering must match the ordering of arguments to interpolate_submobject
@@ -398,6 +411,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.
 
@@ -457,7 +471,7 @@ class Animation:
         return self
 
     def is_remover(self) -> bool:
-        """Test if a the animation is a remover.
+        """Test if the animation is a remover.
 
         Returns
         -------
@@ -467,7 +481,7 @@ class Animation:
         return self.remover
 
     def is_introducer(self) -> bool:
-        """Test if a the animation is an introducer.
+        """Test if the animation is an introducer.
 
         Returns
         -------
@@ -476,9 +490,57 @@ class Animation:
         """
         return self.introducer
 
+    @classmethod
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+
+        cls._original__init__ = cls.__init__
+
+    _original__init__ = __init__  # needed if set_default() is called with no kwargs directly from Animation
+
+    @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,
+    anim: Animation | mobject._AnimationBuilder | opengl_mobject._AnimationBuilder,
 ) -> Animation:
     r"""Returns either an unchanged animation, or the animation built
     from a passed animation factory.
@@ -528,8 +590,8 @@ class Wait(Animation):
     stop_condition
         A function without positional arguments that evaluates to a boolean.
         The function is evaluated after every new frame has been rendered.
-        Playing the animation only stops after the return value is truthy.
-        Overrides the specified ``run_time``.
+        Playing the animation stops after the return value is truthy, or
+        after the specified ``run_time`` has passed.
     frozen_frame
         Controls whether or not the wait animation is static, i.e., corresponds
         to a frozen frame. If ``False`` is passed, the render loop still
@@ -575,6 +637,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/changing.py

@@ -4,15 +4,23 @@ from __future__ import annotations
 
 __all__ = ["AnimatedBoundary", "TracedPath"]
 
-from typing import Callable
+from collections.abc import Callable, Sequence
+from typing import Any
 
-from colour import Color
+from typing_extensions import Self
 
-from manim._config import config
+from manim.mobject.mobject import Mobject
 from manim.mobject.opengl.opengl_compatibility import ConvertToOpenGL
 from manim.mobject.types.vectorized_mobject import VGroup, VMobject
-from manim.utils.color import BLUE_B, BLUE_D, BLUE_E, GREY_BROWN, WHITE
-from manim.utils.rate_functions import smooth
+from manim.utils.color import (
+    BLUE_B,
+    BLUE_D,
+    BLUE_E,
+    GREY_BROWN,
+    WHITE,
+    ParsableManimColor,
+)
+from manim.utils.rate_functions import RateFunction, smooth
 
 
 class AnimatedBoundary(VGroup):
@@ -34,14 +42,14 @@ class AnimatedBoundary(VGroup):
 
     def __init__(
         self,
-        vmobject,
-        colors=[BLUE_D, BLUE_B, BLUE_E, GREY_BROWN],
-        max_stroke_width=3,
-        cycle_rate=0.5,
-        back_and_forth=True,
-        draw_rate_func=smooth,
-        fade_rate_func=smooth,
-        **kwargs,
+        vmobject: VMobject,
+        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: Any,
     ):
         super().__init__(**kwargs)
         self.colors = colors
@@ -55,10 +63,10 @@ class AnimatedBoundary(VGroup):
             vmobject.copy().set_style(stroke_width=0, fill_opacity=0) for x in range(2)
         ]
         self.add(*self.boundary_copies)
-        self.total_time = 0
+        self.total_time = 0.0
         self.add_updater(lambda m, dt: self.update_boundary_copies(dt))
 
-    def update_boundary_copies(self, dt):
+    def update_boundary_copies(self, dt: float) -> None:
         # Not actual time, but something which passes at
         # an altered rate to make the implementation below
         # cleaner
@@ -74,9 +82,9 @@ class AnimatedBoundary(VGroup):
         fade_alpha = self.fade_rate_func(alpha)
 
         if self.back_and_forth and int(time) % 2 == 1:
-            bounds = (1 - draw_alpha, 1)
+            bounds = (1.0 - draw_alpha, 1.0)
         else:
-            bounds = (0, draw_alpha)
+            bounds = (0.0, draw_alpha)
         self.full_family_become_partial(growing, vmobject, *bounds)
         growing.set_stroke(colors[index], width=msw)
 
@@ -86,7 +94,9 @@ class AnimatedBoundary(VGroup):
 
         self.total_time += dt
 
-    def full_family_become_partial(self, mob1, mob2, a, b):
+    def full_family_become_partial(
+        self, mob1: VMobject, mob2: VMobject, a: float, b: float
+    ) -> Self:
         family1 = mob1.family_members_with_points()
         family2 = mob2.family_members_with_points()
         for sm1, sm2 in zip(family1, family2):
@@ -140,22 +150,23 @@ class TracedPath(VMobject, metaclass=ConvertToOpenGL):
         self,
         traced_point_func: Callable,
         stroke_width: float = 2,
-        stroke_color: Color = WHITE,
+        stroke_color: ParsableManimColor | None = WHITE,
         dissipating_time: float | None = None,
-        **kwargs,
-    ):
+        **kwargs: Any,
+    ) -> None:
         super().__init__(stroke_color=stroke_color, stroke_width=stroke_width, **kwargs)
         self.traced_point_func = traced_point_func
         self.dissipating_time = dissipating_time
-        self.time = 1 if self.dissipating_time else None
+        self.time = 1.0 if self.dissipating_time else None
         self.add_updater(self.update_path)
 
-    def update_path(self, mob, dt):
+    def update_path(self, mob: Mobject, dt: float) -> None:
         new_point = self.traced_point_func()
         if not self.has_points():
             self.start_new_path(new_point)
         self.add_line_to(new_point)
         if self.dissipating_time:
+            assert self.time is not None
             self.time += dt
             if self.time - 1 > self.dissipating_time:
                 nppcc = self.n_points_per_curve