manim 0.17.0__py3-none-any.whl → 0.19.1__py3-none-any.whl

manim/animation/indication.py

@@ -25,27 +25,32 @@ Examples
 
 """
 
+from __future__ import annotations
+
 __all__ = [
     "FocusOn",
     "Indicate",
     "Flash",
     "ShowPassingFlash",
     "ShowPassingFlashWithThinningStrokeWidth",
-    "ShowCreationThenFadeOut",
     "ApplyWave",
     "Circumscribe",
     "Wiggle",
+    "Blink",
 ]
 
-from typing import Callable, Iterable, Optional, Tuple, Type, Union
+from collections.abc import Iterable
+from typing import Any
 
 import numpy as np
-from colour import Color
+from typing_extensions import Self
 
 from manim.mobject.geometry.arc import Circle, Dot
 from manim.mobject.geometry.line import Line
 from manim.mobject.geometry.polygram import Rectangle
 from manim.mobject.geometry.shape_matchers import SurroundingRectangle
+from manim.mobject.opengl.opengl_mobject import OpenGLMobject
+from manim.scene.scene import Scene
 
 from .. import config
 from ..animation.animation import Animation
@@ -54,13 +59,14 @@ from ..animation.creation import Create, ShowPartial, Uncreate
 from ..animation.fading import FadeIn, FadeOut
 from ..animation.movement import Homotopy
 from ..animation.transform import Transform
+from ..animation.updaters.update import UpdateFromFunc
 from ..constants import *
 from ..mobject.mobject import Mobject
 from ..mobject.types.vectorized_mobject import VGroup, VMobject
+from ..typing import Point3D, Point3DLike, Vector3DLike
 from ..utils.bezier import interpolate, inverse_interpolate
-from ..utils.color import GREY, YELLOW
-from ..utils.deprecation import deprecated
-from ..utils.rate_functions import smooth, there_and_back, wiggle
+from ..utils.color import GREY, YELLOW, ParsableManimColor
+from ..utils.rate_functions import RateFunction, smooth, there_and_back, wiggle
 from ..utils.space_ops import normalize
 
 
@@ -77,8 +83,6 @@ class FocusOn(Transform):
         The color of the spotlight.
     run_time
         The duration of the animation.
-    kwargs
-        Additional arguments to be passed to the :class:`~.Succession` constructor
 
     Examples
     --------
@@ -94,12 +98,12 @@ class FocusOn(Transform):
 
     def __init__(
         self,
-        focus_point: Union[np.ndarray, Mobject],
+        focus_point: Point3DLike | Mobject,
         opacity: float = 0.2,
-        color: str = GREY,
+        color: ParsableManimColor = GREY,
         run_time: float = 2,
-        **kwargs
-    ) -> None:
+        **kwargs: Any,
+    ):
         self.focus_point = focus_point
         self.color = color
         self.opacity = opacity
@@ -131,7 +135,7 @@ class Indicate(Transform):
     color
         The color the mobject temporally takes.
     rate_func
-        The function definig the animation progress at every point in time.
+        The function defining the animation progress at every point in time.
     kwargs
         Additional arguments to be passed to the :class:`~.Succession` constructor
 
@@ -148,17 +152,17 @@ class Indicate(Transform):
 
     def __init__(
         self,
-        mobject: "Mobject",
+        mobject: Mobject,
         scale_factor: float = 1.2,
-        color: str = YELLOW,
-        rate_func: Callable[[float, Optional[float]], np.ndarray] = there_and_back,
-        **kwargs
-    ) -> None:
+        color: ParsableManimColor = YELLOW,
+        rate_func: RateFunction = there_and_back,
+        **kwargs: Any,
+    ):
         self.color = color
         self.scale_factor = scale_factor
         super().__init__(mobject, rate_func=rate_func, **kwargs)
 
-    def create_target(self) -> "Mobject":
+    def create_target(self) -> Mobject | OpenGLMobject:
         target = self.mobject.copy()
         target.scale(self.scale_factor)
         target.set_color(self.color)
@@ -218,20 +222,20 @@ class Flash(AnimationGroup):
 
     def __init__(
         self,
-        point: Union[np.ndarray, Mobject],
+        point: Point3DLike | Mobject,
         line_length: float = 0.2,
         num_lines: int = 12,
         flash_radius: float = 0.1,
         line_stroke_width: int = 3,
-        color: str = YELLOW,
+        color: ParsableManimColor = YELLOW,
         time_width: float = 1,
         run_time: float = 1.0,
-        **kwargs
-    ) -> None:
+        **kwargs: Any,
+    ):
         if isinstance(point, Mobject):
-            self.point = point.get_center()
+            self.point: Point3D = point.get_center()
         else:
-            self.point = point
+            self.point = np.asarray(point)
         self.color = color
         self.line_length = line_length
         self.num_lines = num_lines
@@ -256,7 +260,7 @@ class Flash(AnimationGroup):
         lines.set_stroke(width=self.line_stroke_width)
         return lines
 
-    def create_line_anims(self) -> Iterable["ShowPassingFlash"]:
+    def create_line_anims(self) -> Iterable[ShowPassingFlash]:
         return [
             ShowPassingFlash(
                 line,
@@ -269,7 +273,7 @@ class Flash(AnimationGroup):
 
 
 class ShowPassingFlash(ShowPartial):
-    """Show only a sliver of the VMobject each frame.
+    r"""Show only a sliver of the VMobject each frame.
 
     Parameters
     ----------
@@ -289,7 +293,7 @@ class ShowPassingFlash(ShowPartial):
                 self.add(p, lbl)
                 p = p.copy().set_color(BLUE)
                 for time_width in [0.2, 0.5, 1, 2]:
-                    lbl.become(Tex(r"\\texttt{time\\_width={{%.1f}}}"%time_width))
+                    lbl.become(Tex(r"\texttt{time\_width={{%.1f}}}"%time_width))
                     self.play(ShowPassingFlash(
                         p.copy().set_color(BLUE),
                         run_time=2,
@@ -302,11 +306,13 @@ class ShowPassingFlash(ShowPartial):
 
     """
 
-    def __init__(self, mobject: "VMobject", time_width: float = 0.1, **kwargs) -> None:
+    def __init__(
+        self, mobject: VMobject, time_width: float = 0.1, **kwargs: Any
+    ) -> None:
         self.time_width = time_width
         super().__init__(mobject, remover=True, introducer=True, **kwargs)
 
-    def _get_bounds(self, alpha: float) -> Tuple[float]:
+    def _get_bounds(self, alpha: float) -> tuple[float, float]:
         tw = self.time_width
         upper = interpolate(0, 1 + tw, alpha)
         lower = upper - tw
@@ -314,14 +320,21 @@ class ShowPassingFlash(ShowPartial):
         lower = max(lower, 0)
         return (lower, upper)
 
-    def clean_up_from_scene(self, scene: "Scene") -> None:
+    def clean_up_from_scene(self, scene: Scene) -> None:
         super().clean_up_from_scene(scene)
         for submob, start in self.get_all_families_zipped():
             submob.pointwise_become_partial(start, 0, 1)
 
 
 class ShowPassingFlashWithThinningStrokeWidth(AnimationGroup):
-    def __init__(self, vmobject, n_segments=10, time_width=0.1, remover=True, **kwargs):
+    def __init__(
+        self,
+        vmobject: VMobject,
+        n_segments: int = 10,
+        time_width: float = 0.1,
+        remover: bool = True,
+        **kwargs: Any,
+    ):
         self.n_segments = n_segments
         self.time_width = time_width
         self.remover = remover
@@ -342,16 +355,6 @@ class ShowPassingFlashWithThinningStrokeWidth(AnimationGroup):
         )
 
 
-@deprecated(
-    since="v0.15.0",
-    until="v0.16.0",
-    message="Use Create then FadeOut to achieve this effect.",
-)
-class ShowCreationThenFadeOut(Succession):
-    def __init__(self, mobject: "Mobject", remover: bool = True, **kwargs) -> None:
-        super().__init__(Create(mobject), FadeOut(mobject), remover=remover, **kwargs)
-
-
 class ApplyWave(Homotopy):
     """Send a wave through the Mobject distorting it temporarily.
 
@@ -397,25 +400,25 @@ class ApplyWave(Homotopy):
 
     def __init__(
         self,
-        mobject: "Mobject",
-        direction: np.ndarray = UP,
+        mobject: Mobject,
+        direction: Vector3DLike = UP,
         amplitude: float = 0.2,
-        wave_func: Callable[[float], float] = smooth,
+        wave_func: RateFunction = smooth,
         time_width: float = 1,
         ripples: int = 1,
         run_time: float = 2,
-        **kwargs
-    ) -> None:
+        **kwargs: Any,
+    ):
         x_min = mobject.get_left()[0]
         x_max = mobject.get_right()[0]
         vect = amplitude * normalize(direction)
 
-        def wave(t):
+        def wave(t: float) -> float:
             # Creates a wave with n ripples from a simple rate_func
             # This wave is build up as follows:
             # The time is split into 2*ripples phases. In every phase the amplitude
             # either rises to one or goes down to zero. Consecutive ripples will have
-            # their amplitudes in oppising directions (first ripple from 0 to 1 to 0,
+            # their amplitudes in opposing directions (first ripple from 0 to 1 to 0,
             # second from 0 to -1 to 0 and so on). This is how two ripples would be
             # divided into phases:
 
@@ -454,7 +457,7 @@ class ApplyWave(Homotopy):
                 return wave_func(t * phases)
             elif phase == phases - 1:
                 # last ripple. Rising or falling depending on the number of ripples
-                # The (ripples % 2)-term is used to make this destinction.
+                # The (ripples % 2)-term is used to make this distinction.
                 t -= phase / phases  # Time relative to the phase
                 return (1 - wave_func(t * phases)) * (2 * (ripples % 2) - 1)
             else:
@@ -470,13 +473,14 @@ class ApplyWave(Homotopy):
             y: float,
             z: float,
             t: float,
-        ) -> Tuple[float, float, float]:
+        ) -> tuple[float, float, float]:
             upper = interpolate(0, 1 + time_width, t)
             lower = upper - time_width
             relative_x = inverse_interpolate(x_min, x_max, x)
             wave_phase = inverse_interpolate(lower, upper, relative_x)
             nudge = wave(wave_phase) * vect
-            return np.array([x, y, z]) + nudge
+            return_value: tuple[float, float, float] = np.array([x, y, z]) + nudge
+            return return_value
 
         super().__init__(homotopy, mobject, run_time=run_time, **kwargs)
 
@@ -516,38 +520,42 @@ class Wiggle(Animation):
 
     def __init__(
         self,
-        mobject: "Mobject",
+        mobject: Mobject,
         scale_value: float = 1.1,
         rotation_angle: float = 0.01 * TAU,
         n_wiggles: int = 6,
-        scale_about_point: Optional[np.ndarray] = None,
-        rotate_about_point: Optional[np.ndarray] = None,
+        scale_about_point: Point3DLike | None = None,
+        rotate_about_point: Point3DLike | None = None,
         run_time: float = 2,
-        **kwargs
-    ) -> None:
+        **kwargs: Any,
+    ):
         self.scale_value = scale_value
         self.rotation_angle = rotation_angle
         self.n_wiggles = n_wiggles
         self.scale_about_point = scale_about_point
+        if scale_about_point is not None:
+            self.scale_about_point = np.array(scale_about_point)
         self.rotate_about_point = rotate_about_point
+        if rotate_about_point is not None:
+            self.rotate_about_point = np.array(rotate_about_point)
         super().__init__(mobject, run_time=run_time, **kwargs)
 
-    def get_scale_about_point(self) -> np.ndarray:
+    def get_scale_about_point(self) -> Point3D:
         if self.scale_about_point is None:
             return self.mobject.get_center()
         return self.scale_about_point
 
-    def get_rotate_about_point(self) -> np.ndarray:
+    def get_rotate_about_point(self) -> Point3D:
         if self.rotate_about_point is None:
             return self.mobject.get_center()
         return self.rotate_about_point
 
     def interpolate_submobject(
         self,
-        submobject: "Mobject",
-        starting_submobject: "Mobject",
+        submobject: Mobject,
+        starting_submobject: Mobject,
         alpha: float,
-    ) -> None:
+    ) -> Self:
         submobject.points[:, :] = starting_submobject.points
         submobject.scale(
             interpolate(1, self.scale_value, there_and_back(alpha)),
@@ -557,17 +565,18 @@ class Wiggle(Animation):
             wiggle(alpha, self.n_wiggles) * self.rotation_angle,
             about_point=self.get_rotate_about_point(),
         )
+        return self
 
 
 class Circumscribe(Succession):
-    """Draw a temporary line surrounding the mobject.
+    r"""Draw a temporary line surrounding the mobject.
 
     Parameters
     ----------
     mobject
         The mobject to be circumscribed.
     shape
-        The shape with which to surrond the given mobject. Should be either
+        The shape with which to surround the given mobject. Should be either
         :class:`~.Rectangle` or :class:`~.Circle`
     fade_in
         Whether to make the surrounding shape to fade in. It will be drawn otherwise.
@@ -591,7 +600,7 @@ class Circumscribe(Succession):
 
         class UsingCircumscribe(Scene):
             def construct(self):
-                lbl = Tex(r"Circum-\\\\scribe").scale(2)
+                lbl = Tex(r"Circum-\\scribe").scale(2)
                 self.add(lbl)
                 self.play(Circumscribe(lbl))
                 self.play(Circumscribe(lbl, Circle))
@@ -604,21 +613,21 @@ class Circumscribe(Succession):
     def __init__(
         self,
         mobject: Mobject,
-        shape: Type = Rectangle,
-        fade_in=False,
-        fade_out=False,
-        time_width=0.3,
+        shape: type[Rectangle] | type[Circle] = Rectangle,
+        fade_in: bool = False,
+        fade_out: bool = False,
+        time_width: float = 0.3,
         buff: float = SMALL_BUFF,
-        color: Color = YELLOW,
-        run_time=1,
-        stroke_width=DEFAULT_STROKE_WIDTH,
-        **kwargs
+        color: ParsableManimColor = YELLOW,
+        run_time: float = 1,
+        stroke_width: float = DEFAULT_STROKE_WIDTH,
+        **kwargs: Any,
     ):
         if shape is Rectangle:
-            frame = SurroundingRectangle(
+            frame: SurroundingRectangle | Circle = SurroundingRectangle(
                 mobject,
-                color,
-                buff,
+                color=color,
+                buff=buff,
                 stroke_width=stroke_width,
             )
         elif shape is Circle:
@@ -654,3 +663,68 @@ class Circumscribe(Succession):
             super().__init__(
                 ShowPassingFlash(frame, time_width, run_time=run_time), **kwargs
             )
+
+
+class Blink(Succession):
+    """Blink the mobject.
+
+    Parameters
+    ----------
+    mobject
+        The mobject to be blinked.
+    time_on
+        The duration that the mobject is shown for one blink.
+    time_off
+        The duration that the mobject is hidden for one blink.
+    blinks
+        The number of blinks
+    hide_at_end
+        Whether to hide the mobject at the end of the animation.
+    kwargs
+        Additional arguments to be passed to the :class:`~.Succession` constructor.
+
+    Examples
+    --------
+
+    .. manim:: BlinkingExample
+
+        class BlinkingExample(Scene):
+            def construct(self):
+                text = Text("Blinking").scale(1.5)
+                self.add(text)
+                self.play(Blink(text, blinks=3))
+
+    """
+
+    def __init__(
+        self,
+        mobject: Mobject,
+        time_on: float = 0.5,
+        time_off: float = 0.5,
+        blinks: int = 1,
+        hide_at_end: bool = False,
+        **kwargs: Any,
+    ):
+        animations = [
+            UpdateFromFunc(
+                mobject,
+                update_function=lambda mob: mob.set_opacity(1.0),
+                run_time=time_on,
+            ),
+            UpdateFromFunc(
+                mobject,
+                update_function=lambda mob: mob.set_opacity(0.0),
+                run_time=time_off,
+            ),
+        ] * blinks
+
+        if not hide_at_end:
+            animations.append(
+                UpdateFromFunc(
+                    mobject,
+                    update_function=lambda mob: mob.set_opacity(1.0),
+                    run_time=time_on,
+                ),
+            )
+
+        super().__init__(*animations, **kwargs)

manim/animation/movement.py

@@ -18,7 +18,13 @@ from ..animation.animation import Animation
 from ..utils.rate_functions import linear
 
 if TYPE_CHECKING:
-    from ..mobject.mobject import Mobject, VMobject
+    from typing_extensions import Self
+
+    from manim.mobject.types.vectorized_mobject import VMobject
+    from manim.typing import MappingFunction, Point3D
+    from manim.utils.rate_functions import RateFunction
+
+    from ..mobject.mobject import Mobject
 
 
 class Homotopy(Animation):
@@ -44,6 +50,26 @@ class Homotopy(Animation):
         Keyword arguments propagated to :meth:`.Mobject.apply_function`.
     kwargs
         Further keyword arguments passed to the parent class.
+
+    Examples
+    --------
+
+    .. manim:: HomotopyExample
+
+        class HomotopyExample(Scene):
+            def construct(self):
+                square = Square()
+
+                def homotopy(x, y, z, t):
+                    if t <= 0.25:
+                        progress = t / 0.25
+                        return (x, y + progress * 0.2 * np.sin(x), z)
+                    else:
+                        wave_progress = (t - 0.25) / 0.75
+                        return (x, y + 0.2 * np.sin(x + 10 * wave_progress), z)
+
+                self.play(Homotopy(homotopy, square, rate_func= linear, run_time=2))
+
     """
 
     def __init__(
@@ -52,27 +78,33 @@ class Homotopy(Animation):
         mobject: Mobject,
         run_time: float = 3,
         apply_function_kwargs: dict[str, Any] | None = None,
-        **kwargs,
-    ) -> None:
+        **kwargs: Any,
+    ):
         self.homotopy = homotopy
         self.apply_function_kwargs = (
             apply_function_kwargs if apply_function_kwargs is not None else {}
         )
         super().__init__(mobject, run_time=run_time, **kwargs)
 
-    def function_at_time_t(self, t: float) -> tuple[float, float, float]:
-        return lambda p: self.homotopy(*p, t)
+    def function_at_time_t(self, t: float) -> MappingFunction:
+        def mapping_function(p: Point3D) -> Point3D:
+            x, y, z = p
+            return np.array(self.homotopy(x, y, z, t))
+
+        return mapping_function
 
     def interpolate_submobject(
         self,
         submobject: Mobject,
         starting_submobject: Mobject,
         alpha: float,
-    ) -> None:
+    ) -> Self:
         submobject.points = starting_submobject.points
         submobject.apply_function(
-            self.function_at_time_t(alpha), **self.apply_function_kwargs
+            self.function_at_time_t(alpha),
+            **self.apply_function_kwargs,
         )
+        return self
 
 
 class SmoothedVectorizedHomotopy(Homotopy):
@@ -81,18 +113,21 @@ class SmoothedVectorizedHomotopy(Homotopy):
         submobject: Mobject,
         starting_submobject: Mobject,
         alpha: float,
-    ) -> None:
+    ) -> Self:
+        assert isinstance(submobject, VMobject)
         super().interpolate_submobject(submobject, starting_submobject, alpha)
         submobject.make_smooth()
+        return self
 
 
 class ComplexHomotopy(Homotopy):
     def __init__(
-        self, complex_homotopy: Callable[[complex], float], mobject: Mobject, **kwargs
-    ) -> None:
-        """
-        Complex Homotopy a function Cx[0, 1] to C
-        """
+        self,
+        complex_homotopy: Callable[[complex, float], float],
+        mobject: Mobject,
+        **kwargs: Any,
+    ):
+        """Complex Homotopy a function Cx[0, 1] to C"""
 
         def homotopy(
             x: float,
@@ -113,9 +148,9 @@ class PhaseFlow(Animation):
         mobject: Mobject,
         virtual_time: float = 1,
         suspend_mobject_updating: bool = False,
-        rate_func: Callable[[float], float] = linear,
-        **kwargs,
-    ) -> None:
+        rate_func: RateFunction = linear,
+        **kwargs: Any,
+    ):
         self.virtual_time = virtual_time
         self.function = function
         super().__init__(
@@ -131,13 +166,12 @@ class PhaseFlow(Animation):
                 self.rate_func(alpha) - self.rate_func(self.last_alpha)
             )
             self.mobject.apply_function(lambda p: p + dt * self.function(p))
-        self.last_alpha = alpha
+        self.last_alpha: float = alpha
 
 
 class MoveAlongPath(Animation):
     """Make one mobject move along the path of another mobject.
-    Example
-    --------
+
     .. manim:: MoveAlongPathExample
 
         class MoveAlongPathExample(Scene):
@@ -154,9 +188,9 @@ class MoveAlongPath(Animation):
         self,
         mobject: Mobject,
         path: VMobject,
-        suspend_mobject_updating: bool | None = False,
-        **kwargs,
-    ) -> None:
+        suspend_mobject_updating: bool = False,
+        **kwargs: Any,
+    ):
         self.path = path
         super().__init__(
             mobject, suspend_mobject_updating=suspend_mobject_updating, **kwargs