The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.
Python
Implement path geometry
Sina Atalaycc6fa864c853
diff --git a/src/manimgx/drawing/__init__.py b/src/manimgx/drawing/__init__.pynew file mode 100644index 00000000..e69de29bdiff --git a/src/manimgx/drawing/geometry.py b/src/manimgx/drawing/geometry.pynew file mode 100644index 00000000..679a67ca--- /dev/null+++ b/src/manimgx/drawing/geometry.py@@ -0,0 +1,2223 @@+# SPDX-FileCopyrightText: 2026 Academa, Inc.+# SPDX-FileCopyrightText: 2024 the Manim Community Developers+# SPDX-FileCopyrightText: 2018 3Blue1Brown LLC+# SPDX-License-Identifier: MIT++"""Geometry as values: vectors, cubic curves, polygon queries, shapes and affine blends.++A shape owns immutable points. A blend places shapes as Σ Mₖ·Sₖ; a path describes+how its coefficients change. The numerical operations here construct, query and+subdivide that geometry without scene objects or rendering state.+"""++from __future__ import annotations++import functools+import heapq+import itertools+import math+from collections.abc import Callable, Iterable, Sequence+from dataclasses import dataclass, field+from types import ModuleType+from typing import TYPE_CHECKING, Final, Literal++import numpy as np+import numpy.typing as npt++from manimgx._engine import digest+from manimgx.caches import Memo, forgets, unchanged+from manimgx.typing import (+ MatrixMN,+ PathFunc,+ Point3D,+ Point3D_Array,+ Point3DLike,+ Point3DLike_Array,+ Vec,+ Vector3D,+ Vector3DLike,+)++if TYPE_CHECKING:+ from pathops import Path as SkiaPath++ from manimgx.typing import (+ Point2D,+ Point2D_Array,+ Point2DLike,+ Point2DLike_Array,+ PointND,+ PointND_Array,+ )+++__all__ = [+ "STRAIGHT_PATH_THRESHOLD",+ "Coefficients",+ "Floats",+ "Path",+ "QuickHull",+ "R3_to_complex",+ "Step",+ "angle_axis_from_quaternion",+ "angle_between_vectors",+ "angle_of_vector",+ "bezier",+ "bezier_remap",+ "carried",+ "cartesian_to_spherical",+ "center_of_mass",+ "clockwise_path",+ "compass_directions",+ "complex_func_to_R3_func",+ "complex_to_R3",+ "counterclockwise_path",+ "cross2d",+ "earclip_triangulation",+ "find_intersection",+ "get_smooth_cubic_bezier_handle_points",+ "get_unit_normal",+ "get_winding_number",+ "integer_interpolate",+ "interpolate",+ "inverse_interpolate",+ "is_closed",+ "line_intersection",+ "midpoint",+ "norm_squared",+ "normalize",+ "normalize_along_axis",+ "partial_bezier_points",+ "path_along_arc",+ "path_along_circles",+ "perpendicular_bisector",+ "polylabel",+ "quaternion_conjugate",+ "quaternion_from_angle_axis",+ "quaternion_mult",+ "regular_vertices",+ "rotate_vector",+ "rotation_about_z",+ "rotation_matrix",+ "rotation_matrix_from_quaternion",+ "rotation_matrix_transpose",+ "rotation_matrix_transpose_from_quaternion",+ "shoelace",+ "shoelace_direction",+ "sigmoid",+ "spherical_to_cartesian",+ "spiral_path",+ "straight_path",+ "subdivide_bezier",+ "thick_diagonal",+ "z_to_vector",+]++_OUT = np.array([0.0, 0.0, 1.0])+_RIGHT = np.array([1.0, 0.0, 0.0])+_UP = np.array([0.0, 1.0, 0.0])+_DOWN = np.array([0.0, -1.0, 0.0])+++def normalize(vect: Vector3DLike) -> Vector3D:+ """The unit vector in a vector's direction.++ Args:+ vect: The vector.++ Returns:+ The vector divided by its length; the zero vector stays zero.+ """+ v = np.asarray(vect, dtype=float)+ norm = np.linalg.norm(v)+ return v / norm if norm > 0 else np.zeros(len(v))+++def rotation_matrix(angle: float, axis: Vector3DLike = _OUT) -> MatrixMN:+ """The matrix of a rotation about an axis through the origin.++ Raises ValueError for a zero axis: a turn about no axis is no turn at all.++ Args:+ angle: The angle, in radians, counterclockwise as seen from the tip of `axis`.+ axis: The axis's direction (its length does not matter).++ Returns:+ The 3×3 rotation matrix.+ """+ # Rodrigues' formula; identical to scipy's+ # `Rotation.from_rotvec(angle * axis).as_matrix()`+ x, y, z = normalize(axis)+ if x == y == z == 0:+ raise ValueError(f"a rotation's axis must not be zero, not {axis}")+ c, s = np.cos(angle), np.sin(angle)+ C = 1 - c+ return np.array(+ [+ [c + x * x * C, x * y * C - z * s, x * z * C + y * s],+ [y * x * C + z * s, c + y * y * C, y * z * C - x * s],+ [z * x * C - y * s, z * y * C + x * s, c + z * z * C],+ ]+ )+++def rotation_about_z(angle: float) -> MatrixMN:+ """The matrix of a rotation about the z axis.++ Args:+ angle: The angle, in radians, counterclockwise.++ Returns:+ The 3×3 rotation matrix.+ """+ c, s = np.cos(angle), np.sin(angle)+ return np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]])+++def rotate_vector(+ vector: Vector3DLike, angle: float, axis: Vector3DLike = _OUT+) -> Vector3D:+ """A vector rotated about an axis through the origin.++ Args:+ vector: The vector; a two-dimensional one gets a z of 0.+ angle: The angle, in radians, counterclockwise as seen from the tip of `axis`.+ axis: The axis's direction.++ Returns:+ The rotated vector.+ """+ v = np.asarray(vector, dtype=float)+ if len(v) == 2:+ v = np.append(v, 0)+ return rotation_matrix(angle, axis) @ v+++def z_to_vector(vector: Vector3DLike) -> MatrixMN:+ """A rotation that takes the z axis to a vector's direction.++ Args:+ vector: The direction.++ Returns:+ The 3×3 rotation matrix, whose columns are where the x, y and z axes go.+ """+ axis_z = normalize(vector)+ axis_y = normalize(np.cross(axis_z, _RIGHT))+ axis_x = np.cross(axis_y, axis_z)+ if np.linalg.norm(axis_y) == 0:+ axis_x = normalize(np.cross(_UP, axis_z))+ axis_y = -np.cross(axis_x, axis_z)+ return np.array([axis_x, axis_y, axis_z]).T+++def angle_of_vector(vector: Vector3DLike) -> float:+ """The angle of a vector in the xy plane, counterclockwise from the x axis (its z is+ ignored).++ Returns:+ The angle, in radians, from −π to π.+ """+ v = np.asarray(vector)+ return float(np.angle(complex(v[0], v[1])))+++def angle_between_vectors(v1: Vector3DLike, v2: Vector3DLike) -> float:+ """The angle between two vectors.++ Args:+ v1: A vector.+ v2: Another vector.++ Returns:+ The angle, in radians, from 0 to π.+ """+ a, b = normalize(v1), normalize(v2)+ return float(2 * np.arctan2(np.linalg.norm(a - b), np.linalg.norm(a + b)))+++def turn_between(v1: Vector3DLike, v2: Vector3DLike) -> tuple[float, Vector3D]:+ """The smallest turn taking one direction to another, as (angle, axis).++ The axis is perpendicular to both; for directions along one line (a half turn, or+ none), it is the part of OUT across them, so a half turn in the plane of the screen+ stays in it, or RIGHT for directions along OUT.++ Args:+ v1: The direction turned.+ v2: The direction it is turned to.++ Returns:+ The angle, from 0 to π, and the unit axis.+ """+ a, b = np.asarray(v1, dtype=float), np.asarray(v2, dtype=float)+ cross = np.cross(a, b)+ norm = np.linalg.norm(cross)+ if norm > 0:+ return angle_between_vectors(a, b), cross / norm+ across = _OUT - (_OUT @ a) / max(float(a @ a), 1e-300) * a+ size = np.linalg.norm(across)+ return angle_between_vectors(a, b), (+ across / size if size > 1e-9 else _RIGHT.copy()+ )+++def get_unit_normal(v1: Vector3DLike, v2: Vector3DLike, tol: float = 1e-6) -> Vector3D:+ """A unit vector perpendicular to two vectors: their cross product, normalized.++ For vectors along one line (or a zero vector), it is the part of the z axis+ perpendicular to them, normalized; [DOWN][manimgx.DOWN] if they lie along the z axis+ or are both zero.++ Args:+ v1: A vector.+ v2: Another vector.+ tol: How small, relative to the vectors, a cross product counts as zero.++ Returns:+ The unit vector.+ """+ a, b = np.asarray(v1, dtype=float), np.asarray(v2, dtype=float)+ d1, d2 = max(np.abs(a)), max(np.abs(b))+ if d1 == 0.0:+ if d2 == 0.0:+ return _DOWN.copy()+ u = b / d2+ elif d2 == 0.0:+ u = a / d1+ else:+ cp = np.cross(a / d1, b / d2)+ n = np.linalg.norm(cp)+ if n > tol:+ return cp / n+ u = a / d1+ if abs(u[0]) < tol and abs(u[1]) < tol:+ return _DOWN.copy()+ cp = np.array([-u[0] * u[2], -u[1] * u[2], u[0] * u[0] + u[1] * u[1]])+ return cp / np.linalg.norm(cp)+++def compass_directions(n: int = 4, start_vect: Vector3DLike = _RIGHT) -> Point3D_Array:+ """Vectors evenly spread around the z axis, counterclockwise from a first one.++ Args:+ n: How many vectors.+ start_vect: The first vector.++ Returns:+ The vectors, as an (n, 3) array.+ """+ angles = np.arange(n) * (2 * np.pi / n)+ vector = np.asarray(start_vect, dtype=float)+ x, y, z = np.append(vector, 0) if len(vector) == 2 else vector+ c, s = np.cos(angles), np.sin(angles)+ # Matrix reductions start from +0.0; retain those zero signs in shape keys.+ return (+ np.column_stack([x * c - y * s, x * s + y * c, np.full(len(angles), z)]) + 0.0+ )+++def regular_vertices(+ n: int, *, radius: float = 1, start_angle: float | None = None+) -> tuple[Point3D_Array, float]:+ """The vertices of a regular polygon centered at the origin, counterclockwise.++ Args:+ n: How many vertices.+ radius: How far they are from the center, in scene units.+ start_angle: The first vertex's angle, in radians, counterclockwise from the x+ axis; None for 0 when `n` is even and π/2 (a vertex on top) when it is odd.++ Returns:+ The vertices, as an (n, 3) array, and the first vertex's angle.+ """+ if start_angle is None:+ start_angle = 0 if n % 2 == 0 else np.pi / 2+ vertices = compass_directions(n, rotate_vector(_RIGHT * radius, start_angle))+ return vertices, start_angle+++def line_intersection(line1: Point3DLike_Array, line2: Point3DLike_Array) -> Point3D:+ """Where two lines in the xy plane cross, each line through two points (their z is+ ignored).++ Raises an exception if the lines are parallel.++ Args:+ line1: Two points on the first line.+ line2: Two points on the second line.++ Returns:+ The point, with a z of 0.+ """+ padded = [+ np.pad(np.array(line)[:, :2], ((0, 0), (0, 1)), constant_values=1)+ for line in (line1, line2)+ ]+ l1, l2 = (np.cross(*p) for p in padded)+ x, y, z = np.cross(l1, l2)+ if z == 0:+ raise ValueError(+ "The lines are parallel, there is no unique intersection point."+ )+ return np.array([x / z, y / z, 0])+++def find_intersection(+ p0s: Point3DLike_Array,+ v0s: Point3DLike_Array,+ p1s: Point3DLike_Array,+ v1s: Point3DLike_Array,+ threshold: float = 1e-5,+) -> list[Point3D]:+ """For each pair of lines, the point of the first nearest the second: where they+ cross, if they do.++ The first line of each pair is `p0 + t·v0`, the second `p1 + s·v1`.++ Args:+ p0s: A point on each first line.+ v0s: Each first line's direction.+ p1s: A point on each second line.+ v1s: Each second line's direction.+ threshold: The least the division is by, so that parallel lines give `p0`+ rather than divide by zero.++ Returns:+ One point per pair.+ """+ result = []+ arrays = (np.asarray(a, dtype=float) for a in (p0s, v0s, p1s, v1s))+ for p0, v0, p1, v1 in zip(*arrays, strict=True):+ normal = np.cross(v1, np.cross(v0, v1))+ denom = max(np.dot(v0, normal), threshold)+ result.append(p0 + np.dot(p1 - p0, normal) / denom * v0)+ return result+++def midpoint(p1: Point3D, p2: Point3D) -> Point3D:+ """The point halfway between two points.++ Args:+ p1: A point.+ p2: Another point.++ Returns:+ The point between them.+ """+ return (np.asarray(p1) + np.asarray(p2)) / 2+++def cartesian_to_spherical(vec: Vector3DLike) -> Vec:+ """A vector's spherical coordinates.++ Args:+ vec: The vector.++ Returns:+ Its length r, its azimuth θ (the angle of its xy part from the x axis, from −π+ to π) and its polar angle φ (from the z axis, from 0 to π); zeros for the zero+ vector.+ """+ v = np.asarray(vec, dtype=float)+ r = np.linalg.norm(v)+ if r == 0:+ return np.zeros(3)+ # the polar angle by its tangent: arccos(z / r) loses digits near the poles+ return np.array([r, np.arctan2(v[1], v[0]), np.arctan2(np.hypot(v[0], v[1]), v[2])])+++def spherical_to_cartesian(spherical: np.ndarray) -> Vector3D:+ """The vector of spherical coordinates (see+ [cartesian_to_spherical][manimgx.cartesian_to_spherical]).++ Args:+ spherical: The length r, the azimuth θ and the polar angle φ, in radians.++ Returns:+ The vector (r cos θ sin φ, r sin θ sin φ, r cos φ).+ """+ r, theta, phi = spherical+ return np.array(+ [+ r * np.cos(theta) * np.sin(phi),+ r * np.sin(theta) * np.sin(phi),+ r * np.cos(phi),+ ]+ )+++def shoelace(xy: np.ndarray) -> float:+ """The signed area of the polygon through points in turn, back to the first: the+ integral of y dx around it.++ It is positive if the polygon runs clockwise, negative if counterclockwise. A+ polygon given closed, its first point repeated last, has the same area.++ Args:+ xy: The polygon's vertices, x and y first in each row.++ Returns:+ The signed area, in square scene units.+ """+ x, y = xy[:, 0], xy[:, 1]+ return float((np.roll(x, -1) - x) @ (np.roll(y, -1) + y) / 2)+++def shoelace_direction(xy: np.ndarray) -> str:+ """Which way a polygon runs around: "CW" (clockwise) if its+ [shoelace][manimgx.shoelace] area is positive, "CCW" (counterclockwise) otherwise.++ Args:+ xy: The polygon's vertices, x and y first in each row.++ Returns:+ "CW" or "CCW".+ """+ return "CW" if shoelace(xy) > 0 else "CCW"+++def perpendicular_bisector(+ line: Point3DLike_Array, norm_vector: Vector3DLike = _OUT+) -> Point3D_Array:+ """Two points on the perpendicular bisector of a segment, in the plane perpendicular+ to a vector.++ Args:+ line: The segment's two ends.+ norm_vector: The normal of the plane the bisector lies in.++ Returns:+ The segment's midpoint plus and minus its direction crossed with+ `norm_vector`; for a unit normal, each a segment's length from the midpoint.+ """+ p1, p2 = np.asarray(line[0]), np.asarray(line[1])+ direction = np.cross(p1 - p2, np.asarray(norm_vector))+ m = midpoint(p1, p2)+ return np.array([m + direction, m - direction])+++def cross2d(a: np.ndarray, b: np.ndarray) -> npt.NDArray[np.float64] | float:+ """The z of the cross product of vectors in the xy plane: `a.x·b.y − a.y·b.x`.++ Args:+ a: A vector, or an (n, 2) array of them.+ b: Another, or as many.++ Returns:+ The number, or one per row.+ """+ if len(a.shape) == 2:+ return a[:, 0] * b[:, 1] - a[:, 1] * b[:, 0]+ return a[0] * b[1] - b[0] * a[1]+++def center_of_mass(points: Point3D_Array) -> Point3D:+ """The average of points.++ Returns:+ Their mean.+ """+ return np.average(np.asarray(points), 0)+++def angle_axis_from_quaternion(quaternion: np.ndarray) -> tuple[float, Vector3D]:+ """The angle and axis of a unit quaternion (w, x, y, z): the angle 2·arccos(w),+ taken from 2π when it is larger than π, and the axis (x, y, z), normalized.++ Args:+ quaternion: The unit quaternion.++ Returns:+ The angle, in radians, from 0 to π, and the axis.+ """+ axis = normalize(quaternion[1:])+ angle = 2 * np.arccos(quaternion[0])+ if angle > np.pi:+ angle = 2 * np.pi - angle+ return angle, axis+++def sigmoid(x: float) -> float:+ """The logistic function, 1 / (1 + e^(−x)): from 0 to 1, 1/2 at 0.++ Args:+ x: The number.+ """+ return 1.0 / (1 + np.exp(-x))+++def complex_to_R3(complex_num: complex) -> Vec:+ """The point of a complex number: its real part as x, its imaginary part as y.++ Args:+ complex_num: The number.++ Returns:+ The point, with a z of 0.+ """+ return np.array((complex_num.real, complex_num.imag, 0))+++def R3_to_complex(point: Point3D) -> complex:+ """The complex number of a point: x + iy (its z is ignored)."""+ return complex(*point[:2])+++def complex_func_to_R3_func(+ complex_func: Callable[[complex], complex],+) -> Callable[[Point3D], Point3D]:+ """A function of complex numbers as a function of points: a point (x, y, z) goes+ where the function sends x + iy, with a z of 0.++ Args:+ complex_func: The function of complex numbers.++ Returns:+ The function of points.+ """+ return lambda p: complex_to_R3(complex_func(R3_to_complex(p)))+++def norm_squared(v: Vector3DLike) -> float:+ """A vector's length, squared.++ Args:+ v: The vector.++ Returns:+ The sum of the squares of its coordinates.+ """+ v = np.asarray(v)+ return float(np.dot(v, v))+++def rotation_matrix_transpose(angle: float, axis: Vector3DLike) -> MatrixMN:+ """The transpose of [rotation_matrix][manimgx.rotation_matrix]: the rotation by+ `-angle`.++ Args:+ angle: The angle, in radians.+ axis: The axis's direction.++ Returns:+ The 3×3 matrix.+ """+ return rotation_matrix(angle, axis).T+++def rotation_matrix_from_quaternion(quat: np.ndarray) -> MatrixMN:+ """The matrix of the rotation by a unit quaternion.++ Args:+ quat: The unit quaternion (w, x, y, z).++ Returns:+ The 3×3 rotation matrix.+ """+ w, x, y, z = quat+ return np.array(+ [+ [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],+ [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],+ [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],+ ]+ )+++def get_winding_number(points: Point3DLike_Array) -> float:+ """How many times the closed polygon through points winds counterclockwise around+ the origin, in the xy plane.++ Args:+ points: The polygon's vertices, in order; it closes from the last back to the+ first.++ Returns:+ The number of turns, negative for clockwise, and whole unless a side passes+ through the origin.+ """+ total = 0.0+ pts = np.asarray(points, dtype=float)+ for p1, p2 in zip(pts, np.roll(pts, -1, axis=0), strict=True):+ d_angle = angle_of_vector(p2) - angle_of_vector(p1)+ d_angle = ((d_angle + np.pi) % (2 * np.pi)) - np.pi+ total += d_angle+ return total / (2 * np.pi)+++def quaternion_mult(*quats: Sequence[float] | npt.NDArray[np.float64]) -> list[float]:+ """The product of quaternions (w, x, y, z), in order: the first times the second,+ and so on.++ Args:+ *quats: The quaternions.++ Returns:+ The product as a list of four floats; (1, 0, 0, 0) for none.+ """+ result = [float(x) for x in quats[0]] if quats else [1.0, 0.0, 0.0, 0.0]+ for quat in quats[1:]:+ (w1, x1, y1, z1), (w2, x2, y2, z2) = result, (float(x) for x in quat)+ result = [+ w1 * w2 - x1 * x2 - y1 * y2 - z1 * z2,+ w1 * x2 + x1 * w2 + y1 * z2 - z1 * y2,+ w1 * y2 + y1 * w2 + z1 * x2 - x1 * z2,+ w1 * z2 + z1 * w2 + x1 * y2 - y1 * x2,+ ]+ return result+++def quaternion_from_angle_axis(+ angle: float, axis: np.ndarray, axis_normalized: bool = False+) -> list[float]:+ """The unit quaternion (w, x, y, z) of a rotation about an axis.++ Args:+ angle: The angle, in radians.+ axis: The axis's direction.+ axis_normalized: Whether `axis` has length 1 already.++ Returns:+ The quaternion, cos(angle/2) followed by the axis times sin(angle/2).+ """+ return [+ np.cos(angle / 2),+ *np.sin(angle / 2) * (axis if axis_normalized else normalize(axis)),+ ]+++def quaternion_conjugate(+ quaternion: Sequence[float] | npt.NDArray[np.float64],+) -> Vec:+ """A quaternion's conjugate: (w, −x, −y, −z), the inverse rotation of a unit one.++ Args:+ quaternion: The quaternion (w, x, y, z).+ """+ result = np.array(quaternion, dtype=float)+ result[1:] *= -1+ return result+++def rotation_matrix_transpose_from_quaternion(quat: np.ndarray) -> list[Vec]:+ """The transpose of the matrix of the rotation by a unit quaternion: its rows are+ where the x, y and z axes go.++ Args:+ quat: The unit quaternion (w, x, y, z).++ Returns:+ The three rows.+ """+ inverse = quaternion_conjugate(quat)+ return [+ np.array(quaternion_mult(quat, [0, *basis], inverse)[1:])+ for basis in np.identity(3)+ ]+++def thick_diagonal(dim: int, thickness: int = 2) -> npt.NDArray[np.uint8]:+ """A square matrix of ones in a band along its diagonal, and zeros elsewhere.++ Args:+ dim: How many rows and columns.+ thickness: The band's width: ones where the row and column differ by less.++ Returns:+ The matrix, of 8-bit integers.+ """+ rows = np.arange(dim).repeat(dim).reshape((dim, dim))+ return (np.abs(rows - rows.T) < thickness).astype("uint8")+++def normalize_along_axis(array: np.ndarray, axis: int) -> npt.NDArray[np.float64]:+ """Divide the vectors along an array's last axis by their lengths, in place (zero+ vectors are left as they are).++ Args:+ array: The array, of floats.+ axis: Its last axis (along another, the lengths are not matched to their+ vectors).++ Returns:+ The same array.+ """+ norms = np.sqrt((array * array).sum(axis))+ norms[norms == 0] = 1+ array /= np.repeat(norms, array.shape[axis]).reshape(array.shape)+ return array+++def earclip_triangulation(+ verts: Point3DLike_Array, ring_ends: Sequence[int]+) -> list[int]:+ """Triangles covering a polygon with holes, by ear clipping.++ Each hole is joined to the outline at their closest vertices, and ears are then+ clipped from the one ring, in order.++ Args:+ verts: The rings' vertices, one ring after another: the outline, then the holes+ (x and y count).+ ring_ends: Where each ring ends in `verts`: the index after its last vertex.++ Returns:+ The triangles, as indices into `verts`, three per triangle.+ """+ points = np.asarray(verts, dtype=float)[:, :2]+ rings = [+ list(range(a, b)) for a, b in zip([0, *ring_ends[:-1]], ring_ends, strict=True)+ ]++ def area(ring: list[int]) -> float: # signed: positive counterclockwise+ x, y = points[ring].T+ return float(np.sum(x * np.roll(y, -1) - np.roll(x, -1) * y) / 2)++ def cross(o: int, a: int, b: int) -> float:+ (ax, ay), (bx, by) = points[a] - points[o], points[b] - points[o]+ return float(ax * by - ay * bx)++ outline = rings[0]+ for hole in rings[1:]:+ if np.sign(area(hole)) == np.sign(area(outline)):+ hole = hole[+ ::-1+ ] # a hole winds against its outline, or the bridged ring crosses itself+ gaps = np.linalg.norm(points[outline][:, None] - points[hole][None], axis=2)+ i, j = np.unravel_index(int(np.argmin(gaps)), gaps.shape)+ outline = outline[: i + 1] + hole[j:] + hole[: j + 1] + outline[i:]+ turn = np.sign(area(outline)) or 1.0+ ring, triangles = list(outline), []+ while len(ring) > 3:+ for k in range(len(ring)):+ a, b, c = ring[k - 1], ring[k], ring[(k + 1) % len(ring)]+ if cross(a, b, c) * turn > 0 and not any(+ cross(a, b, q) * turn >= 0+ and cross(b, c, q) * turn >= 0+ and cross(c, a, q) * turn >= 0+ for q in ring+ if not any(np.allclose(points[q], points[v]) for v in (a, b, c))+ ):+ break+ else:+ k = 1 # no proper ear (degenerate input): clip anyway rather than loop forever+ a, b, c = ring[0], ring[1], ring[2]+ triangles += [a, b, c]+ del ring[k]+ return triangles + ring+++class Polygon:+ """A polygon with holes, as [polylabel][manimgx.polylabel] reads it: its edges, its+ area and its centroid.++ Args:+ rings: Its rings, each closed (its first vertex repeated at its end): the+ outline, then any holes.+ """++ def __init__(self, rings: Sequence[Point2DLike_Array]) -> None:+ np_rings: list[Point2D_Array] = [np.asarray(ring) for ring in rings]+ csum = np.cumsum([ring.shape[0] for ring in np_rings])+ self.array: Point2D_Array = np.concatenate(np_rings, axis=0)+ 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)+ 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:+ """How far a point is from the polygon's edges: positive inside, negative+ outside.++ Args:+ point: The point, x and y.++ Returns:+ The distance, in scene units.+ """+ 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:+ """Whether a point is inside the polygon or on its edges: a ray from it toward+ +x crosses the edges an odd number of times.++ Args:+ point: The point, x and y.+ """+ x, y = point+ x0, y0 = self.start[:, 0], self.start[:, 1]+ x1, y1 = self.stop[:, 0], self.stop[:, 1]+ on = (+ (np.minimum(x0, x1) <= x)+ & (x <= np.maximum(x0, x1))+ & (np.minimum(y0, y1) <= y)+ & (y <= np.maximum(y0, y1))+ & (np.abs((x1 - x0) * (y - y0) - (y1 - y0) * (x - x0)) <= 1e-8)+ )+ if on.any():+ return True+ with np.errstate(divide="ignore", invalid="ignore"):+ crossed = ((y0 > y) != (y1 > y)) & (+ x < (x1 - x0) / (y1 - y0) * (y - y0) + x0+ )+ return bool(np.count_nonzero(crossed) % 2)+++class Cell:+ """A square cell of the search [polylabel][manimgx.polylabel] makes: its center `c`,+ its half-size `h`, its center's distance `d` from the polygon's edges, and `p`, the+ most any point of the cell can be from them.+ Cells are ordered for the search by decreasing `p`.++ Args:+ c: Its center, x and y.+ h: Half its side, in scene units.+ """++ 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.p > other.p+++def polylabel(rings: Sequence[Point3DLike_Array], precision: float = 0.01) -> Cell:+ """The pole of inaccessibility of a polygon: the point inside it farthest from its+ edges, where a label fits best.++ Args:+ rings: The polygon's rings, each closed (its first vertex repeated at its end):+ the outline, then any holes. Their x and y count.+ precision: How far, at most, the point found may be from the best, in its+ distance from the edges, in scene units.++ Returns:+ The cell found, whose `c` is the point (x and y) and `d` its distance from the+ nearest edge.+ """+ np_rings: list[Point2D_Array] = [np.asarray(ring)[:, :2] for ring in rings]+ polygon = Polygon(np_rings)+ 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+ queue: list[Cell] = []+ 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:+ heapq.heappush(queue, Cell(corner + h, h, polygon))+ best = Cell(polygon.centroid, 0, polygon)+ bbox = Cell(mins + dims / 2, 0, polygon)+ if bbox.d > best.d:+ best = bbox+ # No inscribed circle is wider than the bounding box.+ if best.d >= h:+ return best+ directions = np.array([[-1, -1], [1, -1], [-1, 1], [1, 1]])+ while queue:+ cell = heapq.heappop(queue)+ if cell.d > best.d:+ best = cell+ if cell.p - best.d > precision:+ h = cell.h / 2.0+ offsets = cell.c + directions * h+ for offset in offsets:+ heapq.heappush(queue, Cell(offset, h, polygon))+ return best+++class SubFacet:+ """A face of a facet (an end of an edge, an edge of a triangle), equal to another of+ the same points. Its topology identity captures those coordinates at construction.+ """++ def __init__(self, coordinates: PointND_Array) -> None:+ self.coordinates = coordinates+ # Numeric tuples keep topology hashes independent of Python's byte-hash seed.+ self.points = frozenset(tuple(c.tolist()) 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:+ """A facet of a hull (an edge in two dimensions, a triangle in three): its points,+ its center, its outward normal and its subfacets.++ Args:+ coordinates: Its points, one per row.+ internal: A point inside the hull, which its normal points away from.+ """++ 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:+ """The facet's unit normal, pointing away from a point inside the hull.++ Args:+ internal: The point inside.+ """+ 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)+++class Horizon:+ """What a point outside a hull sees of it: the facets it sees, and the subfacets+ between those and the facets it doesn't."""++ def __init__(self) -> None:+ self.facets: set[Facet] = set()+ self.boundary: list[SubFacet] = []+++class QuickHull:+ """The convex hull of points, in two dimensions or more, by the Quickhull algorithm.++ [build][manimgx.QuickHull.build] computes it: the hull's facets (its edges in two+ dimensions, its triangles in three) are then those of `facets` not in `removed`.++ Args:+ tolerance: How far beyond a facet a point must be to count as outside it.+ """++ 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:+ """Start the hull as a simplex of extreme points, and share the points outside+ it among its facets; [build][manimgx.QuickHull.build] calls it first.++ Args:+ points: The points, one per row.+ """+ # The initial simplex from extreme points, each the farthest from the span of those before+ # (CE sampled it with an unseeded generator: the same input gave a different hull layout+ # on every run)+ chosen = [int(np.argmin(points[:, 0]))]+ while len(chosen) < points.shape[1] + 1:+ offsets = points - points[chosen[0]]+ if len(chosen) > 1:+ basis, _ = np.linalg.qr((points[chosen[1:]] - points[chosen[0]]).T)+ offsets = offsets - offsets @ basis @ basis.T+ chosen.append(int(np.argmax(np.linalg.norm(offsets, axis=1))))+ simplex = points[chosen]+ 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:+ """Give a new facet the points no facet has yet that lie beyond it, and among+ them the farthest, the next point to add; [build][manimgx.QuickHull.build] calls+ it for each facet it makes.+ """+ 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:+ """What a point outside the hull sees of it, from a facet it sees: the hull+ grows to the point from the edge of what it sees.++ Args:+ eye: The point.+ start_facet: A facet it sees.++ Returns:+ The facets it sees and the subfacets bounding them.+ """+ 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:+ """Compute the convex hull of points.++ Raises an exception for points in one dimension, or fewer than one more than+ their dimensions.++ Args:+ points: The points, one per row, each of two coordinates or more.+ """+ 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+++def interpolate[T](start: T, end: T, alpha: float | np.ndarray) -> T:+ """The value a fraction of the way from one value to another: (1 − alpha)·start ++ alpha·end.++ Args:+ start: The value at 0: a number or an array.+ end: The value at 1, of the same kind.+ alpha: How far from `start` to `end`: 0 gives `start`, 1 `end`, and beyond them+ it goes on along the line; an array gives one value per entry.++ Returns:+ The value between.+ """+ return (+ 1 - alpha+ ) * start + alpha * end # pyright: ignore[reportOperatorIssue] # ty: ignore[unsupported-operator] # T: numbers, arrays+++def integer_interpolate(start: float, end: float, alpha: float) -> tuple[int, float]:+ """Which whole step from `start` toward `end` a fraction falls in, and how far into+ it: for `start` 0 and `end` n, which of n curves, and where along it.++ Args:+ start: The first step's start, a whole number.+ end: The last step's end, a whole number past `start`.+ alpha: How far from `start` to `end`, from 0 to 1.++ Returns:+ The step, from `start` to `end` − 1, and the fraction of it, from 0 to 1: step ++ fraction is `start` + (`end` − `start`)·`alpha`; at 1, the last step, wholly.+ """+ if alpha >= 1:+ return int(end - 1), 1.0+ if alpha <= 0:+ return int(start), 0.0+ reached = (end - start) * alpha+ # whole steps down (floor, not toward 0), and never past the last, however it rounds+ whole = min(math.floor(reached), int(end - start) - 1)+ return int(start) + whole, reached - whole+++def inverse_interpolate(start: float, end: float, value: float) -> float:+ """How far a value is from one value to another: the inverse of+ [interpolate][manimgx.interpolate].++ Args:+ start: The value at 0.+ end: The value at 1.++ Returns:+ The fraction, (value − start) / (end − start).+ """+ return float(np.true_divide(value - start, end - start))+++_NPPCC = 4+++def sample(function: Callable[..., object], *args: np.ndarray) -> np.ndarray:+ """Evaluate a function at every point of a grid of arguments.++ `args` are arrays of one shape, one per argument of `function`. The function is+ called once on the whole arrays, as most numeric functions allow, and checked+ against single calls at the first, middle and last points; a function written for+ one value at a time (`math.cos`, `if t < 0`) raises or differs there, and is then+ called once per point.++ Args:+ function: The function, from the arguments to a value.+ *args: The arguments' values: arrays of one shape.++ Returns:+ The values: an array of the arguments' shape, followed by a value's.+ """+ shape, n = args[0].shape, args[0].size+ flat = [a.ravel() for a in args]+ try:+ out = np.asarray(function(*args), dtype=float)+ k = len(shape)+ if out.shape[:k] != shape and out.shape[-k:] == shape: # values first+ out = np.moveaxis(out, range(out.ndim - k, out.ndim), range(k))+ values = out.reshape(n, -1)+ for i in {0, n // 2, n - 1}:+ one = np.asarray(function(*(float(f[i]) for f in flat)), dtype=float)+ if not np.allclose(values[i], one.ravel(), rtol=1e-9, atol=1e-12):+ raise ValueError(i)+ return out+ except Exception: # not vectorizable: one point at a time+ out = np.array(+ [function(*(float(f[i]) for f in flat)) for i in range(n)], float+ )+ return out.reshape(*shape, *out.shape[1:])+++def subpath_ranges(+ points: Point3D_Array, atol: float, dims: int = 3+) -> list[tuple[int, int, bool]]:+ """(start, end, closed) per subpath: one starts where a curve does not begin at the previous+ curve's end (CE's rule); it is closed when its ends coincide."""+ n = len(points) - len(points) % _NPPCC+ if n < _NPPCC:+ return []+ ends, starts = (+ points[_NPPCC - 1 : n - 1 : _NPPCC, :dims],+ points[_NPPCC:n:_NPPCC, :dims],+ )+ breaks = ~np.all(np.abs(ends - starts) <= atol + 1e-5 * np.abs(starts), axis=1)+ splits = [0, *((np.flatnonzero(breaks) + 1) * _NPPCC).tolist(), n]+ return [+ (a, b, bool(np.allclose(points[a, :dims], points[b - 1, :dims], atol=atol)))+ for a, b in itertools.pairwise(splits)+ if b - a >= _NPPCC+ ]+++def _pathops() -> ModuleType:+ """skia-pathops, which finds the regions (imported when first needed: it has no build for+ Pyodide, so in the browser these shapes can't be made)."""+ try:+ import pathops+ except ImportError as error:+ raise ImportError(+ "Union, Difference, Intersection and Exclusion need skia-pathops, which has"+ " no build for the browser (Pyodide) yet"+ ) from error+ return pathops+++def _to_path(points: Point3D_Array, tolerance: float) -> SkiaPath:+ """An outline's planar path, with the same complete subpaths and closure tolerance."""+ path = _pathops().Path()+ if not np.all(np.isfinite(points)):+ return path+ for start, end, closed in subpath_ranges(points, tolerance, dims=2):+ path.moveTo(*points[start, :2])+ for _p0, p1, p2, p3 in points[start:end].reshape(-1, 4, 3):+ path.cubicTo(*p1[:2], *p2[:2], *p3[:2])+ if closed:+ path.close()+ return path+++def bezier(points: Point3D_Array) -> Callable[[float], Point3D]:+ """A cubic Bézier curve as a function: from its first control point at 0 to its last+ at 1.++ Args:+ points: Its four control points: anchor, handle, handle, anchor.++ Returns:+ A function of the curve's parameter, from 0 to 1, giving its point there.+ """+ P = np.asarray(points)++ def cubic(t: float) -> Point3D:+ mt = 1 - t+ return mt**3 * P[0] + 3 * t * mt**2 * P[1] + 3 * t**2 * mt * P[2] + t**3 * P[3]++ return cubic+++def partial_bezier_points(points: Point3D_Array, a: float, b: float) -> Point3D_Array:+ """The control points of part of a cubic Bézier curve, from its parameter `a` to+ `b`.++ Args:+ points: The curve's four control points.+ a: Where the part starts, from 0 to 1.+ b: Where it ends, from `a` to 1.++ Returns:+ The part's four control points.+ """+ if a == 1:+ arr = np.array(points)+ arr[:] = arr[-1]+ return arr+ if b == 0:+ arr = np.array(points)+ arr[:] = arr[0]+ return arr+ ma, mb = 1 - a, 1 - b+ a2, b2, ma2, mb2 = a * a, b * b, ma * ma, mb * mb+ a3, b3, ma3, mb3 = a2 * a, b2 * b, ma2 * ma, mb2 * mb+ m = np.array(+ [+ [ma3, 3 * ma2 * a, 3 * ma * a2, a3],+ [ma2 * mb, 2 * ma * a * mb + ma2 * b, a2 * mb + 2 * ma * a * b, a2 * b],+ [ma * mb2, a * mb2 + 2 * ma * mb * b, 2 * a * mb * b + ma * b2, a * b2],+ [mb3, 3 * mb2 * b, 3 * mb * b2, b3],+ ]+ )+ return m @ np.asarray(points)+++_SUBDIVISION: Memo[int, np.ndarray] = Memo(1 << 10)+++def _subdivision_matrix(n: int | np.integer) -> np.ndarray:+ m = _SUBDIVISION.get(n)+ if m is not None:+ return m+ n = int(n)+ m = np.empty((4 * n, 4))+ for i in range(n):+ i2, i3 = i * i, i * i * i+ ip1 = i + 1+ ip12, ip13 = ip1 * ip1, ip1 * ip1 * ip1+ nmi = n - i+ nmi2, nmi3 = nmi * nmi, nmi * nmi * nmi+ nmim1 = nmi - 1+ nmim12, nmim13 = nmim1 * nmim1, nmim1 * nmim1 * nmim1+ m[4 * i : 4 * (i + 1)] = [+ [nmi3, 3 * nmi2 * i, 3 * nmi * i2, i3],+ [+ nmi2 * nmim1,+ 2 * nmi * nmim1 * i + nmi2 * ip1,+ nmim1 * i2 + 2 * nmi * i * ip1,+ i2 * ip1,+ ],+ [+ nmi * nmim12,+ nmim12 * i + 2 * nmi * nmim1 * ip1,+ 2 * nmim1 * i * ip1 + nmi * ip12,+ i * ip12,+ ],+ [nmim13, 3 * nmim12 * ip1, 3 * nmim1 * ip12, ip13],+ ]+ m /= n**3+ return _SUBDIVISION.keep(n, m)+++def subdivide_bezier(points: Point3D_Array, n_divisions: int) -> Point3D_Array:+ """Split a cubic Bézier curve into curves over equal stretches of its parameter.++ Args:+ points: The curve's four control points.+ n_divisions: How many curves.++ Returns:+ Their control points, four per curve, one curve after another.+ """+ points = np.asarray(points)+ if n_divisions == 1:+ return points+ return _subdivision_matrix(n_divisions) @ points+++def bezier_remap(tuples: np.ndarray, new_count: int) -> np.ndarray:+ """Split cubic Bézier curves into more, their shape unchanged.++ Each curve is split over equal stretches of its parameter, the new curves spread+ among the curves as evenly as can be: curve i of m gets the new curves j of+ `new_count` with j·m // `new_count` = i (4 curves into 6: 2, 1, 2, 1).++ Args:+ tuples: The curves' control points: an array of shape (curves, 4, dimensions).+ new_count: How many curves to make, at least as many as there are.++ Returns:+ The new curves' control points, an array of shape (new_count, 4, dimensions).+ """+ tuples = np.asarray(tuples)+ count, nppc, dim = tuples.shape+ if new_count == count:+ return np.array(tuples, dtype=float, order="C")+ if count and new_count % count == 0:+ pieces = _subdivision_matrix(new_count // count) @ tuples+ return np.asarray(pieces, dtype=float).reshape(new_count, nppc, dim)+ starts = (np.arange(count + 1) * new_count + count - 1) // count+ out = np.empty((new_count, nppc, dim))+ for curve, start, end in zip(tuples, starts[:-1], starts[1:], strict=True):+ factor = end - start+ out[start:end] = subdivide_bezier(curve, factor).reshape(factor, nppc, dim)+ return out+++def is_closed(points: Point3D_Array) -> bool:+ """Whether points end where they start: the last equal to the first, within 1e-8+ plus 1e-5 of the first's coordinates.+ """+ # np.isclose's tolerances, independent of the sign+ start, end = points[0], points[-1]+ return bool(np.all(np.abs(end - start) <= 1e-08 + 1e-05 * np.abs(start)))+++def get_smooth_cubic_bezier_handle_points(+ anchors: Point3D_Array,+) -> tuple[Point3D_Array, Point3D_Array]:+ """The handles of a smooth curve through anchors: a cubic spline, bending with no+ change of curvature at any anchor, and closed smoothly if the last anchor is the+ first.++ Args:+ anchors: The anchors, in order.++ Returns:+ Each curve's first handles and second handles, as two arrays with one row per+ curve (one fewer than the anchors).+ """+ A = np.asarray(anchors, dtype=float)+ n = A.shape[0]+ if n == 1:+ return np.zeros((0, A.shape[1])), np.zeros((0, A.shape[1]))+ if n == 2:+ return (+ interpolate(A[0], A[1], 1 / 3)[None],+ interpolate(A[0], A[1], 2 / 3)[None],+ )+ closed = is_closed(A)+ if n > _SMOOTHING_UP_TO:+ return _smooth_closed(A) if closed else _smooth_open(A)+ to_h1, to_h2 = _smoothing(n, closed)+ return to_h1 @ A, to_h2 @ A+++# anchors; beyond, the solve itself (linear time) beats a dense map+_SMOOTHING_UP_TO = 256+++@forgets[email protected]_cache(maxsize=64)+def _smoothing(n: int, closed: bool) -> tuple[np.ndarray, np.ndarray]:+ """(K1, K2): smooth handles are K1·A and K2·A, maps that depend only on the number of anchors+ (the solve, run once on the identity)."""+ k1, k2 = (_smooth_closed if closed else _smooth_open)(np.eye(n))+ k1.flags.writeable = k2.flags.writeable = False+ return k1, k2+++def _smooth_closed(A: np.ndarray) -> tuple[np.ndarray, np.ndarray]:+ N, dim = A.shape[0] - 1, A.shape[1]+ cp, up = np.empty(N - 1), np.empty(N - 1)+ cp[0], up[0] = 1 / 3, 1 / 3+ for i in range(1, N - 1):+ cp[i] = 1 / (4 - cp[i - 1])+ up[i] = -cp[i] * up[i - 1]+ cp_last = 1 / (3 - cp[N - 2])+ up_last = cp_last * (1 - up[N - 2])+ q = np.empty((N, dim))+ q[N - 1] = up_last+ for i in range(N - 2, -1, -1):+ q[i] = up[i] - cp[i] * q[i + 1]+ Dp = np.empty((N, dim))+ AUX = 4 * A[:N] + 2 * A[1:]+ Dp[0] = AUX[0] / 3+ for i in range(1, N - 1):+ Dp[i] = cp[i] * (AUX[i] - Dp[i - 1])+ Dp[N - 1] = cp_last * (AUX[N - 1] - Dp[N - 2])+ Y = Dp+ for i in range(N - 2, -1, -1):+ Y[i] = Dp[i] - cp[i] * Y[i + 1]+ H1 = Y - 1 / (1 + q[0] + q[N - 1]) * q * (Y[0] + Y[N - 1])+ H2 = np.empty((N, dim))+ H2[: N - 1] = 2 * A[1:N] - H1[1:N]+ H2[N - 1] = 2 * A[N] - H1[0]+ return H1, H2+++def _smooth_open(A: np.ndarray) -> tuple[np.ndarray, np.ndarray]:+ N, dim = A.shape[0] - 1, A.shape[1]+ cp = np.empty(N - 1)+ cp[0] = 0.5+ for i in range(1, N - 1):+ cp[i] = 1 / (4 - cp[i - 1])+ Dp = np.empty((N, dim))+ Dp[0] = 0.5 * A[0] + A[1]+ AUX = 4 * A[1 : N - 1] + 2 * A[2:N]+ for i in range(1, N - 1):+ Dp[i] = cp[i] * (AUX[i - 1] - Dp[i - 1])+ Dp[N - 1] = 1 / (7 - 2 * cp[N - 2]) * (8 * A[N - 1] + A[N] - 2 * Dp[N - 2])+ H1 = Dp+ for i in range(N - 2, -1, -1):+ H1[i] = Dp[i] - cp[i] * H1[i + 1]+ H2 = np.empty((N, dim))+ H2[: N - 1] = 2 * A[1:N] - H1[1:N]+ H2[N - 1] = 0.5 * (A[N] + H1[N - 1])+ return H1, H2+++type Floats = npt.NDArray[np.float64]+"""A NumPy array of floats."""+type Coefficients = tuple[Floats, Floats, Floats] # Lₛ, Lₑ, k+"""A path's rule at one moment: the 3×3 matrices Lₛ and Lₑ and the vector k that take+each point to Lₛ·start + Lₑ·end + k."""+type Step = tuple[float, Floats, Floats] | Floats | Callable[[float], Floats]+"""A step of a motion: a turn (an angle, an axis and a pivot, a point of the object as+it began), a move by a vector, or a move along a curve (a function of α giving where the+object has been carried at α)."""++STRAIGHT_PATH_THRESHOLD: Final = 0.01+"""The smallest angle, in radians, [path_along_arc][manimgx.path_along_arc] and+[spiral_path][manimgx.spiral_path] turn through: with less, they are the+[straight path][manimgx.straight_path]."""+_PATH_AXIS: Final = np.array([0.0, 0.0, 1.0])+_EYE: Final = np.eye(3)+_ZERO: Final = np.zeros(3)+++def _cross(axis: Floats) -> Floats:+ """K with K·v = axis × v."""+ x, y, z = axis+ return np.array([[0.0, -z, y], [z, 0.0, -x], [-y, x, 0.0]])+++@dataclass(frozen=True, slots=True, eq=False)+class Path:+ """How the points of a shape travel in a transform, from where they start to where+ they end, as a value.++ A path takes each point to Lₛ·start + Lₑ·end + k, where Lₛ, Lₑ and k depend on the+ animation's progress α alone: so a shape moves without its points being touched.+ Call it as `path(start, end, alpha)`, on arrays of points; the functions below make+ the paths manimgx provides.++ Args:+ kind: What the path is. "motion": the shape is carried by the motion G of its+ `steps` while it changes along straight lines in the moving frame,+ G(α)·((1 − α)·start + α·G(1)⁻¹·end); with no steps, the straight path.+ "arc": each point travels along a circular arc from its start to its end,+ turning through `angle` (and at a steady rate along `axis`, if its ends+ differ along it). "spiral": each point spirals out from its start to+ its end, start + α·R((α − 1)·`angle`)·(end − start).+ angle: The angle an "arc" or "spiral" path turns through, in radians,+ counterclockwise about `axis`.+ axis: The axis the path turns about.+ steps: The steps of a "motion" path, taken in order (see+ [carried][manimgx.carried]).+ """++ kind: Literal["motion", "arc", "spiral"] = "motion"+ angle: float = 0.0+ axis: Floats = field(default_factory=lambda: _PATH_AXIS.copy())+ steps: tuple[Step, ...] = ()+ _end: list[Floats] = field(default_factory=list, init=False, repr=False) # G(1)++ def coefficients(self, alpha: float) -> Coefficients:+ """The path's rule at a moment: each point goes to Lₛ·start + Lₑ·end + k.++ Args:+ alpha: The animation's progress, from 0 to 1.++ Returns:+ The 3×3 matrices Lₛ and Lₑ, and the vector k.+ """+ if self.kind == "motion":+ if not self.steps:+ return (1 - alpha) * _EYE, alpha * _EYE, _ZERO+ if not self._end:+ self._end.append(self.motion(1.0))+ g, end = self.motion(alpha), self._end[0]+ le = alpha * g[:3, :3] @ end[:3, :3].T+ return (+ (1 - alpha) * g[:3, :3],+ le,+ g[:3, 3] - le @ end[:3, 3],+ )+ if self.kind == "spiral":+ rot = rotation_matrix((alpha - 1) * self.angle, self.axis)+ return _EYE - alpha * rot, alpha * rot, _ZERO+ # across the axis, an arc about the center; along it, a steady move (the turn and+ # (I − R) leave a point's height along the axis alone, so it is moved apart)+ rot = rotation_matrix(alpha * self.angle, self.axis)+ along = alpha * np.outer(self.axis, self.axis)+ if self.angle == np.pi:+ cs = ce = 0.5 * _EYE+ else:+ k = _cross(self.axis) / (2 * np.tan(self.angle / 2))+ cs, ce = 0.5 * _EYE - k, 0.5 * _EYE + k+ return (_EYE - rot) @ cs + rot - along, (_EYE - rot) @ ce + along, _ZERO++ def motion(self, alpha: float) -> Floats:+ """The motion the path's steps have carried the shape by at a moment.++ Args:+ alpha: The animation's progress, from 0 to 1.++ Returns:+ The 4×4 affine matrix G(α).+ """+ return carried((step, alpha) for step in self.steps)++ def __call__(+ self, start: Point3D_Array, end: Point3D_Array, alpha: float+ ) -> Point3D_Array:+ ls, le, k = self.coefficients(alpha)+ return start @ ls.T + end @ le.T + k+++def carried(steps: Iterable[tuple[Step, float]]) -> Floats:+ """The motion of steps taken in order, each as far as its own fraction.++ A move goes that fraction of its vector, and a move along a curve to where the curve+ has carried the object at that fraction; a turn turns through that fraction of its+ angle, about its pivot where the steps before it have carried the pivot.++ Args:+ steps: The steps (see [Step][manimgx.Step]), each with its fraction, from 0 to+ 1.++ Returns:+ The 4×4 affine matrix of the motion.+ """+ g = np.eye(4)+ for step, alpha in steps:+ if isinstance(step, np.ndarray):+ g[:3, 3] += alpha * step+ elif isinstance(step, tuple):+ angle, axis, pivot = step+ turn = rotation_matrix(alpha * angle, axis)+ p = g[:3, :3] @ pivot + g[:3, 3]+ g[:3] = turn @ g[:3]+ g[:3, 3] += p - turn @ p+ else:+ g[:3, 3] += step(alpha) - step(0.0)+ return g+++def _unit(axis: Vector3DLike) -> Floats:+ unit = normalize(axis)+ if not unit.any():+ raise ValueError(f"a path's axis must not be zero, not {axis}")+ return unit+++def straight_path() -> Path:+ """The straight path: each point goes along the line from its start to its end, as+ a transform moves points by default.+ """+ return Path()+++def path_along_arc(arc_angle: float, axis: Vector3DLike = _PATH_AXIS) -> Path:+ """A path along arcs: each point travels along a circular arc from its start to its+ end, turning through an angle, as a transform's `path_arc` makes it move.++ Args:+ arc_angle: The angle each arc turns through, in radians, counterclockwise about+ `axis`; smaller in size than+ [STRAIGHT_PATH_THRESHOLD][manimgx.STRAIGHT_PATH_THRESHOLD], the straight+ path.+ axis: The axis the arcs turn about.+ """+ if abs(arc_angle) < STRAIGHT_PATH_THRESHOLD:+ return straight_path()+ return Path("arc", arc_angle, _unit(axis))+++def path_along_circles(+ arc_angle: float,+ centers: Point3DLike | Point3DLike_Array,+ axis: Vector3DLike = _PATH_AXIS,+) -> PathFunc:+ """A path about centers: each point turns about its center through an angle while+ it moves from its start to its end, as a transform's `path_arc_centers` makes it+ move.++ With one center, the shape turns about it as a whole, as a [Path][manimgx.Path];+ with a center per point, each point turns about its own, as a plain function of+ `(start, end, alpha)`.++ Args:+ arc_angle: The angle, in radians, counterclockwise about `axis`.+ centers: One center, or one per point, in scene coordinates.+ axis: The axis the points turn about.+ """+ unit_axis = _unit(axis)+ points: Floats = np.asarray(centers, dtype=np.float64)+ if points.ndim == 1:+ return Path(steps=((arc_angle, unit_axis, points),))++ def path(start: Point3D_Array, end: Point3D_Array, alpha: float) -> Point3D_Array:+ detransformed = (+ points + (end - points) @ rotation_matrix(-arc_angle, unit_axis).T+ )+ rot = rotation_matrix(alpha * arc_angle, unit_axis)+ return points + ((1 - alpha) * start + alpha * detransformed - points) @ rot.T++ return path+++def clockwise_path() -> Path:+ """A path along half circles, clockwise: each point turns through π on its way from+ its start to its end.+ """+ return path_along_arc(-np.pi)+++def counterclockwise_path() -> Path:+ """A path along half circles, counterclockwise: each point turns through π on its+ way from its start to its end.+ """+ return path_along_arc(np.pi)+++def spiral_path(angle: float, axis: Vector3DLike = _PATH_AXIS) -> Path:+ """A spiral path: each point spirals out from its start to its end, its offset from+ its start growing as it turns counterclockwise through `angle` (for a positive+ angle) into line with its end.++ Args:+ angle: How far each point turns, in radians, about `axis`; smaller in size than+ [STRAIGHT_PATH_THRESHOLD][manimgx.STRAIGHT_PATH_THRESHOLD], the straight+ path.+ axis: The axis the points turn about.+ """+ if abs(angle) < STRAIGHT_PATH_THRESHOLD:+ return straight_path()+ return Path("spiral", angle, _unit(axis))+++type Matrix = Floats # 3×4: [linear 3×3 | translation]+type Term = tuple[Matrix, "Shape"]++IDENTITY: Final = np.hstack([np.eye(3), np.zeros((3, 1))])+IDENTITY.flags.writeable = False # a shape's placement, shared+CANONICAL: Final = 1024 # the most points of a shape reduced to a canonical form+_T: Final = np.linspace(0.0, 1.0, 10)[:, None]+_BERNSTEIN: Final = np.hstack(+ [(1 - _T) ** 3, 3 * (1 - _T) ** 2 * _T, 3 * (1 - _T) * _T**2, _T**3]+)+++class Shape:+ """Immutable control points (n × 3). Content-addressed, so equal shapes share GPU memory."""++ __slots__ = ("_affine", "_boxes", "_key", "array", "log")++ def __init__(self, array: Floats, log: Log | None = None) -> None:+ array.flags.writeable = False+ self.array: Floats = array+ # the append-only points this shape is a prefix of (a growing path)+ self.log = log+ self._key: int | None = None+ self._affine: tuple[int, Floats, Matrix] | None = None+ self._boxes: dict[bool, Floats] | None = None++ def box(self, curves: bool) -> Floats:+ """(2, 3): the box of what the points make — for a path (`curves`), its curves' tight box+ (`curve_box`). Kept, as the shape never changes."""+ boxes = self._boxes+ if boxes is None:+ boxes = self._boxes = {}+ box = boxes.get(curves)+ if box is None:+ box = boxes[curves] = extent(self.array, curves)+ return box++ def extended(self, rows: Floats) -> Shape:+ """This shape with rows appended — in place, when it is its log's longest prefix (a+ growing path costs what it grows); else into a log of its own."""+ log = self.log+ if log is None or log.length != len(self.array):+ log = Log(self.array)+ return log.extended(rows)++ @property+ def key(self) -> int:+ """Content address; shapes equal to 1e-9 are the same shape."""+ if self._key is None:+ self._key = digest(+ str(self.array.shape).encode(), np.round(self.array, 9).tobytes()+ )+ return self._key++ @property+ def affine(self) -> tuple[int, Floats, Matrix]:+ """(key, canonical points C, A) with the shape = A·C: C names its affine class (every segment,+ circle or triangle is one), uploaded once, so a shape that only moves, turns, scales or shears is+ never uploaded again. A has zero columns where the shape is flat. A shape of more than+ CANONICAL points is not reduced to a canonical form, which would cost about what uploading+ it does: it is an affine image of the last such shape of its size, if it is one (a surface+ raised, turned or moved by setting its points), or else its own class (C, its points; A,+ the identity), which its key finds again if it recurs as itself."""+ if self._affine is None:+ if len(self.array) > CANONICAL:+ self._affine = _big_class(self)+ return self._affine+ # equal content, seen before: its class and place+ self._affine = _CLASSES.recall(self.key, lambda: _affine_class(self.array))+ return self._affine++ def __deepcopy__(self, memo: dict[int, object]) -> Shape:+ return self+++_CLASSES: Memo[int, tuple[int, Floats, Matrix]] = Memo(1 << 14) # content → class+# (n, 3) → the class of the last shape of n > CANONICAL points given a class of its own+_LAST: Memo[tuple[int, ...], tuple[int, Floats, Matrix]] = Memo(1 << 6)+_LOGS = itertools.count(1)+++def _big_class(shape: Shape) -> tuple[int, Floats, Matrix]:+ """A shape of more than CANONICAL points: the last such shape's class if it is an affine image of+ that shape's points, placed by the map; else a class of its own."""+ last = _LAST.get(shape.array.shape)+ if last is not None:+ a = _affine_image(last[1], shape.array)+ if a is not None:+ return last[0], last[1], a+ return _LAST.keep(shape.array.shape, (shape.key, shape.array, IDENTITY))+++def _affine_image(base: Floats, points: Floats) -> Matrix | None:+ """The affine map A (3×4) with points = A·base, if there is one to 1e-9 of their size: the+ identity for the same points (not a fit, which would be off by rounding); else fitted at 16+ points spread along them (where a shape that is not one fails), then checked at every+ point."""+ if unchanged(points, base):+ return IDENTITY+ probe = np.linspace(0, len(base) - 1, 16).astype(int)+ rows = np.hstack([base[probe], np.ones((len(probe), 1))])+ fit = np.linalg.lstsq(rows, points[probe], rcond=None)[0] # points ≈ [base 1]·fit+ tolerance = 1e-9 * (1.0 + np.abs(points[probe]).max())+ if np.abs(rows @ fit - points[probe]).max() > tolerance:+ return None+ if np.abs(base @ fit[:3] + fit[3] - points).max() > tolerance:+ return None+ return np.ascontiguousarray(fit.T)+++class Log:+ """Control points that only grow: every prefix is a shape sharing the array, and appending to the+ longest writes in place, so a traced path grows by a curve, not by a copy."""++ __slots__ = ("array", "id", "length")++ def __init__(self, rows: Floats) -> None:+ self.array = np.empty((max(64, 2 * len(rows)), 3))+ self.array[: len(rows)] = rows+ self.length = len(rows)+ self.id = next(_LOGS)++ def extended(self, rows: Floats) -> Shape:+ end = self.length + len(rows)+ if end > len(self.array):+ grown = np.empty((2 * end, 3))+ grown[: self.length] = self.array[: self.length]+ self.array = grown+ self.array[self.length : end] = rows+ self.length = end+ return Shape(self.array[:end], self)+++def _affine_class(points: Floats) -> tuple[int, Floats, Matrix]:+ """Center and whiten the points (unit covariance in the subspace they span), then fix the+ remaining rotation by the points themselves: the first farthest point on +x, the first farthest+ from that line in the +y half-plane, then +z (ties within 1e-6 keep their order). Canonical+ points are O(1), well within float32."""+ n = len(points)+ if n == 0:+ return digest(str(points.shape).encode()), points, IDENTITY.copy()+ center = points.mean(axis=0)+ d = points - center+ values, vectors = np.linalg.eigh(d.T @ d / n)+ # a direction thinner than 1e-6 of the shape's size is flat+ spanned = values > values[-1] * 1e-12 if values[-1] > 0 else values > 1.0+ rank = int(spanned.sum())+ canonical = np.zeros_like(points)+ linear = np.zeros((3, 3))+ if rank:+ roots = np.sqrt(values[spanned])+ x = d @ (vectors[:, spanned] / roots) # whitened: n × rank+ frame = np.zeros((rank, rank))+ rest = x+ for axis in range(rank):+ norms = np.einsum("ij,ij->i", rest, rest)+ pick = int(np.argmax(norms >= norms.max() * (1 - 1e-6)))+ frame[axis] = rest[pick] / np.sqrt(norms[pick])+ rest = rest - np.outer(rest @ frame[axis], frame[axis])+ canonical[:, :rank] = x @ frame.T+ linear[:, :rank] = (vectors[:, spanned] * roots) @ frame.T+ canonical.flags.writeable = False+ key = digest( # + 0.0: no negative zeros+ str(points.shape).encode(), (np.round(canonical, 7) + 0.0).tobytes()+ )+ return key, canonical, np.hstack([linear, center[:, None]])+++_DEFINED: Memo[tuple[object, ...], Shape] = Memo(1 << 12)+++def defined(definition: tuple[object, ...], make: Callable[[], Floats]) -> Shape:+ """The shape a definition names (`("arc", start, angle, n)`), made once and shared — with its+ affine class and upload — by every mobject that draws it."""+ return _DEFINED.recall(definition, lambda: Shape(np.array(make(), dtype=float)))+++SEGMENT: Final = Shape(+ np.array([[0.0, 0, 0], [1 / 3, 0, 0], [2 / 3, 0, 0], [1.0, 0, 0]])+)+++def curve_box(points: Floats) -> Floats:+ """(2, D): the tight box of cubic Bézier curves (control points in fours). The anchors lie on+ the curves, and each curve lies in its control points' hull, so the anchors' box is tight+ unless a handle leaves it; only such curves are solved for their turning points: per+ coordinate, the roots of the derivative, a quadratic (solved without cancellation, so a+ vanishing leading term is harmless). Any parameter in [0, 1] is a point of the curve, so a+ clipped or spurious root is harmless too."""+ ends = np.concatenate([points[0::4], points[3::4]])+ lo, hi = ends.min(axis=0), ends.max(axis=0)+ p = points.reshape(-1, 4, points.shape[-1])+ p = p[((p < lo) | (p > hi)).any(axis=(1, 2))]+ if len(p) == 0:+ return np.array([lo, hi])+ p0, p1, p2, p3 = p[:, 0], p[:, 1], p[:, 2], p[:, 3]+ c = p1 - p0 # B'(t)/3 = a t² + 2 h t + c, per coordinate+ h = p2 - p1 - c+ a = p3 - p0 - 3 * (p2 - p1)+ q = -(h + np.copysign(np.sqrt(np.maximum(h * h - a * c, 0)), h)) # roots q/a, c/q+ t = np.clip([q / np.where(a == 0, 1, a), c / np.where(q == 0, 1, q)], 0, 1)+ turns = p0 + t * (3 * c + t * (3 * h + t * a)) # B(t), by Horner+ return np.array(+ [np.minimum(lo, turns.min(axis=(0, 1))), np.maximum(hi, turns.max(axis=(0, 1)))]+ )+++def extent(points: Floats, curves: bool) -> Floats:+ """(2, D): the box of what the points make: a path's (`curves`: complete cubic curves) is its+ curves' tight box, anything else's its points'."""+ if curves and len(points) and len(points) % 4 == 0:+ return curve_box(points)+ return np.array([points.min(axis=0), points.max(axis=0)])+++def placed_box(m: Matrix, shape: Shape, curves: bool) -> Floats:+ """(2, 3): the box of `shape` placed by `m`. A map along the axes keeps each coordinate's+ extremes: there it is the shape's own box, mapped; else the placed points' box."""+ linear = m[:, :3]+ d = linear.diagonal()+ if np.count_nonzero(linear) == np.count_nonzero(d): # along the axes+ ends = shape.box(curves) * d + m[:, 3]+ return np.array([ends.min(axis=0), ends.max(axis=0)])+ return extent(shape.array @ linear.T + m[:, 3], curves)+++def segment(start: Floats, end: Floats) -> Blend:+ """A straight segment (one cubic curve, handles at its thirds, as CE makes it): the one+ segment shape, placed by [end − start | start]."""+ m = np.zeros((3, 4))+ m[:, 0], m[:, 3] = np.subtract(end, start), start+ return Blend(((m, SEGMENT),), 4)+++def _compose(linear: Floats, matrix: Matrix) -> Matrix:+ """linear ∘ matrix, where `linear` is 3×3 (no translation of its own): one product, as the+ translation column transforms like any other."""+ return linear @ matrix+++class Blend:+ """points = Σ M·S over `terms`. Immutable: every edit returns a new blend."""++ __slots__ = ("_boxes", "_pace", "_pieces", "_points", "n", "terms")++ def __init__(self, terms: tuple[Term, ...], n: int) -> None:+ self.terms = terms+ self.n = n # number of points, known without materializing+ self._points: Floats | None = None+ self._pieces: Floats | None = None+ self._pace: tuple[Floats, Floats] | None = None+ self._boxes: dict[bool, Floats] | None = None++ def box(self, curves: bool) -> Floats:+ """(2, 3): the box of what the points make — for a path (`curves`), its curves' tight box:+ not its anchors' (a curve bulges between them), not its handles' (they overshoot).+ Cached: a blend never changes."""+ boxes = self._boxes+ if boxes is None:+ boxes = self._boxes = {}+ box = boxes.get(curves)+ if box is None:+ box = boxes[curves] = (+ placed_box(*self.terms[0], curves) # one shape placed+ if len(self.terms) == 1+ else extent(self.points(), curves)+ )+ return box++ @staticmethod+ def of(points: npt.ArrayLike, dim: int = 3) -> Blend:+ """A blend of one fresh shape. Translation is factored out, so translated copies share it."""+ array = np.array(points, dtype=float).reshape(-1, dim)+ if len(array) == 0:+ return EMPTY+ origin = array[0].copy()+ matrix = IDENTITY.copy()+ matrix[:, 3] = origin+ return Blend(((matrix, Shape(array - origin)),), len(array))++ def points(self) -> Floats:+ if self._points is None:+ out = np.zeros((self.n, 3))+ for m, shape in self.terms:+ out += shape.array @ m[:, :3].T + m[:, 3]+ out.flags.writeable = False+ self._points = out+ return self._points++ @property+ def cached(self) -> Floats | None:+ """The points, if they have been read; else None (what is compared with them for free)."""+ return self._points++ def point(self, k: int) -> Floats:+ """Point k (from the end if negative) without materializing the blend: a path being+ built reads where it ends once a curve, not all its points."""+ if self._points is not None or not self.terms:+ return self.points()[k]+ out = np.zeros(3)+ for m, shape in self.terms:+ out += shape.array[k] @ m[:, :3].T + m[:, 3]+ return out++ def translated(self, vector: Floats) -> Blend:+ """The blend moved by `vector`: one term's offset, no product (a move is the commonest+ edit of all) — and its boxes moved with it, when known."""+ if not self.terms:+ return self+ (first, shape), *rest = self.terms+ moved = first.copy()+ moved[:, 3] += vector+ blend = Blend(((moved, shape), *rest), self.n)+ if self._boxes:+ blend._boxes = {k: box + vector for k, box in self._boxes.items()}+ return blend++ def scaled(self, factor: float, about: Floats) -> Blend:+ """The blend scaled by `factor` about `about` — x ↦ f·x + (1 − f)·about: every term's+ map times f, the rest added once; its boxes, when known, scaled with it."""+ if not self.terms:+ return self+ terms = [(m * factor, shape) for m, shape in self.terms]+ terms[0][0][:, 3] += about * (1.0 - factor)+ blend = Blend(tuple(terms), self.n)+ if self._boxes:+ blend._boxes = {}+ for k, box in self._boxes.items():+ ends = (box - about) * factor + about+ blend._boxes[k] = ends if factor >= 0 else ends[::-1].copy()+ return blend++ def transformed(self, m: Matrix) -> Blend:+ """The blend after the affine map `m` (its boxes follow a map along the axes)."""+ if not self.terms:+ return self+ terms = [(_compose(m[:, :3], a), shape) for a, shape in self.terms]+ terms[0][0][:, 3] += m[:, 3]+ blend = Blend(tuple(terms), self.n)+ if self._boxes:+ d = m.diagonal()+ if np.count_nonzero(m[:, :3]) == np.count_nonzero(d): # along the axes+ blend._boxes = {}+ for k, box in self._boxes.items():+ ends = box * d + m[:, 3]+ blend._boxes[k] = np.array([ends.min(axis=0), ends.max(axis=0)])+ return blend++ @staticmethod+ def mix(a: Blend, b: Blend, coefficients: Coefficients) -> Blend:+ """`Lₛ·a + Lₑ·b + k` point by point; terms of the same shape merge, so a morph between copies+ of one shape stays one matrix."""+ ls, le, offset = coefficients+ merged: dict[int, Term] = {}+ for linear, blend in ((ls, a), (le, b)):+ for m, shape in blend.terms:+ term = _compose(linear, m)+ if shape.key in merged:+ term = merged[shape.key][0] + term+ merged[shape.key] = (term, shape)+ if not merged:+ return Blend((), a.n)+ terms = list(merged.values())+ terms[0][0][:, 3] += offset+ return Blend(tuple(terms), a.n)++ def piece_lengths(self) -> Floats:+ """(curves, 9): lengths of each curve's polyline through 10 points — the path's own+ measure of length, which its reveals, proportions and lengths all go by."""+ pieces = self._pieces+ if pieces is None:+ pts = self.points()+ curves = pts[: len(pts) // 4 * 4].reshape(-1, 4, 3)+ samples = np.einsum("tk,ckd->ctd", _BERNSTEIN, curves)+ pieces = np.linalg.norm(np.diff(samples, axis=1), axis=2)+ pieces.flags.writeable = False+ self._pieces = pieces+ return pieces++ def curve_lengths(self) -> Floats:+ """Length of each cubic curve."""+ return self.piece_lengths().sum(axis=1)++ def pace(self) -> tuple[Floats, Floats]:+ """(s, u): the fraction s of the length reached at curve parameter u. A reveal reads it once:+ constant pen speed, and the drawn part stays put under later transforms."""+ pieces = self.piece_lengths()+ curves = len(pieces)+ u = np.concatenate(+ [+ [0.0],+ (np.arange(curves)[:, None] + np.arange(1, 10)[None, :] / 9).ravel(),+ ]+ )+ s = np.concatenate([[0.0], np.cumsum(pieces.ravel())])+ return (s / s[-1] if s[-1] > 0 else u / max(curves, 1)), u++ def parameter_at(self, fraction: float) -> float:+ """The curve parameter u ∈ [0, curves] a fraction of the length along the path:+ the inverse of `fraction_at`, through the pace."""+ if self._pace is None:+ self._pace = self.pace()+ s, u = self._pace+ return float(np.interp(fraction, s, u))++ def fraction_at(self, parameter: float) -> float:+ """The fraction of the path's length reached at curve parameter u ∈ [0, curves]."""+ if self._pace is None:+ self._pace = self.pace()+ s, u = self._pace+ return float(np.interp(parameter, u, s))++ def __deepcopy__(self, memo: dict[int, object]) -> Blend:+ return self+++EMPTY: Final = Blend((), 0)+++def linear_about(linear: Floats, about: Floats) -> Matrix:+ """The affine map x ↦ L(x − about) + about."""+ m = np.empty((3, 4))+ m[:, :3] = linear+ m[:, 3] = about - linear @ about+ return m+++@forgets+def grid_triangles(u: int, v: int) -> np.ndarray:+ """Two triangles per lattice cell, in the same u-major cell order."""+ index = np.arange((u + 1) * (v + 1)).reshape(u + 1, v + 1)+ a, b, c, d = index[:-1, :-1], index[1:, :-1], index[1:, 1:], index[:-1, 1:]+ triangles = np.stack([a, b, c, a, c, d], axis=-1).reshape(-1, 3)+ triangles.flags.writeable = False+ return trianglesdiff --git a/tests/unit/drawing/test_geometry.py b/tests/unit/drawing/test_geometry.pynew file mode 100644index 00000000..7e9bcc10--- /dev/null+++ b/tests/unit/drawing/test_geometry.py@@ -0,0 +1,1031 @@+"""Bézier algorithms cut, split and smooth curves without changing them.++- A curve is exactly its ends at 0 and 1, and de Casteljau's construction everywhere between.+- A part of a curve is the curve, reparametrized; split into n (any integer, whatever is+ remembered), a curve's pieces are its equal stretches of parameter, end to end, from its start+ to its end exactly; remapped from m curves into n ≥ m, new curve j is an equal stretch of+ curve j·m // n, in an array of its own.+- A smooth curve through anchors is a natural cubic spline: continuous in its first and second+ derivatives at every anchor, straight at its ends (or closed smoothly), on either side of+ the size where a precomputed map gives way to the solve; it moves with its anchors under any+ affine map.+- `integer_interpolate` finds the step and the fraction of it: step + fraction = n·alpha.+++The geometry helpers are the geometry they name.++- A rotation matrix is a rotation: orthogonal, of determinant 1, fixing its axis; turns about+ one axis add; its transpose turns back; it agrees with its quaternion.+- A turn needs an axis: given a zero axis, everything that turns about one (a rotation matrix,+ its transpose, a turned vector, a quaternion, a mobject's rotation, an arc's, a spiral's or a+ circle's path) raises, rather than scaling by cos(angle).+- A compass orbit stays at its height and radius, evenly spaced in the plane.+- A polygon's signed area and its orientation are its own: they do not depend on where it is,+ or on which vertex it starts at.+- Conversions are inverse: spherical and Cartesian coordinates, angles and axes of quaternions.+- A unit normal is a unit vector perpendicular to both vectors; an intersection lies on both+ lines; a triangulation covers its polygon, holes excluded.+- A hull encloses its points, and every boundary of its facets is shared by two of them,+ whatever the points' type, repeats and signed zeros; its points changing afterwards changes+ nothing of it. A boundary is named by its points as they were, in any order, of any type,+ whatever their zeros' signs.+- A polygon's pole of inaccessibility is a point inside it, within `precision` as far from its+ edges as the farthest point inside is, wherever and however large the polygon is.++Geometry is a lazy blend of immutable shapes: points = Σ M·S.++- A blend's points are the points its edits made: every edit (a move, a scale, an affine map,+ a mix of two blends) equals the same edit done on plain points, however they chain.+- A box a blend carries through its edits is the box of its points: a path's is its curves'+ tight box, by the roots of their derivatives, not its anchors' or handles'.+- A shape is its affine class placed: A·C gives back its points, and C is small.+- A shape is named by its content: equal points (to 1e-9) are one key, never 0, the key no+ upload may have. A big shape's class is the last one of its size when it is an affine image+ of it (and other points of that size are not), and the same points are that image exactly,+ by the identity.+- A growing path's shapes are prefixes of one log: growing never changes a shape made before,+ whichever prefix is grown.++A path takes each point from where it starts to where it ends.++- Every path, of every kind, is exactly at the start at 0 and exactly at the end at 1, in+ three dimensions too: an arc about an axis moves along the axis as well.+- The straight path runs along the chord; an arc path turns each point about the center of its+ arc, at a steady angle; a spiral path is the formula its docstring gives.+- A motion is its steps: a turn keeps its pivot, as the steps before it carried the pivot,+ where it is; moves add; a path about one center turns a shape rigidly about it."""++from collections.abc import Callable++import numpy as np+import pytest+from hypothesis import assume, example, given, settings+from hypothesis import strategies as st+from hypothesis.stateful import RuleBasedStateMachine, initialize, invariant, rule+from tests import oracles+from tests.strategies import angles, arrays, curves, points, vectors++import manimgx as m+from manimgx.caches import clear+from manimgx.drawing import geometry as g++unit = st.floats(0, 1)+cubic = arrays((4, 3), 20)+CONTROLS = np.array([[0.0, 0, 0], [2, 4, -1], [6, -3, 5], [10, -5, 2]])+++def close(a: np.ndarray, b: np.ndarray, scale: np.ndarray) -> None:+ np.testing.assert_allclose(a, b, atol=1e-9 * (1 + np.abs(scale).max()))+++class TestCurve:+ @given(points=cubic, t=unit)+ def test_it_is_de_casteljaus_construction(+ self, points: np.ndarray, t: float+ ) -> None:+ close(+ g.bezier(points)(t),+ oracles.bezier_points(points, np.array([t]))[0, 0],+ points,+ )+ np.testing.assert_array_equal(g.bezier(points)(0), points[0])+ np.testing.assert_array_equal(g.bezier(points)(1), points[3])++ @given(points=cubic, a=unit, b=unit, s=unit)+ def test_a_part_is_the_curve_reparametrized(+ self, points: np.ndarray, a: float, b: float, s: float+ ) -> None:+ a, b = min(a, b), max(a, b)+ part = g.partial_bezier_points(points, a, b)+ close(g.bezier(part)(s), g.bezier(points)(a + s * (b - a)), points)++ @given(+ points=cubic,+ n=st.integers(1, 2000),+ numpy=st.booleans(),+ forget=st.booleans(),+ s=unit,+ )+ # n³ overflows numpy's int32; what is made for it is remembered for an int too+ @example(points=CONTROLS, n=2000, numpy=True, forget=True, s=0.37)+ def test_split_pieces_are_equal_stretches_end_to_end(+ self, points: np.ndarray, n: int, numpy: bool, forget: bool, s: float+ ) -> None:+ if forget:+ clear()+ # numpy's integers, as numpy code passes them+ count = np.int32(n) if numpy else n+ with np.errstate(over="raise", invalid="raise"):+ split = g.subdivide_bezier(points, count) # ty: ignore[invalid-argument-type]+ pieces = split.reshape(n, 4, 3)+ close(+ oracles.bezier_points(pieces, np.array([s]))[:, 0],+ oracles.bezier_points(points, (np.arange(n) + s) / n)[0],+ points,+ )+ close(pieces[1:, 0], pieces[:-1, 3], points)+ np.testing.assert_array_equal(pieces[0, 0], points[0])+ np.testing.assert_array_equal(pieces[-1, 3], points[3])++ @given(+ many=st.integers(1, 5).flatmap(lambda n: arrays((n, 4, 3), 20)),+ more=st.integers(0, 20),+ fortran=st.booleans(),+ )+ @example(many=np.zeros((0, 4, 3)), more=0, fortran=False)+ def test_remapped_curves_are_their_curves_equal_stretches(+ self, many: np.ndarray, more: int, fortran: bool+ ) -> None:+ if fortran:+ many = np.asfortranarray(many)+ many.setflags(write=False)+ new = len(many) + more+ out = g.bezier_remap(many, new)+ assert out.shape == (new, 4, 3)+ assert out.flags.c_contiguous+ assert out.flags.writeable+ assert not np.shares_memory(out, many)+ owners = [j * len(many) // new for j in range(new)]+ samples = np.array([0.0, 0.37, 1.0])+ for j, owner in enumerate(owners):+ stretch = (owners[:j].count(owner) + samples) / owners.count(owner)+ close(+ oracles.bezier_points(out[j], samples),+ oracles.bezier_points(many[owner], stretch),+ many,+ )+++def spline(anchors: np.ndarray) -> np.ndarray:+ h1, h2 = g.get_smooth_cubic_bezier_handle_points(anchors)+ return np.stack([anchors[:-1], h1, h2, anchors[1:]], axis=1)+++def derivatives(c: np.ndarray) -> tuple[np.ndarray, ...]:+ """(B'(0), B'(1), B''(0), B''(1)) of each curve."""+ return (+ 3 * (c[:, 1] - c[:, 0]),+ 3 * (c[:, 3] - c[:, 2]),+ 6 * (c[:, 2] - 2 * c[:, 1] + c[:, 0]),+ 6 * (c[:, 3] - 2 * c[:, 2] + c[:, 1]),+ )+++anchors = st.integers(3, 300).flatmap(lambda n: arrays((n, 3), 10))+MAPPED = (+ g._SMOOTHING_UP_TO+) # the most anchors smoothed by a precomputed map, not the solve+++def scattered(n: int) -> np.ndarray:+ return np.random.default_rng(n).normal(size=(n, 3))+++class TestSmooth:+ @given(points=anchors)+ @example(points=scattered(MAPPED))+ @example(points=scattered(MAPPED + 1))+ def test_an_open_curve_is_a_natural_spline(self, points: np.ndarray) -> None:+ points[-1] += 1 # open+ assume(not g.is_closed(points))+ c = spline(points)+ d0, d1, s0, s1 = derivatives(c)+ close(d1[:-1], d0[1:], points)+ close(s1[:-1], s0[1:], points)+ close(s0[0], np.zeros_like(s0[0]), points)+ close(s1[-1], np.zeros_like(s1[-1]), points)++ @given(points=anchors)+ @example(points=scattered(MAPPED - 1)) # and the first again: MAPPED anchors+ @example(points=scattered(MAPPED))+ def test_a_closed_curve_closes_smoothly(self, points: np.ndarray) -> None:+ c = spline(np.vstack([points, points[:1]]))+ d0, d1, s0, s1 = derivatives(c)+ close(np.roll(d1, 1, axis=0), d0, points)+ close(np.roll(s1, 1, axis=0), s0, points)++ @given(+ points=st.integers(3, 30).flatmap(lambda n: arrays((n, 3), 10)),+ linear=arrays((3, 3), 2),+ offset=arrays(3, 10),+ )+ def test_it_moves_with_its_anchors(+ self, points: np.ndarray, linear: np.ndarray, offset: np.ndarray+ ) -> None:+ points[-1] += 1+ assume(not g.is_closed(points) and not g.is_closed(points @ linear.T + offset))+ close(+ spline(points @ linear.T + offset),+ spline(points) @ linear.T + offset,+ points,+ )+++alphas = unit | st.sampled_from(+ [np.nextafter(0, 1), np.nextafter(1, 0)]+) # rounding bites there+++@given(start=st.integers(-50, 50), n=st.integers(1, 1000), alpha=alphas)+def test_integer_interpolate_finds_the_step_and_its_fraction(+ start: int, n: int, alpha: float+) -> None:+ # (it truncated toward 0 below a start of 0, and could step past the last step)+ step, fraction = g.integer_interpolate(start, start + n, alpha)+ assert start <= step < start + n+ assert 0 <= fraction <= 1+ assert step + fraction == pytest.approx(+ start + n * alpha, abs=1e-9 * (n + abs(start))+ )+++@given(start=st.floats(-100, 100), end=st.floats(-100, 100), alpha=unit)+def test_inverse_interpolate_inverts_interpolate(+ start: float, end: float, alpha: float+) -> None:+ assume(abs(end - start) > 1e-6)+ assert g.inverse_interpolate(+ start, end, g.interpolate(start, end, alpha)+ ) == pytest.approx(alpha, abs=1e-9 * (1 + abs(start) + abs(end)) / abs(end - start))+++class TestRotationMatrix:+ @given(angle=angles(), axis=vectors())+ def test_it_is_a_rotation_about_its_axis(+ self, angle: float, axis: np.ndarray+ ) -> None:+ r = g.rotation_matrix(angle, axis)+ np.testing.assert_allclose(r @ r.T, np.eye(3), atol=1e-12)+ assert np.linalg.det(r) == pytest.approx(1, abs=1e-12)+ np.testing.assert_allclose(r @ axis, axis, atol=1e-12 * np.linalg.norm(axis))++ @given(a=angles(), b=angles(), axis=vectors())+ def test_turns_about_one_axis_add(+ self, a: float, b: float, axis: np.ndarray+ ) -> None:+ np.testing.assert_allclose(+ g.rotation_matrix(a, axis) @ g.rotation_matrix(b, axis),+ g.rotation_matrix(a + b, axis),+ atol=1e-12,+ )+ np.testing.assert_allclose(+ g.rotation_matrix_transpose(a, axis),+ g.rotation_matrix(-a, axis),+ atol=1e-12,+ )++ @given(angle=st.floats(0.01, np.pi - 0.01), axis=vectors(), v=vectors())+ def test_it_turns_counterclockwise_seen_from_its_axis(+ self, angle: float, axis: np.ndarray, v: np.ndarray+ ) -> None:+ across = v - (v @ axis) / (axis @ axis) * axis # v's part a turn moves+ assume(np.linalg.norm(across) > 1e-2 * np.linalg.norm(v))+ turned = g.rotation_matrix(angle, axis) @ across+ assert np.cross(across, turned) @ axis > 0++ @given(angle=angles(), axis=vectors())+ def test_it_is_its_quaternion(self, angle: float, axis: np.ndarray) -> None:+ q = np.array(g.quaternion_from_angle_axis(angle, axis))+ np.testing.assert_allclose(+ g.rotation_matrix_from_quaternion(q),+ g.rotation_matrix(angle, axis),+ atol=1e-12,+ )+ rows = g.rotation_matrix_transpose_from_quaternion(q)+ np.testing.assert_allclose(rows, g.rotation_matrix(angle, axis).T, atol=1e-12)++ @given(v=arrays(2, 10), angle=angles())+ def test_a_plane_vector_turns_in_its_plane(+ self, v: np.ndarray, angle: float+ ) -> None:+ c, s = np.cos(angle), np.sin(angle)+ np.testing.assert_allclose(+ g.rotate_vector(v, angle),+ [c * v[0] - s * v[1], s * v[0] + c * v[1], 0],+ atol=1e-12 * (1 + np.abs(v).max()),+ )+++class TestZToVector:+ @given(v=vectors())+ def test_it_turns_the_z_axis_to_the_vector(self, v: np.ndarray) -> None:+ r = g.z_to_vector(v)+ np.testing.assert_allclose(r @ r.T, np.eye(3), atol=1e-12)+ assert np.linalg.det(r) == pytest.approx(1, abs=1e-12)+ np.testing.assert_allclose(r @ m.OUT, v / np.linalg.norm(v), atol=1e-12)+++polygons = st.integers(3, 12).flatmap(lambda n: arrays((n, 2), 10))+++class TestShoelace:+ @given(xy=polygons, shift=arrays(2, 50), start=st.integers(0, 11))+ def test_the_area_is_the_polygons_wherever_it_is(+ self, xy: np.ndarray, shift: np.ndarray, start: int+ ) -> None:+ # shoelace's sign: positive clockwise+ expected = -oracles.polygon_area(xy)+ moved = np.roll(xy + shift, start % len(xy), axis=0)+ assert g.shoelace(moved) == pytest.approx(+ expected, abs=1e-9 * (1 + np.abs(moved).max()) ** 2+ )++ @given(xy=polygons, shift=arrays(2, 50))+ def test_the_orientation_is_the_polygons_wherever_it_is(+ self, xy: np.ndarray, shift: np.ndarray+ ) -> None:+ area = oracles.polygon_area(xy)+ assume(abs(area) > 1e-6)+ expected = "CCW" if area > 0 else "CW"+ assert g.shoelace_direction(xy) == expected+ assert g.shoelace_direction(xy + shift) == expected++ def test_a_closed_ring_counts_its_repeated_vertex_once(self) -> None:+ square = np.array([[0, 0], [1, 0], [1, 1], [0, 1]], dtype=float)+ assert g.shoelace(square) == g.shoelace(np.vstack([square, square[:1]])) == -1+++class TestWindingNumber:+ @given(radius=st.floats(0.1, 10), center=arrays(2, 20), n=st.integers(3, 40))+ def test_a_circle_winds_once_about_what_it_holds(+ self, radius: float, center: np.ndarray, n: int+ ) -> None:+ t = np.linspace(0, 2 * np.pi, n, endpoint=False)+ ring = np.stack(+ [center[0] + radius * np.cos(t), center[1] + radius * np.sin(t), 0 * t], 1+ )+ inside = np.linalg.norm(center) < radius * np.cos(np.pi / n) - 1e-9+ outside = np.linalg.norm(center) > radius + 1e-9+ assume(inside or outside)+ assert g.get_winding_number(ring) == pytest.approx(1 if inside else 0, abs=1e-9)+ assert g.get_winding_number(ring[::-1]) == pytest.approx(+ -1 if inside else 0, abs=1e-9+ )+++class TestConversions:+ @given(v=vectors(min_norm=1e-6, bound=100))+ def test_spherical_coordinates_are_inverse(self, v: np.ndarray) -> None:+ r, theta, phi = g.cartesian_to_spherical(v)+ assert r >= 0+ assert -np.pi <= theta <= np.pi+ assert 0 <= phi <= np.pi+ np.testing.assert_allclose(+ g.spherical_to_cartesian(np.array([r, theta, phi])), v, atol=1e-12 * r+ )++ @given(angle=st.floats(0, np.pi), axis=vectors())+ def test_a_quaternions_angle_and_axis_are_inverse(+ self, angle: float, axis: np.ndarray+ ) -> None:+ got_angle, got_axis = g.angle_axis_from_quaternion(+ np.array(g.quaternion_from_angle_axis(angle, axis))+ )+ assert got_angle == pytest.approx(angle, abs=1e-6)+ if angle > 1e-6:+ np.testing.assert_allclose(got_axis, axis / np.linalg.norm(axis), atol=1e-9)++ @given(quats=st.lists(arrays(4, 2), min_size=3, max_size=3))+ def test_quaternion_products_associate(self, quats: list[np.ndarray]) -> None:+ a, b, c = quats+ np.testing.assert_allclose(+ g.quaternion_mult(g.quaternion_mult(a, b), c),+ g.quaternion_mult(a, g.quaternion_mult(b, c)),+ atol=1e-9,+ )+++class TestUnitNormal:+ @given(a=points(10), b=points(10))+ def test_it_is_a_unit_vector_perpendicular_to_both(+ self, a: np.ndarray, b: np.ndarray+ ) -> None:+ n = g.get_unit_normal(a, b)+ assert np.linalg.norm(n) == pytest.approx(1, abs=1e-12)+ for v in (a, b):+ if np.linalg.norm(v) > 1e-9:+ assert abs(n @ v) / np.linalg.norm(v) < 1e-6+++class TestAngles:+ @given(a=vectors(), b=vectors(), angle=angles(), axis=vectors())+ def test_the_angle_between_two_vectors_turns_with_them(+ self, a: np.ndarray, b: np.ndarray, angle: float, axis: np.ndarray+ ) -> None:+ between = g.angle_between_vectors(a, b)+ assert 0 <= between <= np.pi+ cos = a @ b / np.linalg.norm(a) / np.linalg.norm(b)+ assert np.cos(between) == pytest.approx(cos, abs=1e-9)+ r = g.rotation_matrix(angle, axis)+ assert g.angle_between_vectors(r @ a, r @ b) == pytest.approx(between, abs=1e-6)+++class TestIntersections:+ @given(lines=arrays((2, 2, 3), 10))+ def test_where_two_lines_cross_is_on_both(self, lines: np.ndarray) -> None:+ (a, b), (c, d) = lines[:, :, :2]+ u, v = b - a, d - c+ assume(min(np.linalg.norm(u), np.linalg.norm(v)) > 1e-2)+ assume(+ abs(u[0] * v[1] - u[1] * v[0])+ > 1e-2 * np.linalg.norm(u) * np.linalg.norm(v)+ )+ p = g.line_intersection(lines[0], lines[1])[:2]+ for start, direction in ((a, u), (c, v)):+ offset = p - start+ cross = direction[0] * offset[1] - direction[1] * offset[0]+ assert abs(cross) <= 1e-6 * np.linalg.norm(direction) * (+ 1 + np.linalg.norm(offset)+ )++ @given(+ a=st.tuples(st.integers(-9, 9), st.integers(-9, 9)),+ u=st.tuples(st.integers(-9, 9), st.integers(-9, 9)).filter(any),+ t=st.integers(-5, 5),+ )+ def test_parallel_lines_have_no_intersection(+ self, a: tuple[int, int], u: tuple[int, int], t: int+ ) -> None:+ # whole numbers: exactly parallel in floats too+ line1 = np.array([[*a, 0], [a[0] + u[0], a[1] + u[1], 0]], dtype=float)+ line2 = line1 + np.array([u[1], -u[0], 0]) * t # moved across itself, or not+ with pytest.raises(ValueError, match="parallel"):+ g.line_intersection(line1, line2)+++class TestEarclipTriangulation:+ @given(+ n=st.integers(3, 30),+ radii=st.lists(st.floats(0.5, 2), min_size=30, max_size=30),+ hole=st.just(0.0) | st.floats(0.05, 0.5),+ )+ def test_its_triangles_cover_a_star_shaped_polygon_but_its_hole(+ self, n: int, radii: list[float], hole: float+ ) -> None:+ t = np.linspace(0, 2 * np.pi, n, endpoint=False)+ ring = np.stack([radii[:n] * np.cos(t), radii[:n] * np.sin(t), 0 * t], 1)+ # the polygon scaled about a point it holds, its center: a hole inside it+ verts, ends = (+ (np.vstack([ring, hole * ring]), [n, 2 * n]) if hole else (ring, [n])+ )+ triangles = np.array(g.earclip_triangulation(verts, ends)).reshape(-1, 3)+ assert len(triangles) == len(verts) - 2 + 2 * (len(ends) - 1)+ total = sum(abs(oracles.polygon_area(verts[tri, :2])) for tri in triangles)+ expected = abs(oracles.polygon_area(ring[:, :2])) * (1 - hole**2)+ assert total == pytest.approx(expected, rel=1e-9)+++@given(n=st.integers(1, 40), radius=st.floats(0.1, 10), start=st.floats(-7, 7))+def test_regular_vertices_are_evenly_spread_on_their_circle(+ n: int, radius: float, start: float+) -> None:+ vertices, first = g.regular_vertices(n, radius=radius, start_angle=start)+ assert first == start+ np.testing.assert_allclose(+ vertices[0],+ radius * np.array([np.cos(start), np.sin(start), 0]),+ atol=1e-12 * radius,+ )+ turn = g.rotation_matrix(2 * np.pi / n)+ np.testing.assert_allclose(+ vertices[1:], vertices[:-1] @ turn.T, atol=1e-12 * radius+ )++[email protected]("dimension", [2, 3])+@given(n=st.integers(1, 96), start=arrays(3, 20))+def test_compass_orbits_keep_height_radius_and_even_spacing(+ dimension: int, n: int, start: np.ndarray+) -> None:+ orbit = g.compass_directions(n, start[:dimension])+ assert orbit.shape == (n, 3)+ np.testing.assert_array_equal(orbit[:, 2], start[2] if dimension == 3 else 0)+ planar = orbit[:, 0] + 1j * orbit[:, 1]+ np.testing.assert_allclose(np.abs(planar), np.hypot(*start[:2]), atol=1e-12)+ np.testing.assert_allclose(+ np.roll(planar, -1), planar * np.exp(2j * np.pi / n), atol=1e-12+ )+ np.testing.assert_array_equal(orbit[0, :2], start[:2])+++@given(+ dimension=st.integers(2, 5),+ seed=st.integers(0, 2**32 - 1),+ dtype=st.sampled_from(["float32", "float64", "int64"]),+ zeros=st.lists(st.tuples(st.integers(0, 15), st.integers(0, 4)), max_size=6),+ repeats=st.lists(st.integers(0, 15), max_size=4),+)+def test_a_hull_encloses_its_points_with_shared_closed_boundaries(+ dimension: int,+ seed: int,+ dtype: str,+ zeros: list[tuple[int, int]],+ repeats: list[int],+) -> None:+ coordinates = 100 * np.random.default_rng(seed).normal(size=(16, dimension))+ for row, column in zeros:+ coordinates[row, column % dimension] = 0.0+ coordinates = coordinates.astype(dtype)+ again = coordinates[repeats]+ again[again == 0] *= -1 # a repeat with its zeros' signs turned+ points = np.concatenate((coordinates, again))+ kept = points.copy()+ hull = g.QuickHull(tolerance=1e-3)+ hull.build(points)+ # a hull's points are a value: changing them afterwards changes nothing+ points += 10++ active = set(hull.facets) - hull.removed+ assert active+ for facet in active:+ assert len(facet.subfacets) == dimension+ np.testing.assert_allclose(np.linalg.norm(facet.normal), 1, atol=1e-7)+ assert np.max((kept - facet.center) @ facet.normal) < 1e-3+ for boundary in facet.subfacets:+ adjacent = hull.neighbors[boundary]+ assert facet in adjacent+ assert len(adjacent) == 2+ assert adjacent <= active+ assert all(boundary in neighbor.subfacets for neighbor in adjacent)+ # a boundary is named by its points as they were: in any order, of any type,+ # whatever their zeros' signs+ rows = boundary.coordinates[::-1].astype(np.float64)+ rows[rows == 0] *= -1+ name = g.SubFacet(rows)+ rows += 1+ assert hull.neighbors[name] == adjacent+++def from_edges(rings: list[np.ndarray], point: np.ndarray) -> float:+ """How far a point is from the nearest edge of the rings: positive inside them (an odd+ number of edges crossed on the way to +x), negative outside."""+ edges = np.concatenate([np.stack([r[:-1, :2], r[1:, :2]], 1) for r in rings])+ a, b = edges[:, 0], edges[:, 1]+ along = np.clip(+ np.einsum("ij,ij->i", point - a, b - a) / np.einsum("ij,ij->i", b - a, b - a),+ 0,+ 1,+ )+ nearest = float(+ np.min(np.linalg.norm(a + along[:, None] * (b - a) - point, axis=1))+ )+ spans = (a[:, 1] > point[1]) != (b[:, 1] > point[1])+ with np.errstate(divide="ignore", invalid="ignore"):+ cross = a[:, 0] + (point[1] - a[:, 1]) * (b[:, 0] - a[:, 0]) / (+ b[:, 1] - a[:, 1]+ )+ inside = np.count_nonzero(spans & (point[0] < cross)) % 2+ return nearest if inside else -nearest+++def poles(draw: st.DrawFn) -> tuple[list[np.ndarray], float]:+ """A polygon's closed rings and how far its pole of inaccessibility is from its edges: a+ rectangle's (half its height), a triangle's (its incircle's radius), a regular polygon's+ (its apothem), or a square's with a square hole in its middle (its pole on a diagonal,+ as far from the outline as from the hole's corner); placed by any similarity."""+ kind = draw(st.sampled_from(["rectangle", "triangle", "regular", "holed"]))+ if kind == "rectangle":+ width = draw(st.floats(1, 8))+ rings = [np.array([[0, 0], [width, 0], [width, 1], [0, 1]])]+ radius = 0.5+ elif kind == "triangle":+ apex = np.array([draw(st.floats(-1, 2)), draw(st.floats(0.3, 2))])+ corners = np.array([[0, 0], [1, 0], apex])+ sides = np.linalg.norm(corners - np.roll(corners, 1, axis=0), axis=1)+ rings, radius = (+ [corners],+ apex[1] / sides.sum(),+ ) # twice the area, by the perimeter+ elif kind == "regular":+ n = draw(st.integers(3, 12))+ t = 2 * np.pi * np.arange(n) / n+ rings, radius = [np.stack([np.cos(t), np.sin(t)], 1)], np.cos(np.pi / n)+ else:+ hole = draw(st.floats(0.1, 1.5))+ square = np.array([[-1, -1], [1, -1], [1, 1], [-1, 1]])+ rings = [2 * square, hole * square[::-1]]+ radius = np.sqrt(2) * (2 - hole) / (1 + np.sqrt(2))+ scale, turn = draw(st.floats(0.1, 10)), g.rotate_vector+ angle, shift = draw(angles()), draw(arrays(2, 100))+ placed = []+ for ring in rings:+ closed = np.vstack([ring, ring[:1]]).astype(float)+ flat = np.column_stack([closed, np.zeros(len(closed))])+ placed.append(np.array([turn(p, angle) for p in flat]) * scale + [*shift, 0])+ return placed, float(radius * scale)+++@given(polygon=poles(), precision=st.floats(0.005, 0.2))+def test_the_pole_is_inside_within_precision_of_the_farthest_point(+ polygon: tuple[list[np.ndarray], float], precision: float+) -> None:+ rings, radius = polygon+ precision *= radius+ cell = g.polylabel(rings, precision)+ assert cell.d == pytest.approx(from_edges(rings, cell.c), rel=1e-9, abs=1e-12)+ assert radius - precision <= cell.d <= radius * (1 + 1e-9)+++def scale_of(points: np.ndarray) -> float:+ return 1.0 + float(np.abs(points).max(initial=0.0))+++class TestCurveBox:+ @given(points=curves())+ def test_it_is_the_curves_tight_box(self, points: np.ndarray) -> None:+ np.testing.assert_allclose(+ g.curve_box(points), oracles.curve_box(points), atol=1e-9 * scale_of(points)+ )++ @given(points=curves())+ def test_it_holds_every_point_of_the_curves(self, points: np.ndarray) -> None:+ low, high = g.curve_box(points)+ drawn = oracles.sample(points)+ tolerance = 1e-9 * scale_of(points)+ assert np.all(drawn >= low - tolerance)+ assert np.all(drawn <= high + tolerance)++ @given(points=arrays((7, 3)))+ def test_anything_but_a_path_is_boxed_by_its_points(+ self, points: np.ndarray+ ) -> None:+ np.testing.assert_array_equal(+ g.extent(points, curves=True), [points.min(0), points.max(0)]+ )+ np.testing.assert_array_equal(+ g.extent(points[:4], curves=False), [points[:4].min(0), points[:4].max(0)]+ )+++class TestShape:+ @given(points=curves())+ def test_its_affine_class_placed_is_itself(self, points: np.ndarray) -> None:+ _, canonical, placement = g.Shape(points.copy()).affine+ # a direction thinner than 1e-6 of the shape's size counts as flat (float32 holds+ # 7 digits), so the shape comes back to within that+ size = float(np.ptp(points, axis=0).max())+ np.testing.assert_allclose(+ canonical @ placement[:, :3].T + placement[:, 3],+ points,+ atol=2e-6 * size + 1e-12,+ )+ # whitened: O(1), whatever the shape's size, so float32 holds it+ assert np.abs(canonical).max() <= np.sqrt(len(points)) + 1e-9++ @given(points=curves())+ def test_equal_content_is_one_key_never_0(self, points: np.ndarray) -> None:+ key = g.Shape(points.copy()).key+ assert key == g.Shape(points.copy()).key+ assert key != 0++ @given(+ seed=st.integers(0, 2**32 - 1),+ more=st.integers(1, 8),+ angle=angles(),+ axis=vectors(),+ scale=st.floats(0.5, 2),+ shift=arrays(3, 10),+ )+ def test_a_big_shape_is_the_last_ones_class_when_it_is_its_image(+ self,+ seed: int,+ more: int,+ angle: float,+ axis: np.ndarray,+ scale: float,+ shift: np.ndarray,+ ) -> None:+ rng = np.random.default_rng(seed)+ points = rng.normal(size=(g.CANONICAL + more, 3))+ key, base, _ = g.Shape(points.copy()).affine+ again, again_base, placement = g.Shape(points.copy()).affine+ assert again == key+ assert again_base is base+ assert np.array_equal(placement, g.IDENTITY) # exactly: no fit, no jitter+ turn = np.column_stack([scale * g.rotation_matrix(angle, axis), shift])+ moved = points @ turn[:, :3].T + turn[:, 3]+ moved_key, moved_base, placed = g.Shape(moved).affine+ assert moved_key == key+ assert moved_base is base+ np.testing.assert_allclose(placed, turn, atol=1e-6)+ assert g.Shape(points + rng.normal(size=points.shape)).affine[0] != key++ def test_a_shape_never_changes(self) -> None:+ shape = g.Shape(np.zeros((4, 3)))+ with pytest.raises(ValueError, match="read-only"):+ shape.array[0, 0] = 1+++class GrowingPaths(RuleBasedStateMachine):+ """Shapes extended from any prefix of a log keep their own points."""++ @initialize(rows=arrays((4, 3), 10))+ def begin(self, rows: np.ndarray) -> None:+ self.made = [(g.Shape(rows.copy()), rows.copy())]++ @rule(+ which=st.integers(0, 1000),+ rows=st.integers(1, 40).flatmap(lambda n: arrays((n, 3), 10)),+ )+ def extend(self, which: int, rows: np.ndarray) -> None:+ shape, expected = self.made[which % len(self.made)]+ self.made.append((shape.extended(rows), np.concatenate([expected, rows])))++ @invariant()+ def every_shape_keeps_its_points(self) -> None:+ for shape, expected in self.made:+ np.testing.assert_array_equal(shape.array, expected)+++TestGrowingPaths = GrowingPaths.TestCase+TestGrowingPaths.settings = settings(stateful_step_count=30)+++class BlendEdits(RuleBasedStateMachine):+ """A blend under any chain of edits is the plain points under the same edits, and the+ boxes it carries are its points' boxes."""++ @initialize(points=curves())+ def begin(self, points: np.ndarray) -> None:+ self.blend = g.Blend.of(points)+ self.points = points.copy()++ @rule()+ def measure(self) -> None: # boxes cached now are carried through the edits after+ self.blend.box(True)+ self.blend.box(False)++ @rule(vector=arrays(3, 10))+ def translate(self, vector: np.ndarray) -> None:+ self.blend = self.blend.translated(vector)+ self.points = self.points + vector++ @rule(factor=st.floats(-3, 3), about=arrays(3, 10))+ def scale(self, factor: float, about: np.ndarray) -> None:+ self.blend = self.blend.scaled(factor, about)+ self.points = (self.points - about) * factor + about++ @rule(matrix=arrays((3, 4), 3))+ def transform(self, matrix: np.ndarray) -> None:+ self.blend = self.blend.transformed(matrix)+ self.points = self.points @ matrix[:, :3].T + matrix[:, 3]++ @rule(factors=arrays(3, 3), offset=arrays(3, 10))+ def transform_along_the_axes(self, factors: np.ndarray, offset: np.ndarray) -> None:+ matrix = np.hstack([np.diag(factors), offset[:, None]])+ self.blend = self.blend.transformed(matrix)+ self.points = self.points * factors + offset++ @rule(+ other=curves(min_curves=6, max_curves=6),+ alpha=st.floats(0, 1),+ angle=st.floats(0.02, 3),+ axis=vectors(),+ )+ def mix(+ self, other: np.ndarray, alpha: float, angle: float, axis: np.ndarray+ ) -> None:+ other = (+ other[: len(self.points)]+ if len(other) >= len(self.points)+ else np.resize(other, self.points.shape)+ )+ path = g.path_along_arc(angle, axis) if angle > 1.5 else g.straight_path()+ self.blend = g.Blend.mix(+ self.blend, g.Blend.of(other), path.coefficients(alpha)+ )+ self.points = path(self.points, other, alpha)++ @invariant()+ def its_points_are_the_edited_points(self) -> None:+ np.testing.assert_allclose(+ self.blend.points(), self.points, atol=1e-9 * scale_of(self.points)+ )++ @invariant()+ def its_boxes_are_its_points_boxes(self) -> None:+ tolerance = 1e-9 * scale_of(self.points)+ np.testing.assert_allclose(+ self.blend.box(True), oracles.curve_box(self.points), atol=tolerance+ )+ np.testing.assert_allclose(+ self.blend.box(False),+ [self.points.min(0), self.points.max(0)],+ atol=tolerance,+ )+++TestBlendEdits = BlendEdits.TestCase+TestBlendEdits.settings = settings(stateful_step_count=12)+++@given(start=arrays(3), end=arrays(3))+def test_a_segment_is_one_straight_curve_between_its_ends(+ start: np.ndarray, end: np.ndarray+) -> None:+ points = g.segment(start, end).points()+ np.testing.assert_allclose(+ points,+ [start + k / 3 * (end - start) for k in range(4)],+ atol=1e-12 * scale_of(points),+ )+++@given(angle=angles(), about=arrays(3, 10))+def test_linear_about_keeps_its_point(angle: float, about: np.ndarray) -> None:+ turn = np.array(+ [+ [np.cos(angle), -np.sin(angle), 0],+ [np.sin(angle), np.cos(angle), 0],+ [0, 0, 1],+ ]+ )+ m = g.linear_about(turn, about)+ np.testing.assert_allclose(+ m[:, :3] @ about + m[:, 3], about, atol=1e-12 * scale_of(about)+ )+++clouds = st.integers(1, 6).flatmap(+ lambda n: st.tuples(arrays((n, 3), 10), arrays((n, 3), 10))+)+arc_angles = st.floats(g.STRAIGHT_PATH_THRESHOLD, 2 * np.pi - 1e-3).map(+ lambda a: a+) | st.floats(-2 * np.pi + 1e-3, -g.STRAIGHT_PATH_THRESHOLD)+++def every_path(draw: st.DrawFn) -> g.PathFunc:+ kind = draw(st.sampled_from(["straight", "arc", "spiral", "circles", "motion"]))+ if kind == "straight":+ return g.straight_path()+ if kind == "arc":+ return g.path_along_arc(draw(arc_angles), draw(vectors()))+ if kind == "spiral":+ return g.spiral_path(draw(arc_angles), draw(vectors()))+ if kind == "circles":+ return g.path_along_circles(+ draw(angles()), draw(arrays(3, 10)), draw(vectors())+ )+ steps = draw(+ st.lists(+ st.one_of(+ arrays(3, 10),+ st.tuples(angles(), vectors(), arrays(3, 10)),+ ),+ max_size=4,+ )+ )+ return g.Path(steps=tuple(steps))+++@given(path=every_path(), ends=clouds)+def test_every_path_starts_at_the_start_and_ends_at_the_end(+ path: g.PathFunc, ends: tuple[np.ndarray, np.ndarray]+) -> None:+ start, end = ends+ np.testing.assert_allclose(path(start, end, 0.0), start, atol=1e-9)+ np.testing.assert_allclose(path(start, end, 1.0), end, atol=1e-9)+++@given(ends=clouds, alpha=st.floats(0, 1))+def test_the_straight_path_runs_along_the_chord(+ ends: tuple[np.ndarray, np.ndarray], alpha: float+) -> None:+ start, end = ends+ np.testing.assert_allclose(+ g.straight_path()(start, end, alpha),+ start + alpha * (end - start),+ atol=1e-12,+ )+++@given(angle=arc_angles, axis=vectors(), ends=clouds, alpha=st.floats(0, 1))+def test_an_arc_path_turns_each_point_about_its_arcs_center(+ angle: float, axis: np.ndarray, ends: tuple[np.ndarray, np.ndarray], alpha: float+) -> None:+ """Across the axis, each point turns at a steady rate about a center it keeps its+ distance from; along the axis, it moves at a steady rate."""+ start, end = ends+ unit = axis / np.linalg.norm(axis)+ at = g.path_along_arc(angle, axis)(start, end, alpha)+ along = lambda p: p @ unit # noqa: E731+ across = lambda p: p - np.outer(p @ unit, unit) # noqa: E731+ np.testing.assert_allclose(+ along(at), along(start) + alpha * (along(end) - along(start)), atol=1e-9+ )+ s, e, a = across(start), across(end), across(at)+ chord = e - s+ center = (s + e) / 2 + np.cross(unit, chord) / (2 * np.tan(angle / 2))+ np.testing.assert_allclose(+ a - center,+ (s - center) @ g.rotation_matrix(alpha * angle, unit).T,+ atol=1e-7 * (1 + np.abs(center).max()),+ )+++@given(angle=arc_angles, axis=vectors(), ends=clouds, alpha=st.floats(0, 1))+def test_a_spiral_path_is_its_formula(+ angle: float, axis: np.ndarray, ends: tuple[np.ndarray, np.ndarray], alpha: float+) -> None:+ start, end = ends+ turn = g.rotation_matrix((alpha - 1) * angle, axis)+ np.testing.assert_allclose(+ g.spiral_path(angle, axis)(start, end, alpha),+ start + alpha * (end - start) @ turn.T,+ atol=1e-9,+ )+++@given(+ angle=angles(),+ center=arrays(3, 10),+ axis=vectors(),+ shape=arrays((5, 3), 10),+ alpha=st.floats(0, 1),+)+def test_a_path_about_one_center_turns_a_shape_rigidly(+ angle: float, center: np.ndarray, axis: np.ndarray, shape: np.ndarray, alpha: float+) -> None:+ turned = (shape - center) @ g.rotation_matrix(angle, axis).T + center+ at = g.path_along_circles(angle, center, axis)(shape, turned, alpha)+ np.testing.assert_allclose(+ at,+ (shape - center) @ g.rotation_matrix(alpha * angle, axis).T + center,+ atol=1e-9,+ )+++class TestCarried:+ @given(+ steps=st.lists(+ st.one_of(arrays(3, 10), st.tuples(angles(), vectors(), arrays(3, 10))),+ max_size=5,+ ),+ shape=arrays((5, 3), 10),+ alpha=st.floats(-0.25, 1.25),+ )+ def test_mixed_steps_carry_a_shape_rigidly_in_three_dimensions(+ self, steps: list[g.Step], shape: np.ndarray, alpha: float+ ) -> None:+ def curve(t: float) -> np.ndarray:+ return np.array([2 + t, 3 - t * t, -1 + t * t * t])++ steps = [*steps]+ steps.insert(len(steps) // 2, curve)++ def at(t: float) -> np.ndarray:+ # Carry the points and every future pivot themselves, without composing+ # matrices. Each turn fixes the pivot where earlier steps brought it.+ pivots = np.array([s[2] for s in steps if isinstance(s, tuple)])+ points = np.concatenate((shape, pivots.reshape(-1, 3)))+ pivot_index = len(shape)+ for step in steps:+ if isinstance(step, np.ndarray):+ points += t * step+ elif isinstance(step, tuple):+ angle, axis, _ = step+ pivot = points[pivot_index].copy()+ points = (points - pivot) @ g.rotation_matrix(+ t * angle, axis+ ).T + pivot+ pivot_index += 1+ else:+ points += step(t) - step(0)+ return points[: len(shape)]++ expected = at(alpha)+ motion = g.carried((step, alpha) for step in steps)+ np.testing.assert_allclose(+ shape @ motion[:3, :3].T + motion[:3, 3], expected, atol=1e-9+ )+ path = g.Path(steps=tuple(steps))+ actual = path(shape, at(1), alpha)+ np.testing.assert_allclose(actual, expected, atol=1e-9)+ np.testing.assert_allclose(+ np.linalg.norm(actual[:, None] - actual, axis=2),+ np.linalg.norm(shape[:, None] - shape, axis=2),+ atol=1e-9,+ )+++ZERO_AXIS: dict[str, Callable[[float, np.ndarray], object]] = {+ "rotation_matrix": g.rotation_matrix,+ "rotation_matrix_transpose": g.rotation_matrix_transpose,+ "rotate_vector": lambda angle, axis: g.rotate_vector(m.RIGHT, angle, axis),+ "quaternion_from_angle_axis": g.quaternion_from_angle_axis,+ "Mobject.rotate": lambda angle, axis: m.Square().rotate(angle, axis=axis),+ "path_along_arc": g.path_along_arc,+ "spiral_path": g.spiral_path,+ "path_along_circles": lambda angle, axis: g.path_along_circles(+ angle, m.ORIGIN, axis+ ),+}++[email protected]("name", ZERO_AXIS)[email protected]("angle", [1.0, -2.5])+def test_a_turn_needs_an_axis(name: str, angle: float) -> None:+ with pytest.raises(ValueError, match="axis"):+ ZERO_AXIS[name](angle, np.zeros(3))