Menu - Top - Home - Donate to Me

H3DU.GraphicsPath

Back to documentation index.

H3DU.GraphicsPath()

Represents a two-dimensional path.

This class is considered a supplementary class to the Public Domain HTML 3D Library and is not considered part of that library.

To use this class, you must include the script "extras/path.js"; the class is not included in the "h3du_min.js" file which makes up the HTML 3D Library. Example:

<script type="text/javascript" src="extras/path.js"></script>

Some methods may be defined in other scripts, in which case the script to be included this way will be mentioned.

Parameters

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: H3DU.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: H3DU.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: H3DU.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: H3DU.GraphicsPath)

GraphicsPath#closePath()

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

Return Value

This object. (Type: H3DU.GraphicsPath)

GraphicsPath#difference(path, [flatness])

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

Parameters

Return Value

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

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([flatness])

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

Parameters

Return Value

A curve evaluator object that implements the following additional method:

(Type: Object)

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, [flatness])

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#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 H3DU.Math.vec3lerp for examples of interpolation functions.

Return Value

The interpolated path. (Type: H3DU.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 H3DU.GraphicsPath#union method apply to this method.

Parameters

Return Value

A path whose shape is contained in both paths. (Type: H3DU.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#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: H3DU.GraphicsPath)

GraphicsPath#merge(path)

Merges the path segments in another path onto this one.

Parameters

Return Value

This object. (Type: H3DU.GraphicsPath)

GraphicsPath#moveTo(x, y)

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

Parameters

Return Value

This object. (Type: H3DU.GraphicsPath)

GraphicsPath#pathLength([flatness])

Finds the approximate length of this path.

Parameters

Return Value

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

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: H3DU.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: H3DU.GraphicsPath)

GraphicsPath#reverse()

Returns a path that reverses the course of this path.

Return Value

A GraphicsPath object with its path segments reversed. (Type: H3DU.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: H3DU.GraphicsPath)

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: H3DU.GraphicsPath)

GraphicsPath#toString()

Returns this path in the form of a string in SVG path format. See H3DU.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: H3DU.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: H3DU.GraphicsPath)

GraphicsPath#xor(path, [flatness])

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

Parameters

Return Value

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

(static) H3DU.GraphicsPath.GraphicsPath.fromString(str)

Creates a graphics path from a string whose format follows the SVG specification.

Parameters

Return Value

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

Example

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

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

H3DU.GraphicsPath#arcShape(cx, cy, 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.

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

Parameters

Return Value

This object. If "w" or "h" is 0, no path segments will be appended. (Type: H3DU.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.

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

Parameters

Return Value

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

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

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

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

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

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

Parameters

Return Value

This object. If "w" or "h" is 0, no path segments will be appended. (Type: H3DU.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.

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

Parameters

Return Value

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

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

Adds a line segment to this path.

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

Parameters

Return Value

This object. (Type: H3DU.GraphicsPath)

H3DU.GraphicsPath#polyline(pointCoords, closed)

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

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

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: H3DU.GraphicsPath)

H3DU.GraphicsPath#regularPolygon(cx, cy, sides, radius, phaseInDegrees)

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

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

Parameters

Return Value

This object. (Type: H3DU.GraphicsPath)

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

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

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

Parameters

Return Value

This object. (Type: H3DU.GraphicsPath)

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

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

To use this method, you must include the script "extras/pathshapes.js"; this is in addition to "extras/path.js". Example:

<script type="text/javascript" src="extras/path.js"></script>
<script type="text/javascript" src="extras/pathshapes.js"></script>

Parameters

Return Value

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

Back to documentation index.