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

manim/utils/space_ops.py

@@ -2,7 +2,34 @@
 
 from __future__ import annotations
 
-from manim.typing import Point3D_Array, Vector
+import itertools as it
+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
+from manim.utils.iterables import adjacent_pairs
+
+if TYPE_CHECKING:
+    import numpy.typing as npt
+
+    from manim.typing import (
+        ManimFloat,
+        MatrixMN,
+        Point2D_Array,
+        Point3D,
+        Point3DLike,
+        Point3DLike_Array,
+        PointND,
+        PointNDLike_Array,
+        Vector2D,
+        Vector2D_Array,
+        Vector3D,
+        Vector3D_Array,
+    )
 
 __all__ = [
     "quaternion_mult",
@@ -38,19 +65,19 @@ __all__ = [
 ]
 
 
-import itertools as it
-from typing import Sequence
-
-import numpy as np
-from mapbox_earcut import triangulate_float32 as earcut
-from scipy.spatial.transform import Rotation
-
-from ..constants import DOWN, OUT, PI, RIGHT, TAU, UP, RendererType
-from ..utils.iterables import adjacent_pairs
+def norm_squared(v: float) -> float:
+    val: float = np.dot(v, v)
+    return val
 
 
-def norm_squared(v: float) -> float:
-    return np.dot(v, v)
+def cross(v1: Vector3D, v2: Vector3D) -> Vector3D:
+    return np.array(
+        [
+            v1[1] * v2[2] - v1[2] * v2[1],
+            v1[2] * v2[0] - v1[0] * v2[2],
+            v1[0] * v2[1] - v1[1] * v2[0],
+        ]
+    )
 
 
 # Quaternions
@@ -104,7 +131,7 @@ def quaternion_from_angle_axis(
 
     Returns
     -------
-    List[float]
+    list[float]
         Gives back a quaternion from the angle and axis
     """
     if not axis_normalized:
@@ -174,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:
@@ -182,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")
@@ -230,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()
@@ -273,12 +297,12 @@ def z_to_vector(vector: np.ndarray) -> np.ndarray:
     (normalized) vector provided as an argument
     """
     axis_z = normalize(vector)
-    axis_y = normalize(np.cross(axis_z, RIGHT))
-    axis_x = np.cross(axis_y, axis_z)
+    axis_y = normalize(cross(axis_z, RIGHT))
+    axis_x = cross(axis_y, axis_z)
     if np.linalg.norm(axis_y) == 0:
         # the vector passed just so happened to be in the x direction.
-        axis_x = normalize(np.cross(UP, axis_z))
-        axis_y = -np.cross(axis_x, axis_z)
+        axis_x = normalize(cross(UP, axis_z))
+        axis_y = -cross(axis_x, axis_z)
 
     return np.array([axis_x, axis_y, axis_z]).T
 
@@ -302,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:
@@ -322,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
@@ -359,7 +388,7 @@ def normalize_along_axis(array: np.ndarray, axis: np.ndarray) -> np.ndarray:
     return array
 
 
-def get_unit_normal(v1: np.ndarray, v2: np.ndarray, tol: float = 1e-6) -> np.ndarray:
+def get_unit_normal(v1: Vector3D, v2: Vector3D, tol: float = 1e-6) -> Vector3D:
     """Gets the unit normal of the vectors.
 
     Parameters
@@ -376,16 +405,37 @@ def get_unit_normal(v1: np.ndarray, v2: np.ndarray, tol: float = 1e-6) -> np.nda
     np.ndarray
         The normal of the two vectors.
     """
-    v1, v2 = (normalize(i) for i in (v1, v2))
-    cp = np.cross(v1, v2)
-    cp_norm = np.linalg.norm(cp)
-    if cp_norm < tol:
-        # Vectors align, so find a normal to them in the plane shared with the z-axis
-        cp = np.cross(np.cross(v1, OUT), v1)
-        cp_norm = np.linalg.norm(cp)
-        if cp_norm < tol:
+    # Instead of normalizing v1 and v2, just divide by the greatest
+    # of all their absolute components, which is just enough
+    div1, div2 = max(np.abs(v1)), max(np.abs(v2))
+    if div1 == 0.0:
+        if div2 == 0.0:
             return DOWN
-    return normalize(cp)
+        u = v2 / div2
+    elif div2 == 0.0:
+        u = v1 / div1
+    else:
+        # Normal scenario: v1 and v2 are both non-null
+        u1, u2 = v1 / div1, v2 / div2
+        cp = cross(u1, u2)
+        cp_norm = np.sqrt(norm_squared(cp))
+        if cp_norm > tol:
+            return cp / cp_norm
+        # Otherwise, v1 and v2 were aligned
+        u = u1
+
+    # If you are here, you have an "unique", non-zero, unit-ish vector u
+    # If it's also too aligned to the Z axis, just return DOWN
+    if abs(u[0]) < tol and abs(u[1]) < tol:
+        return DOWN
+    # Otherwise rotate u in the plane it shares with the Z axis,
+    # 90° TOWARDS the Z axis. This is done via (u x [0, 0, 1]) x u,
+    # which gives [-xz, -yz, x²+y²] (slightly scaled as well)
+    cp = np.array([-u[0] * u[2], -u[1] * u[2], u[0] * u[0] + u[1] * u[1]])
+    cp_norm = np.sqrt(norm_squared(cp))
+    # Because the norm(u) == 0 case was filtered in the beginning,
+    # there is no need to check if the norm of cp is 0
+    return cp / cp_norm
 
 
 ###
@@ -434,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)
@@ -455,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
@@ -529,8 +577,8 @@ def line_intersection(
         np.pad(np.array(i)[:, :2], ((0, 0), (0, 1)), constant_values=1)
         for i in (line1, line2)
     )
-    line1, line2 = (np.cross(*i) for i in padded)
-    x, y, z = np.cross(line1, line2)
+    line1, line2 = (cross(*i) for i in padded)
+    x, y, z = cross(line1, line2)
 
     if z == 0:
         raise ValueError(
@@ -541,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
@@ -558,7 +606,7 @@ def find_intersection(
     result = []
 
     for p0, v0, p1, v1 in zip(*[p0s, v0s, p1s, v1s]):
-        normal = np.cross(v1, np.cross(v0, v1))
+        normal = cross(v1, cross(v0, v1))
         denom = max(np.dot(v0, normal), threshold)
         result += [p0 + np.dot(p1 - p0, normal) / denom * v0]
     return result
@@ -581,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
@@ -605,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.
@@ -623,8 +673,9 @@ def shoelace_direction(x_y: np.ndarray) -> str:
 
 
 def cross2d(
-    a: Sequence[Vector] | Vector, b: Sequence[Vector] | Vector
-) -> Sequence[float] | float:
+    a: Vector2D | Vector2D_Array,
+    b: Vector2D | Vector2D_Array,
+) -> ManimFloat | npt.NDArray[ManimFloat]:
     """Compute the determinant(s) of the passed
     vector (sequences).
 
@@ -647,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]]),
@@ -715,12 +766,17 @@ def earclip_triangulation(verts: np.ndarray, ring_ends: list) -> list:
 
         # Move the ring which j belongs to from the
         # attached list to the detached list
-        new_ring = next(filter(lambda ring: ring[0] <= j < ring[-1], detached_rings))
-        detached_rings.remove(new_ring)
-        attached_rings.append(new_ring)
+        new_ring = next(
+            (ring for ring in detached_rings if ring[0] <= j < ring[-1]), None
+        )
+        if new_ring is not None:
+            detached_rings.remove(new_ring)
+            attached_rings.append(new_ring)
+        else:
+            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))
@@ -791,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
@@ -814,6 +870,6 @@ def perpendicular_bisector(
     """
     p1 = line[0]
     p2 = line[1]
-    direction = np.cross(p1 - p2, norm_vector)
+    direction = cross(p1 - p2, norm_vector)
     m = midpoint(p1, p2)
     return [m + direction, m - direction]

manim/utils/testing/__init__.py

@@ -0,0 +1,17 @@
+"""Utilities for Manim tests using `pytest <https://pytest.org>`_.
+
+For more information about Manim testing, see:
+
+-   :doc:`/contributing/development`, specifically the ``Tests`` bullet
+    point under :ref:`polishing-changes-and-submitting-a-pull-request`
+-   :doc:`/contributing/testing`
+
+.. autosummary::
+   :toctree: ../reference
+
+   frames_comparison
+   _frames_testers
+   _show_diff
+   _test_class_makers
+
+"""

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

manim/utils/testing/_test_class_makers.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
-from typing import Callable
+from typing import Any, Callable
 
+from manim.renderer.cairo_renderer import CairoRenderer
+from manim.renderer.opengl_renderer import OpenGLRenderer
 from manim.scene.scene import Scene
 from manim.scene.scene_file_writer import SceneFileWriter
+from manim.typing import PixelArray, StrPath
 
 from ._frames_testers import _FramesTester
 
@@ -11,13 +14,14 @@ from ._frames_testers import _FramesTester
 def _make_test_scene_class(
     base_scene: type[Scene],
     construct_test: Callable[[Scene], None],
-    test_renderer,
+    test_renderer: CairoRenderer | OpenGLRenderer | None,
 ) -> type[Scene]:
-    class _TestedScene(base_scene):
-        def __init__(self, *args, **kwargs):
-            super().__init__(renderer=test_renderer, *args, **kwargs)
+    # TODO: Get the type annotation right for the base_scene argument.
+    class _TestedScene(base_scene):  # type: ignore[valid-type, misc]
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            super().__init__(*args, renderer=test_renderer, **kwargs)
 
-        def construct(self):
+        def construct(self) -> None:
             construct_test(self)
 
             # Manim hack to render the very last frame (normally the last frame is not the very end of the animation)
@@ -28,7 +32,7 @@ def _make_test_scene_class(
     return _TestedScene
 
 
-def _make_test_renderer_class(from_renderer):
+def _make_test_renderer_class(from_renderer: type) -> Any:
     # Just for inheritance.
     class _TestRenderer(from_renderer):
         pass
@@ -39,39 +43,50 @@ def _make_test_renderer_class(from_renderer):
 class DummySceneFileWriter(SceneFileWriter):
     """Delegate of SceneFileWriter used to test the frames."""
 
-    def __init__(self, renderer, scene_name, **kwargs):
+    def __init__(
+        self,
+        renderer: CairoRenderer | OpenGLRenderer,
+        scene_name: StrPath,
+        **kwargs: Any,
+    ) -> None:
         super().__init__(renderer, scene_name, **kwargs)
         self.i = 0
 
-    def init_output_directories(self, scene_name):
+    def init_output_directories(self, scene_name: StrPath) -> None:
         pass
 
-    def add_partial_movie_file(self, hash_animation):
+    def add_partial_movie_file(self, hash_animation: str) -> None:
         pass
 
-    def begin_animation(self, allow_write=True):
+    def begin_animation(
+        self, allow_write: bool = True, file_path: StrPath | None = None
+    ) -> Any:
         pass
 
-    def end_animation(self, allow_write):
+    def end_animation(self, allow_write: bool = False) -> None:
         pass
 
-    def combine_to_movie(self):
+    def combine_to_movie(self) -> None:
         pass
 
-    def combine_to_section_videos(self):
+    def combine_to_section_videos(self) -> None:
         pass
 
-    def clean_cache(self):
+    def clean_cache(self) -> None:
         pass
 
-    def write_frame(self, frame_or_renderer):
+    def write_frame(
+        self, frame_or_renderer: PixelArray | OpenGLRenderer, num_frames: int = 1
+    ) -> None:
         self.i += 1
 
 
 def _make_scene_file_writer_class(tester: _FramesTester) -> type[SceneFileWriter]:
     class TestSceneFileWriter(DummySceneFileWriter):
-        def write_frame(self, frame_or_renderer):
+        def write_frame(
+            self, frame_or_renderer: PixelArray | OpenGLRenderer, num_frames: int = 1
+        ) -> None:
             tester.check_frame(self.i, frame_or_renderer)
-            super().write_frame(frame_or_renderer)
+            super().write_frame(frame_or_renderer, num_frames=num_frames)
 
     return TestSceneFileWriter