@joint/core/src/g/curve.mjs

JavaScript diagramming library

import { Point } from './point.mjs';
import { Rect } from './rect.mjs';
import { Line } from './line.mjs';
import { Polyline } from './polyline.mjs';
import { types } from './types.mjs';

const {
    abs,
    sqrt,
    min,
    max,
    pow
} = Math;

export const Curve = function(p1, p2, p3, p4) {

    if (!(this instanceof Curve)) {
        return new Curve(p1, p2, p3, p4);
    }

    if (p1 instanceof Curve) {
        return new Curve(p1.start, p1.controlPoint1, p1.controlPoint2, p1.end);
    }

    this.start = new Point(p1);
    this.controlPoint1 = new Point(p2);
    this.controlPoint2 = new Point(p3);
    this.end = new Point(p4);
};

// Curve passing through points.
// Ported from C# implementation by Oleg V. Polikarpotchkin and Peter Lee (http://www.codeproject.com/KB/graphics/BezierSpline.aspx).
// @param {array} points Array of points through which the smooth line will go.
// @return {array} curves.
Curve.throughPoints = (function() {

    // Get open-ended Bezier Spline Control Points.
    // @param knots Input Knot Bezier spline points (At least two points!).
    // @param firstControlPoints Output First Control points. Array of knots.length - 1 length.
    // @param secondControlPoints Output Second Control points. Array of knots.length - 1 length.
    function getCurveControlPoints(knots) {

        var firstControlPoints = [];
        var secondControlPoints = [];
        var n = knots.length - 1;
        var i;

        // Special case: Bezier curve should be a straight line.
        if (n == 1) {
            // 3P1 = 2P0 + P3
            firstControlPoints[0] = new Point(
                (2 * knots[0].x + knots[1].x) / 3,
                (2 * knots[0].y + knots[1].y) / 3
            );

            // P2 = 2P1 – P0
            secondControlPoints[0] = new Point(
                2 * firstControlPoints[0].x - knots[0].x,
                2 * firstControlPoints[0].y - knots[0].y
            );

            return [firstControlPoints, secondControlPoints];
        }

        // Calculate first Bezier control points.
        // Right hand side vector.
        var rhs = [];

        // Set right hand side X values.
        for (i = 1; i < n - 1; i++) {
            rhs[i] = 4 * knots[i].x + 2 * knots[i + 1].x;
        }

        rhs[0] = knots[0].x + 2 * knots[1].x;
        rhs[n - 1] = (8 * knots[n - 1].x + knots[n].x) / 2.0;

        // Get first control points X-values.
        var x = getFirstControlPoints(rhs);

        // Set right hand side Y values.
        for (i = 1; i < n - 1; ++i) {
            rhs[i] = 4 * knots[i].y + 2 * knots[i + 1].y;
        }

        rhs[0] = knots[0].y + 2 * knots[1].y;
        rhs[n - 1] = (8 * knots[n - 1].y + knots[n].y) / 2.0;

        // Get first control points Y-values.
        var y = getFirstControlPoints(rhs);

        // Fill output arrays.
        for (i = 0; i < n; i++) {
            // First control point.
            firstControlPoints.push(new Point(x[i], y[i]));

            // Second control point.
            if (i < n - 1) {
                secondControlPoints.push(new Point(
                    2 * knots [i + 1].x - x[i + 1],
                    2 * knots[i + 1].y - y[i + 1]
                ));

            } else {
                secondControlPoints.push(new Point(
                    (knots[n].x + x[n - 1]) / 2,
                    (knots[n].y + y[n - 1]) / 2
                ));
            }
        }

        return [firstControlPoints, secondControlPoints];
    }

    // Solves a tridiagonal system for one of coordinates (x or y) of first Bezier control points.
    // @param rhs Right hand side vector.
    // @return Solution vector.
    function getFirstControlPoints(rhs) {

        var n = rhs.length;
        // `x` is a solution vector.
        var x = [];
        var tmp = [];
        var b = 2.0;

        x[0] = rhs[0] / b;

        // Decomposition and forward substitution.
        for (var i = 1; i < n; i++) {
            tmp[i] = 1 / b;
            b = (i < n - 1 ? 4.0 : 3.5) - tmp[i];
            x[i] = (rhs[i] - x[i - 1]) / b;
        }

        for (i = 1; i < n; i++) {
            // Backsubstitution.
            x[n - i - 1] -= tmp[n - i] * x[n - i];
        }

        return x;
    }

    return function(points) {

        if (!points || (Array.isArray(points) && points.length < 2)) {
            throw new Error('At least 2 points are required');
        }

        var controlPoints = getCurveControlPoints(points);

        var curves = [];
        var n = controlPoints[0].length;
        for (var i = 0; i < n; i++) {

            var controlPoint1 = new Point(controlPoints[0][i].x, controlPoints[0][i].y);
            var controlPoint2 = new Point(controlPoints[1][i].x, controlPoints[1][i].y);

            curves.push(new Curve(points[i], controlPoint1, controlPoint2, points[i + 1]));
        }

        return curves;
    };
})();

Curve.prototype = {

    type: types.Curve,

    // Returns a bbox that tightly envelops the curve.
    bbox: function() {

        var start = this.start;
        var controlPoint1 = this.controlPoint1;
        var controlPoint2 = this.controlPoint2;
        var end = this.end;

        var x0 = start.x;
        var y0 = start.y;
        var x1 = controlPoint1.x;
        var y1 = controlPoint1.y;
        var x2 = controlPoint2.x;
        var y2 = controlPoint2.y;
        var x3 = end.x;
        var y3 = end.y;

        var points = new Array(); // local extremes
        var tvalues = new Array(); // t values of local extremes
        var bounds = [new Array(), new Array()];

        var a, b, c, t;
        var t1, t2;
        var b2ac, sqrtb2ac;

        for (var i = 0; i < 2; ++i) {

            if (i === 0) {
                b = 6 * x0 - 12 * x1 + 6 * x2;
                a = -3 * x0 + 9 * x1 - 9 * x2 + 3 * x3;
                c = 3 * x1 - 3 * x0;

            } else {
                b = 6 * y0 - 12 * y1 + 6 * y2;
                a = -3 * y0 + 9 * y1 - 9 * y2 + 3 * y3;
                c = 3 * y1 - 3 * y0;
            }

            if (abs(a) < 1e-12) { // Numerical robustness
                if (abs(b) < 1e-12) { // Numerical robustness
                    continue;
                }

                t = -c / b;
                if ((0 < t) && (t < 1)) tvalues.push(t);

                continue;
            }

            b2ac = b * b - 4 * c * a;
            sqrtb2ac = sqrt(b2ac);

            if (b2ac < 0) continue;

            t1 = (-b + sqrtb2ac) / (2 * a);
            if ((0 < t1) && (t1 < 1)) tvalues.push(t1);

            t2 = (-b - sqrtb2ac) / (2 * a);
            if ((0 < t2) && (t2 < 1)) tvalues.push(t2);
        }

        var j = tvalues.length;
        var jlen = j;
        var mt;
        var x, y;

        while (j--) {
            t = tvalues[j];
            mt = 1 - t;

            x = (mt * mt * mt * x0) + (3 * mt * mt * t * x1) + (3 * mt * t * t * x2) + (t * t * t * x3);
            bounds[0][j] = x;

            y = (mt * mt * mt * y0) + (3 * mt * mt * t * y1) + (3 * mt * t * t * y2) + (t * t * t * y3);
            bounds[1][j] = y;

            points[j] = { X: x, Y: y };
        }

        tvalues[jlen] = 0;
        tvalues[jlen + 1] = 1;

        points[jlen] = { X: x0, Y: y0 };
        points[jlen + 1] = { X: x3, Y: y3 };

        bounds[0][jlen] = x0;
        bounds[1][jlen] = y0;

        bounds[0][jlen + 1] = x3;
        bounds[1][jlen + 1] = y3;

        tvalues.length = jlen + 2;
        bounds[0].length = jlen + 2;
        bounds[1].length = jlen + 2;
        points.length = jlen + 2;

        var left = min.apply(null, bounds[0]);
        var top = min.apply(null, bounds[1]);
        var right = max.apply(null, bounds[0]);
        var bottom = max.apply(null, bounds[1]);

        return new Rect(left, top, (right - left), (bottom - top));
    },

    clone: function() {

        return new Curve(this.start, this.controlPoint1, this.controlPoint2, this.end);
    },

    // Returns the point on the curve closest to point `p`
    closestPoint: function(p, opt) {

        return this.pointAtT(this.closestPointT(p, opt));
    },

    closestPointLength: function(p, opt) {

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision;
        var subdivisions = (opt.subdivisions === undefined) ? this.getSubdivisions({ precision: precision }) : opt.subdivisions;
        var localOpt = { precision: precision, subdivisions: subdivisions };

        return this.lengthAtT(this.closestPointT(p, localOpt), localOpt);
    },

    closestPointNormalizedLength: function(p, opt) {

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision;
        var subdivisions = (opt.subdivisions === undefined) ? this.getSubdivisions({ precision: precision }) : opt.subdivisions;
        var localOpt = { precision: precision, subdivisions: subdivisions };

        var cpLength = this.closestPointLength(p, localOpt);
        if (!cpLength) return 0;

        var length = this.length(localOpt);
        if (length === 0) return 0;

        return cpLength / length;
    },

    // Returns `t` of the point on the curve closest to point `p`
    closestPointT: function(p, opt) {

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision;
        var subdivisions = (opt.subdivisions === undefined) ? this.getSubdivisions({ precision: precision }) : opt.subdivisions;
        // does not use localOpt

        // identify the subdivision that contains the point:
        var investigatedSubdivision;
        var investigatedSubdivisionStartT; // assume that subdivisions are evenly spaced
        var investigatedSubdivisionEndT;
        var distFromStart; // distance of point from start of baseline
        var distFromEnd; // distance of point from end of baseline
        var chordLength; // distance between start and end of the subdivision
        var minSumDist; // lowest observed sum of the two distances
        var n = subdivisions.length;
        var subdivisionSize = (n ? (1 / n) : 0);
        for (var i = 0; i < n; i++) {

            var currentSubdivision = subdivisions[i];

            var startDist = currentSubdivision.start.distance(p);
            var endDist = currentSubdivision.end.distance(p);
            var sumDist = startDist + endDist;

            // check that the point is closest to current subdivision and not any other
            if (!minSumDist || (sumDist < minSumDist)) {
                investigatedSubdivision = currentSubdivision;

                investigatedSubdivisionStartT = i * subdivisionSize;
                investigatedSubdivisionEndT = (i + 1) * subdivisionSize;

                distFromStart = startDist;
                distFromEnd = endDist;

                chordLength = currentSubdivision.start.distance(currentSubdivision.end);

                minSumDist = sumDist;
            }
        }

        var precisionRatio = pow(10, -precision);

        // recursively divide investigated subdivision:
        // until distance between baselinePoint and closest path endpoint is within 10^(-precision)
        // then return the closest endpoint of that final subdivision
        while (true) {

            // check if we have reached at least one required observed precision
            // - calculated as: the difference in distances from point to start and end divided by the distance
            // - note that this function is not monotonic = it doesn't converge stably but has "teeth"
            // - the function decreases while one of the endpoints is fixed but "jumps" whenever we switch
            // - this criterion works well for points lying far away from the curve
            var startPrecisionRatio = (distFromStart ? (abs(distFromStart - distFromEnd) / distFromStart) : 0);
            var endPrecisionRatio = (distFromEnd ? (abs(distFromStart - distFromEnd) / distFromEnd) : 0);
            var hasRequiredPrecision = ((startPrecisionRatio < precisionRatio) || (endPrecisionRatio < precisionRatio));

            // check if we have reached at least one required minimal distance
            // - calculated as: the subdivision chord length multiplied by precisionRatio
            // - calculation is relative so it will work for arbitrarily large/small curves and their subdivisions
            // - this is a backup criterion that works well for points lying "almost at" the curve
            var hasMinimalStartDistance = (distFromStart ? (distFromStart < (chordLength * precisionRatio)) : true);
            var hasMinimalEndDistance = (distFromEnd ? (distFromEnd < (chordLength * precisionRatio)) : true);
            var hasMinimalDistance = (hasMinimalStartDistance || hasMinimalEndDistance);

            // do we stop now?
            if (hasRequiredPrecision || hasMinimalDistance) {
                return ((distFromStart <= distFromEnd) ? investigatedSubdivisionStartT : investigatedSubdivisionEndT);
            }

            // otherwise, set up for next iteration
            var divided = investigatedSubdivision.divide(0.5);
            subdivisionSize /= 2;

            var startDist1 = divided[0].start.distance(p);
            var endDist1 = divided[0].end.distance(p);
            var sumDist1 = startDist1 + endDist1;

            var startDist2 = divided[1].start.distance(p);
            var endDist2 = divided[1].end.distance(p);
            var sumDist2 = startDist2 + endDist2;

            if (sumDist1 <= sumDist2) {
                investigatedSubdivision = divided[0];

                investigatedSubdivisionEndT -= subdivisionSize; // subdivisionSize was already halved

                distFromStart = startDist1;
                distFromEnd = endDist1;

            } else {
                investigatedSubdivision = divided[1];

                investigatedSubdivisionStartT += subdivisionSize; // subdivisionSize was already halved

                distFromStart = startDist2;
                distFromEnd = endDist2;
            }
        }
    },

    closestPointTangent: function(p, opt) {

        return this.tangentAtT(this.closestPointT(p, opt));
    },

    // Returns `true` if the area surrounded by the curve contains the point `p`.
    // Implements the even-odd algorithm (self-intersections are "outside").
    // Closes open curves (always imagines a closing segment).
    // Precision may be adjusted by passing an `opt` object.
    containsPoint: function(p, opt) {

        var polyline = this.toPolyline(opt);
        return polyline.containsPoint(p);
    },

    // Divides the curve into two at requested `ratio` between 0 and 1 with precision better than `opt.precision`; optionally using `opt.subdivisions` provided.
    // For a function that uses `t`, use Curve.divideAtT().
    divideAt: function(ratio, opt) {

        if (ratio <= 0) return this.divideAtT(0);
        if (ratio >= 1) return this.divideAtT(1);

        var t = this.tAt(ratio, opt);

        return this.divideAtT(t);
    },

    // Divides the curve into two at requested `length` with precision better than requested `opt.precision`; optionally using `opt.subdivisions` provided.
    divideAtLength: function(length, opt) {

        var t = this.tAtLength(length, opt);

        return this.divideAtT(t);
    },

    // Divides the curve into two at point defined by `t` between 0 and 1.
    // Using de Casteljau's algorithm (http://math.stackexchange.com/a/317867).
    // Additional resource: https://pomax.github.io/bezierinfo/#decasteljau
    divideAtT: function(t) {

        var start = this.start;
        var controlPoint1 = this.controlPoint1;
        var controlPoint2 = this.controlPoint2;
        var end = this.end;

        // shortcuts for `t` values that are out of range
        if (t <= 0) {
            return [
                new Curve(start, start, start, start),
                new Curve(start, controlPoint1, controlPoint2, end)
            ];
        }

        if (t >= 1) {
            return [
                new Curve(start, controlPoint1, controlPoint2, end),
                new Curve(end, end, end, end)
            ];
        }

        var dividerPoints = this.getSkeletonPoints(t);

        var startControl1 = dividerPoints.startControlPoint1;
        var startControl2 = dividerPoints.startControlPoint2;
        var divider = dividerPoints.divider;
        var dividerControl1 = dividerPoints.dividerControlPoint1;
        var dividerControl2 = dividerPoints.dividerControlPoint2;

        // return array with two new curves
        return [
            new Curve(start, startControl1, startControl2, divider),
            new Curve(divider, dividerControl1, dividerControl2, end)
        ];
    },

    // Returns the distance between the curve's start and end points.
    endpointDistance: function() {

        return this.start.distance(this.end);
    },

    // Checks whether two curves are exactly the same.
    equals: function(c) {

        return !!c &&
            this.start.x === c.start.x &&
            this.start.y === c.start.y &&
            this.controlPoint1.x === c.controlPoint1.x &&
            this.controlPoint1.y === c.controlPoint1.y &&
            this.controlPoint2.x === c.controlPoint2.x &&
            this.controlPoint2.y === c.controlPoint2.y &&
            this.end.x === c.end.x &&
            this.end.y === c.end.y;
    },

    // Returns five helper points necessary for curve division.
    getSkeletonPoints: function(t) {

        var start = this.start;
        var control1 = this.controlPoint1;
        var control2 = this.controlPoint2;
        var end = this.end;

        // shortcuts for `t` values that are out of range
        if (t <= 0) {
            return {
                startControlPoint1: start.clone(),
                startControlPoint2: start.clone(),
                divider: start.clone(),
                dividerControlPoint1: control1.clone(),
                dividerControlPoint2: control2.clone()
            };
        }

        if (t >= 1) {
            return {
                startControlPoint1: control1.clone(),
                startControlPoint2: control2.clone(),
                divider: end.clone(),
                dividerControlPoint1: end.clone(),
                dividerControlPoint2: end.clone()
            };
        }

        var midpoint1 = (new Line(start, control1)).pointAt(t);
        var midpoint2 = (new Line(control1, control2)).pointAt(t);
        var midpoint3 = (new Line(control2, end)).pointAt(t);

        var subControl1 = (new Line(midpoint1, midpoint2)).pointAt(t);
        var subControl2 = (new Line(midpoint2, midpoint3)).pointAt(t);

        var divider = (new Line(subControl1, subControl2)).pointAt(t);

        var output = {
            startControlPoint1: midpoint1,
            startControlPoint2: subControl1,
            divider: divider,
            dividerControlPoint1: subControl2,
            dividerControlPoint2: midpoint3
        };

        return output;
    },

    // Returns a list of curves whose flattened length is better than `opt.precision`.
    // That is, observed difference in length between recursions is less than 10^(-3) = 0.001 = 0.1%
    // (Observed difference is not real precision, but close enough as long as special cases are covered)
    // As a rule of thumb, increasing `precision` by 1 requires 2 more iterations (= levels of division operations)
    // - Precision 0 (endpointDistance) - 0 iterations => total of 2^0 - 1 = 0 operations (1 subdivision)
    // - Precision 1 (<10% error) - 2 iterations => total of 2^2 - 1 = 3 operations (4 subdivisions)
    // - Precision 2 (<1% error) - 4 iterations => total of 2^4 - 1 = 15 operations requires 4 division operations on all elements (15 operations total) (16 subdivisions)
    // - Precision 3 (<0.1% error) - 6 iterations => total of 2^6 - 1 = 63 operations - acceptable when drawing (64 subdivisions)
    // - Precision 4 (<0.01% error) - 8 iterations => total of 2^8 - 1 = 255 operations - high resolution, can be used to interpolate `t` (256 subdivisions)
    // (Variation of 1 recursion worse or better is possible depending on the curve, doubling/halving the number of operations accordingly)
    getSubdivisions: function(opt) {

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision;
        // not using opt.subdivisions
        // not using localOpt

        var start = this.start;
        var control1 = this.controlPoint1;
        var control2 = this.controlPoint2;
        var end = this.end;

        var subdivisions = [new Curve(start, control1, control2, end)];
        if (precision === 0) return subdivisions;

        // special case #1: point-like curves
        // - no need to calculate subdivisions, they would all be identical
        var isPoint = !this.isDifferentiable();
        if (isPoint) return subdivisions;

        var previousLength = this.endpointDistance();

        var precisionRatio = pow(10, -precision);

        // special case #2: sine-like curves may have the same observed length in iteration 0 and 1 - skip iteration 1
        // - not a problem for further iterations because cubic curves cannot have more than two local extrema
        // - (i.e. cubic curves cannot intersect the baseline more than once)
        // - therefore starting from iteration = 2 ensures that subsequent iterations do not produce sampling with equal length
        // - (unless it's a straight-line curve, see below)
        var minIterations = 2; // = 2*1

        // special case #3: straight-line curves have the same observed length in all iterations
        // - this causes observed precision ratio to always be 0 (= lower than `precisionRatio`, which is our exit condition)
        // - we enforce the expected number of iterations = 2 * precision
        var isLine = ((control1.cross(start, end) === 0) && (control2.cross(start, end) === 0));
        if (isLine) {
            minIterations = (2 * precision);
        }

        // recursively divide curve at `t = 0.5`
        // until we reach `minIterations`
        // and until the difference between observed length at subsequent iterations is lower than `precision`
        var iteration = 0;
        while (true) {
            iteration += 1;

            // divide all subdivisions
            var newSubdivisions = [];
            var numSubdivisions = subdivisions.length;
            for (var i = 0; i < numSubdivisions; i++) {

                var currentSubdivision = subdivisions[i];
                var divided = currentSubdivision.divide(0.5); // dividing at t = 0.5 (not at middle length!)
                newSubdivisions.push(divided[0], divided[1]);
            }

            // measure new length
            var length = 0;
            var numNewSubdivisions = newSubdivisions.length;
            for (var j = 0; j < numNewSubdivisions; j++) {

                var currentNewSubdivision = newSubdivisions[j];
                length += currentNewSubdivision.endpointDistance();
            }

            // check if we have reached minimum number of iterations
            if (iteration >= minIterations) {

                // check if we have reached required observed precision
                var observedPrecisionRatio = ((length !== 0) ? ((length - previousLength) / length) : 0);
                if (observedPrecisionRatio < precisionRatio) {
                    return newSubdivisions;
                }
            }

            // otherwise, set up for next iteration
            subdivisions = newSubdivisions;
            previousLength = length;
        }
    },

    isDifferentiable: function() {

        var start = this.start;
        var control1 = this.controlPoint1;
        var control2 = this.controlPoint2;
        var end = this.end;

        return !(start.equals(control1) && control1.equals(control2) && control2.equals(end));
    },

    // Returns flattened length of the curve with precision better than `opt.precision`; or using `opt.subdivisions` provided.
    length: function(opt) {

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision; // opt.precision only used in getSubdivisions() call
        var subdivisions = (opt.subdivisions === undefined) ? this.getSubdivisions({ precision: precision }) : opt.subdivisions;
        // not using localOpt

        var length = 0;
        var n = subdivisions.length;
        for (var i = 0; i < n; i++) {

            var currentSubdivision = subdivisions[i];
            length += currentSubdivision.endpointDistance();
        }

        return length;
    },

    // Returns distance along the curve up to `t` with precision better than requested `opt.precision`. (Not using `opt.subdivisions`.)
    lengthAtT: function(t, opt) {

        if (t <= 0) return 0;

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision;
        // not using opt.subdivisions
        // not using localOpt

        var subCurve = this.divide(t)[0];
        var subCurveLength = subCurve.length({ precision: precision });

        return subCurveLength;
    },

    // Returns point at requested `ratio` between 0 and 1 with precision better than `opt.precision`; optionally using `opt.subdivisions` provided.
    // Mirrors Line.pointAt() function.
    // For a function that tracks `t`, use Curve.pointAtT().
    pointAt: function(ratio, opt) {

        if (ratio <= 0) return this.start.clone();
        if (ratio >= 1) return this.end.clone();

        var t = this.tAt(ratio, opt);

        return this.pointAtT(t);
    },

    // Returns point at requested `length` with precision better than requested `opt.precision`; optionally using `opt.subdivisions` provided.
    pointAtLength: function(length, opt) {

        var t = this.tAtLength(length, opt);

        return this.pointAtT(t);
    },

    // Returns the point at provided `t` between 0 and 1.
    // `t` does not track distance along curve as it does in Line objects.
    // Non-linear relationship, speeds up and slows down as curve warps!
    // For linear length-based solution, use Curve.pointAt().
    pointAtT: function(t) {

        if (t <= 0) return this.start.clone();
        if (t >= 1) return this.end.clone();

        return this.getSkeletonPoints(t).divider;
    },

    // Default precision
    PRECISION: 3,

    round: function(precision) {

        this.start.round(precision);
        this.controlPoint1.round(precision);
        this.controlPoint2.round(precision);
        this.end.round(precision);
        return this;
    },

    scale: function(sx, sy, origin) {

        this.start.scale(sx, sy, origin);
        this.controlPoint1.scale(sx, sy, origin);
        this.controlPoint2.scale(sx, sy, origin);
        this.end.scale(sx, sy, origin);
        return this;
    },

    // Returns a tangent line at requested `ratio` with precision better than requested `opt.precision`; or using `opt.subdivisions` provided.
    tangentAt: function(ratio, opt) {

        if (!this.isDifferentiable()) return null;

        if (ratio < 0) ratio = 0;
        else if (ratio > 1) ratio = 1;

        var t = this.tAt(ratio, opt);

        return this.tangentAtT(t);
    },

    // Returns a tangent line at requested `length` with precision better than requested `opt.precision`; or using `opt.subdivisions` provided.
    tangentAtLength: function(length, opt) {

        if (!this.isDifferentiable()) return null;

        var t = this.tAtLength(length, opt);

        return this.tangentAtT(t);
    },

    // Returns a tangent line at requested `t`.
    tangentAtT: function(t) {

        if (!this.isDifferentiable()) return null;

        if (t < 0) t = 0;
        else if (t > 1) t = 1;

        var skeletonPoints = this.getSkeletonPoints(t);

        var p1 = skeletonPoints.startControlPoint2;
        var p2 = skeletonPoints.dividerControlPoint1;

        var tangentStart = skeletonPoints.divider;

        var tangentLine = new Line(p1, p2);
        tangentLine.translate(tangentStart.x - p1.x, tangentStart.y - p1.y); // move so that tangent line starts at the point requested

        return tangentLine;
    },

    // Returns `t` at requested `ratio` with precision better than requested `opt.precision`; optionally using `opt.subdivisions` provided.
    tAt: function(ratio, opt) {

        if (ratio <= 0) return 0;
        if (ratio >= 1) return 1;

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision;
        var subdivisions = (opt.subdivisions === undefined) ? this.getSubdivisions({ precision: precision }) : opt.subdivisions;
        var localOpt = { precision: precision, subdivisions: subdivisions };

        var curveLength = this.length(localOpt);
        var length = curveLength * ratio;

        return this.tAtLength(length, localOpt);
    },

    // Returns `t` at requested `length` with precision better than requested `opt.precision`; optionally using `opt.subdivisions` provided.
    // Uses `precision` to approximate length within `precision` (always underestimates)
    // Then uses a binary search to find the `t` of a subdivision endpoint that is close (within `precision`) to the `length`, if the curve was as long as approximated
    // As a rule of thumb, increasing `precision` by 1 causes the algorithm to go 2^(precision - 1) deeper
    // - Precision 0 (chooses one of the two endpoints) - 0 levels
    // - Precision 1 (chooses one of 5 points, <10% error) - 1 level
    // - Precision 2 (<1% error) - 3 levels
    // - Precision 3 (<0.1% error) - 7 levels
    // - Precision 4 (<0.01% error) - 15 levels
    tAtLength: function(length, opt) {

        var fromStart = true;
        if (length < 0) {
            fromStart = false; // negative lengths mean start calculation from end point
            length = -length; // absolute value
        }

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision;
        var subdivisions = (opt.subdivisions === undefined) ? this.getSubdivisions({ precision: precision }) : opt.subdivisions;
        var localOpt = { precision: precision, subdivisions: subdivisions };

        // identify the subdivision that contains the point at requested `length`:
        var investigatedSubdivision;
        var investigatedSubdivisionStartT; // assume that subdivisions are evenly spaced
        var investigatedSubdivisionEndT;
        //var baseline; // straightened version of subdivision to investigate
        //var baselinePoint; // point on the baseline that is the requested distance away from start
        var baselinePointDistFromStart; // distance of baselinePoint from start of baseline
        var baselinePointDistFromEnd; // distance of baselinePoint from end of baseline
        var l = 0; // length so far
        var n = subdivisions.length;
        var subdivisionSize = 1 / n;
        for (var i = 0; i < n; i++) {
            var index = (fromStart ? i : (n - 1 - i));

            var currentSubdivision = subdivisions[i];
            var d = currentSubdivision.endpointDistance(); // length of current subdivision

            if (length <= (l + d)) {
                investigatedSubdivision = currentSubdivision;

                investigatedSubdivisionStartT = index * subdivisionSize;
                investigatedSubdivisionEndT = (index + 1) * subdivisionSize;

                baselinePointDistFromStart = (fromStart ? (length - l) : ((d + l) - length));
                baselinePointDistFromEnd = (fromStart ? ((d + l) - length) : (length - l));

                break;
            }

            l += d;
        }

        if (!investigatedSubdivision) return (fromStart ? 1 : 0); // length requested is out of range - return maximum t
        // note that precision affects what length is recorded
        // (imprecise measurements underestimate length by up to 10^(-precision) of the precise length)
        // e.g. at precision 1, the length may be underestimated by up to 10% and cause this function to return 1

        var curveLength = this.length(localOpt);

        var precisionRatio = pow(10, -precision);

        // recursively divide investigated subdivision:
        // until distance between baselinePoint and closest path endpoint is within 10^(-precision)
        // then return the closest endpoint of that final subdivision
        while (true) {

            // check if we have reached required observed precision
            var observedPrecisionRatio;

            observedPrecisionRatio = ((curveLength !== 0) ? (baselinePointDistFromStart / curveLength) : 0);
            if (observedPrecisionRatio < precisionRatio) return investigatedSubdivisionStartT;
            observedPrecisionRatio = ((curveLength !== 0) ? (baselinePointDistFromEnd / curveLength) : 0);
            if (observedPrecisionRatio < precisionRatio) return investigatedSubdivisionEndT;

            // otherwise, set up for next iteration
            var newBaselinePointDistFromStart;
            var newBaselinePointDistFromEnd;

            var divided = investigatedSubdivision.divide(0.5);
            subdivisionSize /= 2;

            var baseline1Length = divided[0].endpointDistance();
            var baseline2Length = divided[1].endpointDistance();

            if (baselinePointDistFromStart <= baseline1Length) { // point at requested length is inside divided[0]
                investigatedSubdivision = divided[0];

                investigatedSubdivisionEndT -= subdivisionSize; // sudivisionSize was already halved

                newBaselinePointDistFromStart = baselinePointDistFromStart;
                newBaselinePointDistFromEnd = baseline1Length - newBaselinePointDistFromStart;

            } else { // point at requested length is inside divided[1]
                investigatedSubdivision = divided[1];

                investigatedSubdivisionStartT += subdivisionSize; // subdivisionSize was already halved

                newBaselinePointDistFromStart = baselinePointDistFromStart - baseline1Length;
                newBaselinePointDistFromEnd = baseline2Length - newBaselinePointDistFromStart;
            }

            baselinePointDistFromStart = newBaselinePointDistFromStart;
            baselinePointDistFromEnd = newBaselinePointDistFromEnd;
        }
    },

    // Returns an array of points that represents the curve when flattened, up to `opt.precision`; or using `opt.subdivisions` provided.
    // Flattened length is no more than 10^(-precision) away from real curve length.
    toPoints: function(opt) {

        opt = opt || {};
        var precision = (opt.precision === undefined) ? this.PRECISION : opt.precision; // opt.precision only used in getSubdivisions() call
        var subdivisions = (opt.subdivisions === undefined) ? this.getSubdivisions({ precision: precision }) : opt.subdivisions;
        // not using localOpt

        var points = [subdivisions[0].start.clone()];
        var n = subdivisions.length;
        for (var i = 0; i < n; i++) {

            var currentSubdivision = subdivisions[i];
            points.push(currentSubdivision.end.clone());
        }

        return points;
    },

    // Returns a polyline that represents the curve when flattened, up to `opt.precision`; or using `opt.subdivisions` provided.
    // Flattened length is no more than 10^(-precision) away from real curve length.
    toPolyline: function(opt) {

        return new Polyline(this.toPoints(opt));
    },

    toString: function() {

        return this.start + ' ' + this.controlPoint1 + ' ' + this.controlPoint2 + ' ' + this.end;
    },

    translate: function(tx, ty) {

        this.start.translate(tx, ty);
        this.controlPoint1.translate(tx, ty);
        this.controlPoint2.translate(tx, ty);
        this.end.translate(tx, ty);
        return this;
    }
};

Curve.prototype.divide = Curve.prototype.divideAtT;