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

manim/utils/opengl.py

@@ -1,9 +1,25 @@
 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
+
+if TYPE_CHECKING:
+    import numpy.typing as npt
+    from typing_extensions import TypeAlias
+
+    from manim.typing import MatrixMN, Point3D
+
+
+if TYPE_CHECKING:
+    from typing_extensions import TypeAlias
+
+    from manim.typing import MatrixMN
+
 
 depth = 20
 
@@ -21,18 +37,37 @@ __all__ = [
     "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):
+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:
@@ -45,13 +80,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:
@@ -64,13 +105,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],
@@ -78,10 +119,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],
@@ -92,7 +134,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],
@@ -103,7 +145,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],
@@ -115,7 +157,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(
@@ -125,14 +169,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],
@@ -140,15 +184,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

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
+from collections.abc import Iterable
 from types import GeneratorType
-from typing import Iterable, TypeVar
+from typing import TypeVar
 
 T = TypeVar("T")
 
@@ -22,7 +23,7 @@ def flatten_iterable_parameters(
     :class:`list`
         The flattened list of parameters.
     """
-    flattened_parameters = []
+    flattened_parameters: list[T] = []
     for arg in args:
         if isinstance(arg, (Iterable, GeneratorType)):
             flattened_parameters.extend(arg)

manim/utils/paths.py

@@ -19,13 +19,13 @@ from ..utils.bezier import interpolate
 from ..utils.space_ops import rotation_matrix
 
 if TYPE_CHECKING:
-    from manim.typing import PathFuncType, Vector3D
+    from manim.typing import PathFuncType, Point3D_Array, Vector3D
 
 
 STRAIGHT_PATH_THRESHOLD = 0.01
 
 
-def straight_path():
+def straight_path() -> PathFuncType:
     """Simplest path function. Each point in a set goes in a straight path toward its destination.
 
     Examples
@@ -136,7 +136,9 @@ def path_along_circles(
         axis = OUT
     unit_axis = axis / np.linalg.norm(axis)
 
-    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
         )
@@ -206,7 +208,9 @@ def path_along_arc(arc_angle: float, axis: Vector3D = OUT) -> PathFuncType:
         axis = OUT
     unit_axis = axis / np.linalg.norm(axis)
 
-    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:
@@ -365,7 +369,9 @@ def spiral_path(angle: float, axis: Vector3D = OUT) -> PathFuncType:
         axis = OUT
     unit_axis = axis / np.linalg.norm(axis)
 
-    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,168 @@
+#!/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 collection of closed polygonal ring.
+    """
+
+    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 inside(self, point: Point2DLike) -> bool:
+        """Check if a point is inside the polygon."""
+        # Views
+        px, py = point
+        x, y = self.start[:, 0], self.start[:, 1]
+        xr, yr = self.stop[:, 0], self.stop[:, 1]
+
+        # Count Crossings (enforce short-circuit)
+        c = (y > py) != (yr > py)
+        c = px < x[c] + (py - y[c]) * (xr[c] - x[c]) / (yr[c] - y[c])
+        c_sum: int = np.sum(c)
+        return c_sum % 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

manim/utils/qhull.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from manim.typing import PointND, PointND_Array
+
+
+class QuickHullPoint:
+    def __init__(self, coordinates: PointND_Array) -> None:
+        self.coordinates = coordinates
+
+    def __hash__(self) -> int:
+        return hash(self.coordinates.tobytes())
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, QuickHullPoint):
+            raise ValueError
+        are_coordinates_equal: bool = np.array_equal(
+            self.coordinates, other.coordinates
+        )
+        return are_coordinates_equal
+
+
+class SubFacet:
+    def __init__(self, coordinates: PointND_Array) -> None:
+        self.coordinates = coordinates
+        self.points = frozenset(QuickHullPoint(c) for c in coordinates)
+
+    def __hash__(self) -> int:
+        return hash(self.points)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, SubFacet):
+            raise ValueError
+        return self.points == other.points
+
+
+class Facet:
+    def __init__(self, coordinates: PointND_Array, internal: PointND) -> None:
+        self.coordinates = coordinates
+        self.center: PointND = np.mean(coordinates, axis=0)
+        self.normal = self.compute_normal(internal)
+        self.subfacets = frozenset(
+            SubFacet(np.delete(self.coordinates, i, axis=0))
+            for i in range(self.coordinates.shape[0])
+        )
+
+    def compute_normal(self, internal: PointND) -> PointND:
+        centered = self.coordinates - self.center
+        _, _, vh = np.linalg.svd(centered)
+        normal: PointND = vh[-1, :]
+        normal /= np.linalg.norm(normal)
+
+        # If the normal points towards the internal point, flip it!
+        if np.dot(normal, self.center - internal) < 0:
+            normal *= -1
+
+        return normal
+
+    def __hash__(self) -> int:
+        return hash(self.subfacets)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Facet):
+            raise ValueError
+        return self.subfacets == other.subfacets
+
+
+class Horizon:
+    def __init__(self) -> None:
+        self.facets: set[Facet] = set()
+        self.boundary: list[SubFacet] = []
+
+
+class QuickHull:
+    """
+    QuickHull algorithm for constructing a convex hull from a set of points.
+
+    Parameters
+    ----------
+    tolerance
+        A tolerance threshold for determining when points lie on the convex hull (default is 1e-5).
+
+    Attributes
+    ----------
+    facets
+        List of facets considered.
+    removed
+        Set of internal facets that have been removed from the hull during the construction process.
+    outside
+        Dictionary mapping each facet to its outside points and eye point.
+    neighbors
+        Mapping of subfacets to their neighboring facets. Each subfacet links precisely two neighbors.
+    unclaimed
+        Points that have not yet been classified as inside or outside the current hull.
+    internal
+        An internal point (i.e., the center of the initial simplex) used as a reference during hull construction.
+    tolerance
+        The tolerance used to determine if points are considered outside the current hull.
+    """
+
+    def __init__(self, tolerance: float = 1e-5) -> None:
+        self.facets: list[Facet] = []
+        self.removed: set[Facet] = set()
+        self.outside: dict[Facet, tuple[PointND_Array | None, PointND | None]] = {}
+        self.neighbors: dict[SubFacet, set[Facet]] = {}
+        self.unclaimed: PointND_Array | None = None
+        self.internal: PointND | None = None
+        self.tolerance = tolerance
+
+    def initialize(self, points: PointND_Array) -> None:
+        # Sample Points
+        simplex = points[
+            np.random.choice(points.shape[0], points.shape[1] + 1, replace=False)
+        ]
+        self.unclaimed = points
+        new_internal: PointND = np.mean(simplex, axis=0)
+        self.internal = new_internal
+
+        # Build Simplex
+        for c in range(simplex.shape[0]):
+            facet = Facet(np.delete(simplex, c, axis=0), internal=new_internal)
+            self.classify(facet)
+            self.facets.append(facet)
+
+        # Attach Neighbors
+        for f in self.facets:
+            for sf in f.subfacets:
+                self.neighbors.setdefault(sf, set()).add(f)
+
+    def classify(self, facet: Facet) -> None:
+        assert self.unclaimed is not None, (
+            "Call .initialize() before using .classify()."
+        )
+
+        if not self.unclaimed.size:
+            self.outside[facet] = (None, None)
+            return
+
+        # Compute Projections
+        projections = (self.unclaimed - facet.center) @ facet.normal
+        arg = np.argmax(projections)
+        mask = projections > self.tolerance
+
+        # Identify Eye and Outside Set
+        eye = self.unclaimed[arg] if projections[arg] > self.tolerance else None
+        outside = self.unclaimed[mask]
+        self.outside[facet] = (outside, eye)
+        self.unclaimed = self.unclaimed[~mask]
+
+    def compute_horizon(self, eye: PointND, start_facet: Facet) -> Horizon:
+        horizon = Horizon()
+        self._recursive_horizon(eye, start_facet, horizon)
+        return horizon
+
+    def _recursive_horizon(self, eye: PointND, facet: Facet, horizon: Horizon) -> bool:
+        visible = np.dot(facet.normal, eye - facet.center) > 0
+        if not visible:
+            return False
+
+        # If the eye is visible from the facet:
+        # Label the facet as visible and cross each edge
+        horizon.facets.add(facet)
+        for subfacet in facet.subfacets:
+            neighbor = (self.neighbors[subfacet] - {facet}).pop()
+            # If the neighbor is not visible, then the edge shared must be on the boundary
+            if neighbor not in horizon.facets and not self._recursive_horizon(
+                eye, neighbor, horizon
+            ):
+                horizon.boundary.append(subfacet)
+        return True
+
+    def build(self, points: PointND_Array) -> None:
+        num, dim = points.shape
+        if (dim == 0) or (num < dim + 1):
+            raise ValueError("Not enough points supplied to build Convex Hull!")
+        if dim == 1:
+            raise ValueError("The Convex Hull of 1D data is its min-max!")
+
+        self.initialize(points)
+
+        # This helps the type checker.
+        assert self.unclaimed is not None
+        assert self.internal is not None
+
+        while True:
+            updated = False
+            for facet in self.facets:
+                if facet in self.removed:
+                    continue
+                outside, eye = self.outside[facet]
+                if eye is not None:
+                    updated = True
+                    horizon = self.compute_horizon(eye, facet)
+                    for f in horizon.facets:
+                        points_to_append = self.outside[f][0]
+                        # TODO: is this always true?
+                        assert points_to_append is not None
+                        self.unclaimed = np.vstack((self.unclaimed, points_to_append))
+                        self.removed.add(f)
+                        for sf in f.subfacets:
+                            self.neighbors[sf].discard(f)
+                            if self.neighbors[sf] == set():
+                                del self.neighbors[sf]
+                    for sf in horizon.boundary:
+                        nf = Facet(
+                            np.vstack((sf.coordinates, eye)), internal=self.internal
+                        )
+                        self.classify(nf)
+                        self.facets.append(nf)
+                        for nsf in nf.subfacets:
+                            self.neighbors.setdefault(nsf, set()).add(nf)
+            if not updated:
+                break