# H3DU.Curve

### H3DU.Curve(curve, [curveParam])

A curve evaluator object for a parametric curve.

A parametric curve is a curve whose points are based on a parametric curve function. A curve function takes a number (U) and returns a point (in 1 or more dimensions, but usually 2 or 3) that lies on the curve. For example, in 3 dimensions, a curve function has the following form:

**F**(u) = [ x(u), y(u), z(u) ]

where x(u) returns an X coordinate, y(u) a Y coordinate, and z(u) returns a Z coordinate.

Specialized curves should subclass this class and implement
the `evaluate`

method and, optionally, the other methods mentioned in the "curve" parameter below.

#### Parameters

`curve`

(Type: Object)

A**curve evaluator object**, which is an object that must contain an`evaluate`

method and may contain an`endPoints`

,`velocity`

,`accel`

,`jerk`

,`normal`

, and/or`arcLength`

method, as described in the corresponding methods of this class.`curveParam`

(Type: Object) (optional)

An object for reparameterizing a curve object. It implements a method named`endPoints`

, which has the same meaning as H3DU.Curve#endPoints and whose return value takes precedence over the given curve's`endPoints`

method. It also implements a method named`getCoordinate(u)`

, which converts a U coordinate in the old parameterization to a U coordinate in the new parameterization.

#### Example

The following function defines a parametric circle curve. It demonstrates how all methods defined for curve evaluator objects can be implemented.

var circle=new Curve({"evaluate":function(u) { "use strict"; return [Math.cos(u),Math.sin(u),0] }, "velocity":function(u) { return [-Math.sin(u),Math.cos(u),0] }, "accel":function(u) { return [-Math.cos(u),-Math.sin(u),0] }, "jerk":function(u) { return [Math.sin(u),-Math.cos(u),0] }, "normal":function(u) { // NOTE: The velocity vector will already be a // unit vector, so we use the accel vector instead return H3DU.Math.vec3normalize(this.accel(u)); }, "arcLength":function(u) { return u; }, "endPoints":function(u) { return [0,Math.PiTimes2] } });

### Methods

- accel

Finds an approximate acceleration vector at the given U coordinate of this curve. - arcLength

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

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. - endPoints

Returns the starting and ending U coordinates of this curve. - evaluate

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

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. - getLength

Convenience method for getting the total length of this curve. - getPoints

Gets an array of positions on the curve at fixed intervals of U coordinates. - jerk

Finds an approximate jerk vector at the given U coordinate of this curve. - normal

Finds an approximate principal normal vector at the given U coordinate of this curve. - tangent

Convenience method for finding an approximate tangent vector of this curve at the given U coordinate. - toArcLengthParam

Creates 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*. - velocity

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

### H3DU.Curve#accel(u)

Finds an approximate acceleration vector at the given U coordinate of this curve.
The implementation in H3DU.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 unit vector.

#### Parameters

`u`

(Type: number)

U coordinate of a point on the curve.

#### 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>)

### H3DU.Curve#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.
The implementation in H3DU.Curve calls the evaluator's `arcLength`

method if it implements it; otherwise, calculates a numerical integral using the velocity vector.

The **arc length** function returns a number; if the curve is "smooth", this is the integral, from the starting point to `u`

, of the length of the velocity vector.

#### Parameters

`u`

(Type: number)

U coordinate of a point on the curve.

#### Return Value

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

### H3DU.Curve#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.

#### Parameters

`ep1`

(Type: number)

New start point of the curve.`ep2`

(Type: number)

New end point of the curve.

#### Return Value

Return value. (Type: H3DU.Curve)

### H3DU.Curve#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, 1]`

if the evaluator doesn't implement an `endPoints`

method.

### H3DU.Curve#evaluate(u)

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

#### Parameters

`u`

(Type: number)

U coordinate of a point on the curve.

#### 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>)

### H3DU.Curve#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

`ep1`

(Type: number)

New value to use as the start point of the curve.`ep2`

(Type: number)

New value to use as the end point of the curve.

#### Return Value

Return value. (Type: H3DU.Curve)

### H3DU.Curve#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)

### H3DU.Curve#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

`count`

(Type: number)

Number of positions to generate. Throws an error if this number is 0. If this value is 1, returns an array containing the starting point of this curve.

#### 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>>)

### H3DU.Curve#jerk(u)

Finds an approximate jerk vector at the given U coordinate of this curve.
The implementation in H3DU.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 unit vector.

#### Parameters

`u`

(Type: number)

U coordinate of a point on the curve.

#### 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>)

### H3DU.Curve#normal(u)

Finds an approximate principal normal vector at the given U coordinate of this curve.
The implementation in H3DU.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 unit vector. (Compare with H3DU.Surface#gradient.)

#### Parameters

`u`

(Type: number)

U coordinate of a point on the curve.

#### 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>)

### H3DU.Curve#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

`u`

(Type: number)

U coordinate of a point on the curve.

#### 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>)

### H3DU.Curve#toArcLengthParam()

Creates 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. (Type: H3DU.Curve)

### H3DU.Curve#velocity(u)

Finds an approximate velocity vector at the given U coordinate of this curve.
The implementation in H3DU.Curve calls the evaluator's `velocity`

method if it implements it; otherwise, does a numerical differentiation using
the position (from the `evaluate`

method).

The **velocity** of a curve is a vector which is the derivative of the curve's position at the given coordinate. The vector returned by this method *should not* be "normalized" to a unit vector.

#### Parameters

`u`

(Type: number)

U coordinate of a point on the curve.

#### 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>)