PiecewiseCurve

Back to documentation index.

### new PiecewiseCurve(curves)

Augments: Curve

A curve evaluator object for a curve made up of one or more individual curves.

The combined curve’s U coordinates range from 0 to N, where N is the number of curves. In this way, the integer part of a U coordinate indicates the curve the coordinate refers to. For example, if there are four curves, coordinates from 0, but less than 1, belong to the first curve, and coordinates from 1, but less than 2, belong to the second curve. The U coordinate equal to N refers to the end of the last curve in the piecewise curve.

Parameters

Examples

// Generates a piecewise polygon curve from an array of
// vectors (arrays with the same number of elements) that
// specify the points that make up the polygon.
function polygonCurve(points) {
var curves=[]
for(var i=0;<points.length;i++) {
var cp=points[i]
var np=(i==points.length-1) ? points[0] : points[i+1]
curves.push(BSplineCurve.fromBezierCurve([cp,np]))
}
return new PiecewiseCurve(curves)
}

Methods

### PiecewiseCurve#accel(u)

Finds an approximate acceleration vector at the given U coordinate of this curve. The implementation in Curve calls the evaluator’s accel method if it implements it; otherwise, does a numerical differentiation using the velocity vector.

The acceleration of a curve is a vector which is the second-order derivative of the curve’s position at the given coordinate. The vector returned by this method should not be “normalized” to a glmath.

Parameters

Return Value

An array describing an acceleration vector. It should have at least as many elements as the number of dimensions of the underlying curve. (Type: Array.<number>)

### PiecewiseCurve#arcLength(u)

Finds an approximate arc length (distance) between the start of this curve and the point at the given U coordinate of this curve.

Parameters

Return Value

The approximate arc length of this curve at the given U coordinate. (Type: number)

### PiecewiseCurve#changeEnds(ep1, ep2)

Creates a curve evaluator object for a curve that is generated using the same formula as this one (and uses the same U coordinates), but has a different set of end points. For example, this method can be used to shrink the path of a curve from [0, π] to [0, π/8].

Note, however, that in general, shrinking the range of a curve will not shrink the length of a curve in the same proportion, unless the curve’s path runs at constant speed with respect to time. For example, shrinking the range of a curve from [0, 1] to [0, 0.5] will not generally result in a curve that’s exactly half as long as the original curve.

For some curves, this method can also be used to grow the path of the curve.

Parameters

Return Value

Return value. (Type: Curve)

### PiecewiseCurve#endPoints()

Returns the starting and ending U coordinates of this curve.

Return Value

A two-element array. The first element is the starting coordinate of the curve, and the second is its ending coordinate. Returns [0, n], where n is the number of curves that make up this piecewise curve.

### PiecewiseCurve#evaluate(u)

Finds the position of this curve at the given U coordinate.

Parameters

Return Value

An array describing a position. It should have at least as many elements as the number of dimensions of the underlying curve. (Type: Array.<number>)

### PiecewiseCurve#fitRange(ep1, ep2)

Creates a curve evaluator object for a curve that follows the same path as this one but has its U coordinates remapped to fit the given range. For example, this method can be used to shrink the range of U coordinates from [-π, π] to [0, 1] without shortening the path of the curve. Here, -π now maps to 0, and π now maps to 1.

Parameters

Return Value

Return value. (Type: Curve)

### (static) PiecewiseCurve.fromCatmullRomSpline(spline, [param], [closed])

Creates a piecewise curve made up of B-spline curves from the control points of a cubic Catmull–Rom spline. A Catmull–Rom spline is defined by a collection of control points that the spline will go through, and the shape of each curve segment is also determined by the positions of neighboring points on the spline.

Parameters

Return Value

A piecewise curve made up of cubic B-spline curves describing the same path as the Catmull–Rom spline. (Type: PiecewiseCurve)

### (static) PiecewiseCurve.fromEllipseArc(x, y, w, h, start, sweep)

Creates a piecewise curve that describes an arc running along an axis-aligned ellipse, or a shape based on that arc and ellipse, given the ellipse’s center and dimensions, start angle, and sweep angle. The arc is rendered as cubic rational B-spline curves.

Parameters

Return Value

The resulting piecewise curve. (Type: PiecewiseCurve)

### (static) PiecewiseCurve.fromHermiteSpline(spline)

Creates a piecewise curve made up of B-spline curves from the control points of a Hermite spline. A Hermite spline is a collection of points that the curve will go through, together with the velocity vectors (derivatives or instantaneous rates of change) at those points.

Hermite splines are useful for representing an approximate polynomial form of a function or curve whose derivative is known; however, Hermite splines are not guaranteed to preserve the increasing or decreasing nature of the function or curve.

Parameters

Return Value

A piecewise curve made up of cubic B-spline curves describing the same path as the Hermite spline. (Type: PiecewiseCurve)

### (static) PiecewiseCurve.fromTCBSpline(spline, [tension], [continuity], [bias], [closed], [rigidEnds])

Creates a piecewise curve made up of B-spline curves from the control points of a cubic TCB spline (tension/continuity/bias spline, also known as Kochanek–Bartels spline). (If tension, continuity, and bias are all 0, the result is a cubic Catmull–Rom spline in uniform parameterization.)

Parameters

Return Value

A piecewise curve made up of cubic B-spline curves describing the same path as the TCB spline. (Type: PiecewiseCurve)

### PiecewiseCurve#getCurves()

Gets a reference to the curves that make up this piecewise curve.

Return Value

The curves that make up this piecewise curve. (Type: Array.<Curve>)

### PiecewiseCurve#getLength()

Convenience method for getting the total length of this curve.

Return Value

The distance from the start of the curve to its end. (Type: number)

### PiecewiseCurve#getPoints(count)

Gets an array of positions on the curve at fixed intervals of U coordinates. Note that these positions will not generally be evenly spaced along the curve unless the curve uses an arc-length parameterization.

Parameters

Return Value

An array of curve positions. The first element will be the start of the curve. If “count” is 2 or greater, the last element will be the end of the curve. (Type: Array.<Array.<number» | Array.<Object>)

### PiecewiseCurve#getPointsAsObjects(count)

Gets an array of positions on the curve at fixed intervals of U coordinates. Note that these positions will not generally be evenly spaced along the curve unless the curve uses an arc-length parameterization. The positions will be in the form of objects with up to four properties: x, y, z, and w retrieve the first, second, third, and fourth coordinate of each position, respectively.

Parameters

Return Value

An array of curve positions. The first element will be the start of the curve. If “count” is 2 or greater, the last element will be the end of the curve. (Type: Array.<Array.<number» | Array.<Object>)

Examples

The following example initializes a three.js BufferGeometry with the points retrieved by this method. This example requires the three.js library.

var points=curve.getPointsAsObjects(50)
var buffer=new THREE.BufferGeometry()
.setFromPoints(points);

### PiecewiseCurve#jerk(u)

Finds an approximate jerk vector at the given U coordinate of this curve. The implementation in Curve calls the evaluator’s jerk method if it implements it; otherwise, does a numerical differentiation using the acceleration vector.

The jerk of a curve is a vector which is the third-order derivative of the curve’s position at the given coordinate. The vector returned by this method should not be “normalized” to a glmath.

Parameters

Return Value

An array describing a jerk vector. It should have at least as many elements as the number of dimensions of the underlying curve. (Type: Array.<number>)

### PiecewiseCurve#normal(u)

Finds an approximate principal normal vector at the given U coordinate of this curve. The implementation in Curve calls the evaluator’s normal method if it implements it; otherwise, does a numerical differentiation using the velocity vector.

The principal normal of a curve is the derivative of the “normalized” velocity vector divided by that derivative’s length. The normal returned by this method should be “normalized” to a glmath. (Compare with Surface#gradient.)

Parameters

Return Value

An array describing a normal vector. It should have at least as many elements as the number of dimensions of the underlying curve. (Type: Array.<number>)

### PiecewiseCurve#tangent(u)

Convenience method for finding an approximate tangent vector of this curve at the given U coordinate. The tangent vector is the same as the velocity vector, but “normalized” to a unit vector.

Parameters

Return Value

An array describing a normal vector. It should have at least as many elements as the number of dimensions of the underlying curve. (Type: Array.<number>)

### PiecewiseCurve#toArcLengthParam()

Gets a curve evaluator object for a curve that follows the same path as this one but has its U coordinates remapped to an arc length parameterization. Arc length parameterization allows for moving along a curve’s path at a uniform speed and for generating points which are spaced evenly along that path – both features are more difficult with most other kinds of curve parameterization.

The end points of the curve (obtained by calling the endPoints method) will be (0, N), where N is the distance to the end of the curve from its start.

When converting to an arc length parameterization, the curve should be continuous and have a speed greater than 0 at every point on the curve. The arc length parameterization used in this method is approximate.

Return Value

Return value. Returns this object if this curve already uses an arc length parameterization. (Type: Curve)

Examples

The following example uses the arc-length parameterization to generate, uniformly at random, a point that lies anywhere on a curve.

var arclen = curve.toArcLengthParam();
var point = arclen.evaluate(Math.random()*arclen.getLength())

### PiecewiseCurve#velocity(u)

Finds an approximate velocity vector at the given U coordinate of this curve.

Parameters

Return Value

An array describing a velocity vector. It should have at least as many elements as the number of dimensions of the underlying curve. (Type: Array.<number>)

Back to documentation index.