# module:extras/evaluators.Roulette

### new module:extras/evaluators.Roulette(rollingCurve, fixedCurve, polePoint, [revolutions])

**Augments:** Curve

A curve evaluator object for a curve drawn by a curve that rolls along another curve whose position is fixed.

This object generates two-dimensional curves, which are returned by the `evaluate`

method as three-dimensional points with the third element (Z coordinate) set to 0.

#### Parameters

`rollingCurve`

(Type: Object)

A curve evaluator object that describes the curve that rolls to generate the roulette curve. This curve is assumed to be a smooth, convex closed curve such as a circle. The curve evaluator object*should*support extrapolating curve positions outside its`endPoints()`

range.`fixedCurve`

(Type: Object)

A curve evaluator object that describes the curve on which the rolling curve will move. This curve is assumed to be smooth at every point; this includes periodic waves and circles. The curve evaluator object*should*support extrapolating curve positions outside its`endPoints()`

range.`polePoint`

(Type: Array.<number>)

X and Y coordinates of a point, from the same coordinate system (reference frame) as*rollingCurve*, that will generate the roulette curve.`revolutions`

(Type: number) (optional)

The roulette will be generated by rolling the rolling curve the distance of the fixed curve times this parameter; this will be reflected in this instance's`endPoints`

method. This can be an integer or a noninteger number. If null, undefined, or omitted, the default is 1.

### 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. - epitrochoid

Creates a curve evaluator object for an*epitrochoid*, a curve drawn by a circle that rolls along the outside of another circle, whose position is fixed, with a center of (0,0). - 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. - getPointsAsObjects

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

Creates a curve evaluator object for a*hypotrochoid*, a curve drawn by a circle that rolls along the inside of another circle, whose position is fixed, with a center of (0,0). - 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. - rose

Creates a curve evaluator object for a rose, a special form of hypotrochoid (roulette curve generated when one circle rolls inside another fixed circle). - tangent

Convenience method for finding an approximate tangent vector of this curve at the given U coordinate. - 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*. - trochoid

Creates a curve evaluator object for a*trochoid*, a curve drawn by a circle that rolls along the X axis. - velocity

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

### module:extras/evaluators.Roulette#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 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>)

### module:extras/evaluators.Roulette#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 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)

### module:extras/evaluators.Roulette#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

`ep1`

(Type: number)

New start point of the curve.`ep2`

(Type: number)

New end point of the curve.

#### Return Value

Return value. (Type: Curve)

### module:extras/evaluators.Roulette#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.

### (static) module:extras/evaluators~Roulette.epitrochoid(outerRadius, rollerRadius, distFromRollerCenter, [rotationDegrees], [revolutions])

Creates a curve evaluator object for an *epitrochoid*, a curve drawn by a circle that rolls along the outside
of another circle, whose position is fixed, with a center of (0,0).
The rolling circle will start at the positive X axis of the fixed circle
unless otherwise given in the parameter `rotationDegrees`

.

This is a special case of a roulette in which the fixed and rolling curves are circles, and the pole point is the starting point of a circle with the same center as the rolling circle.

The following curves can be generated with this class (in the following
descriptions, O = `outerRadius`

, R means `rollerRadius`

,
and D = `distFromRollerCenter`

).

- Epicycloid: D = R (epitrochoid touching the fixed circle).
- Curtate epicycloid: D < R (epitrochoid not touching the fixed circle).
- Prolate epicycloid: D > R (epitrochoid crossing the fixed circle).
- Cardioid: R = O; D = O.
- Nephroid: R = O/2; D = O/2.
- Ranunculoid: R = O/5; D = O/5.
- N-cusped epicycloid: R = O/N; D = O/N.
- Circle: O = 0; the radius will be R - D.

#### Parameters

`outerRadius`

(Type: number)

Radius of the circle whose position is fixed.`rollerRadius`

(Type: number)

Radius of the rolling circle. An epicycloid results when distFromRollerCenter=rollerRadius.`distFromRollerCenter`

(Type: number)

Distance from the center of the rolling circle to the drawing pen.`rotationDegrees`

(Type: number) (optional)

Starting angle of the curve from the positive X axis toward the positive Y axis, in degrees. If null, undefined, or omitted, the default is 0.`revolutions`

(Type: number) (optional)

Number of times to roll the inner circle around the outer circle to generate the epitrochoid. This can be an integer or a noninteger number. If null, undefined, or omitted, the default is 1.

### module:extras/evaluators.Roulette#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>)

### module:extras/evaluators.Roulette#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: Curve)

### module:extras/evaluators.Roulette#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)

### module:extras/evaluators.Roulette#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>> | Array.<Object>)

### module:extras/evaluators.Roulette#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

`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>> | 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);

### (static) module:extras/evaluators~Roulette.hypotrochoid(outerRadius, innerRadius, distFromInnerCenter, [rotationDegrees], [revolutions])

Creates a curve evaluator object for a *hypotrochoid*, a curve drawn by a circle that rolls along the inside
of another circle, whose position is fixed, with a center of (0,0).

This is a special case of a roulette in which the fixed and rolling curves are circles, and the pole point is the starting point of a circle with the same center as the rolling circle.

The following curves can be generated with this class (in the following
descriptions, O = `outerRadius`

, R means `innerRadius`

,
and D = `distFromInnerCenter`

).

- Hypocycloid: D = R (hypotrochoid touching the fixed circle).
- Curtate hypocycloid: D < R (hypotrochoid not touching the fixed circle).
- Prolate hypocycloid: D > R (hypotrochoid crossing the fixed circle).
- Circle: O = R*2; the circle will have radius R - D.
- Ellipse: O = R*2; the ellipse (unrotated) will have width abs(R+D)*2 and height abs(R-D)*2.
- Line segment with length O*2: O = R*2; D = R.
- Deltoid: O = R*3; D = R.
- Astroid: O = R*4; D = R.
- N-pointed hypocycloid: O = R * N; D = R.

#### Parameters

`outerRadius`

(Type: number)

Radius of the circle whose position is fixed.`innerRadius`

(Type: number)

Radius of the rolling circle. A hypocycloid results when distFromInnerCenter=innerRadius.`distFromInnerCenter`

(Type: number)

Distance from the center of the rolling circle to the drawing pen.`rotationDegrees`

(Type: number) (optional)

Starting angle of the curve from the positive X axis toward the positive Y axis, in degrees. If null, undefined, or omitted, the default is 0.`revolutions`

(Type: number) (optional)

Number of times to roll the inner circle around the outer circle to generate the hypotrochoid. This can be an integer or a noninteger number. If null, undefined, or omitted, the default is 1.

### module:extras/evaluators.Roulette#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 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>)

### module:extras/evaluators.Roulette#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 unit vector. (Compare with 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>)

### (static) module:extras/evaluators~Roulette.rose(num, denom, distFromInnerCenter, [rotationDegrees])

Creates a curve evaluator object for a rose, a special form of hypotrochoid (roulette curve generated when one circle rolls inside another fixed circle).

#### Parameters

`num`

(Type: number)

Integer numerator of a parameter that determines the petal form of the rose. For example, the rose is symmetrical if 'num' is even and 'den' is 1.`denom`

(Type: number)

Integer denominator of a parameter that determines the petal form of the rose. Must not be 0.`distFromInnerCenter`

(Type: number)

Distance from the center of the rolling circle to the drawing pen.`rotationDegrees`

(Type: number) (optional)

Starting angle of the curve from the positive X axis toward the positive Y axis, in degrees. Default is 0.

#### Return Value

The resulting curve evaluator object. (Type: Roulette)

### module:extras/evaluators.Roulette#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>)

### module:extras/evaluators.Roulette#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())

### (static) module:extras/evaluators~Roulette.trochoid(radius, distFromCenter, [distance])

Creates a curve evaluator object for a *trochoid*, a curve drawn by a circle that rolls along the X axis.

The following curves can be generated with this class (in the following
descriptions, R = `radius`

and D = `distFromCenter`

).

- Cycloid: D = R (trochoid touching the X axis).
- Curtate cycloid: D < R (trochoid not touching the X axis).
- Prolate cycloid: D > R (trochoid crossing the X axis).

#### Parameters

`radius`

(Type: number)

Radius of the rolling circle.`distFromCenter`

(Type: number)

Distance from the center of the rolling circle to the drawing pen.`distance`

(Type: number) (optional)

Distance to roll the inner circle along the X axis to generate the epitrochoid. This can be an integer or a noninteger number. If null, undefined, or omitted, the default is 2 * π *`radius`

.

### module:extras/evaluators.Roulette#velocity(u)

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