ThreeJS Curve
An abstract base class for creating a Curve object with interpolation methods. CurvePath is an array of Curves.
Constructor
Curve()
This constructor creates a new Curve.
Properties
.arcLengthDivisions : Integer
This value determines the amount of divisions when calculating the cumulative segment lengths of a curve via .getLengths. To ensure precision when using methods like .getSpacedPoints, it is recommended to increase .arcLengthDivisions if the curve is very large. Default is 200.
Methods
.getPoint ( t : Float, optionalTarget : Vector ) : Vector
t - A position on the curve. Must be in the range [ 0, 1 ].
optionalTarget — (optional) If specified, the result will be copied into this Vector, otherwise a new Vector will be created.
Returns a vector for a given position on the curve.
.getPointAt ( u : Float, optionalTarget : Vector ) : Vector
u - A position on the curve according to the arc length. Must be in the range [ 0, 1 ].
optionalTarget — (optional) If specified, the result will be copied into this Vector, otherwise a new Vector will be created.
Returns a vector for a given position on the curve according to the arc length.
.getPoints ( divisions : Integer ) : Array
divisions -- number of pieces to divide the curve into. Default is 5.
Returns a set of divisions + 1 points using getPoint( t ).
.getSpacedPoints ( divisions : Integer ) : Array
divisions -- number of pieces to divide the curve into. Default is 5.
Returns a set of divisions + 1 equi-spaced points using getPointAt( u ).
.getLength () : Float
Get total curve arc length.
.getLengths ( divisions : Integer ) : Array
Get list of cumulative segment lengths.
.updateArcLengths () : undefined
Update the cumlative segment distance cache. The method must be called every time curve parameters are changed. If an updated curve is part of a composed curve like CurvePath, .updateArcLengths() must be called on the composed curve, too.
.getUtoTmapping ( u : Float, distance : Float ) : Float
Given u in the range ( 0 .. 1 ), returns t also in the range ( 0 .. 1 ). u and t can then be used to give you points which are equidistant from the ends of the curve, using .getPoint.
.getTangent ( t : Float, optionalTarget : Vector ) : Vector
t - A position on the curve. Must be in the range [ 0, 1 ].
optionalTarget — (optional) If specified, the result will be copied into this Vector, otherwise a new Vector will be created.
Returns a unit vector tangent at t. If the derived curve does not implement its tangent derivation, two points a small delta apart will be used to find its gradient which seems to give a reasonable approximation.
.getTangentAt ( u : Float, optionalTarget : Vector ) : Vector
u - A position on the curve according to the arc length. Must be in the range [ 0, 1 ].
optionalTarget — (optional) If specified, the result will be copied into this Vector, otherwise a new Vector will be created.
Returns tangent at a point which is equidistant to the ends of the curve from the point given in .getTangent.
.computeFrenetFrames ( segments : Integer, closed : Boolean ) : Object
Generates the Frenet Frames. Requires a curve definition in 3D space. Used in geometries like TubeGeometry or ExtrudeGeometry.
.clone () : Curve
Creates a clone of this instance.
.copy ( source : Curve ) : this
Copies another Curve object to this instance.
.toJSON () : Object
Returns a JSON object representation of this instance.
.fromJSON ( json : Object ) : this
Copies the data from the given JSON object to this instance.
CurvePath
An abstract base class extending Curve. A CurvePath is simply an array of connected curves but retains the api of a curve.
Constructor
CurvePath()
The constructor takes no parameters.
Properties
See the base Curve class for common properties.
.curves : Array
The array of Curves.
.autoClose : Boolean
Whether or not to automatically close the path.
Methods
See the base Curve class for common methods.
.add ( curve : Curve ) : undefined
Add a curve to the .curves array.
.closePath () : undefined
Adds a lineCurve to close the path.
.getCurveLengths () : Array
Get list of cumulative curve lengths of the curves in the .curves array.
.getPoints ( divisions : Integer ) : Array
divisions -- number of pieces to divide the curve into. Default is 12.
Returns a point array representing a series of curves. The division parameter specifies how many pieces each curve is divided into. The actual sampling resolution for each curve, however, depends on its type for optimization and quality purposes. For example, the returned number of points for a LineCurve is always just 2.
.getSpacedPoints ( divisions : Integer ) : Array
divisions -- number of pieces to divide the curve into. Default is 40.
Returns a set of divisions + 1 equi-spaced points using getPointAt( u ).
Interpolations
Interpolations contains spline and Bézier functions internally used by concrete curve classes.
Methods
.CatmullRom ( t : Float, p0 : Float, p1 : Float, p2 : Float, p3 : Float ) : Float
t -- interpolation weight.
p0, p1, p2, p3 -- the points defining the spline curve.
Used internally by SplineCurve.
.QuadraticBezier ( t : Float, p0 : Float, p1 : Float, p2 : Float ) : Float
t -- interpolation weight.
p0, p1, p2 -- the starting, control and end points defining the curve.
Used internally by QuadraticBezierCurve3 and QuadraticBezierCurve.
.CubicBezier ( t : Float, p0 : Float, p1 : Float, p2 : Float, p3 : Float ) : Float
t -- interpolation weight.
p0, p1, p2, p3 -- the starting, control(twice) and end points defining the curve.
Used internally by CubicBezierCurve3 and CubicBezierCurve.
Path
A two-dimensional path representation. Similar to the 2D Canvas API, the class provides methods for creating paths and contours of 2D shapes.
Code Example
const path = new THREE.Path();
path.lineTo( 0, 0.8 );
path.quadraticCurveTo( 0, 1, 0.2, 1 );
path.lineTo( 1, 1 );
const points = path.getPoints();
const geometry = new THREE.BufferGeometry().setFromPoints( points );
const material = new THREE.LineBasicMaterial( { color: 0xffffff } );
const line = new THREE.Line( geometry, material );
scene.add( line );
Constructor
Path( points : Array )
points -- (optional) array of Vector2s.
Creates a Path from the points. The first point defines the offset, then successive points are added to the curves array as LineCurves.
If no points are specified, an empty path is created and the .currentPoint is set to the origin.
Properties
See the base CurvePath class for common properties.
.currentPoint : Array
The current offset of the path. Any new Curve added will start here.
Methods
See the base CurvePath class for common methods.
.absarc ( x : Float, y : Float, radius : Float, startAngle : Float, endAngle : Float, clockwise : Boolean ) : this
x, y -- The absolute center of the arc.
radius -- The radius of the arc.
startAngle -- The start angle in radians.
endAngle -- The end angle in radians.
clockwise -- Sweep the arc clockwise. Defaults to false.
Adds an absolutely positioned EllipseCurve to the path.
.absellipse ( x : Float, y : Float, xRadius : Float, yRadius : Float, startAngle : Float, endAngle : Float, clockwise : Boolean, rotation : Float ) : this
x, y -- The absolute center of the ellipse.
xRadius -- The radius of the ellipse in the x axis.
yRadius -- The radius of the ellipse in the y axis.
startAngle -- The start angle in radians.
endAngle -- The end angle in radians.
clockwise -- Sweep the ellipse clockwise. Defaults to false.
rotation -- The rotation angle of the ellipse in radians, counterclockwise from the positive X axis. Optional, defaults to 0.
Adds an absolutely positioned EllipseCurve to the path.
.arc (x : Float, y : Float, radius : Float, startAngle : Float, endAngle : Float, clockwise : Boolean ) : this
x, y -- The center of the arc offset from the last call.
radius -- The radius of the arc.
startAngle -- The start angle in radians.
endAngle -- The end angle in radians.
clockwise -- Sweep the arc clockwise. Defaults to false.
Adds an EllipseCurve to the path, positioned relative to .currentPoint.
.bezierCurveTo ( cp1X : Float, cp1Y : Float, cp2X : Float, cp2Y : Float, x : Float, y : Float ) : this
This creates a bezier curve from .currentPoint with (cp1X, cp1Y) and (cp2X, cp2Y) as control points and updates .currentPoint to x and y.
.ellipse ( x : Float, y : Float, xRadius : Float, yRadius : Float, startAngle : Float, endAngle : Float, clockwise : Boolean, rotation : Float ) : this
x, y -- The center of the ellipse offset from the last call.
xRadius -- The radius of the ellipse in the x axis.
yRadius -- The radius of the ellipse in the y axis.
startAngle -- The start angle in radians.
endAngle -- The end angle in radians.
clockwise -- Sweep the ellipse clockwise. Defaults to false.
rotation -- The rotation angle of the ellipse in radians, counterclockwise from the positive X axis. Optional, defaults to 0.
Adds an EllipseCurve to the path, positioned relative to .currentPoint.
.lineTo ( x : Float, y : Float ) : this
Connects a LineCurve from .currentPoint to x, y onto the path.
.moveTo ( x : Float, y : Float ) : this
Move the .currentPoint to x, y.
.quadraticCurveTo ( cpX : Float, cpY : Float, x : Float, y : Float ) : this
Creates a quadratic curve from .currentPoint with cpX and cpY as control point and updates .currentPoint to x and y.
.setFromPoints ( vector2s : Array ) : this
points -- array of Vector2s.
Points are added to the curves array as LineCurves.
.splineThru ( points : Array ) : this
points - An array of Vector2s
Connects a new SplineCurve onto the path.
Shape
Paths with optional holes are used to define an arbitrary 2d shape plane. It can be combined with ExtrudeGeometry and ShapeGeometry to generate points or triangulated faces.
Code Example
const heartShape = new THREE.Shape();
heartShape.moveTo( 25, 25 );
heartShape.bezierCurveTo( 25, 25, 20, 0, 0, 0 );
heartShape.bezierCurveTo( - 30, 0, - 30, 35, - 30, 35 );
heartShape.bezierCurveTo( - 30, 55, - 10, 77, 25, 95 );
heartShape.bezierCurveTo( 60, 77, 80, 55, 80, 35 );
heartShape.bezierCurveTo( 80, 35, 80, 0, 50, 0 );
heartShape.bezierCurveTo( 35, 0, 25, 25, 25, 25 );
const extrudeSettings = { depth: 8, bevelEnabled: true, bevelSegments: 2, steps: 2, bevelSize: 1, bevelThickness: 1 };
const geometry = new THREE.ExtrudeGeometry( heartShape, extrudeSettings );
const mesh = new THREE.Mesh( geometry, new THREE.MeshPhongMaterial() );
Constructor
Shape( points : Array )
points -- (optional) array of Vector2s.
Creates a Shape from the points. The first point defines the offset, then successive points are added to the curves array as LineCurves.
If no points are specified, an empty shape is created and the .currentPoint is set to the origin.
Properties
See the base Path class for common properties.
.uuid : String
UUID of this instance. This gets automatically assigned, so this shouldn't be edited.
.holes : Array
An array of paths that define the holes in the shape.
Methods
See the base Path class for common methods.
.extractPoints ( divisions : Integer ) : Array
divisions -- The fineness of the result.
Call getPoints on the shape and the .holes array, and return an object of the form:
{
shape
holes
}
where shape and holes are arrays of Vector2s.
.getPointsHoles ( divisions : Integer ) : Array
divisions -- The fineness of the result.
Get an array of Vector2s that represent the holes in the shape.
ShapePath
This class is used to convert a series of shapes to an array of Paths, for example an SVG shape to a path.
Constructor
ShapePath( )
Creates a new ShapePath. Unlike a Path, no points are passed in as the ShapePath is designed to be generated after creation.
Properties
.subPaths : Array
Array of Paths.
.currentPath : Array
The current Path that is being generated.
.color : Color
Color of the shape, by default set to white (0xffffff).
Methods
.moveTo ( x : Float, y : Float ) : this
Starts a new Path and calls Path.moveTo( x, y ) on that Path. Also points currentPath to that Path.
.lineTo ( x : Float, y : Float ) : this
This creates a line from the currentPath's offset to X and Y and updates the offset to X and Y.
.quadraticCurveTo ( cpX : Float, cpY : Float, x : Float, y : Float ) : this
This creates a quadratic curve from the currentPath's offset to x and y with cpX and cpY as control point and updates the currentPath's offset to x and y.
.bezierCurveTo ( cp1X : Float, cp1Y : Float, cp2X : Float, cp2Y : Float, x : Float, y : Float ) : this
This creates a bezier curve from the currentPath's offset to x and y with cp1X, cp1Y and cp2X, cp2Y as control points and updates the currentPath's offset to x and y.
.splineThru ( points : Array ) : this
points - An array of Vector2s
Connects a new SplineCurve onto the currentPath.
.toShapes ( isCCW : Boolean, noHoles : Boolean ) : Array
isCCW -- Changes how solids and holes are generated
noHoles -- Whether or not to generate holes
Converts the subPaths array to a Shapes array. Solid shapes are defined clockwise (CW) by default, while holes are defined counterclockwise (CCW). If isCCW is set to true, those are reversed. If the parameter noHoles is set to true, all paths are converted to solid shapes, and the isCCW parameter is ignored.
CatmullRomCurve3
Create a smooth 3d spline curve from a series of points using the Catmull-Rom algorithm.
Code Example
//Create a closed wavey loop
const curve = new THREE.CatmullRomCurve3( [
new THREE.Vector3( -10, 0, 10 ),
new THREE.Vector3( -5, 5, 5 ),
new THREE.Vector3( 0, 0, 0 ),
new THREE.Vector3( 5, -5, 5 ),
new THREE.Vector3( 10, 0, 10 )
] );
const points = curve.getPoints( 50 );
const geometry = new THREE.BufferGeometry().setFromPoints( points );
const material = new THREE.LineBasicMaterial( { color : 0xff0000 } );
// Create the final object to add to the scene
const curveObject = new THREE.Line( geometry, material );
Constructor
CatmullRomCurve3( points : Array, closed : Boolean, curveType : String, tension : Float )
points – An array of Vector3 points
closed – Whether the curve is closed. Default is false.
curveType – Type of the curve. Default is centripetal.
tension – Tension of the curve. Default is 0.5.
Properties
See the base Curve class for common properties.
.points : Array
The array of Vector3 points that define the curve. It needs at least two entries.
.closed : Boolean
The curve will loop back onto itself when this is true.
.curveType : String
Possible values are centripetal, chordal and catmullrom.
.tension : Float
When .curveType is catmullrom, defines catmullrom's tension.
CubicBezierCurve
Create a smooth 2d cubic bezier curve, defined by a start point, endpoint and two control points.
Code Example
const curve = new THREE.CubicBezierCurve(
new THREE.Vector2( -10, 0 ),
new THREE.Vector2( -5, 15 ),
new THREE.Vector2( 20, 15 ),
new THREE.Vector2( 10, 0 )
);
const points = curve.getPoints( 50 );
const geometry = new THREE.BufferGeometry().setFromPoints( points );
const material = new THREE.LineBasicMaterial( { color : 0xff0000 } );
// Create the final object to add to the scene
const curveObject = new THREE.Line( geometry, material );
Constructor
CubicBezierCurve ( v0 : Vector2, v1 : Vector2, v2 : Vector2, v3 : Vector2 )
v0 – The starting point.
v1 – The first control point.
v2 – The second control point.
v3 – The ending point.
Properties
See the base Curve class for common properties.
.v0 : Vector2
The starting point.
.v1 : Vector2
The first control point.
.v2 : Vector2
The second control point.
.v3 : Vector2
The ending point.
CubicBezierCurve3
Create a smooth 3d cubic bezier curve, defined by a start point, endpoint and two control points.
Code Example
const curve = new THREE.CubicBezierCurve3(
new THREE.Vector3( -10, 0, 0 ),
new THREE.Vector3( -5, 15, 0 ),
new THREE.Vector3( 20, 15, 0 ),
new THREE.Vector3( 10, 0, 0 )
);
const points = curve.getPoints( 50 );
const geometry = new THREE.BufferGeometry().setFromPoints( points );
const material = new THREE.LineBasicMaterial( { color : 0xff0000 } );
// Create the final object to add to the scene
const curveObject = new THREE.Line( geometry, material );
Constructor
CubicBezierCurve3( v0 : Vector3, v1 : Vector3, v2 : Vector3, v3 : Vector3 )
v0 – The starting point.
v1 – The first control point.
v2 – The second control point.
v3 – The ending point.
Properties
See the base Curve class for common properties.
.v0 : Vector3
The starting point.
.v1 : Vector3
The first control point.
.v2 : Vector3
The second control point.
.v3 : Vector3
The ending point.
EllipseCurve
Creates a 2d curve in the shape of an ellipse. Setting the xRadius equal to the yRadius will result in a circle.
Code Example
const curve = new THREE.EllipseCurve(
0, 0, // ax, aY
10, 10, // xRadius, yRadius
0, 2 * Math.PI, // aStartAngle, aEndAngle
false, // aClockwise
0 // aRotation
);
const points = curve.getPoints( 50 );
const geometry = new THREE.BufferGeometry().setFromPoints( points );
const material = new THREE.LineBasicMaterial( { color : 0xff0000 } );
// Create the final object to add to the scene
const ellipse = new THREE.Line( geometry, material );
Constructor
EllipseCurve( aX : Float, aY : Float, xRadius : Float, yRadius : Float, aStartAngle : Radians, aEndAngle : Radians, aClockwise : Boolean, aRotation : Radians )
aX – The X center of the ellipse. Default is 0.
aY – The Y center of the ellipse. Default is 0.
xRadius – The radius of the ellipse in the x direction. Default is 1.
yRadius – The radius of the ellipse in the y direction. Default is 1.
aStartAngle – The start angle of the curve in radians starting from the positive X axis. Default is 0.
aEndAngle – The end angle of the curve in radians starting from the positive X axis. Default is 2 x Math.PI.
aClockwise – Whether the ellipse is drawn clockwise. Default is false.
aRotation – The rotation angle of the ellipse in radians, counterclockwise from the positive X axis (optional). Default is 0.
Properties
See the base Curve class for common properties.
.aX : Float
The X center of the ellipse.
.aY : Float
The Y center of the ellipse.
.xRadius : Radians
The radius of the ellipse in the x direction.
.yRadius : Radians
The radius of the ellipse in the y direction.
.aStartAngle : Float
The start angle of the curve in radians starting from the middle right side.
.aEndAngle : Float
The end angle of the curve in radians starting from the middle right side.
.aClockwise : Boolean
Whether the ellipse is drawn clockwise.
.aRotation : Float
The rotation angle of the ellipse in radians, counterclockwise from the positive X axis (optional). Default is 0.
LineCurve
A curve representing a 2d line segment.
Constructor
LineCurve( v1 : Vector2, v2 : Vector2 )
v1 – The start point.
v2 - The end point.
Properties
See the base Curve class for common properties.
.v1 : Vector2
The start point.
.v2 : Vector2
The end point
QuadraticBezierCurve
Create a smooth 2d quadratic bezier curve, defined by a startpoint, endpoint and a single control point.
Code Example
const curve = new THREE.QuadraticBezierCurve(
new THREE.Vector2( -10, 0 ),
new THREE.Vector2( 20, 15 ),
new THREE.Vector2( 10, 0 )
);
const points = curve.getPoints( 50 );
const geometry = new THREE.BufferGeometry().setFromPoints( points );
const material = new THREE.LineBasicMaterial( { color : 0xff0000 } );
// Create the final object to add to the scene
const curveObject = new THREE.Line( geometry, material );
Constructor
QuadraticBezierCurve( v0 : Vector2, v1 : Vector2, v2 : Vector2 )
v0 – The startpoint.
v1 – The control point.
v2 – The endpoint.
Properties
See the base Curve class for common properties.
.v0 : Vector2
The startpoint.
.v1 : Vector2
The control point.
.v2 : Vector2
The endpoint.
QuadraticBezierCurve3
Create a smooth 3d quadratic Bezier curve, defined by a start point, endpoint and a single control point.
Code Example
const curve = new THREE.QuadraticBezierCurve3(
new THREE.Vector3( -10, 0, 0 ),
new THREE.Vector3( 20, 15, 0 ),
new THREE.Vector3( 10, 0, 0 )
);
const points = curve.getPoints( 50 );
const geometry = new THREE.BufferGeometry().setFromPoints( points );
const material = new THREE.LineBasicMaterial( { color : 0xff0000 } );
// Create the final object to add to the scene
const curveObject = new THREE.Line( geometry, material );
Constructor
QuadraticBezierCurve3( v0 : Vector3, v1 : Vector3, v2 : Vector3 )
v0 – The starting point
v1 – The middle control point
v2 – The ending point
Properties
See the base Curve class for common properties.
.v0 : Vector3
The startpoint.
.v1 : Vector3
The control point.
.v2 : Vector3
The endpoint.
SplineCurve
Create a smooth 2d spline curve from a series of points. Internally this uses Interpolations.CatmullRom to create the curve.
Code Example
// Create a sine-like wave
const curve = new THREE.SplineCurve( [
new THREE.Vector2( -10, 0 ),
new THREE.Vector2( -5, 5 ),
new THREE.Vector2( 0, 0 ),
new THREE.Vector2( 5, -5 ),
new THREE.Vector2( 10, 0 )
] );
const points = curve.getPoints( 50 );
const geometry = new THREE.BufferGeometry().setFromPoints( points );
const material = new THREE.LineBasicMaterial( { color : 0xff0000 } );
// Create the final object to add to the scene
const splineObject = new THREE.Line( geometry, material );
Constructor
SplineCurve( points : Array )
points – An array of Vector2 points that define the curve.
Properties
See the base Curve class for common properties.
.points : Array
The array of Vector2 points that defines the curve.