H3DU.GraphicsPath

Back to documentation index.

### new H3DU.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 H3DU.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

### H3DU.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)

### H3DU.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)

### H3DU.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)

### H3DU.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)

### H3DU.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)

### H3DU.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)

### H3DU.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)

### H3DU.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)

### H3DU.GraphicsPath#closePath()

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

Return Value

This object. (Type: GraphicsPath)

### H3DU.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)

### H3DU.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)

### H3DU.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) H3DU.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")

### H3DU.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>)

### H3DU.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>)

### H3DU.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:<ul>

  • getCurves() - Returns a list of curve evaluator objects described by this path. The list will contain one curve evaluator object for each disconnected portion of the path. For example, if the path contains one polygon, the list will contain one curve object. And if the path is empty, the list will be empty too. Each curve takes U coordinates that range from 0 to 1, depending on how far the point is from the start or the end of the path (similar to arc-length parameterization). Each curve returns a 3-element array containing the X, Y, and Z coordinates of the point lying on the curve at the given "u" position (however, the z will always be 0 since paths can currently only be 2-dimensional). </ul> (Type: Object) ### H3DU.GraphicsPath#getLinePoints([flatness]) Gets an array of the end points of line segments approximating the path. #### Parameters * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. #### Return Value Array of the end points of line segments approximating the path. (Type: Array.<Array.<number>>) ### H3DU.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 * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. #### 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); ### H3DU.GraphicsPath#getLines([flatness]) Gets an array of line segments approximating the path. #### Parameters * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. #### 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>>) ### H3DU.GraphicsPath#getPoints(numPoints) Gets an array of points evenly spaced across the length of the path. #### Parameters * `numPoints` (Type: number)
    Number of points to return. #### 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>>) ### H3DU.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 * `numPoints` (Type: number)
    Number of points to return. #### 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); ### H3DU.GraphicsPath#getSubpaths() TODO: Not documented yet. #### Return Value Return value. (Type: *) ### H3DU.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 * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. #### 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>>) ### H3DU.GraphicsPath#interpolate(other, t) Does a linear interpolation between two graphics paths. #### Parameters * `other` (Type: GraphicsPath)
    The second graphics path. * `t` (Type: number)
    An interpolation factor, generally ranging from 0 through 1. Closer to 0 means closer to this path, and closer to 1 means closer to "other". If the input paths contain arc segments that differ in the large arc and sweep flags, the flags from the first path's arc are used if "t" is less than 0.5; and the flags from the second path's arc are used otherwise. 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) ### H3DU.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 * `path` (Type: GraphicsPath)
    A path to combine with this one. * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. #### Return Value A path whose shape is contained in both paths. (Type: GraphicsPath) ### H3DU.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) ### H3DU.GraphicsPath#line(x0, y0, x1, y1) Adds a line segment to this path. #### Parameters * `x0` (Type: number)
    X coordinate of the line segment's starting point. The moveTo method will be called on the starting point. * `y0` (Type: number)
    Y coordinate of the line segment's starting point. * `x1` (Type: number)
    X coordinate of the line segment's ending point. The lineTo method will be called on the ending point. * `y1` (Type: number)
    X coordinate of the line segment's ending point. #### Return Value This object. (Type: GraphicsPath) ### H3DU.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 * `x` (Type: number)
    X coordinate of the end of the line segment. * `y` (Type: number)
    Y coordinate of the end of the line segment. #### Return Value This object. (Type: GraphicsPath) ### H3DU.GraphicsPath#merge(path) Merges the path segments in another path onto this one. #### Parameters * `path` (Type: GraphicsPath)
    Another graphics path. Can be null. #### Return Value This object. (Type: GraphicsPath) ### H3DU.GraphicsPath#moveTo(x, y) Moves the current start position and end position to the given position. #### Parameters * `x` (Type: number)
    X coordinate of the position. * `y` (Type: number)
    Y coordinate of the position. #### Return Value This object. (Type: GraphicsPath) ### H3DU.GraphicsPath#pathLength([flatness]) Finds the approximate length of this path. #### Parameters * `flatness` (Type: number) (optional)
    No longer used by this method. #### Return Value Approximate length of this path in units. (Type: number) ### H3DU.GraphicsPath#polyline(pointCoords, closed) Adds path segments to this path that form a polygon or a connected line segment strand. #### Parameters * `pointCoords` (Type: Array.<number>)
    An array of numbers containing the X and Y coordinates of each point in the sequence of line segments. Each pair of numbers gives the X and Y coordinates, in that order, of one of the points in the sequence. The number of elements in the array must be even. If two or more pairs of numbers are given, line segments will connect each point given (except the last) to the next point given. * `closed` (Type: number)
    If "true", the sequence of points describes a closed polygon and a command to close the path will be added to the path (even if only one pair of numbers is given in "pointCoords"). #### 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) ### H3DU.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 * `x` (Type: number)
    X coordinate of the curve's second control point. * `y` (Type: number)
    Y coordinate of the curve's second control point. * `x2` (Type: number)
    X coordinate of the curve's end point (third control point). * `y2` (Type: number)
    Y coordinate of the curve's end point (third control point). #### Return Value This object. (Type: GraphicsPath) ### H3DU.GraphicsPath#rect(x, y, w, h) Adds path segments to this path that form an axis-aligned rectangle. #### Parameters * `x` (Type: number)
    X coordinate of the rectangle's upper-left corner (assuming the coordinate system's X axis points right and the Y axis down). * `y` (Type: number)
    Y coordinate of the rectangle's upper-left corner (assuming the coordinate system's X axis points right and the Y axis down). * `w` (Type: number)
    Width of the rectangle. * `h` (Type: number)
    Height of the rectangle. #### Return Value This object. If "w" or "h" is 0, no path segments will be appended. (Type: GraphicsPath) ### H3DU.GraphicsPath#regularPolygon(cx, cy, sides, radius, [phaseInDegrees]) Adds path segments to this path that form a regular polygon. #### Parameters * `cx` (Type: number)
    X coordinate of the center of the polygon. * `cy` (Type: number)
    Y coordinate of the center of the polygon. * `sides` (Type: number)
    Number of sides the polygon has. Nothing will be added to the path if this value is 2 or less. * `radius` (Type: number)
    Radius from the center to each vertex of the polygon. * `phaseInDegrees` (Type: number) (optional)
    Starting angle of the first vertex of the polygon, in degrees. 0 means the positive X axis, 90 means the positive Y axis, 180 means the negative X axis, and 270 means the negative Y axis. If null, undefined, or omitted, the default is 0. #### Return Value This object. (Type: GraphicsPath) ### H3DU.GraphicsPath#regularStar(cx, cy, points, radiusOut, radiusIn, phaseInDegrees) Adds path segments to this path that form a regular N-pointed star. #### Parameters * `cx` (Type: number)
    X coordinate of the center of the star. * `cy` (Type: number)
    Y coordinate of the center of the star. * `points` (Type: number)
    Number of points the star has. Nothing will be added to the path if this value is 0 or less. * `radiusOut` (Type: number)
    Radius from the center to each outer vertex of the star. * `radiusIn` (Type: number)
    Radius from the center to each inner vertex of the star. * `phaseInDegrees` (Type: number)
    Starting angle of the first vertex of the polygon, in degrees. 0 means the positive X axis, 90 means the positive Y axis, 180 means the negative X axis, and 270 means the negative Y axis. #### Return Value This object. (Type: GraphicsPath) ### H3DU.GraphicsPath#reverse() Returns a path that reverses the course of this path. #### Return Value A GraphicsPath object with its path segments reversed. (Type: GraphicsPath) ### H3DU.GraphicsPath#roundRect(x, y, w, h, arccx, arccy) Adds path segments to this path that form an axis-aligned rounded rectangle. #### Parameters * `x` (Type: number)
    X coordinate of the rectangle's upper-left corner (assuming the coordinate system's X axis points right and the Y axis down). * `y` (Type: number)
    Y coordinate of the rectangle's upper-left corner (assuming the coordinate system's X axis points right and the Y axis down). * `w` (Type: number)
    Width of the rectangle. * `h` (Type: number)
    Height of the rectangle. * `arccx` (Type: number)
    Horizontal extent (from end to end) of the ellipse formed by each arc that makes up the rectangle's corners. Will be adjusted to be not less than 0 and not greater than "w". * `arccy` (Type: number)
    Vertical extent (from end to end) of the ellipse formed by each arc that makes up the rectangle's corners. Will be adjusted to be not less than 0 and not greater than "h". #### Return Value This object. If "w" or "h" is less than 0, no path segments will be appended. (Type: GraphicsPath) ### H3DU.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) ### H3DU.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 * `zStart` (Type: number)
    Starting Z coordinate of the mesh buffer's "walls". * `zEnd` (Type: number)
    Ending Z coordinate of the mesh buffer's "walls". * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. * `closed` (Type: boolean) (optional)
    If true, the generated mesh buffer will include a base and top. If null, undefined, or omitted, the default is false. #### Return Value The resulting mesh buffer. (Type: MeshBuffer) ### H3DU.GraphicsPath#toLineMeshBuffer([z], [flatness]) Generates a mesh buffer consisting of the approximate line segments that make up this graphics path. #### Parameters * `z` (Type: number) (optional)
    Z coordinate for each line segment. If null, undefined, or omitted, the default is 0. * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. #### Return Value The resulting mesh buffer. (Type: MeshBuffer) ### H3DU.GraphicsPath#toLinePath([flatness]) Creates a path in which curves and arcs are decomposed to line segments. #### Parameters * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. #### Return Value A path consisting only of line segments and close commands. (Type: GraphicsPath) ### H3DU.GraphicsPath#toMeshBuffer([z], [flatness]) TODO: Not documented yet. #### Parameters * `z` (Type: number) (optional)
    The Z coordinate of each triangle generated. If null, undefined, or omitted, default is 0. * `flatness` (Type: number) (optional)
    When curves and arcs are decomposed to line segments, the segments will be close to the true path of the curve by this value, given in units. If null, undefined, or omitted, default is 1. #### Return Value The resulting mesh buffer. (Type: MeshBuffer) ### H3DU.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) ### H3DU.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 * `trans` (Type: Array.<number>)
    An array of six numbers describing a 2-dimensional affine transformation. For each point in the current path, its new X coordinate is `trans[0] \* X + trans[2] \* Y + trans[4]`, and its new Y coordinate is `trans[1] \* X + trans[3] \* Y + trans[5]`. #### Return Value The transformed version of this path. (Type: GraphicsPath) ### H3DU.GraphicsPath#union(path, [flatness]) Computes the combination of this path's shape with another path's shape. The following points apply to this method: