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

manim/animation/numbers.py

@@ -5,7 +5,8 @@ from __future__ import annotations
 __all__ = ["ChangingDecimal", "ChangeDecimalToValue"]
 
 
-import typing
+from collections.abc import Callable
+from typing import Any
 
 from manim.mobject.text.numbers import DecimalNumber
 
@@ -14,12 +15,47 @@ from ..utils.bezier import interpolate
 
 
 class ChangingDecimal(Animation):
+    """Animate a :class:`~.DecimalNumber` to values specified by a user-supplied function.
+
+    Parameters
+    ----------
+    decimal_mob
+        The :class:`~.DecimalNumber` instance to animate.
+    number_update_func
+        A function that returns the number to display at each point in the animation.
+    suspend_mobject_updating
+        If ``True``, the mobject is not updated outside this animation.
+
+    Raises
+    ------
+    TypeError
+        If ``decimal_mob`` is not an instance of :class:`~.DecimalNumber`.
+
+    Examples
+    --------
+
+    .. manim:: ChangingDecimalExample
+
+        class ChangingDecimalExample(Scene):
+            def construct(self):
+                number = DecimalNumber(0)
+                self.add(number)
+                self.play(
+                    ChangingDecimal(
+                        number,
+                        lambda a: 5 * a,
+                        run_time=3
+                    )
+                )
+                self.wait()
+    """
+
     def __init__(
         self,
         decimal_mob: DecimalNumber,
-        number_update_func: typing.Callable[[float], float],
-        suspend_mobject_updating: bool | None = False,
-        **kwargs,
+        number_update_func: Callable[[float], float],
+        suspend_mobject_updating: bool = False,
+        **kwargs: Any,
     ) -> None:
         self.check_validity_of_input(decimal_mob)
         self.number_update_func = number_update_func
@@ -32,12 +68,34 @@ class ChangingDecimal(Animation):
             raise TypeError("ChangingDecimal can only take in a DecimalNumber")
 
     def interpolate_mobject(self, alpha: float) -> None:
-        self.mobject.set_value(self.number_update_func(self.rate_func(alpha)))
+        self.mobject.set_value(self.number_update_func(self.rate_func(alpha)))  # type: ignore[attr-defined]
 
 
 class ChangeDecimalToValue(ChangingDecimal):
+    """Animate a :class:`~.DecimalNumber` to a target value using linear interpolation.
+
+    Parameters
+    ----------
+    decimal_mob
+        The :class:`~.DecimalNumber` instance to animate.
+    target_number
+        The target value to transition to.
+
+    Examples
+    --------
+
+    .. manim:: ChangeDecimalToValueExample
+
+        class ChangeDecimalToValueExample(Scene):
+            def construct(self):
+                number = DecimalNumber(0)
+                self.add(number)
+                self.play(ChangeDecimalToValue(number, 10, run_time=3))
+                self.wait()
+    """
+
     def __init__(
-        self, decimal_mob: DecimalNumber, target_number: int, **kwargs
+        self, decimal_mob: DecimalNumber, target_number: int, **kwargs: Any
     ) -> None:
         start_number = decimal_mob.number
         super().__init__(

manim/animation/rotation.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 
 __all__ = ["Rotating", "Rotate"]
 
-from typing import TYPE_CHECKING, Callable, Sequence
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
@@ -18,19 +19,85 @@ if TYPE_CHECKING:
 
 
 class Rotating(Animation):
+    """Animation that rotates a Mobject.
+
+    Parameters
+    ----------
+    mobject
+        The mobject to be rotated.
+    angle
+        The rotation angle in radians. Predefined constants such as ``DEGREES``
+        can also be used to specify the angle in degrees.
+    axis
+        The rotation axis as a numpy vector.
+    about_point
+        The rotation center.
+    about_edge
+        If ``about_point`` is ``None``, this argument specifies
+        the direction of the bounding box point to be taken as
+        the rotation center.
+    run_time
+        The duration of the animation in seconds.
+    rate_func
+        The function defining the animation progress based on the relative
+        runtime (see :mod:`~.rate_functions`) .
+    **kwargs
+        Additional keyword arguments passed to :class:`~.Animation`.
+
+    Examples
+    --------
+    .. manim:: RotatingDemo
+
+        class RotatingDemo(Scene):
+            def construct(self):
+                circle = Circle(radius=1, color=BLUE)
+                line = Line(start=ORIGIN, end=RIGHT)
+                arrow = Arrow(start=ORIGIN, end=RIGHT, buff=0, color=GOLD)
+                vg = VGroup(circle,line,arrow)
+                self.add(vg)
+                anim_kw = {"about_point": arrow.get_start(), "run_time": 1}
+                self.play(Rotating(arrow, 180*DEGREES, **anim_kw))
+                self.play(Rotating(arrow, PI, **anim_kw))
+                self.play(Rotating(vg, PI, about_point=RIGHT))
+                self.play(Rotating(vg, PI, axis=UP, about_point=ORIGIN))
+                self.play(Rotating(vg, PI, axis=RIGHT, about_edge=UP))
+                self.play(vg.animate.move_to(ORIGIN))
+
+    .. manim:: RotatingDifferentAxis
+
+        class RotatingDifferentAxis(ThreeDScene):
+            def construct(self):
+                axes = ThreeDAxes()
+                cube = Cube()
+                arrow2d = Arrow(start=[0, -1.2, 1], end=[0, 1.2, 1], color=YELLOW_E)
+                cube_group = VGroup(cube,arrow2d)
+                self.set_camera_orientation(gamma=0, phi=40*DEGREES, theta=40*DEGREES)
+                self.add(axes, cube_group)
+                play_kw = {"run_time": 1.5}
+                self.play(Rotating(cube_group, PI), **play_kw)
+                self.play(Rotating(cube_group, PI, axis=UP), **play_kw)
+                self.play(Rotating(cube_group, 180*DEGREES, axis=RIGHT), **play_kw)
+                self.wait(0.5)
+
+    See also
+    --------
+    :class:`~.Rotate`, :meth:`~.Mobject.rotate`
+
+    """
+
     def __init__(
         self,
         mobject: Mobject,
+        angle: float = TAU,
         axis: np.ndarray = OUT,
-        radians: np.ndarray = TAU,
         about_point: np.ndarray | None = None,
         about_edge: np.ndarray | None = None,
         run_time: float = 5,
         rate_func: Callable[[float], float] = linear,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
+        self.angle = angle
         self.axis = axis
-        self.radians = radians
         self.about_point = about_point
         self.about_edge = about_edge
         super().__init__(mobject, run_time=run_time, rate_func=rate_func, **kwargs)
@@ -38,7 +105,7 @@ class Rotating(Animation):
     def interpolate_mobject(self, alpha: float) -> None:
         self.mobject.become(self.starting_mobject)
         self.mobject.rotate(
-            self.rate_func(alpha) * self.radians,
+            self.rate_func(alpha) * self.angle,
             axis=self.axis,
             about_point=self.about_point,
             about_edge=self.about_edge,
@@ -59,7 +126,7 @@ class Rotate(Transform):
     about_point
         The rotation center.
     about_edge
-        If ``about_point``is ``None``, this argument specifies
+        If ``about_point`` is ``None``, this argument specifies
         the direction of the bounding box point to be taken as
         the rotation center.
 
@@ -79,6 +146,10 @@ class Rotate(Transform):
                     Rotate(Square(side_length=0.5), angle=2*PI, rate_func=linear),
                     )
 
+    See also
+    --------
+    :class:`~.Rotating`, :meth:`~.Mobject.rotate`
+
     """
 
     def __init__(
@@ -88,7 +159,7 @@ class Rotate(Transform):
         axis: np.ndarray = OUT,
         about_point: Sequence[float] | None = None,
         about_edge: Sequence[float] | None = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         if "path_arc" not in kwargs:
             kwargs["path_arc"] = angle

manim/animation/specialized.py

@@ -2,9 +2,11 @@ from __future__ import annotations
 
 __all__ = ["Broadcast"]
 
-from typing import Any, Sequence
+from collections.abc import Sequence
+from typing import Any
 
 from manim.animation.transform import Restore
+from manim.mobject.mobject import Mobject
 
 from ..constants import *
 from .composition import LaggedStart
@@ -49,7 +51,7 @@ class Broadcast(LaggedStart):
 
     def __init__(
         self,
-        mobject,
+        mobject: Mobject,
         focal_point: Sequence[float] = ORIGIN,
         n_mobs: int = 5,
         initial_opacity: float = 1,
@@ -69,10 +71,7 @@ class Broadcast(LaggedStart):
         anims = []
 
         # Works by saving the mob that is passed into the animation, scaling it to 0 (or the initial_width) and then restoring the original mob.
-        if mobject.fill_opacity:
-            fill_o = True
-        else:
-            fill_o = False
+        fill_o = bool(mobject.fill_opacity)
 
         for _ in range(self.n_mobs):
             mob = mobject.copy()
@@ -84,7 +83,7 @@ class Broadcast(LaggedStart):
 
             mob.move_to(self.focal_point)
             mob.save_state()
-            mob.set_width(self.initial_width)
+            mob.set(width=self.initial_width)
 
             if fill_o:
                 mob.set_opacity(self.initial_opacity)

manim/animation/speedmodifier.py

@@ -2,18 +2,23 @@
 
 from __future__ import annotations
 
+import inspect
 import types
-from typing import Callable
+from collections.abc import Callable
+from typing import TYPE_CHECKING
 
 from numpy import piecewise
 
-from manim.utils.simple_functions import get_parameters
-
 from ..animation.animation import Animation, Wait, prepare_animation
 from ..animation.composition import AnimationGroup
-from ..mobject.mobject import Mobject, Updater, _AnimationBuilder
+from ..mobject.mobject import Mobject, _AnimationBuilder
 from ..scene.scene import Scene
 
+if TYPE_CHECKING:
+    from ..mobject.mobject import Updater
+
+__all__ = ["ChangeSpeed"]
+
 
 class ChangeSpeed(Animation):
     """Modifies the speed of passed animation.
@@ -97,7 +102,6 @@ class ChangeSpeed(Animation):
         affects_speed_updaters: bool = True,
         **kwargs,
     ) -> None:
-
         if issubclass(type(anim), AnimationGroup):
             self.anim = type(anim)(
                 *map(self.setup, anim.animations),
@@ -110,9 +114,9 @@ class ChangeSpeed(Animation):
             self.anim = self.setup(anim)
 
         if affects_speed_updaters:
-            assert (
-                ChangeSpeed.is_changing_dt is False
-            ), "Only one animation at a time can play that changes speed (dt) for ChangeSpeed updaters"
+            assert ChangeSpeed.is_changing_dt is False, (
+                "Only one animation at a time can play that changes speed (dt) for ChangeSpeed updaters"
+            )
             ChangeSpeed.is_changing_dt = True
             self.t = 0
         self.affects_speed_updaters = affects_speed_updaters
@@ -261,8 +265,7 @@ class ChangeSpeed(Animation):
         :class:`.ChangeSpeed`
         :meth:`.Mobject.add_updater`
         """
-        parameters = get_parameters(update_function)
-        if "dt" in parameters:
+        if "dt" in inspect.signature(update_function).parameters:
             mobject.add_updater(
                 lambda mob, dt: update_function(
                     mob, ChangeSpeed.dt if ChangeSpeed.is_changing_dt else dt

manim/animation/transform.py

@@ -28,10 +28,12 @@ __all__ = [
 
 import inspect
 import types
-from typing import TYPE_CHECKING, Any, Callable, Iterable, Sequence
+from collections.abc import Callable, Iterable, Sequence
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
+from manim.data_structures import MethodWithArgs
 from manim.mobject.opengl.opengl_mobject import OpenGLGroup, OpenGLMobject
 
 from .. import config
@@ -122,6 +124,10 @@ class Transform(Animation):
 
                 self.play(*anims, run_time=2)
                 self.wait()
+
+    See also
+    --------
+    :class:`~.ReplacementTransform`, :meth:`~.Mobject.interpolate`, :meth:`~.Mobject.align_data`
     """
 
     def __init__(
@@ -203,7 +209,7 @@ class Transform(Animation):
             self.mobject.align_data(self.target_copy)
         super().begin()
 
-    def create_target(self) -> Mobject:
+    def create_target(self) -> Mobject | OpenGLMobject:
         # Has no meaningful effect here, but may be useful
         # in subclasses
         return self.target_mobject
@@ -211,8 +217,7 @@ class Transform(Animation):
     def clean_up_from_scene(self, scene: Scene) -> None:
         super().clean_up_from_scene(scene)
         if self.replace_mobject_with_target_in_scene:
-            scene.remove(self.mobject)
-            scene.add(self.target_mobject)
+            scene.replace(self.mobject, self.target_mobject)
 
     def get_all_mobjects(self) -> Sequence[Mobject]:
         return [
@@ -298,9 +303,7 @@ class ReplacementTransform(Transform):
 
 
 class TransformFromCopy(Transform):
-    """
-    Performs a reversed Transform
-    """
+    """Performs a reversed Transform"""
 
     def __init__(self, mobject: Mobject, target_mobject: Mobject, **kwargs) -> None:
         super().__init__(target_mobject, mobject, **kwargs)
@@ -431,18 +434,18 @@ class MoveToTarget(Transform):
     def check_validity_of_input(self, mobject: Mobject) -> None:
         if not hasattr(mobject, "target"):
             raise ValueError(
-                "MoveToTarget called on mobject" "without attribute 'target'",
+                "MoveToTarget called on mobjectwithout attribute 'target'",
             )
 
 
 class _MethodAnimation(MoveToTarget):
-    def __init__(self, mobject, methods):
+    def __init__(self, mobject: Mobject, methods: list[MethodWithArgs]) -> None:
         self.methods = methods
         super().__init__(mobject)
 
     def finish(self) -> None:
-        for method, method_args, method_kwargs in self.methods:
-            method.__func__(self.mobject, *method_args, **method_kwargs)
+        for item in self.methods:
+            item.method.__func__(self.mobject, *item.args, **item.kwargs)
         super().finish()
 
 

manim/animation/transform_matching_parts.py

@@ -76,7 +76,6 @@ class TransformMatchingAbstractBase(AnimationGroup):
         key_map: dict | None = None,
         **kwargs,
     ):
-
         if isinstance(mobject, OpenGLVMobject):
             group_type = OpenGLVGroup
         elif isinstance(mobject, OpenGLMobject):
@@ -97,7 +96,6 @@ class TransformMatchingAbstractBase(AnimationGroup):
         # target_map
         transform_source = group_type()
         transform_target = group_type()
-        kwargs["final_alpha_value"] = 0
         for key in set(source_map).intersection(target_map):
             transform_source.add(source_map[key])
             transform_target.add(target_map[key])
@@ -226,8 +224,9 @@ class TransformMatchingShapes(TransformMatchingAbstractBase):
     def get_mobject_key(mobject: Mobject) -> int:
         mobject.save_state()
         mobject.center()
-        mobject.set_height(1)
-        result = hash(np.round(mobject.points, 3).tobytes())
+        mobject.set(height=1)
+        rounded_points = np.round(mobject.points, 3) + 0.0
+        result = hash(rounded_points.tobytes())
         mobject.restore()
         return result
 

manim/animation/updaters/mobject_update_utils.py

@@ -15,21 +15,27 @@ __all__ = [
 
 
 import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING
 
 import numpy as np
 
 from manim.constants import DEGREES, RIGHT
 from manim.mobject.mobject import Mobject
 from manim.opengl import OpenGLMobject
+from manim.utils.space_ops import normalize
 
+if TYPE_CHECKING:
+    from manim.animation.animation import Animation
 
-def assert_is_mobject_method(method):
+
+def assert_is_mobject_method(method: Callable) -> None:
     assert inspect.ismethod(method)
     mobject = method.__self__
     assert isinstance(mobject, (Mobject, OpenGLMobject))
 
 
-def always(method, *args, **kwargs):
+def always(method: Callable, *args, **kwargs) -> Mobject:
     assert_is_mobject_method(method)
     mobject = method.__self__
     func = method.__func__
@@ -37,7 +43,7 @@ def always(method, *args, **kwargs):
     return mobject
 
 
-def f_always(method, *arg_generators, **kwargs):
+def f_always(method: Callable[[Mobject], None], *arg_generators, **kwargs) -> Mobject:
     """
     More functional version of always, where instead
     of taking in args, it takes in functions which output
@@ -55,59 +61,175 @@ def f_always(method, *arg_generators, **kwargs):
     return mobject
 
 
-def always_redraw(func):
+def always_redraw(func: Callable[[], Mobject]) -> Mobject:
+    """Redraw the mobject constructed by a function every frame.
+
+    This function returns a mobject with an attached updater that
+    continuously regenerates the mobject according to the
+    specified function.
+
+    Parameters
+    ----------
+    func
+        A function without (required) input arguments that returns
+        a mobject.
+
+    Examples
+    --------
+
+    .. manim:: TangentAnimation
+
+        class TangentAnimation(Scene):
+            def construct(self):
+                ax = Axes()
+                sine = ax.plot(np.sin, color=RED)
+                alpha = ValueTracker(0)
+                point = always_redraw(
+                    lambda: Dot(
+                        sine.point_from_proportion(alpha.get_value()),
+                        color=BLUE
+                    )
+                )
+                tangent = always_redraw(
+                    lambda: TangentLine(
+                        sine,
+                        alpha=alpha.get_value(),
+                        color=YELLOW,
+                        length=4
+                    )
+                )
+                self.add(ax, sine, point, tangent)
+                self.play(alpha.animate.set_value(1), rate_func=linear, run_time=2)
+    """
     mob = func()
-    mob.add_updater(lambda m: mob.become(func()))
+    mob.add_updater(lambda _: mob.become(func()))
     return mob
 
 
-def always_shift(mobject, direction=RIGHT, rate=0.1):
-    def normalize(v):
-        norm = np.linalg.norm(v)
-        if norm == 0:
-            return v
-        return v / norm
-
+def always_shift(
+    mobject: Mobject, direction: np.ndarray[np.float64] = RIGHT, rate: float = 0.1
+) -> Mobject:
+    """A mobject which is continuously shifted along some direction
+    at a certain rate.
+
+    Parameters
+    ----------
+    mobject
+        The mobject to shift.
+    direction
+        The direction to shift. The vector is normalized, the specified magnitude
+        is not relevant.
+    rate
+        Length in Manim units which the mobject travels in one
+        second along the specified direction.
+
+    Examples
+    --------
+
+    .. manim:: ShiftingSquare
+
+        class ShiftingSquare(Scene):
+            def construct(self):
+                sq = Square().set_fill(opacity=1)
+                tri = Triangle()
+                VGroup(sq, tri).arrange(LEFT)
+
+                # construct a square which is continuously
+                # shifted to the right
+                always_shift(sq, RIGHT, rate=5)
+
+                self.add(sq)
+                self.play(tri.animate.set_fill(opacity=1))
+    """
     mobject.add_updater(lambda m, dt: m.shift(dt * rate * normalize(direction)))
     return mobject
 
 
-def always_rotate(mobject, rate=20 * DEGREES, **kwargs):
+def always_rotate(mobject: Mobject, rate: float = 20 * DEGREES, **kwargs) -> Mobject:
+    """A mobject which is continuously rotated at a certain rate.
+
+    Parameters
+    ----------
+    mobject
+        The mobject to be rotated.
+    rate
+        The angle which the mobject is rotated by
+        over one second.
+    kwags
+        Further arguments to be passed to :meth:`.Mobject.rotate`.
+
+    Examples
+    --------
+
+    .. manim:: SpinningTriangle
+
+        class SpinningTriangle(Scene):
+            def construct(self):
+                tri = Triangle().set_fill(opacity=1).set_z_index(2)
+                sq = Square().to_edge(LEFT)
+
+                # will keep spinning while there is an animation going on
+                always_rotate(tri, rate=2*PI, about_point=ORIGIN)
+
+                self.add(tri, sq)
+                self.play(sq.animate.to_edge(RIGHT), rate_func=linear, run_time=1)
+    """
     mobject.add_updater(lambda m, dt: m.rotate(dt * rate, **kwargs))
     return mobject
 
 
-def turn_animation_into_updater(animation, cycle=False, **kwargs):
+def turn_animation_into_updater(
+    animation: Animation, cycle: bool = False, delay: float = 0, **kwargs
+) -> Mobject:
     """
     Add an updater to the animation's mobject which applies
     the interpolation and update functions of the animation
 
     If cycle is True, this repeats over and over.  Otherwise,
     the updater will be popped upon completion
+
+    The ``delay`` parameter is the delay (in seconds) before the animation starts..
+
+    Examples
+    --------
+
+    .. manim:: WelcomeToManim
+
+        class WelcomeToManim(Scene):
+            def construct(self):
+                words = Text("Welcome to")
+                banner = ManimBanner().scale(0.5)
+                VGroup(words, banner).arrange(DOWN)
+
+                turn_animation_into_updater(Write(words, run_time=0.9))
+                self.add(words)
+                self.wait(0.5)
+                self.play(banner.expand(), run_time=0.5)
     """
     mobject = animation.mobject
     animation.suspend_mobject_updating = False
     animation.begin()
-    animation.total_time = 0
-
-    def update(m, dt):
-        run_time = animation.get_run_time()
-        time_ratio = animation.total_time / run_time
-        if cycle:
-            alpha = time_ratio % 1
-        else:
-            alpha = np.clip(time_ratio, 0, 1)
-            if alpha >= 1:
-                animation.finish()
-                m.remove_updater(update)
-                return
-        animation.interpolate(alpha)
-        animation.update_mobjects(dt)
+    animation.total_time = -delay
+
+    def update(m: Mobject, dt: float):
+        if animation.total_time >= 0:
+            run_time = animation.get_run_time()
+            time_ratio = animation.total_time / run_time
+            if cycle:
+                alpha = time_ratio % 1
+            else:
+                alpha = np.clip(time_ratio, 0, 1)
+                if alpha >= 1:
+                    animation.finish()
+                    m.remove_updater(update)
+                    return
+            animation.interpolate(alpha)
+            animation.update_mobjects(dt)
         animation.total_time += dt
 
     mobject.add_updater(update)
     return mobject
 
 
-def cycle_animation(animation, **kwargs):
+def cycle_animation(animation: Animation, **kwargs) -> Mobject:
     return turn_animation_into_updater(animation, cycle=True, **kwargs)