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 itsendPoints()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 itsendPoints()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'sendPointsmethod. 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>)