Cubic Bézier curve interpolation utilities.#

Cubic Bézier curve interpolation utilities.

This module provides a mathematical implementation of a cubic Bézier curve interpolator ported from the Android Material Design animation framework.

The implementation is primarily used for calculating easing functions and animation timing curves. It allows converting an input progress value (X-axis) into the corresponding interpolated output value (Y-axis) based on four Bézier control points.

The module includes:

A compatibility implementation of the cubic root function for Python versions older than 3.11.
Numerical helpers for solving cubic equations.
The CubicBezier class for evaluating cubic Bézier easing curves.

The implementation follows the algorithm used in Android’s Material Design motion system to achieve accurate interpolation behavior.

API - `kivymd.utils.cubic_bezier`#

kivymd.utils.cubic_bezier.float_epsilon = 8.34465e-07#

kivymd.utils.cubic_bezier.cbrt#

class kivymd.utils.cubic_bezier.CubicBezier(*args)#

Ported from Android source code. Represents a cubic Bézier curve interpolator.

A cubic Bézier curve is defined by four control points:

P0 — start point P1 — first control point P2 — second control point P3 — end point

The curve is commonly used in UI animations to define easing behavior. Given an input progress value x in the range [0, 1], the class calculates the corresponding output value y on the curve.

This implementation solves the cubic equation required to find the curve parameter t for a given X value and then evaluates the curve at that parameter to obtain the interpolated Y value.

Attributes:

p0 (float): First control point value. p1 (float): Second control point value. p2 (float): Third control point value. p3 (float): Fourth control point value.

This type of interpolation is commonly used for:

Animation easing functions.
Progress indicators.
UI transitions.
Material Design motion effects.

p0 = 0#

p1 = 0#

p2 = 0#

p3 = 0#

evaluate_cubic(p1, p2, t)#

Evaluates a cubic Bézier polynomial.

Args:: p1 (float): First control point. p2 (float): Second control point. t (float): Curve parameter in the range [0, 1].
Returns:: float: Calculated Bézier curve value.

clamp_range(r)#

Clamps a calculated root value into the valid Bézier range.

Small floating-point calculation errors are corrected using an epsilon tolerance. Values outside the acceptable range are converted to NaN.

Args:: r (float): Calculated root value.
Returns:: float: Corrected value or NaN if invalid.

close_to(x, y)#

Checks whether two floating-point numbers are approximately equal.

Args:: x (float): First value. y (float): Second value.
Returns:: bool: True when the difference is below the precision threshold.

find_first_cubic_root(p0, p1, p2, p3)#

Finds the first valid root of a cubic equation.

The method solves the cubic polynomial generated from the Bézier curve equation and returns a parameter t within the valid interval [0, 1].

The implementation handles:

Linear equations.
Quadratic equations.
Cubic equations with one or multiple roots.
Floating-point precision issues.

Args:

p0 (float): Polynomial coefficient. p1 (float): Polynomial coefficient. p2 (float): Polynomial coefficient. p3 (float): Polynomial coefficient.

Returns:

float:: The first valid root in the range [0, 1], or NaN if no valid root exists.

t(value: float)#

Calculates the interpolated Bézier value for an input progress value.

This method converts an X-axis position into the corresponding Y-axis position on the cubic Bézier curve.