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.

Returns the parameter value along the curve that is closest (in terms of geometric distance) to the given `point`. The approximation uses a two-pass projection test that relies on the curve’s position look up table. First, the method determines the point in the look up table that is closest to `point`. Afterward, it checks the fine interval around that point to see if a better projection can be found.
The optional parameter `cachedPositionLookUpTable` allows the method to use previously calculated values for `positionLookUpTable` instead of repeating the calculations. The optional `stepSize` parameter determines how much to increment the parameter value at each iteration when searching the fine interval for the best projection. The default `stepSize` value of 0.1 means that the function will do around twenty iterations. Reducing the value of `stepSize` will increase the number of iterations.