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

manim/utils/opengl.py

@@ -1,24 +1,67 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 import numpy as np
 import numpy.linalg as linalg
 
-from .. import config
+from manim._config import config
+from manim.typing import ManimFloat
 
-depth = 20
+if TYPE_CHECKING:
+    import numpy.typing as npt
+    from typing_extensions import TypeAlias
+
+    from manim.typing import MatrixMN, Point3D
 
 
-def matrix_to_shader_input(matrix):
+depth = 20
+
+__all__ = [
+    "matrix_to_shader_input",
+    "orthographic_projection_matrix",
+    "perspective_projection_matrix",
+    "translation_matrix",
+    "x_rotation_matrix",
+    "y_rotation_matrix",
+    "z_rotation_matrix",
+    "rotate_in_place_matrix",
+    "rotation_matrix",
+    "scale_matrix",
+    "view_matrix",
+]
+
+FlattenedMatrix4x4: TypeAlias = tuple[
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+    float,
+]
+
+
+def matrix_to_shader_input(matrix: MatrixMN) -> FlattenedMatrix4x4:
     return tuple(matrix.T.ravel())
 
 
 def orthographic_projection_matrix(
-    width=None,
-    height=None,
-    near=1,
-    far=depth + 1,
-    format=True,
-):
+    width: float | None = None,
+    height: float | None = None,
+    near: float = 1,
+    far: float = depth + 1,
+    format_: bool = True,
+) -> MatrixMN | FlattenedMatrix4x4:
     if width is None:
         width = config["frame_width"]
     if height is None:
@@ -31,13 +74,19 @@ def orthographic_projection_matrix(
             [0, 0, 0, 1],
         ],
     )
-    if format:
+    if format_:
         return matrix_to_shader_input(projection_matrix)
     else:
         return projection_matrix
 
 
-def perspective_projection_matrix(width=None, height=None, near=2, far=50, format=True):
+def perspective_projection_matrix(
+    width: float | None = None,
+    height: float | None = None,
+    near: float = 2,
+    far: float = 50,
+    format_: bool = True,
+) -> MatrixMN | FlattenedMatrix4x4:
     if width is None:
         width = config["frame_width"] / 6
     if height is None:
@@ -50,13 +99,13 @@ def perspective_projection_matrix(width=None, height=None, near=2, far=50, forma
             [0, 0, -1, 0],
         ],
     )
-    if format:
+    if format_:
         return matrix_to_shader_input(projection_matrix)
     else:
         return projection_matrix
 
 
-def translation_matrix(x=0, y=0, z=0):
+def translation_matrix(x: float = 0, y: float = 0, z: float = 0) -> MatrixMN:
     return np.array(
         [
             [1, 0, 0, x],
@@ -64,10 +113,11 @@ def translation_matrix(x=0, y=0, z=0):
             [0, 0, 1, z],
             [0, 0, 0, 1],
         ],
+        dtype=ManimFloat,
     )
 
 
-def x_rotation_matrix(x=0):
+def x_rotation_matrix(x: float = 0) -> MatrixMN:
     return np.array(
         [
             [1, 0, 0, 0],
@@ -78,7 +128,7 @@ def x_rotation_matrix(x=0):
     )
 
 
-def y_rotation_matrix(y=0):
+def y_rotation_matrix(y: float = 0) -> MatrixMN:
     return np.array(
         [
             [np.cos(y), 0, np.sin(y), 0],
@@ -89,7 +139,7 @@ def y_rotation_matrix(y=0):
     )
 
 
-def z_rotation_matrix(z=0):
+def z_rotation_matrix(z: float = 0) -> MatrixMN:
     return np.array(
         [
             [np.cos(z), -np.sin(z), 0, 0],
@@ -101,7 +151,9 @@ def z_rotation_matrix(z=0):
 
 
 # TODO: When rotating around the x axis, rotation eventually stops.
-def rotate_in_place_matrix(initial_position, x=0, y=0, z=0):
+def rotate_in_place_matrix(
+    initial_position: Point3D, x: float = 0, y: float = 0, z: float = 0
+) -> MatrixMN:
     return np.matmul(
         translation_matrix(*-initial_position),
         np.matmul(
@@ -111,14 +163,14 @@ def rotate_in_place_matrix(initial_position, x=0, y=0, z=0):
     )
 
 
-def rotation_matrix(x=0, y=0, z=0):
+def rotation_matrix(x: float = 0, y: float = 0, z: float = 0) -> MatrixMN:
     return np.matmul(
         np.matmul(x_rotation_matrix(x), y_rotation_matrix(y)),
         z_rotation_matrix(z),
     )
 
 
-def scale_matrix(scale_factor=1):
+def scale_matrix(scale_factor: float = 1) -> npt.NDArray:
     return np.array(
         [
             [scale_factor, 0, 0, 0],
@@ -126,15 +178,16 @@ def scale_matrix(scale_factor=1):
             [0, 0, scale_factor, 0],
             [0, 0, 0, 1],
         ],
+        dtype=ManimFloat,
     )
 
 
 def view_matrix(
-    translation=None,
-    x_rotation=0,
-    y_rotation=0,
-    z_rotation=0,
-):
+    translation: Point3D | None = None,
+    x_rotation: float = 0,
+    y_rotation: float = 0,
+    z_rotation: float = 0,
+) -> MatrixMN:
     if translation is None:
         translation = np.array([0, 0, depth / 2 + 1])
     model_matrix = np.matmul(

manim/utils/parameter_parsing.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from types import GeneratorType
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def flatten_iterable_parameters(
+    args: Iterable[T | Iterable[T] | GeneratorType],
+) -> list[T]:
+    """Flattens an iterable of parameters into a list of parameters.
+
+    Parameters
+    ----------
+    args
+        The iterable of parameters to flatten.
+        [(generator), [], (), ...]
+
+    Returns
+    -------
+    :class:`list`
+        The flattened list of parameters.
+    """
+    flattened_parameters: list[T] = []
+    for arg in args:
+        if isinstance(arg, (Iterable, GeneratorType)):
+            flattened_parameters.extend(arg)
+        else:
+            flattened_parameters.append(arg)
+    return flattened_parameters

manim/utils/paths.py

@@ -10,28 +10,27 @@ __all__ = [
 ]
 
 
-from typing import Callable
+from typing import TYPE_CHECKING
 
 import numpy as np
 
 from ..constants import OUT
 from ..utils.bezier import interpolate
-from ..utils.deprecation import deprecated_params
-from ..utils.space_ops import rotation_matrix
+from ..utils.space_ops import normalize, rotation_matrix
+
+if TYPE_CHECKING:
+    from manim.typing import (
+        PathFuncType,
+        Point3D_Array,
+        Point3DLike_Array,
+        Vector3DLike,
+    )
 
-STRAIGHT_PATH_THRESHOLD = 0.01
 
-PATH_FUNC_TYPE = Callable[[np.ndarray, np.ndarray, float], np.ndarray]
+STRAIGHT_PATH_THRESHOLD = 0.01
 
 
-# Remove `*args` and the `if` inside the functions when removing deprecation
-@deprecated_params(
-    params="start_points, end_points, alpha",
-    since="v0.14",
-    until="v0.15",
-    message="Straight path is now returning interpolating function to make it consistent with other path functions. Use straight_path()(a,b,c) instead of straight_path(a,b,c).",
-)
-def straight_path(*args) -> PATH_FUNC_TYPE:
+def straight_path() -> PathFuncType:
     """Simplest path function. Each point in a set goes in a straight path toward its destination.
 
     Examples
@@ -74,14 +73,12 @@ def straight_path(*args) -> PATH_FUNC_TYPE:
                 self.wait()
 
     """
-    if len(args) > 0:
-        return interpolate(*args)
     return interpolate
 
 
 def path_along_circles(
-    arc_angle: float, circles_centers: np.ndarray, axis: np.ndarray = OUT
-) -> PATH_FUNC_TYPE:
+    arc_angle: float, circles_centers: Point3DLike_Array, axis: Vector3DLike = OUT
+) -> PathFuncType:
     """This function transforms each point by moving it roughly along a circle, each with its own specified center.
 
     The path may be seen as each point smoothly changing its orbit from its starting position to its destination.
@@ -140,11 +137,11 @@ def path_along_circles(
                 self.wait()
 
     """
-    if np.linalg.norm(axis) == 0:
-        axis = OUT
-    unit_axis = axis / np.linalg.norm(axis)
+    unit_axis = normalize(axis, fall_back=OUT)
 
-    def path(start_points: np.ndarray, end_points: np.ndarray, alpha: float):
+    def path(
+        start_points: Point3D_Array, end_points: Point3D_Array, alpha: float
+    ) -> Point3D_Array:
         detransformed_end_points = circles_centers + np.dot(
             end_points - circles_centers, rotation_matrix(-arc_angle, unit_axis).T
         )
@@ -158,7 +155,7 @@ def path_along_circles(
     return path
 
 
-def path_along_arc(arc_angle: float, axis: np.ndarray = OUT) -> PATH_FUNC_TYPE:
+def path_along_arc(arc_angle: float, axis: Vector3DLike = OUT) -> PathFuncType:
     """This function transforms each point by moving it along a circular arc.
 
     Parameters
@@ -210,11 +207,11 @@ def path_along_arc(arc_angle: float, axis: np.ndarray = OUT) -> PATH_FUNC_TYPE:
     """
     if abs(arc_angle) < STRAIGHT_PATH_THRESHOLD:
         return straight_path()
-    if np.linalg.norm(axis) == 0:
-        axis = OUT
-    unit_axis = axis / np.linalg.norm(axis)
+    unit_axis = normalize(axis, fall_back=OUT)
 
-    def path(start_points: np.ndarray, end_points: np.ndarray, alpha: float):
+    def path(
+        start_points: Point3D_Array, end_points: Point3D_Array, alpha: float
+    ) -> Point3D_Array:
         vects = end_points - start_points
         centers = start_points + 0.5 * vects
         if arc_angle != np.pi:
@@ -225,7 +222,7 @@ def path_along_arc(arc_angle: float, axis: np.ndarray = OUT) -> PATH_FUNC_TYPE:
     return path
 
 
-def clockwise_path() -> PATH_FUNC_TYPE:
+def clockwise_path() -> PathFuncType:
     """This function transforms each point by moving clockwise around a half circle.
 
     Examples
@@ -271,7 +268,7 @@ def clockwise_path() -> PATH_FUNC_TYPE:
     return path_along_arc(-np.pi)
 
 
-def counterclockwise_path() -> PATH_FUNC_TYPE:
+def counterclockwise_path() -> PathFuncType:
     """This function transforms each point by moving counterclockwise around a half circle.
 
     Examples
@@ -317,7 +314,7 @@ def counterclockwise_path() -> PATH_FUNC_TYPE:
     return path_along_arc(np.pi)
 
 
-def spiral_path(angle: float, axis: np.ndarray = OUT) -> PATH_FUNC_TYPE:
+def spiral_path(angle: float, axis: Vector3DLike = OUT) -> PathFuncType:
     """This function transforms each point by moving along a spiral to its destination.
 
     Parameters
@@ -369,11 +366,11 @@ def spiral_path(angle: float, axis: np.ndarray = OUT) -> PATH_FUNC_TYPE:
     """
     if abs(angle) < STRAIGHT_PATH_THRESHOLD:
         return straight_path()
-    if np.linalg.norm(axis) == 0:
-        axis = OUT
-    unit_axis = axis / np.linalg.norm(axis)
+    unit_axis = normalize(axis, fall_back=OUT)
 
-    def path(start_points: np.ndarray, end_points: np.ndarray, alpha: float):
+    def path(
+        start_points: Point3D_Array, end_points: Point3D_Array, alpha: float
+    ) -> Point3D_Array:
         rot_matrix = rotation_matrix((alpha - 1) * angle, unit_axis)
         return start_points + alpha * np.dot(end_points - start_points, rot_matrix.T)
 

manim/utils/polylabel.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python
+from __future__ import annotations
+
+from queue import PriorityQueue
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from manim.typing import (
+        Point2D,
+        Point2D_Array,
+        Point2DLike,
+        Point2DLike_Array,
+        Point3DLike_Array,
+    )
+
+
+class Polygon:
+    """
+    Initializes the Polygon with the given rings.
+
+    Parameters
+    ----------
+    rings
+        A sequence of points, where each sequence represents the rings of the polygon.
+        Typically, multiple rings indicate holes in the polygon.
+    """
+
+    def __init__(self, rings: Sequence[Point2DLike_Array]) -> None:
+        np_rings: list[Point2D_Array] = [np.asarray(ring) for ring in rings]
+        # Flatten Array
+        csum = np.cumsum([ring.shape[0] for ring in np_rings])
+        self.array: Point2D_Array = np.concatenate(np_rings, axis=0)
+
+        # Compute Boundary
+        self.start: Point2D_Array = np.delete(self.array, csum - 1, axis=0)
+        self.stop: Point2D_Array = np.delete(self.array, csum % csum[-1], axis=0)
+        self.diff: Point2D_Array = np.delete(
+            np.diff(self.array, axis=0), csum[:-1] - 1, axis=0
+        )
+        self.norm: Point2D_Array = self.diff / np.einsum(
+            "ij,ij->i", self.diff, self.diff
+        ).reshape(-1, 1)
+
+        # Compute Centroid
+        x, y = self.start[:, 0], self.start[:, 1]
+        xr, yr = self.stop[:, 0], self.stop[:, 1]
+        self.area: float = 0.5 * (np.dot(x, yr) - np.dot(xr, y))
+        if self.area:
+            factor = x * yr - xr * y
+            cx = np.sum((x + xr) * factor) / (6.0 * self.area)
+            cy = np.sum((y + yr) * factor) / (6.0 * self.area)
+            self.centroid = np.array([cx, cy])
+
+    def compute_distance(self, point: Point2DLike) -> float:
+        """Compute the minimum distance from a point to the polygon."""
+        scalars = np.einsum("ij,ij->i", self.norm, point - self.start)
+        clips = np.clip(scalars, 0, 1).reshape(-1, 1)
+        d: float = np.min(
+            np.linalg.norm(self.start + self.diff * clips - point, axis=1)
+        )
+        return d if self.inside(point) else -d
+
+    def _is_point_on_segment(
+        self,
+        x_point: float,
+        y_point: float,
+        x0: float,
+        y0: float,
+        x1: float,
+        y1: float,
+    ) -> bool:
+        """
+        Check if a point is on the segment.
+
+        The segment is defined by (x0, y0) to (x1, y1).
+        """
+        if min(x0, x1) <= x_point <= max(x0, x1) and min(y0, y1) <= y_point <= max(
+            y0, y1
+        ):
+            dx = x1 - x0
+            dy = y1 - y0
+            cross = dx * (y_point - y0) - dy * (x_point - x0)
+            return bool(np.isclose(cross, 0.0))
+        return False
+
+    def _ray_crosses_segment(
+        self,
+        x_point: float,
+        y_point: float,
+        x0: float,
+        y0: float,
+        x1: float,
+        y1: float,
+    ) -> bool:
+        """
+        Check if a horizontal ray to the right from point (x_point, y_point) crosses the segment.
+
+        The segment is defined by (x0, y0) to (x1, y1).
+        """
+        if (y0 > y_point) != (y1 > y_point):
+            slope = (x1 - x0) / (y1 - y0)
+            x_intersect = slope * (y_point - y0) + x0
+            return bool(x_point < x_intersect)
+        return False
+
+    def inside(self, point: Point2DLike) -> bool:
+        """
+        Check if a point is inside the polygon.
+
+        Uses ray casting algorithm and checks boundary points consistently.
+        """
+        point_x, point_y = point
+        start_x, start_y = self.start[:, 0], self.start[:, 1]
+        stop_x, stop_y = self.stop[:, 0], self.stop[:, 1]
+        segment_count = len(start_x)
+
+        for i in range(segment_count):
+            if self._is_point_on_segment(
+                point_x,
+                point_y,
+                start_x[i],
+                start_y[i],
+                stop_x[i],
+                stop_y[i],
+            ):
+                return True
+
+        crossings = 0
+        for i in range(segment_count):
+            if self._ray_crosses_segment(
+                point_x,
+                point_y,
+                start_x[i],
+                start_y[i],
+                stop_x[i],
+                stop_y[i],
+            ):
+                crossings += 1
+
+        return crossings % 2 == 1
+
+
+class Cell:
+    """
+    A square in a mesh covering the :class:`~.Polygon` passed as an argument.
+
+    Parameters
+    ----------
+    c
+        Center coordinates of the Cell.
+    h
+        Half-Size of the Cell.
+    polygon
+        :class:`~.Polygon` object for which the distance is computed.
+    """
+
+    def __init__(self, c: Point2DLike, h: float, polygon: Polygon) -> None:
+        self.c: Point2D = np.asarray(c)
+        self.h = h
+        self.d = polygon.compute_distance(self.c)
+        self.p = self.d + self.h * np.sqrt(2)
+
+    def __lt__(self, other: Cell) -> bool:
+        return self.d < other.d
+
+    def __gt__(self, other: Cell) -> bool:
+        return self.d > other.d
+
+    def __le__(self, other: Cell) -> bool:
+        return self.d <= other.d
+
+    def __ge__(self, other: Cell) -> bool:
+        return self.d >= other.d
+
+
+def polylabel(rings: Sequence[Point3DLike_Array], precision: float = 0.01) -> Cell:
+    """
+    Finds the pole of inaccessibility (the point that is farthest from the edges of the polygon)
+    using an iterative grid-based approach.
+
+    Parameters
+    ----------
+    rings
+        A list of lists, where each list is a sequence of points representing the rings of the polygon.
+        Typically, multiple rings indicate holes in the polygon.
+    precision
+        The precision of the result (default is 0.01).
+
+    Returns
+    -------
+    Cell
+        A Cell containing the pole of inaccessibility to a given precision.
+    """
+    # Precompute Polygon Data
+    np_rings: list[Point2D_Array] = [np.asarray(ring)[:, :2] for ring in rings]
+    polygon = Polygon(np_rings)
+
+    # Bounding Box
+    mins = np.min(polygon.array, axis=0)
+    maxs = np.max(polygon.array, axis=0)
+    dims = maxs - mins
+    s = np.min(dims)
+    h = s / 2.0
+
+    # Initial Grid
+    queue: PriorityQueue[Cell] = PriorityQueue()
+    xv, yv = np.meshgrid(np.arange(mins[0], maxs[0], s), np.arange(mins[1], maxs[1], s))
+    for corner in np.vstack([xv.ravel(), yv.ravel()]).T:
+        queue.put(Cell(corner + h, h, polygon))
+
+    # Initial Guess
+    best = Cell(polygon.centroid, 0, polygon)
+    bbox = Cell(mins + (dims / 2), 0, polygon)
+    if bbox.d > best.d:
+        best = bbox
+
+    # While there are cells to consider...
+    directions = np.array([[-1, -1], [1, -1], [-1, 1], [1, 1]])
+    while not queue.empty():
+        cell = queue.get()
+        if cell > best:
+            best = cell
+        # If a cell is promising, subdivide!
+        if cell.p - best.d > precision:
+            h = cell.h / 2.0
+            offsets = cell.c + directions * h
+            queue.put(Cell(offsets[0], h, polygon))
+            queue.put(Cell(offsets[1], h, polygon))
+            queue.put(Cell(offsets[2], h, polygon))
+            queue.put(Cell(offsets[3], h, polygon))
+    return best