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

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

manim/utils/rate_functions.py

@@ -83,12 +83,14 @@ There are primarily 3 kinds of standard easing functions:
             self.wait()
 """
 
-
 from __future__ import annotations
 
 __all__ = [
     "linear",
     "smooth",
+    "smoothstep",
+    "smootherstep",
+    "smoothererstep",
     "rush_into",
     "rush_from",
     "slow_into",
@@ -103,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:
@@ -130,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:
@@ -155,6 +161,33 @@ def smooth(t: float, inflection: float = 10.0) -> float:
     )
 
 
+@unit_interval
+def smoothstep(t: float) -> float:
+    """Implementation of the 1st order SmoothStep sigmoid function.
+    The 1st derivative (speed) is zero at the endpoints.
+    https://en.wikipedia.org/wiki/Smoothstep
+    """
+    return 3 * t**2 - 2 * t**3
+
+
+@unit_interval
+def smootherstep(t: float) -> float:
+    """Implementation of the 2nd order SmoothStep sigmoid function.
+    The 1st and 2nd derivatives (speed and acceleration) are zero at the endpoints.
+    https://en.wikipedia.org/wiki/Smoothstep
+    """
+    return 6 * t**5 - 15 * t**4 + 10 * t**3
+
+
+@unit_interval
+def smoothererstep(t: float) -> float:
+    """Implementation of the 3rd order SmoothStep sigmoid function.
+    The 1st, 2nd and 3rd derivatives (speed, acceleration and jerk) are zero at the endpoints.
+    https://en.wikipedia.org/wiki/Smoothstep
+    """
+    return 35 * t**4 - 84 * t**5 + 70 * t**6 - 20 * t**7
+
+
 @unit_interval
 def rush_into(t: float, inflection: float = 10.0) -> float:
     return 2 * smooth(t / 2.0, inflection)
@@ -167,7 +200,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
@@ -186,7 +220,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:
@@ -199,40 +233,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
 
@@ -245,29 +299,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
@@ -404,7 +466,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
@@ -415,7 +478,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
@@ -426,9 +490,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

@@ -6,27 +6,25 @@ __all__ = [
     "binary_search",
     "choose",
     "clip",
-    "get_parameters",
     "sigmoid",
 ]
 
 
-import inspect
+from collections.abc import Callable
 from functools import lru_cache
-from types import MappingProxyType
-from typing import Callable
+from typing import Any, 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
@@ -43,10 +41,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`
@@ -57,7 +55,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))
@@ -91,10 +89,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)
+
+
+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 <, >).
@@ -117,23 +125,6 @@ def clip(a, min_a, max_a):
     return a
 
 
-def get_parameters(function: Callable) -> MappingProxyType[str, inspect.Parameter]:
-    """Return the parameters of ``function`` as an ordered mapping of parameters'
-    names to their corresponding ``Parameter`` objects.
-
-    Examples
-    --------
-    ::
-
-        >>> get_parameters(get_parameters)
-        mappingproxy(OrderedDict([('function', <Parameter "function: 'Callable'">)]))
-
-        >>> tuple(get_parameters(choose))
-        ('n', 'k')
-    """
-    return inspect.signature(function).parameters
-
-
 def sigmoid(x: float) -> float:
     r"""Returns the output of the logistic function.
 
@@ -145,4 +136,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"),