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.