Source code for manim.utils.bezier

"""Utility functions related to Bézier curves."""

from __future__ import annotations

from manim.typing import (
    BezierPoints,
    ColVector,
    MatrixMN,
    Point3D,
    Point3D_Array,
    PointDType,
    QuadraticBezierPoints,
    QuadraticBezierPoints_Array,
)

__all__ = [
    "bezier",
    "partial_bezier_points",
    "partial_quadratic_bezier_points",
    "interpolate",
    "integer_interpolate",
    "mid",
    "inverse_interpolate",
    "match_interpolate",
    "get_smooth_handle_points",
    "get_smooth_cubic_bezier_handle_points",
    "diag_to_matrix",
    "is_closed",
    "proportions_along_bezier_curve_for_point",
    "point_lies_on_bezier",
]


from functools import reduce
from typing import Any, Callable, Sequence, overload

import numpy as np
import numpy.typing as npt
from scipy import linalg

from ..utils.simple_functions import choose
from ..utils.space_ops import cross2d, find_intersection


[docs]def bezier( points: Sequence[Point3D] | Point3D_Array, ) -> Callable[[float], Point3D]: """Classic implementation of a bezier curve. Parameters ---------- points points defining the desired bezier curve. Returns ------- function describing the bezier curve. You can pass a t value between 0 and 1 to get the corresponding point on the curve. """ n = len(points) - 1 # Cubic Bezier curve if n == 3: return lambda t: np.asarray( (1 - t) ** 3 * points[0] + 3 * t * (1 - t) ** 2 * points[1] + 3 * (1 - t) * t**2 * points[2] + t**3 * points[3], dtype=PointDType, ) # Quadratic Bezier curve if n == 2: return lambda t: np.asarray( (1 - t) ** 2 * points[0] + 2 * t * (1 - t) * points[1] + t**2 * points[2], dtype=PointDType, ) return lambda t: np.asarray( np.asarray( [ (((1 - t) ** (n - k)) * (t**k) * choose(n, k) * point) for k, point in enumerate(points) ], dtype=PointDType, ).sum(axis=0) )
# !TODO: This function has still a weird implementation with the overlapping points
[docs]def partial_bezier_points(points: BezierPoints, a: float, b: float) -> BezierPoints: """Given an array of points which define bezier curve, and two numbers 0<=a<b<=1, return an array of the same size, which describes the portion of the original bezier curve on the interval [a, b]. This algorithm is pretty nifty, and pretty dense. Parameters ---------- points set of points defining the bezier curve. a lower bound of the desired partial bezier curve. b upper bound of the desired partial bezier curve. Returns ------- np.ndarray Set of points defining the partial bezier curve. """ _len = len(points) if a == 1: return np.asarray([points[-1]] * _len, dtype=PointDType) a_to_1 = np.asarray( [bezier(points[i:])(a) for i in range(_len)], dtype=PointDType, ) end_prop = (b - a) / (1.0 - a) return np.asarray( [bezier(a_to_1[: i + 1])(end_prop) for i in range(_len)], dtype=PointDType, )
# Shortened version of partial_bezier_points just for quadratics, # since this is called a fair amount
[docs]def partial_quadratic_bezier_points( points: QuadraticBezierPoints, a: float, b: float ) -> QuadraticBezierPoints: if a == 1: return np.asarray(3 * [points[-1]]) def curve(t: float) -> Point3D: return np.asarray( points[0] * (1 - t) * (1 - t) + 2 * points[1] * t * (1 - t) + points[2] * t * t ) # bezier(points) h0 = curve(a) if a > 0 else points[0] h2 = curve(b) if b < 1 else points[2] h1_prime = (1 - a) * points[1] + a * points[2] end_prop = (b - a) / (1.0 - a) h1 = (1 - end_prop) * h0 + end_prop * h1_prime return np.asarray((h0, h1, h2))
[docs]def split_quadratic_bezier(points: QuadraticBezierPoints, t: float) -> BezierPoints: """Split a quadratic Bézier curve at argument ``t`` into two quadratic curves. Parameters ---------- points The control points of the bezier curve has shape ``[a1, h1, b1]`` t The ``t``-value at which to split the Bézier curve Returns ------- The two Bézier curves as a list of tuples, has the shape ``[a1, h1, b1], [a2, h2, b2]`` """ a1, h1, a2 = points s1 = interpolate(a1, h1, t) s2 = interpolate(h1, a2, t) p = interpolate(s1, s2, t) return np.array((a1, s1, p, p, s2, a2))
[docs]def subdivide_quadratic_bezier(points: QuadraticBezierPoints, n: int) -> BezierPoints: """Subdivide a quadratic Bézier curve into ``n`` subcurves which have the same shape. The points at which the curve is split are located at the arguments :math:`t = i/n` for :math:`i = 1, ..., n-1`. Parameters ---------- points The control points of the Bézier curve in form ``[a1, h1, b1]`` n The number of curves to subdivide the Bézier curve into Returns ------- The new points for the Bézier curve in the form ``[a1, h1, b1, a2, h2, b2, ...]`` .. image:: /_static/bezier_subdivision_example.png """ beziers = np.empty((n, 3, 3)) current = points for j in range(0, n): i = n - j tmp = split_quadratic_bezier(current, 1 / i) beziers[j] = tmp[:3] current = tmp[3:] return beziers.reshape(-1, 3)
[docs]def quadratic_bezier_remap( triplets: QuadraticBezierPoints_Array, new_number_of_curves: int ) -> QuadraticBezierPoints_Array: """Remaps the number of curves to a higher amount by splitting bezier curves Parameters ---------- triplets The triplets of the quadratic bezier curves to be remapped shape(n, 3, 3) new_number_of_curves The number of curves that the output will contain. This needs to be higher than the current number. Returns ------- The new triplets for the quadratic bezier curves. """ difference = new_number_of_curves - len(triplets) if difference <= 0: return triplets new_triplets = np.zeros((new_number_of_curves, 3, 3)) idx = 0 for triplet in triplets: if difference > 0: tmp_noc = int(np.ceil(difference / len(triplets))) + 1 tmp = subdivide_quadratic_bezier(triplet, tmp_noc).reshape(-1, 3, 3) for i in range(tmp_noc): new_triplets[idx + i] = tmp[i] difference -= tmp_noc - 1 idx += tmp_noc else: new_triplets[idx] = triplet idx += 1 return new_triplets """ This is an alternate version of the function just for documentation purposes -------- difference = new_number_of_curves - len(triplets) if difference <= 0: return triplets new_triplets = [] for triplet in triplets: if difference > 0: tmp_noc = int(np.ceil(difference / len(triplets))) + 1 tmp = subdivide_quadratic_bezier(triplet, tmp_noc).reshape(-1, 3, 3) for i in range(tmp_noc): new_triplets.append(tmp[i]) difference -= tmp_noc - 1 else: new_triplets.append(triplet) return new_triplets """
# Linear interpolation variants @overload def interpolate(start: float, end: float, alpha: float) -> float: ... @overload def interpolate(start: Point3D, end: Point3D, alpha: float) -> Point3D: ...
[docs]def interpolate( start: int | float | Point3D, end: int | float | Point3D, alpha: float | Point3D ) -> float | Point3D: return (1 - alpha) * start + alpha * end
[docs]def integer_interpolate( start: float, end: float, alpha: float, ) -> tuple[int, float]: """ This is a variant of interpolate that returns an integer and the residual Parameters ---------- start The start of the range end The end of the range alpha a float between 0 and 1. Returns ------- tuple[int, float] This returns an integer between start and end (inclusive) representing appropriate interpolation between them, along with a "residue" representing a new proportion between the returned integer and the next one of the list. Example ------- .. code-block:: pycon >>> integer, residue = integer_interpolate(start=0, end=10, alpha=0.46) >>> np.allclose((integer, residue), (4, 0.6)) True """ if alpha >= 1: return (int(end - 1), 1.0) if alpha <= 0: return (int(start), 0) value = int(interpolate(start, end, alpha)) residue = ((end - start) * alpha) % 1 return (value, residue)
@overload def mid(start: float, end: float) -> float: ... @overload def mid(start: Point3D, end: Point3D) -> Point3D: ...
[docs]def mid(start: float | Point3D, end: float | Point3D) -> float | Point3D: """Returns the midpoint between two values. Parameters ---------- start The first value end The second value Returns ------- The midpoint between the two values """ return (start + end) / 2.0
@overload def inverse_interpolate(start: float, end: float, value: float) -> float: ... @overload def inverse_interpolate(start: float, end: float, value: Point3D) -> Point3D: ... @overload def inverse_interpolate(start: Point3D, end: Point3D, value: Point3D) -> Point3D: ...
[docs]def inverse_interpolate( start: float | Point3D, end: float | Point3D, value: float | Point3D ) -> float | Point3D: """Perform inverse interpolation to determine the alpha values that would produce the specified ``value`` given the ``start`` and ``end`` values or points. Parameters ---------- start The start value or point of the interpolation. end The end value or point of the interpolation. value The value or point for which the alpha value should be determined. Returns ------- The alpha values producing the given input when interpolating between ``start`` and ``end``. Example ------- .. code-block:: pycon >>> inverse_interpolate(start=2, end=6, value=4) 0.5 >>> start = np.array([1, 2, 1]) >>> end = np.array([7, 8, 11]) >>> value = np.array([4, 5, 5]) >>> inverse_interpolate(start, end, value) array([0.5, 0.5, 0.4]) """ return np.true_divide(value - start, end - start)
@overload def match_interpolate( new_start: float, new_end: float, old_start: float, old_end: float, old_value: float, ) -> float: ... @overload def match_interpolate( new_start: float, new_end: float, old_start: float, old_end: float, old_value: Point3D, ) -> Point3D: ...
[docs]def match_interpolate( new_start: float, new_end: float, old_start: float, old_end: float, old_value: float | Point3D, ) -> float | Point3D: """Interpolate a value from an old range to a new range. Parameters ---------- new_start The start of the new range. new_end The end of the new range. old_start The start of the old range. old_end The end of the old range. old_value The value within the old range whose corresponding value in the new range (with the same alpha value) is desired. Returns ------- The interpolated value within the new range. Examples -------- >>> match_interpolate(0, 100, 10, 20, 15) 50.0 """ old_alpha = inverse_interpolate(old_start, old_end, old_value) return interpolate( new_start, new_end, old_alpha, # type: ignore )
[docs]def get_smooth_cubic_bezier_handle_points( points: Point3D_Array, ) -> tuple[BezierPoints, BezierPoints]: points = np.asarray(points) num_handles = len(points) - 1 dim = points.shape[1] if num_handles < 1: return np.zeros((0, dim)), np.zeros((0, dim)) # Must solve 2*num_handles equations to get the handles. # l and u are the number of lower an upper diagonal rows # in the matrix to solve. l, u = 2, 1 # diag is a representation of the matrix in diagonal form # See https://www.particleincell.com/2012/bezier-splines/ # for how to arrive at these equations diag: MatrixMN = np.zeros((l + u + 1, 2 * num_handles)) diag[0, 1::2] = -1 diag[0, 2::2] = 1 diag[1, 0::2] = 2 diag[1, 1::2] = 1 diag[2, 1:-2:2] = -2 diag[3, 0:-3:2] = 1 # last diag[2, -2] = -1 diag[1, -1] = 2 # This is the b as in Ax = b, where we are solving for x, # and A is represented using diag. However, think of entries # to x and b as being points in space, not numbers b: Point3D_Array = np.zeros((2 * num_handles, dim)) b[1::2] = 2 * points[1:] b[0] = points[0] b[-1] = points[-1] def solve_func(b: ColVector) -> ColVector | MatrixMN: return linalg.solve_banded((l, u), diag, b) # type: ignore use_closed_solve_function = is_closed(points) if use_closed_solve_function: # Get equations to relate first and last points matrix = diag_to_matrix((l, u), diag) # last row handles second derivative matrix[-1, [0, 1, -2, -1]] = [2, -1, 1, -2] # first row handles first derivative matrix[0, :] = np.zeros(matrix.shape[1]) matrix[0, [0, -1]] = [1, 1] b[0] = 2 * points[0] b[-1] = np.zeros(dim) def closed_curve_solve_func(b: ColVector) -> ColVector | MatrixMN: return linalg.solve(matrix, b) # type: ignore handle_pairs = np.zeros((2 * num_handles, dim)) for i in range(dim): if use_closed_solve_function: handle_pairs[:, i] = closed_curve_solve_func(b[:, i]) else: handle_pairs[:, i] = solve_func(b[:, i]) return handle_pairs[0::2], handle_pairs[1::2]
[docs]def get_smooth_handle_points( points: BezierPoints, ) -> tuple[BezierPoints, BezierPoints]: """Given some anchors (points), compute handles so the resulting bezier curve is smooth. Parameters ---------- points Anchors. Returns ------- typing.Tuple[np.ndarray, np.ndarray] Computed handles. """ # NOTE points here are anchors. points = np.asarray(points) num_handles = len(points) - 1 dim = points.shape[1] if num_handles < 1: return np.zeros((0, dim)), np.zeros((0, dim)) # Must solve 2*num_handles equations to get the handles. # l and u are the number of lower an upper diagonal rows # in the matrix to solve. l, u = 2, 1 # diag is a representation of the matrix in diagonal form # See https://www.particleincell.com/2012/bezier-splines/ # for how to arrive at these equations diag: MatrixMN = np.zeros((l + u + 1, 2 * num_handles)) diag[0, 1::2] = -1 diag[0, 2::2] = 1 diag[1, 0::2] = 2 diag[1, 1::2] = 1 diag[2, 1:-2:2] = -2 diag[3, 0:-3:2] = 1 # last diag[2, -2] = -1 diag[1, -1] = 2 # This is the b as in Ax = b, where we are solving for x, # and A is represented using diag. However, think of entries # to x and b as being points in space, not numbers b = np.zeros((2 * num_handles, dim)) b[1::2] = 2 * points[1:] b[0] = points[0] b[-1] = points[-1] def solve_func(b: ColVector) -> ColVector | MatrixMN: return linalg.solve_banded((l, u), diag, b) # type: ignore use_closed_solve_function = is_closed(points) if use_closed_solve_function: # Get equations to relate first and last points matrix = diag_to_matrix((l, u), diag) # last row handles second derivative matrix[-1, [0, 1, -2, -1]] = [2, -1, 1, -2] # first row handles first derivative matrix[0, :] = np.zeros(matrix.shape[1]) matrix[0, [0, -1]] = [1, 1] b[0] = 2 * points[0] b[-1] = np.zeros(dim) def closed_curve_solve_func(b: ColVector) -> ColVector | MatrixMN: return linalg.solve(matrix, b) # type: ignore handle_pairs = np.zeros((2 * num_handles, dim)) for i in range(dim): if use_closed_solve_function: handle_pairs[:, i] = closed_curve_solve_func(b[:, i]) else: handle_pairs[:, i] = solve_func(b[:, i]) return handle_pairs[0::2], handle_pairs[1::2]
[docs]def diag_to_matrix( l_and_u: tuple[int, int], diag: npt.NDArray[Any] ) -> npt.NDArray[Any]: """ Converts array whose rows represent diagonal entries of a matrix into the matrix itself. See scipy.linalg.solve_banded """ l, u = l_and_u dim = diag.shape[1] matrix = np.zeros((dim, dim)) for i in range(l + u + 1): np.fill_diagonal( matrix[max(0, i - u) :, max(0, u - i) :], diag[i, max(0, u - i) :], ) return matrix
# Given 4 control points for a cubic bezier curve (or arrays of such) # return control points for 2 quadratics (or 2n quadratics) approximating them.
[docs]def get_quadratic_approximation_of_cubic( a0: Point3D, h0: Point3D, h1: Point3D, a1: Point3D ) -> BezierPoints: a0 = np.array(a0, ndmin=2) h0 = np.array(h0, ndmin=2) h1 = np.array(h1, ndmin=2) a1 = np.array(a1, ndmin=2) # Tangent vectors at the start and end. T0 = h0 - a0 T1 = a1 - h1 # Search for inflection points. If none are found, use the # midpoint as a cut point. # Based on http://www.caffeineowl.com/graphics/2d/vectorial/cubic-inflexion.html has_infl = np.ones(len(a0), dtype=bool) p = h0 - a0 q = h1 - 2 * h0 + a0 r = a1 - 3 * h1 + 3 * h0 - a0 a = cross2d(q, r) b = cross2d(p, r) c = cross2d(p, q) disc = b * b - 4 * a * c has_infl &= disc > 0 sqrt_disc = np.sqrt(np.abs(disc)) settings = np.seterr(all="ignore") ti_bounds = [] for sgn in [-1, +1]: ti = (-b + sgn * sqrt_disc) / (2 * a) ti[a == 0] = (-c / b)[a == 0] ti[(a == 0) & (b == 0)] = 0 ti_bounds.append(ti) ti_min, ti_max = ti_bounds np.seterr(**settings) ti_min_in_range = has_infl & (0 < ti_min) & (ti_min < 1) ti_max_in_range = has_infl & (0 < ti_max) & (ti_max < 1) # Choose a value of t which starts at 0.5, # but is updated to one of the inflection points # if they lie between 0 and 1 t_mid = 0.5 * np.ones(len(a0)) t_mid[ti_min_in_range] = ti_min[ti_min_in_range] t_mid[ti_max_in_range] = ti_max[ti_max_in_range] m, n = a0.shape t_mid = t_mid.repeat(n).reshape((m, n)) # Compute bezier point and tangent at the chosen value of t (these are vectorized) mid = bezier([a0, h0, h1, a1])(t_mid) # type: ignore Tm = bezier([h0 - a0, h1 - h0, a1 - h1])(t_mid) # type: ignore # Intersection between tangent lines at end points # and tangent in the middle i0 = find_intersection(a0, T0, mid, Tm) i1 = find_intersection(a1, T1, mid, Tm) m, n = np.shape(a0) result = np.zeros((6 * m, n)) result[0::6] = a0 result[1::6] = i0 result[2::6] = mid result[3::6] = mid result[4::6] = i1 result[5::6] = a1 return result
[docs]def is_closed(points: Point3D_Array) -> bool: return np.allclose(points[0], points[-1]) # type: ignore
[docs]def proportions_along_bezier_curve_for_point( point: Point3D, control_points: BezierPoints, round_to: float = 1e-6, ) -> npt.NDArray[Any]: """Obtains the proportion along the bezier curve corresponding to a given point given the bezier curve's control points. The bezier polynomial is constructed using the coordinates of the given point as well as the bezier curve's control points. On solving the polynomial for each dimension, if there are roots common to every dimension, those roots give the proportion along the curve the point is at. If there are no real roots, the point does not lie on the curve. Parameters ---------- point The Cartesian Coordinates of the point whose parameter should be obtained. control_points The Cartesian Coordinates of the ordered control points of the bezier curve on which the point may or may not lie. round_to A float whose number of decimal places all values such as coordinates of points will be rounded. Returns ------- np.ndarray[float] List containing possible parameters (the proportions along the bezier curve) for the given point on the given bezier curve. This usually only contains one or zero elements, but if the point is, say, at the beginning/end of a closed loop, may return a list with more than 1 value, corresponding to the beginning and end etc. of the loop. Raises ------ :class:`ValueError` When ``point`` and the control points have different shapes. """ # Method taken from # http://polymathprogrammer.com/2012/04/03/does-point-lie-on-bezier-curve/ if not all(np.shape(point) == np.shape(c_p) for c_p in control_points): raise ValueError( f"Point {point} and Control Points {control_points} have different shapes.", ) control_points = np.array(control_points) n = len(control_points) - 1 roots = [] for dim, coord in enumerate(point): control_coords = control_points[:, dim] terms = [] for term_power in range(n, -1, -1): outercoeff = choose(n, term_power) term = [] sign = 1 for subterm_num in range(term_power, -1, -1): innercoeff = choose(term_power, subterm_num) * sign subterm = innercoeff * control_coords[subterm_num] if term_power == 0: subterm -= coord term.append(subterm) sign *= -1 terms.append(outercoeff * sum(np.array(term))) if all(term == 0 for term in terms): # Then both Bezier curve and Point lie on the same plane. # Roots will be none, but in this specific instance, we don't need to consider that. continue bezier_polynom = np.polynomial.Polynomial(terms[::-1]) polynom_roots = bezier_polynom.roots() # type: ignore if len(polynom_roots) > 0: polynom_roots = np.around(polynom_roots, int(np.log10(1 / round_to))) roots.append(polynom_roots) roots = [[root for root in rootlist if root.imag == 0] for rootlist in roots] # Get common roots # arg-type: ignore roots = reduce(np.intersect1d, roots) # type: ignore result = np.asarray([r.real for r in roots if 0 <= r.real <= 1]) return result
[docs]def point_lies_on_bezier( point: Point3D, control_points: BezierPoints, round_to: float = 1e-6, ) -> bool: """Checks if a given point lies on the bezier curves with the given control points. This is done by solving the bezier polynomial with the point as the constant term; if any real roots exist, the point lies on the bezier curve. Parameters ---------- point The Cartesian Coordinates of the point to check. control_points The Cartesian Coordinates of the ordered control points of the bezier curve on which the point may or may not lie. round_to A float whose number of decimal places all values such as coordinates of points will be rounded. Returns ------- bool Whether the point lies on the curve. """ roots = proportions_along_bezier_curve_for_point(point, control_points, round_to) return len(roots) > 0