Class Path

A 2D Path representation.

Remarks

The class provides methods for creating paths and contours of 2D shapes similar to the 2D Canvas API.

Example

const {@link 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);

See

Hierarchy (view full)

Constructors

constructor

Properties

arcLengthDivisions autoClose currentPoint curves type

Methods

absarc absellipse add arc bezierCurveTo clone closePath computeFrenetFrames copy ellipse fromJSON getCurveLengths getLength getLengths getPoint getPointAt getPoints getSpacedPoints getTangent getTangentAt getUtoTmapping lineTo moveTo quadraticCurveTo setFromPoints splineThru toJSON updateArcLengths

Constructors

constructor

  • new Path(points?): Path

  • Creates a Path from the points

    Parameters

    Returns Path

    Remarks

    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

arcLengthDivisions

arcLengthDivisions: number

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 Value

200

Remarks

Expects a Integer

autoClose

autoClose: boolean

Whether or not to automatically close the path.

Default Value

false

currentPoint

currentPoint: Vector2

The current offset of the path. Any new Curve added will start here.

Default Value

new THREE.Vector2()

curves

curves: Curve<Vector2>[]

The array of Curves.

Default Value

[]

Readonly type

type: string

A Read-only string to check if this object type.

Remarks

Sub-classes will update this value.

Default Value

Path

Methods

absarc

  • absarc(aX, aY, aRadius, aStartAngle, aEndAngle, aClockwise?): this

  • Adds an absolutely positioned EllipseCurve to the path.

    Parameters

    • aX: number
    • aY: number
    • aRadius: number
    • aStartAngle: number
    • aEndAngle: number
    • Optional aClockwise: boolean

    Returns this

absellipse

  • absellipse(aX, aY, xRadius, yRadius, aStartAngle, aEndAngle, aClockwise?, aRotation?): this

  • Adds an absolutely positioned EllipseCurve to the path.

    Parameters

    • aX: number
    • aY: number
    • xRadius: number

      The radius of the ellipse in the x axis. Expects a Float

    • yRadius: number

      The radius of the ellipse in the y axis. Expects a Float

    • aStartAngle: number
    • aEndAngle: number
    • Optional aClockwise: boolean
    • Optional aRotation: number

    Returns this

add

  • add(curve): void

  • Add a curve to the .curves array.

    Parameters

    Returns void

arc

  • arc(aX, aY, aRadius, aStartAngle, aEndAngle, aClockwise?): this

  • Adds an EllipseCurve to the path, positioned relative to .currentPoint.

    Parameters

    • aX: number
    • aY: number
    • aRadius: number
    • aStartAngle: number
    • aEndAngle: number
    • Optional aClockwise: boolean

    Returns this

bezierCurveTo

  • bezierCurveTo(aCP1x, aCP1y, aCP2x, aCP2y, aX, aY): this

  • This creates a bezier curve from .currentPoint with (cp1X, cp1Y) and (cp2X, cp2Y) as control points and updates .currentPoint to x and y.

    Parameters

    • aCP1x: number
    • aCP1y: number
    • aCP2x: number
    • aCP2y: number
    • aX: number
    • aY: number

    Returns this

clone

  • clone(): this

  • Creates a clone of this instance.

    Returns this

closePath

  • closePath(): this

  • Adds a lineCurve to close the path.

    Returns this

computeFrenetFrames

copy

  • copy(source): this

  • Copies another Curve object to this instance.

    Parameters

    Returns this

ellipse

  • ellipse(aX, aY, xRadius, yRadius, aStartAngle, aEndAngle, aClockwise?, aRotation?): this

  • Adds an EllipseCurve to the path, positioned relative to .currentPoint.

    Parameters

    • aX: number
    • aY: number
    • xRadius: number

      The radius of the ellipse in the x axis. Expects a Float

    • yRadius: number

      The radius of the ellipse in the y axis. Expects a Float

    • aStartAngle: number
    • aEndAngle: number
    • Optional aClockwise: boolean
    • Optional aRotation: number

    Returns this

fromJSON

  • fromJSON(json): this

  • Copies the data from the given JSON object to this instance.

    Parameters

    • json: {}

      Returns this

    getCurveLengths

    • getCurveLengths(): number[]

    • Get list of cumulative curve lengths of the curves in the .curves array.

      Returns number[]

    getLength

    • getLength(): number

    • Get total Curve arc length.

      Returns number

    getLengths

    • getLengths(divisions?): number[]

    • Get list of cumulative segment lengths.

      Parameters

      • Optional divisions: number

        Expects a Integer

      Returns number[]

    getPoint

    • getPoint(t, optionalTarget?): Vector2

    • Returns a vector for a given position on the curve.

      Parameters

      • t: number

        A position on the curve. Must be in the range [ 0, 1 ]. Expects a Float

      • Optional optionalTarget: Vector2

        If specified, the result will be copied into this Vector, otherwise a new Vector will be created. Default new T.

      Returns Vector2

    getPointAt

    • getPointAt(u, optionalTarget?): Vector2

    • Returns a vector for a given position on the Curve according to the arc length.

      Parameters

      • u: number

        A position on the Curve according to the arc length. Must be in the range [ 0, 1 ]. Expects a Float

      • Optional optionalTarget: Vector2

        If specified, the result will be copied into this Vector, otherwise a new Vector will be created. Default new T.

      Returns Vector2

    getPoints

    • getPoints(divisions?): Vector2[]

    • Returns an array of points representing a sequence of curves

      Parameters

      • Optional divisions: number

        Number of pieces to divide the curve into. Expects a Integer. Default 12

      Returns Vector2[]

      Remarks

      The division parameter defines the number of pieces each curve is divided into However, for optimization and quality purposes, the actual sampling resolution for each curve depends on its type For example, for a LineCurve, the returned number of points is always just 2.

    getSpacedPoints

    • getSpacedPoints(divisions?): Vector2[]

    • Returns a set of divisions +1 equi-spaced points using .getPointAt | getPointAt(u).

      Parameters

      • Optional divisions: number

        Number of pieces to divide the curve into. Expects a Integer. Default 40

      Returns Vector2[]

    getTangent

    • getTangent(t, optionalTarget?): Vector2

    • Returns a unit vector tangent at t

      Parameters

      • t: number

        A position on the curve. Must be in the range [ 0, 1 ]. Expects a Float

      • Optional optionalTarget: Vector2

        If specified, the result will be copied into this Vector, otherwise a new Vector will be created.

      Returns Vector2

      Remarks

      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

    • getTangentAt(u, optionalTarget?): Vector2

    • Returns tangent at a point which is equidistant to the ends of the Curve from the point given in .getTangent.

      Parameters

      • u: number

        A position on the Curve according to the arc length. Must be in the range [ 0, 1 ]. Expects a Float

      • Optional optionalTarget: Vector2

        If specified, the result will be copied into this Vector, otherwise a new Vector will be created.

      Returns Vector2

    getUtoTmapping

    • getUtoTmapping(u, distance): number

    • Given u in the range [ 0, 1 ],

      Parameters

      • u: number

        Expects a Float

      • distance: number

        Expects a Float

      Returns number

      t also in the range [ 0, 1 ]. Expects a Float.

      Remarks

      u and t can then be used to give you points which are equidistant from the ends of the curve, using .getPoint.

    lineTo

    • lineTo(x, y): this

    • Connects a LineCurve from .currentPoint to x, y onto the path.

      Parameters

      • x: number

        Expects a Float

      • y: number

        Expects a Float

      Returns this

    moveTo

    • moveTo(x, y): this

    • Move the .currentPoint to x, y.

      Parameters

      • x: number

        Expects a Float

      • y: number

        Expects a Float

      Returns this

    quadraticCurveTo

    • quadraticCurveTo(aCPx, aCPy, aX, aY): this

    • Creates a quadratic curve from .currentPoint with cpX and cpY as control point and updates .currentPoint to x and y.

      Parameters

      • aCPx: number
      • aCPy: number
      • aX: number
      • aY: number

      Returns this

    setFromPoints

    • setFromPoints(vectors): this

    • Points are added to the curves array as LineCurves.

      Parameters

      Returns this

    splineThru

    • splineThru(pts): this

    • Connects a new SplineCurve onto the path.

      Parameters

      Returns this

    toJSON

    • toJSON(): {}

    • Returns a JSON object representation of this instance.

      Returns {}

      updateArcLengths

      • updateArcLengths(): void

      • Update the cumulative segment distance cache

        Returns void

        Remarks

        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.

      Settings

      Member Visibility

      On This Page

      constructorarcLengthDivisionsautoClosecurrentPointcurvestypeabsarcabsellipseaddarcbezierCurveTocloneclosePathcomputeFrenetFramescopyellipsefromJSONgetCurveLengthsgetLengthgetLengthsgetPointgetPointAtgetPointsgetSpacedPointsgetTangentgetTangentAtgetUtoTmappinglineTomoveToquadraticCurveTosetFromPointssplineThrutoJSONupdateArcLengths