bezier.dart is a simple open-source Dart library for handling 2D Bézier curve math.

The library was developed, documented, and published by Aaron Barrett and Isaac Barrett. It is based heavily on the work of Pomax, including his excellent Primer on Bézier Curves and his original JavaScript library, Bezier.js.

We’re trying to design bezier.dart to be both platform independent and context independent. You can run the library anywhere you can run Dart: in a web browser, in a Flutter application, server side, and beyond.

Download the library from Pub or visit the GitHub project page. Full documentation is available here.

A simple web animation demonstrating several API functions can be seen here. Its source code is included in the example folder of the Pub package.

Working With Bézier Curves

In order to use this library, you’ll need some understanding of the theory behind Bézier curves and the terminology that goes with them. We’ll quickly cover the basics here. For a more complete reference, try Pomax’s Primer.

Bézier curves are a class of parametric curves commonly used in computer graphics. Applications include everything from vector illustrations to animation eases to the characters in the font you’re reading right now.

There are different types of Bézier curve, each based on its own polynomial function. These classifications of curve are known as orders. The most commonly used orders of curve are second order (or quadratic curves) and third order (or cubic curves). Although higher order curves exist, quadratic and cubic curves are the only two orders supported by this library. Bézier curves can also be drawn in three-dimensional space (and higher), but this library only deals with two-dimensional curves.

The shape of a Bézier curve is defined by its end points and control points. Naturally, each curve has two end points. Quadratic curves have a single control point, while cubic curves have two control points. To find the coordinates of points along a Bézier curve, we pass values into the curve’s polynomial function. The parameter values that we pass in, known as t values, range from 0 to 1 (inclusive). For example, to find the point at the parametric middle of a Bézier curve, we would use a t value of 0.5.

API Examples

pointAt

Returns the point along the curve at the parameter value t.

length

The approximate arc length of the curve.

The arc length is computed using a 30th order Legendre polynomial.

extrema, extremaOnX, extremaOnY

extrema returns the parameter values that correspond with extrema on both the x and y axes. To find extrema on a single axis, use extremaOnX or extremaOnY.

derivativeAt

Returns the tangent vector at parameter t.

The return value is not normalized. The optional parameter cachedFirstOrderDerivativePoints allows the method to use previously calculated values for firstOrderDerivativePoints instead of repeating the calculations.

normalAt

The normal vector of the curve at parameter value t.

The return value is normalized. See derivativeAt for information about the optional parameter cachedFirstOrderDerivativePoints.

subcurveBetween, leftSubcurveAt, rightSubcurveAt

subcurveBetween returns the subcurve obtained by taking the portion of the curve between parameter values t1 and t2.

To find the subcurve obtained by taking the portion of the curve to the left or right of a t value, use leftSubcurveAt or rightSubcurveAt.

boundingBox

Returns the axis-aligned bounding box of the curve.

hullPointsAt

Returns the hull points at the parameter value t.

simpleSubcurves, simpleSlices

simpleSlices returns a List of BezierSlice instances containing simple Bezier instances along with their endpoint parameter values from this. In cases where no simple subcurves can be found with the given stepSize, returns an empty List. simpleSubcurves relies on simpleSlices, but it returns only the simple Bezier instances themselves and omits their endpoint parameter values.

Reduction is performed in two passes. The first pass splits the curve at the parameter values of extrema along the x and y axes. The second pass divides any non-simple portions of the curve into simple curves. The optional stepSize parameter determines how much to increment the parameter value at each iteration when searching for non-simple portions of curves. The default stepSize value of 0.01 means that the function will do around one hundred iterations for each segment between the parameter values for extrema. Reducing the value of stepSize will increase the number of iterations.

offsetCurve

Returns a List of Bezier instances that, when taken together, form an approximation of the offset curve distance units away from this.

See simpleSubcurves for information about the optional parameter stepSize.

offsetPointAt

Returns the point distance units away in the clockwise direction from the point along the curve at parameter value t.

See derivativeAt for information about the optional parameter cachedFirstOrderDerivativePoints.

scaledCurve

Returns a Bezier instance whose endpoints are distance units away from the endpoints of this and whose control points have been moved in the same direction.

Results are best on simple curves. Although scaledCurve can be called on non-simple curves, the return value may not resemble a proper offset curve. For better results on non-simple curves, try offsetCurve.

A scaled linear curve is translated by distance units along its start point normal vector.

intersectionsWithSelf

Returns the List of intersections between this and itself. Since it is impossible for a quadratic curve to intersect with itself, this method applies only to cubic curves.

See intersectionsWithCurve for information about the optional parameters.

 cubic

intersectionsWithLineSegment

Returns the List of parameter values for intersections between this and the line segment defined by lineStartPoint and lineEndPoint.

intersectionsWithCurve

Returns the List of intersections between this and curve.

The optional parameter curveIntersectionThreshold determines how small to divide the bounding boxes of overlapping segments in the search for intersection points. This value is in the coordinate space of the curve. The optional parameter minTValueDifference specifies how far away intersection results must be from each other in terms of curve parameter values to be considered separate intersections.

With the optional parameters at their default values, this method may return more than the expected number of intersections for curves that cross at a shallow angle or pass extremely close to each other. Decreasing curveIntersectionThreshold or increasing minTValueDifference may reduce the number of intersections returned in such cases.

positionLookUpTable

Returns a List of Vector2 positions at evenly spaced parameter values from 0.0 to 1.0.

The intervalsCount parameter is used to calculate the size of the interval. The returned List will contain intervalsCount + 1 entries.

Note that although the returned positions will be parametrically equidistant, the arc length between them may vary significantly. To obtain more evenly distributed positions along the arc, use the EvenSpacer class.

EvenSpacer, evenTValues

The EvenSpacer class allows you to calculate parameter values of points in a Bezier evenly spaced along its arc length. evenTValues returns a List of evenly distributed parameter values.

The optional parameter parametersCount is used to calculate the arc length fraction. The returned value will have parametersCount + 1 entries.