GraphicsPath

Back to documentation index.

new GraphicsPath()

Represents a two-dimensional path. A path is a collection of two-dimensional line segments and/or curves. Many paths describe closed figures or connected sequences of lines and curves. Specifically, a path is made up of straight line segments, elliptical arcs, quadratic Bézier curves, cubic Bézier curves, or any combination of these, and the path can be discontinuous and/or contain closed parts.

Creating Paths

There are two ways to create paths: using an SVG path string (see GraphicsPath.fromString), or by calling methods that add its segments.

A GraphicsPath object stores a current position and a starting position, and many methods don't have you specify a starting position, to cover the common case of drawing a series of connected lines and curves. .moveTo(x, y) - Moves the starting position and current position. .lineTo(x, y) - Adds a line segment from the current position to a new ending position. .closePath() - Closes the path by drawing a line to the starting point, if needed.

Path Segments

Each path can include a number of line segments, Bézier curves, and elliptical arcs. Line segments are relatively easy to understand. The other two kinds of segments deserve some discussion. A Bézier curve is a parametric curve based on a polynomial formula. In this kind of curve the endpoints are defined as they are, but the other points define the shape of the curve and generally don't cross the curve. A quadratic Bézier curve uses 3 points. A cubic Bézier curve uses 4 points. An elliptical arc is a curve which forms part of an ellipse. There are several ways to parameterize an elliptical arc, as seen in the .arc(), .arcTo(), and .arcSvgTo() methods of the GraphicsPath class.

Methods

GraphicsPath#arc(x, y, radius, startAngle, endAngle, ccw)

Adds path segments in the form of a circular arc to this path, using the parameterization specified in the "arc" method of the HTML Canvas 2D Context.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#arcShape(x, y, w, h, start, sweep, type)

Adds path segments to this path that form an arc running along an axis-aligned ellipse, or a shape based on that arc and ellipse, given the ellipse's center and dimensions, start angle, and sweep angle.

Parameters

Return Value

This object. If "w" or "h" is 0, no path segments will be appended. (Type: GraphicsPath)

GraphicsPath#arcShapeForBox(x, y, w, h, start, sweep, type)

Adds path segments to this path that form an arc running along an axis-aligned ellipse, or a shape based on that arc and ellipse, given the ellipse's corner point and dimensions, start angle, and sweep angle.

Parameters

Return Value

This object. If "w" or "h" is 0, no path segments will be appended. (Type: GraphicsPath)

GraphicsPath#arcSvgTo(rx, ry, rot, largeArc, sweep, x2, y2)

Adds path segments in the form of an elliptical arc to this path, using the parameterization used by the SVG specification.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#arcTo(x1, y1, x2, y2, radius)

Adds path segments in the form of a circular arc to this path, using the parameterization specified in the "arcTo" method of the HTML Canvas 2D Context.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#arrow(x0, y0, x1, y1, headWidth, headLength, tailWidth)

Adds path segments to this path in the form of an arrow shape.

Parameters

Return Value

This object. Nothing will be added to the path if the distance from (x0, y0) and (x1, y1) is 0 or extremely close to 0. (Type: GraphicsPath)

GraphicsPath#bevelRect(x, y, w, h, arccx, arccy)

Adds path segments to this path that form an axis-aligned rectangle with beveled corners.

Parameters

Return Value

This object. If "w" or "h" is less than 0, no path segments will be appended. (Type: GraphicsPath)

GraphicsPath#bezierCurveTo(x, y, x2, y2, x3, y3)

Adds a cubic Bézier curve to this path starting at this path's current position. The current position will be the curve's first control point.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#closePath()

Makes this path closed. Adds a line segment to the path's start position, if necessary.

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#difference(path, [flatness])

Computes the difference between this path's shape and another path's shape. The points given in the GraphicsPath#union method apply to this method.

Parameters

Return Value

The difference between this path and the other path. (Type: GraphicsPath)

GraphicsPath#ellipse(cx, cy, w, h)

Adds path segments to this path that form an axis-aligned ellipse given its center and dimensions.

Parameters

Return Value

This object. If "w" or "h" is 0, no path segments will be appended. (Type: GraphicsPath)

GraphicsPath#ellipseForBox(x, y, w, h)

Adds path segments to this path that form an axis-aligned ellipse, given the ellipse's corner point and dimensions.

Parameters

Return Value

This object. If "w" or "h" is 0, no path segments will be appended. (Type: GraphicsPath)

(static) GraphicsPath.fromString(str)

Creates a graphics path from a string whose format follows the SVG (Scalable Vector Graphics) specification.

Parameters

Return Value

The resulting path. If an error occurs while parsing the path, the path's "isIncomplete()" method will return true. (Type: GraphicsPath)

Examples

The following example creates a graphics path from an SVG string describing a polyline.

var path=GraphicsPath.fromString("M10,20L40,30,24,32,55,22")

The following example creates a graphics path from an SVG string describing a curved path.

var path=GraphicsPath.fromString("M50,20C230,245,233,44,22,44")

GraphicsPath#getBounds()

Calculates an axis-aligned bounding box that tightly fits this graphics path.

Return Value

An array of four numbers describing the bounding box. The first two are the lowest X and Y coordinates, and the last two are the highest X and Y coordinates. If the path is empty, returns the array (Infinity, Infinity, -Infinity, -Infinity). (Type: Array.<number>)

GraphicsPath#getCurrentPoint()

Gets the current point stored in this path.

Return Value

A two-element array giving the X and Y coordinates of the current point. (Type: Array.<number>)

GraphicsPath#getCurves()

Gets a curve evaluator object for the curves described by this path. The return value doesn't track changes to the path.

Return Value

A curve evaluator object that implements the following additional method:

(Type: Object)

GraphicsPath#getLinePoints([flatness])

Gets an array of the end points of line segments approximating the path.

Parameters

Return Value

Array of the end points of line segments approximating the path. (Type: Array.<Array.<number>>)

GraphicsPath#getLinePointsAsObjects([flatness])

Gets an array of the end points of line segments approximating the path. The positions will be in the form of objects with two properties: x and y retrieve the X or Y coordinate of each position, respectively.

Parameters

Return Value

Array of the end points of line segments approximating the path. (Type: Array.<Array.<number>>)

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=path.getLinePointsAsObjects()
var buffer=new THREE.BufferGeometry()
.setFromPoints(points);

GraphicsPath#getLines([flatness])

Gets an array of line segments approximating the path.

Parameters

Return Value

Array of line segments. Each line segment is an array of four numbers: the X and Y coordinates of the start point, respectively, then the X and Y coordinates of the end point, respectively. (Type: Array.<Array.<number>>)

GraphicsPath#getPoints(numPoints)

Gets an array of points evenly spaced across the length of the path.

Parameters

Return Value

Array of points lying on the path and evenly spaced across the length of the path, starting and ending with the path's endPoints. Returns an empty array if numPoints is less than 1. Returns an array consisting of the start point if numPoints is 1. (Type: Array.<Array.<number>>)

GraphicsPath#getPointsAsObjects(numPoints)

Gets an array of points evenly spaced across the length of the path. The positions will be in the form of objects with two properties: x and y retrieve the X or Y coordinate of each position, respectively.

Parameters

Return Value

Array of points lying on the path and evenly spaced across the length of the path, starting and ending with the path's endPoints. Returns an empty array if numPoints is less than 1. Returns an array consisting of the start point if numPoints is 1. (Type: Array.<Array.<number>>)

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=path.getPointsAsObjects(50)
var buffer=new THREE.BufferGeometry()
.setFromPoints(points);

GraphicsPath#getSubpaths()

Creates an array of the disconnected portions of this path.

Return Value

An array containing a GraphicsPath object for each disconnected portion of this path. Returns an empty array if this path has no subpaths. (Type: Array.<GraphicsPath>)

GraphicsPath#getTriangles([flatness])

Converts the subpaths in this path to triangles. Treats each subpath as a polygon even if it isn't closed. Each subpath should not contain self-intersections or duplicate vertices, except duplicate vertices that appear consecutively or at the start and end.

The path can contain holes. In this case, subpaths whose winding order (counterclockwise or clockwise) differs from the first subpath's winding order can be holes.

Parameters

Return Value

Array of six-element arrays each describing a single triangle. For each six-element array, the first two, next two, and last two numbers each describe a vertex position of that triangle (X and Y coordinates in that order). (Type: Array.<Array.<number>>)

GraphicsPath#interpolate(other, t)

Does a linear interpolation between two graphics paths.

Parameters

For a nonlinear interpolation, define a function that takes a value that usually ranges from 0 through 1 and generally returns a value that usually ranges from 0 through 1, and pass the result of that function to this method. See the documentation for MathUtil.vec3lerp for examples of interpolation functions.

Return Value

The interpolated path. (Type: GraphicsPath)

GraphicsPath#intersection(path, [flatness])

Computes the intersection, or the area common to both this path's shape and another path's shape. The points given in the GraphicsPath#union method apply to this method.

Parameters

Return Value

A path whose shape is contained in both paths. (Type: GraphicsPath)

GraphicsPath#isIncomplete()

Returns whether the curve path is incomplete because of an error in parsing the curve string. This flag will be reset if a moveTo command, closePath command, or another path segment is added to the path.

Return Value

Return value. (Type: boolean)

GraphicsPath#line(x0, y0, x1, y1)

Adds a line segment to this path.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#lineTo(x, y)

Adds a line segment to the path, starting at the path's end position, then sets the end position to the end of the segment.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#merge(path)

Merges the path segments in another path onto this one.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#moveTo(x, y)

Moves the current start position and end position to the given position.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#pathLength([flatness])

Finds the approximate length of this path.

Parameters

Return Value

Approximate length of this path in units. (Type: number)

GraphicsPath#polyline(pointCoords, closed)

Adds path segments to this path that form a polygon or a connected line segment strand.

Parameters

Return Value

This object. If "pointCoords" is empty, no path segments will be appended. Throws an error if "pointCoords" has an odd length. (Type: GraphicsPath)

GraphicsPath#quadraticCurveTo(x, y, x2, y2)

Adds a quadratic Bézier curve to this path starting at this path's current position. The current position will be the curve's first control point.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#rect(x, y, w, h)

Adds path segments to this path that form an axis-aligned rectangle.

Parameters

Return Value

This object. If "w" or "h" is 0, no path segments will be appended. (Type: GraphicsPath)

GraphicsPath#regularPolygon(cx, cy, sides, radius, [phaseInDegrees])

Adds path segments to this path that form a regular polygon.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#regularStar(cx, cy, points, radiusOut, radiusIn, phaseInDegrees)

Adds path segments to this path that form a regular N-pointed star.

Parameters

Return Value

This object. (Type: GraphicsPath)

GraphicsPath#reverse()

Returns a path that reverses the course of this path.

Return Value

A GraphicsPath object with its path segments reversed. (Type: GraphicsPath)

GraphicsPath#roundRect(x, y, w, h, arccx, arccy)

Adds path segments to this path that form an axis-aligned rounded rectangle.

Parameters

Return Value

This object. If "w" or "h" is less than 0, no path segments will be appended. (Type: GraphicsPath)

GraphicsPath#toCurvePath()

Creates a path in which arcs are decomposed to cubic Bézier curves (which will approximate those arcs).

Return Value

A path consisting only of line segments, Bézier curves, and close commands. (Type: GraphicsPath)

GraphicsPath#toExtrudedMeshBuffer(zStart, zEnd, [flatness], [closed])

Generates a mesh buffer consisting of "walls" that follow this graphics path approximately, and, optionally, a base and toop.

Parameters

Return Value

The resulting mesh buffer. (Type: MeshBuffer)

GraphicsPath#toLineMeshBuffer([z], [flatness])

Generates a mesh buffer consisting of the approximate line segments that make up this graphics path.

Parameters

Return Value

The resulting mesh buffer. (Type: MeshBuffer)

GraphicsPath#toLinePath([flatness])

Creates a path in which curves and arcs are decomposed to line segments.

Parameters

Return Value

A path consisting only of line segments and close commands. (Type: GraphicsPath)

GraphicsPath#toMeshBuffer([z], [flatness])

Decomposes this path into triangles and generates a mesh buffer with those triangles. Each triangle's normal will point toward the Z axis, and each triangle vertex's texture coordinates will be the same as that vertex's position.

Parameters

Return Value

The resulting mesh buffer. (Type: MeshBuffer)

GraphicsPath#toString()

Returns this path in the form of a string in SVG path format. See GraphicsPath.fromString.

Return Value

A string describing the path in the SVG path format. (Type: string)

GraphicsPath#transform(trans)

Returns a modified version of this path that is transformed according to the given affine transformation (a transformation that keeps straight lines straight and parallel lines parallel).

Parameters

Return Value

The transformed version of this path. (Type: GraphicsPath)

GraphicsPath#union(path, [flatness])

Computes the combination of this path's shape with another path's shape. The following points apply to this method:

Parameters

Return Value

The union of the two paths. (Type: GraphicsPath)

GraphicsPath#xor(path, [flatness])

Computes the shape contained in either this path or another path, but not both. The points given in the GraphicsPath#union method apply to this method.

Parameters

Return Value

A path whose shape is contained in only one of the two paths. (Type: GraphicsPath)

Back to documentation index.