manim 0.18.1__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/utils/rate_functions.py

@@ -105,21 +105,25 @@ __all__ = [
     "exponential_decay",
 ]
 
-import typing
 from functools import wraps
 from math import sqrt
+from typing import Any, Protocol
 
 import numpy as np
 
-from ..utils.bezier import bezier
-from ..utils.simple_functions import sigmoid
+from manim.utils.simple_functions import sigmoid
+
+
+# TODO: rewrite this to use ParamSpec when Python 3.9 is out of life
+class RateFunction(Protocol):
+    def __call__(self, t: float, *args: Any, **kwargs: Any) -> float: ...
 
 
 # This is a decorator that makes sure any function it's used on will
 # return 0 if t<0 and 1 if t>1.
-def unit_interval(function):
+def unit_interval(function: RateFunction) -> RateFunction:
     @wraps(function)
-    def wrapper(t, *args, **kwargs):
+    def wrapper(t: float, *args: Any, **kwargs: Any) -> float:
         if 0 <= t <= 1:
             return function(t, *args, **kwargs)
         elif t < 0:
@@ -132,9 +136,9 @@ def unit_interval(function):
 
 # This is a decorator that makes sure any function it's used on will
 # return 0 if t<0 or t>1.
-def zero(function):
+def zero(function: RateFunction) -> RateFunction:
     @wraps(function)
-    def wrapper(t, *args, **kwargs):
+    def wrapper(t: float, *args: Any, **kwargs: Any) -> float:
         if 0 <= t <= 1:
             return function(t, *args, **kwargs)
         else:
@@ -178,7 +182,7 @@ def smoothererstep(t: float) -> float:
     The 1st, 2nd and 3rd derivatives (speed, acceleration and jerk) are zero at the endpoints.
     https://en.wikipedia.org/wiki/Smoothstep
     """
-    alpha = 0
+    alpha: float = 0
     if 0 < t < 1:
         alpha = 35 * t**4 - 84 * t**5 + 70 * t**6 - 20 * t**7
     elif t >= 1:
@@ -198,7 +202,8 @@ def rush_from(t: float, inflection: float = 10.0) -> float:
 
 @unit_interval
 def slow_into(t: float) -> float:
-    return np.sqrt(1 - (1 - t) * (1 - t))
+    val: float = np.sqrt(1 - (1 - t) * (1 - t))
+    return val
 
 
 @unit_interval
@@ -217,7 +222,7 @@ def there_and_back(t: float, inflection: float = 10.0) -> float:
 
 @zero
 def there_and_back_with_pause(t: float, pause_ratio: float = 1.0 / 3) -> float:
-    a = 1.0 / pause_ratio
+    a = 2.0 / (1.0 - pause_ratio)
     if t < 0.5 - pause_ratio / 2:
         return smooth(a * t)
     elif t < 0.5 + pause_ratio / 2:
@@ -230,40 +235,60 @@ def there_and_back_with_pause(t: float, pause_ratio: float = 1.0 / 3) -> float:
 def running_start(
     t: float,
     pull_factor: float = -0.5,
-) -> typing.Iterable:  # what is func return type?
-    return bezier([0, 0, pull_factor, pull_factor, 1, 1, 1])(t)
+) -> float:
+    t2 = t * t
+    t3 = t2 * t
+    t4 = t3 * t
+    t5 = t4 * t
+    t6 = t5 * t
+    mt = 1 - t
+    mt2 = mt * mt
+    mt3 = mt2 * mt
+    mt4 = mt3 * mt
+
+    # This is equivalent to creating a Bézier with [0, 0, pull_factor, pull_factor, 1, 1, 1]
+    # and evaluating it at t.
+    return (
+        15 * t2 * mt4 * pull_factor
+        + 20 * t3 * mt3 * pull_factor
+        + 15 * t4 * mt2
+        + 6 * t5 * mt
+        + t6
+    )
 
 
 def not_quite_there(
-    func: typing.Callable[[float], float] = smooth,
+    func: RateFunction = smooth,
     proportion: float = 0.7,
-) -> typing.Callable[[float], float]:
-    def result(t):
-        return proportion * func(t)
+) -> RateFunction:
+    def result(t: float, *args: Any, **kwargs: Any) -> float:
+        return proportion * func(t, *args, **kwargs)
 
     return result
 
 
 @zero
 def wiggle(t: float, wiggles: float = 2) -> float:
-    return there_and_back(t) * np.sin(wiggles * np.pi * t)
+    val: float = np.sin(wiggles * np.pi * t)
+    return there_and_back(t) * val
 
 
 def squish_rate_func(
-    func: typing.Callable[[float], float],
+    func: RateFunction,
     a: float = 0.4,
     b: float = 0.6,
-) -> typing.Callable[[float], float]:
-    def result(t):
+) -> RateFunction:
+    def result(t: float, *args: Any, **kwargs: Any) -> float:
         if a == b:
             return a
 
         if t < a:
-            return func(0)
+            new_t = 0.0
         elif t > b:
-            return func(1)
+            new_t = 1.0
         else:
-            return func((t - a) / (b - a))
+            new_t = (t - a) / (b - a)
+        return func(new_t, *args, **kwargs)
 
     return result
 
@@ -276,29 +301,37 @@ def squish_rate_func(
 
 @unit_interval
 def lingering(t: float) -> float:
-    return squish_rate_func(lambda t: t, 0, 0.8)(t)
+    def identity(t: float) -> float:
+        return t
+
+    # TODO: Isn't this just 0.8 * t?
+    return squish_rate_func(identity, 0, 0.8)(t)
 
 
 @unit_interval
 def exponential_decay(t: float, half_life: float = 0.1) -> float:
     # The half-life should be rather small to minimize
     # the cut-off error at the end
-    return 1 - np.exp(-t / half_life)
+    val: float = 1 - np.exp(-t / half_life)
+    return val
 
 
 @unit_interval
 def ease_in_sine(t: float) -> float:
-    return 1 - np.cos((t * np.pi) / 2)
+    val: float = 1 - np.cos((t * np.pi) / 2)
+    return val
 
 
 @unit_interval
 def ease_out_sine(t: float) -> float:
-    return np.sin((t * np.pi) / 2)
+    val: float = np.sin((t * np.pi) / 2)
+    return val
 
 
 @unit_interval
 def ease_in_out_sine(t: float) -> float:
-    return -(np.cos(np.pi * t) - 1) / 2
+    val: float = -(np.cos(np.pi * t) - 1) / 2
+    return val
 
 
 @unit_interval
@@ -435,7 +468,8 @@ def ease_in_elastic(t: float) -> float:
     elif t == 1:
         return 1
     else:
-        return -pow(2, 10 * t - 10) * np.sin((t * 10 - 10.75) * c4)
+        val: float = -pow(2, 10 * t - 10) * np.sin((t * 10 - 10.75) * c4)
+        return val
 
 
 @unit_interval
@@ -446,7 +480,8 @@ def ease_out_elastic(t: float) -> float:
     elif t == 1:
         return 1
     else:
-        return pow(2, -10 * t) * np.sin((t * 10 - 0.75) * c4) + 1
+        val: float = pow(2, -10 * t) * np.sin((t * 10 - 0.75) * c4) + 1
+        return val
 
 
 @unit_interval
@@ -457,9 +492,11 @@ def ease_in_out_elastic(t: float) -> float:
     elif t == 1:
         return 1
     elif t < 0.5:
-        return -(pow(2, 20 * t - 10) * np.sin((20 * t - 11.125) * c5)) / 2
+        val: float = -(pow(2, 20 * t - 10) * np.sin((20 * t - 11.125) * c5)) / 2
+        return val
     else:
-        return (pow(2, -20 * t + 10) * np.sin((20 * t - 11.125) * c5)) / 2 + 1
+        val = (pow(2, -20 * t + 10) * np.sin((20 * t - 11.125) * c5)) / 2 + 1
+        return val
 
 
 @unit_interval

manim/utils/simple_functions.py

@@ -10,22 +10,20 @@ __all__ = [
 ]
 
 
-import inspect
 from functools import lru_cache
-from types import MappingProxyType
-from typing import Callable
+from typing import Any, Callable, Protocol, TypeVar
 
 import numpy as np
 from scipy import special
 
 
 def binary_search(
-    function: Callable[[int | float], int | float],
-    target: int | float,
-    lower_bound: int | float,
-    upper_bound: int | float,
-    tolerance: int | float = 1e-4,
-) -> int | float | None:
+    function: Callable[[float], float],
+    target: float,
+    lower_bound: float,
+    upper_bound: float,
+    tolerance: float = 1e-4,
+) -> float | None:
     """Searches for a value in a range by repeatedly dividing the range in half.
 
     To be more precise, performs numerical binary search to determine the
@@ -42,10 +40,10 @@ def binary_search(
     ::
 
         >>> solution = binary_search(lambda x: x**2 + 3*x + 1, 11, 0, 5)
-        >>> abs(solution - 2) < 1e-4
+        >>> bool(abs(solution - 2) < 1e-4)
         True
         >>> solution = binary_search(lambda x: x**2 + 3*x + 1, 11, 0, 5, tolerance=0.01)
-        >>> abs(solution - 2) < 0.01
+        >>> bool(abs(solution - 2) < 0.01)
         True
 
     Searching in the interval :math:`[0, 5]` for a target value of :math:`71`
@@ -56,7 +54,7 @@ def binary_search(
     """
     lh = lower_bound
     rh = upper_bound
-    mh = np.mean(np.array([lh, rh]))
+    mh: float = np.mean(np.array([lh, rh]))
     while abs(rh - lh) > tolerance:
         mh = np.mean(np.array([lh, rh]))
         lx, mx, rx = (function(h) for h in (lh, mh, rh))
@@ -90,10 +88,20 @@ def choose(n: int, k: int) -> int:
     - https://en.wikipedia.org/wiki/Combination
     - https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.comb.html
     """
-    return special.comb(n, k, exact=True)
+    value: int = special.comb(n, k, exact=True)
+    return value
 
 
-def clip(a, min_a, max_a):
+class Comparable(Protocol):
+    def __lt__(self, other: Any) -> bool: ...
+
+    def __gt__(self, other: Any) -> bool: ...
+
+
+ComparableT = TypeVar("ComparableT", bound=Comparable)  # noqa: Y001
+
+
+def clip(a: ComparableT, min_a: ComparableT, max_a: ComparableT) -> ComparableT:
     """Clips ``a`` to the interval [``min_a``, ``max_a``].
 
     Accepts any comparable objects (i.e. those that support <, >).
@@ -127,4 +135,5 @@ def sigmoid(x: float) -> float:
     - https://en.wikipedia.org/wiki/Sigmoid_function
     - https://en.wikipedia.org/wiki/Logistic_function
     """
-    return 1.0 / (1 + np.exp(-x))
+    value: float = 1.0 / (1 + np.exp(-x))
+    return value

manim/utils/sounds.py

@@ -6,13 +6,19 @@ __all__ = [
     "get_full_sound_file_path",
 ]
 
+from typing import TYPE_CHECKING
 
 from .. import config
 from ..utils.file_ops import seek_full_path_from_defaults
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from manim.typing import StrPath
+
 
 # Still in use by add_sound() function in scene_file_writer.py
-def get_full_sound_file_path(sound_file_name):
+def get_full_sound_file_path(sound_file_name: StrPath) -> Path:
     return seek_full_path_from_defaults(
         sound_file_name,
         default_dir=config.get_dir("assets_dir"),

manim/utils/space_ops.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 import itertools as it
-from typing import TYPE_CHECKING, Sequence
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Callable
 
 import numpy as np
 from mapbox_earcut import triangulate_float32 as earcut
 from scipy.spatial.transform import Rotation
 
-from manim.constants import DOWN, OUT, PI, RIGHT, TAU, UP, RendererType
+from manim.constants import DOWN, OUT, PI, RIGHT, TAU, UP
 from manim.utils.iterables import adjacent_pairs
 
 if TYPE_CHECKING:
@@ -17,10 +18,17 @@ if TYPE_CHECKING:
 
     from manim.typing import (
         ManimFloat,
-        Point3D_Array,
+        MatrixMN,
+        Point2D_Array,
+        Point3D,
+        Point3DLike,
+        Point3DLike_Array,
+        PointND,
+        PointNDLike_Array,
         Vector2D,
         Vector2D_Array,
         Vector3D,
+        Vector3D_Array,
     )
 
 __all__ = [
@@ -58,7 +66,8 @@ __all__ = [
 
 
 def norm_squared(v: float) -> float:
-    return np.dot(v, v)
+    val: float = np.dot(v, v)
+    return val
 
 
 def cross(v1: Vector3D, v2: Vector3D) -> Vector3D:
@@ -192,7 +201,6 @@ def rotate_vector(
     ValueError
         If vector is not of dimension 2 or 3.
     """
-
     if len(vector) > 3:
         raise ValueError("Vector must have the correct dimensions.")
     if len(vector) == 2:
@@ -200,7 +208,7 @@ def rotate_vector(
     return rotation_matrix(angle, axis) @ vector
 
 
-def thick_diagonal(dim: int, thickness=2) -> np.ndarray:
+def thick_diagonal(dim: int, thickness: int = 2) -> MatrixMN:
     row_indices = np.arange(dim).repeat(dim).reshape((dim, dim))
     col_indices = np.transpose(row_indices)
     return (np.abs(row_indices - col_indices) < thickness).astype("uint8")
@@ -248,9 +256,7 @@ def rotation_matrix(
     axis: np.ndarray,
     homogeneous: bool = False,
 ) -> np.ndarray:
-    """
-    Rotation in R^3 about a specified axis of rotation.
-    """
+    """Rotation in R^3 about a specified axis of rotation."""
     inhomogeneous_rotation_matrix = Rotation.from_rotvec(
         angle * normalize(np.array(axis))
     ).as_matrix()
@@ -320,8 +326,10 @@ def angle_of_vector(vector: Sequence[float] | np.ndarray) -> float:
         c_vec = np.empty(vector.shape[1], dtype=np.complex128)
         c_vec.real = vector[0]
         c_vec.imag = vector[1]
-        return np.angle(c_vec)
-    return np.angle(complex(*vector[:2]))
+        val1: float = np.angle(c_vec)
+        return val1
+    val: float = np.angle(complex(*vector[:2]))
+    return val
 
 
 def angle_between_vectors(v1: np.ndarray, v2: np.ndarray) -> float:
@@ -340,14 +348,17 @@ def angle_between_vectors(v1: np.ndarray, v2: np.ndarray) -> float:
     float
         The angle between the vectors.
     """
-
-    return 2 * np.arctan2(
+    val: float = 2 * np.arctan2(
         np.linalg.norm(normalize(v1) - normalize(v2)),
         np.linalg.norm(normalize(v1) + normalize(v2)),
     )
 
+    return val
+
 
-def normalize(vect: np.ndarray | tuple[float], fall_back=None) -> np.ndarray:
+def normalize(
+    vect: np.ndarray | tuple[float], fall_back: np.ndarray | None = None
+) -> np.ndarray:
     norm = np.linalg.norm(vect)
     if norm > 0:
         return np.array(vect) / norm
@@ -473,12 +484,8 @@ def regular_vertices(
     start_angle : :class:`float`
         The angle the vertices start at.
     """
-
     if start_angle is None:
-        if n % 2 == 0:
-            start_angle = 0
-        else:
-            start_angle = TAU / 4
+        start_angle = 0 if n % 2 == 0 else TAU / 4
 
     start_vector = rotate_vector(RIGHT * radius, start_angle)
     vertices = compass_directions(n, start_vector)
@@ -494,11 +501,13 @@ def R3_to_complex(point: Sequence[float]) -> np.ndarray:
     return complex(*point[:2])
 
 
-def complex_func_to_R3_func(complex_func):
+def complex_func_to_R3_func(
+    complex_func: Callable[[complex], complex],
+) -> Callable[[Point3DLike], Point3D]:
     return lambda p: complex_to_R3(complex_func(R3_to_complex(p)))
 
 
-def center_of_mass(points: Sequence[float]) -> np.ndarray:
+def center_of_mass(points: PointNDLike_Array) -> PointND:
     """Gets the center of mass of the points in space.
 
     Parameters
@@ -580,12 +589,12 @@ def line_intersection(
 
 
 def find_intersection(
-    p0s: Sequence[np.ndarray] | Point3D_Array,
-    v0s: Sequence[np.ndarray] | Point3D_Array,
-    p1s: Sequence[np.ndarray] | Point3D_Array,
-    v1s: Sequence[np.ndarray] | Point3D_Array,
+    p0s: Point3DLike_Array,
+    v0s: Vector3D_Array,
+    p1s: Point3DLike_Array,
+    v1s: Vector3D_Array,
     threshold: float = 1e-5,
-) -> Sequence[np.ndarray]:
+) -> list[Point3D]:
     """
     Return the intersection of a line passing through p0 in direction v0
     with one passing through p1 in direction v1 (or array of intersections
@@ -620,21 +629,22 @@ def get_winding_number(points: Sequence[np.ndarray]) -> float:
     >>> from manim import Square, get_winding_number
     >>> polygon = Square()
     >>> get_winding_number(polygon.get_vertices())
-    1.0
-    >>> polygon.shift(2*UP)
+    np.float64(1.0)
+    >>> polygon.shift(2 * UP)
     Square
     >>> get_winding_number(polygon.get_vertices())
-    0.0
+    np.float64(0.0)
     """
-    total_angle = 0
+    total_angle: float = 0
     for p1, p2 in adjacent_pairs(points):
         d_angle = angle_of_vector(p2) - angle_of_vector(p1)
         d_angle = ((d_angle + PI) % TAU) - PI
         total_angle += d_angle
-    return total_angle / TAU
+    val: float = total_angle / TAU
+    return val
 
 
-def shoelace(x_y: np.ndarray) -> float:
+def shoelace(x_y: Point2D_Array) -> float:
     """2D implementation of the shoelace formula.
 
     Returns
@@ -644,10 +654,11 @@ def shoelace(x_y: np.ndarray) -> float:
     """
     x = x_y[:, 0]
     y = x_y[:, 1]
-    return np.trapz(y, x)
+    val: float = np.trapz(y, x)
+    return val
 
 
-def shoelace_direction(x_y: np.ndarray) -> str:
+def shoelace_direction(x_y: Point2D_Array) -> str:
     """
     Uses the area determined by the shoelace method to determine whether
     the input set of points is directed clockwise or counterclockwise.
@@ -687,7 +698,7 @@ def cross2d(
     .. code-block:: pycon
 
         >>> cross2d(np.array([1, 2]), np.array([3, 4]))
-        -2
+        np.int64(-2)
         >>> cross2d(
         ...     np.array([[1, 2, 0], [1, 0, 0]]),
         ...     np.array([[3, 4, 0], [0, 1, 0]]),
@@ -765,7 +776,7 @@ def earclip_triangulation(verts: np.ndarray, ring_ends: list) -> list:
             raise Exception("Could not find a ring to attach")
 
     # Setup linked list
-    after = []
+    after: list[int] = []
     end0 = 0
     for end1 in ring_ends:
         after.extend(range(end0 + 1, end1))
@@ -836,7 +847,7 @@ def spherical_to_cartesian(spherical: Sequence[float]) -> np.ndarray:
 
 def perpendicular_bisector(
     line: Sequence[np.ndarray],
-    norm_vector=OUT,
+    norm_vector: Vector3D = OUT,
 ) -> Sequence[np.ndarray]:
     """Returns a list of two points that correspond
     to the ends of the perpendicular bisector of the

manim/utils/testing/_frames_testers.py

@@ -1,21 +1,25 @@
 from __future__ import annotations
 
 import contextlib
+import logging
 import warnings
+from collections.abc import Generator
 from pathlib import Path
 
 import numpy as np
 
-from manim import logger
+from manim.typing import PixelArray
 
 from ._show_diff import show_diff_helper
 
 FRAME_ABSOLUTE_TOLERANCE = 1.01
 FRAME_MISMATCH_RATIO_TOLERANCE = 1e-5
 
+logger = logging.getLogger("manim")
+
 
 class _FramesTester:
-    def __init__(self, file_path: Path, show_diff=False) -> None:
+    def __init__(self, file_path: Path, show_diff: bool = False) -> None:
         self._file_path = file_path
         self._show_diff = show_diff
         self._frames: np.ndarray
@@ -23,7 +27,7 @@ class _FramesTester:
         self._frames_compared = 0
 
     @contextlib.contextmanager
-    def testing(self):
+    def testing(self) -> Generator[None, None, None]:
         with np.load(self._file_path) as data:
             self._frames = data["frame_data"]
             # For backward compatibility, when the control data contains only one frame (<= v0.8.0)
@@ -37,7 +41,7 @@ class _FramesTester:
                 f"when there are {self._number_frames} control frames for this test."
             )
 
-    def check_frame(self, frame_number: int, frame: np.ndarray):
+    def check_frame(self, frame_number: int, frame: PixelArray) -> None:
         assert frame_number < self._number_frames, (
             f"The tested scene is at frame number {frame_number} "
             f"when there are {self._number_frames} control frames."
@@ -63,7 +67,8 @@ class _FramesTester:
                 warnings.warn(
                     f"Mismatch of {number_of_mismatches} pixel values in frame {frame_number} "
                     f"against control data in {self._file_path}. Below error threshold, "
-                    "continuing..."
+                    "continuing...",
+                    stacklevel=1,
                 )
                 return
 
@@ -84,17 +89,17 @@ class _ControlDataWriter(_FramesTester):
         self._number_frames_written: int = 0
 
     # Actually write a frame.
-    def check_frame(self, index: int, frame: np.ndarray):
+    def check_frame(self, index: int, frame: PixelArray) -> None:
         frame = frame[np.newaxis, ...]
         self.frames = np.concatenate((self.frames, frame))
         self._number_frames_written += 1
 
     @contextlib.contextmanager
-    def testing(self):
+    def testing(self) -> Generator[None, None, None]:
         yield
         self.save_contol_data()
 
-    def save_contol_data(self):
+    def save_contol_data(self) -> None:
         self.frames = self.frames.astype("uint8")
         np.savez_compressed(self.file_path, frame_data=self.frames)
         logger.info(

manim/utils/testing/_show_diff.py

@@ -5,13 +5,15 @@ import warnings
 
 import numpy as np
 
+from manim.typing import PixelArray
+
 
 def show_diff_helper(
     frame_number: int,
-    frame_data: np.ndarray,
-    expected_frame_data: np.ndarray,
+    frame_data: PixelArray,
+    expected_frame_data: PixelArray,
     control_data_filename: str,
-):
+) -> None:
     """Will visually display with matplotlib differences between frame generated and the one expected."""
     import matplotlib.gridspec as gridspec
     import matplotlib.pyplot as plt