Version: 4.1

Path

constructor

g.Path(segments)

Return a new path object consisting of path segments provided.

The path returned is not guaranteed to be a valid path (i.e. its path data might not be immediately usable as a d attribute of an SVG DOM element). This happens when the segments array does not start with a Moveto segment. The path.isValid() function may be used to test whether the path is valid. Use the path.validate() function to fix invalid paths.

The constructor also accepts an array of Line and/or Curve objects as an argument. Then, path segments are generated using this array. An initial Moveto segment is added, and additional Moveto segments are insterted between any two disconnected objects (the end point of one is not the start point of another).

It is not necessary to pass single-element arrays to the constructor; a single Segment, Line or Curve object is accepted as well.

Alternatively, the constructor accepts a Polyline object as an argument; Lineto path segments are generated to connect the polyline's points.

Finally, the constructor accepts a path data string as an argument; then the g.Path.parse() function is used to generate path segments.

Methods

appendSegment()

path.appendSegment(segment)

Append segment to the path.

Also accepts an array of segments as an argument. The segments are appended in the order they appear in the provided array.

The function does not return anything.

bbox()

path.bbox()

Return a rectangle that is the tight bounding box of the path (i.e. without curve control points).

Invisible path segments do not affect the bounding box. If the path contains no visible segments, a bounding box with 0 width and 0 height is returned, with the coordinates of the end point of the last path segment. If the path has no segments at all, null is returned.

clone()

path.clone()

Return another path which is a clone of the path.

closestPoint()

path.closestPoint(point [, opt])

Return the point on the path that lies closest to point.

Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm. If the path contains no visible segments, the end point of the last segment is returned. If the path has no segments at all, null is returned.

The function uses the same algorithm as the path.closestPointLength() function. It finds a visible segment whose identified closest point lies at the lowest distance from point.

The opt argument is optional. Two properties may be specified, opt.precision and opt.segmentSubdivisions, which determine maximum error allowed in segment closestPoint calculations for curved segments (default precision is 3; this corresponds to maximum observed error of 0.1%). The opt.segmentSubdivisions property is an array of individual segments' subdivision arrays. The path.getSegmentSubdivisions() function may be used to obtain the segmentSubdivisions array. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm in curved segments.

closestPointLength()

path.closestPointLength(point [, opt])

Return the length of the path up to the point that lies closest to point.

Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm; if the path contains no visible segments, 0 is returned. If the path has no segments at all, 0 is returned.

The function finds a visible segment whose identified closest point lies at the lowest distance from point. It then determines the length of the path up to the identified closest point.

closestPointNormalizedLength()

path.closestPointNormalizedLength(point [, opt])

Return the normalized length (distance from the start of the path / total path length) of the path up to the point that lies closest to point.

The function uses the same algorithm as the path.closestPointLength() function. It finds a visible segment whose identified closest point lies at the lowest distance from point. It then determines the normalized length of the path up to the identified closest point.

closestPointT()

path.closestPointT(point [, opt])

Private helper method.

Returns a t object that simplifies calculations for other path.closestPoint functions.

closestPointTangent()

path.closestPointTangent(point [, opt])

Return a line that is tangent to the path at the point that lies closest to point.

If the identified closest point is a point of discontinuity (e.g. it is a point shared by two Lineto segments with different slopes), the tangent line is constructed for the earlier segment (i.e. the segment closer to the beginning of the path).

The tangent line starts at the identified closest point. The direction from start to end is the same as the direction of the curve at the closest point.

The algorithm skips over segments that are not differentiable. This includes all invisible segments (e.g. Moveto segments) and visible segments with zero length. If the path contains no valid segments, null is returned. If the path has no segments at all, null is returned, as well. The segment.isDifferentiable() functions may be used to determine whether a given segment is valid; the path.isDifferentiable() function may be used to determine whether the path contains at least one valid segment.

The function finds a valid segment whose identified closest point lies at the lowest distance from point. It then finds a tangent to the segment at the identified closest point.

containsPoint()

path.containsPoint(p [, opt])

Return true if the point p is inside the area surrounded by the path (inclusive). Return false otherwise. Uses the even-odd algorithm to resolve self-intersections.

Uses the path.toPolylines() function in the background. The precision of the calculation may be adjusted by passing the opt.precision and opt.subdivisions properties.

divideAt()

path.divideAt(ratio [, opt])

Divide the path into two paths at the point that lies ratio (normalized length) away from the beginning of the path.

Returns an array with two new paths without modifying the original path. The returned paths are valid; that is, they both start with an appropriate Moveto segment. Additionally, Closepath segments are converted into Lineto segments if necessary. The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively. Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm. If the path contains no visible segments, null is returned.

The function uses the same algorithm as the path.divideAtLength() function. It finds a visible segment which contains the point at length that corresponds to given ratio and then calls the segment's divideAtLength() function.

The opt argument is optional. Two properties may be specified, opt.precision and opt.segmentSubdivisions, which determine maximum error allowed in divideAtLength calculations for curved segments (default precision is 3; this corresponds to maximum observed error of 0.1%). The opt.segmentSubdivisions property is an array of individual segments' subdivision arrays. The path.getSegmentSubdivisions() function may be used to obtain the segmentSubdivisions array. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm in curved segments.

divideAtLength()

path.pointAtLength(length [, opt])

Divide the path into two paths at the point that lies length away from the beginning of the path.

Returns an array with two new paths without modifying the original path. The returned paths are valid; that is, they both start with an appropriate Moveto segment. Additionally, Closepath segments are converted into Lineto segments if necessary. If negative length is provided, the algorithm starts looking from the end of the path. If length is higher than path length, the path is divided at the closest visible path endpoint instead. Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm. If the path contains no visible segments, the end point of the last segment is returned. If the path has no segments at all, null is returned.

One visible segment is identified which contains the point at length. Finding the desired point is straightforward for linear segments (see line.pointAtLength() for reference). Finding the desired point in curved segments is more complex, as illustrated by the curve.pointAtLength() function.

The opt argument is optional. Two properties may be specified, opt.precision and opt.segmentSubdivisions, which determine maximum error allowed in pointAtLength calculations for curved segments (default precision is 3; this corresponds to maximum observed error of 0.1%). The opt.segmentSubdivisions property is an array of individual segments' subdivision arrays. The path.getSegmentSubdivisions() function may be used to obtain the segmentSubdivisions array. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm in curved segments.

equals()

path.equals(otherPath)

Return true if the path exactly equals the other path.

The two paths are equal only if every segment of one path exactly equals the corresponding segment of the other path. The function returns true if segments arrays of both paths have no elements.

getSegment()

path.getSegment(index)

Return the path segment at index.

Negative indices are accepted; they instruct the algorithm to start looking from the end of the segments array.

Throws an error if the path has no segments. Also throws an error if the index is out of range.

getSegmentSubdivisions()

path.getSegmentSubdivisions([opt])

Return an array of segment subdivision arrays.

In Curveto segments, subdivisions are obtained by recursive halving up to given precision. Other types of segments do not have subdivisions; [] placeholders are used in their place.

This is an intermediary function. Path functions that rely on length calculations may need to work with flattened curves, with points obtained by curve subdivision at an arbitrary precision level. Refer to curve.length() documentation for more information about precision and curve flattening.

This function makes it possible to avoid expensive re-subdivisions of curved segments when several operations need to be performed at the same level of precision (for example, obtaining the length of the path and then finding the point at 10% length). The returned array may be passed to all such functions as the opt.segmentSubdivisions property.

The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1% in the flattened length of curved segments.

insertSegment()

path.insertSegment(index, segment)

Insert segment to the path at index provided.

Negative indices are accepted; they instruct the algorithm to start looking from the end of the segments array.

Also accepts an array of segments as an argument. The segments are inserted at index as a group, in the order they appear in the provided array.

The function does not return anything.

intersectionWithLine()

path.intersectionWithLine(line [, opt])

Return an array of the intersection points of the path and the line. Return null if no intersection exists.

isDifferentiable()

path.isDifferentiable()

Return true if a tangent line can be found for at least one segment of the path.

Invisible segments (e.g. Moveto segments) are never differentiable. In Line-based segments (e.g. Lineto segments), tangents cannot be found both line endpoints are coincident. In Curve-based segments (e.g. Curveto segments), tangents cannot be found if all control points are coincident. If the path contains no segments, return false.

isValid()

path.isValid()

Return true if the path has valid path data (and thus may be used as a d attribute of an SVG DOM element).

Return true if the path has no segments. Return false if the path has segments but does not start with a Moveto.

You may use the path.validate() function to add an initial 'M 0 0' segment to invalid paths; the method leaves valid paths unchanged.

length()

path.length([opt])

Return the length of the path.

The path length is a sum of the lengths of visible path segments; invisible segments (e.g. Moveto segments) have a length of 0. If the path has no segments at all, 0 is returned.

Although calculating the length of linear segments (e.g. Lineto and Closepath segments) is straightforward, determining the length of curved segments is complex. Refer to curve.length() documentation for more information.

The opt argument is optional. Two properties may be specified, opt.precision and opt.segmentSubdivisions, which determine maximum error allowed for the length calculation (default precision is 3; this corresponds to maximum observed error of 0.1%). The opt.segmentSubdivisions property is an array of individual segments' subdivision arrays. The path.getSegmentSubdivisions() function may be used to obtain the segmentSubdivisions array.

lengthAtT()

path.lengthAtT(t [, opt])

Private helper method.

Makes use of t objects obtained from the path.closestPointT() function. Used as an intermediary by other path.closestPoint functions.

pointAt()

path.pointAt(ratio [, opt])

Return a point on the path that lies ratio (normalized length) away from the beginning of the path.

The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively. Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm. If the path contains no visible segments, the end point of the last segment is returned. If the path has no segments at all, null is returned.

The function uses the same algorithm as the path.pointAtLength() function. It finds a visible segment which contains the point at length that corresponds to given ratio and then calls the segment's pointAtLength() function.

pointAtLength()

path.pointAtLength(length [, opt])

Return a point on the path that lies length away from the beginning of the path.

If negative length is provided, the algorithm starts looking from the end of the path. If length is higher than path length, the closest visible path endpoint is returned instead. Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm. If the path contains no visible segments, the end point of the last segment is returned. If the path has no segments at all, null is returned.

pointAtT()

path.pointAtT(t)

Private helper method.

Makes use of t objects obtained from the path.closestPointT() function. Used as an intermediary by other path.closestPoint functions.

removeSegment()

path.removeSegment(index)

Remove the path segment at index.

Negative indices are accepted; they instruct the algorithm to start looking from the end of the segments array.

The function does not return anything.

replaceSegment()

path.replaceSegment(index, segment)

Replace the path segment at index with the segment provided.

Negative indices are accepted; they instruct the algorithm to start looking from the end of the segments array.

Also accepts an array of segments as an argument. The segments replace the segment at index as a group, in the order they appear in the provided array.

The function does not return anything.

round()

path.round([precision])

Round all coordinates of the path to the given precision.

Default precision is 0.

Modifies this path in-place, and returns it.

scale()

path.scale(sx, sy [, origin])

Scale the path by sx and sy about the given origin.

If origin is not specified, the path is scaled around 0,0.

Modifies this path in-place, and returns it.

segmentAt()

path.segmentAt(ratio [, opt])

Return the path segment that contains a point that lies ratio (normalized length) away from the beginning of the path.

The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively. Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm. If the path contains no visible segments, null is returned. If the path has no segments at all, null is returned, as well.

segmentAtLength()

path.segmentAtLength(length [, opt])

Return the path segment that contains a point that lies length away from the beginning of the path.

If negative length is provided, the algorithm starts looking from the end of the path. If length is higher than path length, the closest visible path segment is returned. Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm. If the path contains no visible segments, null is returned. If the path has no segments at all, null is returned, as well.

segmentIndexAt()

path.segmentIndexAt(ratio [, opt])

Return the index of the path segment that contains a point that lies ratio (normalized length) away from the beginning of the path.

The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively. Invisible segments (e.g. Moveto segments) have no length and are therefore skipped by the algorithm. If the path contains no visible segments, null is returned. If the path has no segments at all, null is returned, as well.

segmentIndexAtLength()

path.segmentIndexAtLength(length [, opt])

Return the index of the path segment that contains a point that lies length away from the beginning of the path.

serialize()

path.serialize()

Return the path represented as a path data string.

Whenever a Path object needs to be converted to a string for the SVG d attribute, this function should be used. Unlike the path.toString() function, this function checks whether the path data string is valid. The function throws an error if the path is not valid. This happens if the path has segments but does not start with a Moveto segment. Note that an empty string is valid, according to the SVG specification.

new g.Path('M 150 100 L 100 100 C 100 100 0 150 100 200 Z').serialize() = "M 150 100 L 100 100 C 100 100 0 150 100 200 Z"

tangentAt()

path.tangentAt(ratio [, opt])

Return a line tangent to the path at point that lies ratio (normalized length) away from the beginning of the path.

The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively. If point at ratio is a point of discontinuity (e.g. it is a point shared by two Lineto segments with different slopes), the tangent line is constructed for the earlier segment (i.e. the segment closer to the beginning of the path).

The tangent line starts at the specified point. The direction from start to end is the same as the direction of the path segment at the specified point.

The function uses the same algorithm as the path.tangentAtLength() function. It finds a valid segment which contains the point at length that corresponds to given ratio and then calls the segment's segment.tangentAtLength() function.

tangentAtLength()

path.tangentAtLength(length [, opt])

Return a line tangent to the path at point that lies length away from the beginning of the path.

If negative length is provided, the algorithm starts looking from the end of the path. If length is higher than path length, a line tangent to the closest valid path endpoint is returned instead. If point at length is a point of discontinuity (e.g. it is a point shared by two Lineto segments with different slopes), the tangent line is constructed for the earlier segment (i.e. the segment closer to the beginning of the path).

The tangent line starts at the specified point. The direction from start to end is the same as the direction of the path segment at the specified point.

One valid segment is identified which contains the point at length. Finding the desired point is straightforward for linear segments (see line.pointAtLength() for reference). Finding the desired point in curved segments is more complex, as illustrated by the curve.pointAtLength() function. A tangent line is then obtained that touches the path at the identified point (see curve.tangentAtLength() for reference).

tangentAtT()

path.tangentAtT(t)

Private helper method.

Makes use of t objects obtained from the path.closestPointT() function. Used as an intermediary by other path.closestPoint functions.

toPoints()

path.toPoints([opt])

Return an array of arrays of points that approximate the path at given precision. If there are no segments, null is returned.

Every Moveto segment starts a new subpath within the path. Every subpath has a separate array of points in the returned array. If there is only one subpath, an array with one array of points is returned.

The points are found as endpoints of Lineto and Closepath segments and as endpoints of curve subdivisions whose flattened length is up to the specified precision level away from actual curved length. Refer to path.length() documentation for more information about precision and curve flattening.

The opt argument is optional. Two properties may be specified, opt.precision and opt.segmentSubdivisions, which determine maximum error allowed in the calculation (default precision is 3; this corresponds to maximum observed error of 0.1% in flattened curve length). The opt.segmentSubdivisions property is an array of individual segments' subdivision arrays. The path.getSegmentSubdivisions() function may be used to obtain the segmentSubdivisions array.

toPolylines()

path.toPolylines([opt])

Return an array of polylines that approximates the path at given precision. If there are no segments, null is returned.

Every Moveto segment starts a new subpath within the path. Every subpath has a separate entry in the returned array. If there is only one subpath, an array with one element is returned.

The polyline points are found as endpoints of Lineto and Closepath segments and as endpoints of curve subdivisions whose flattened length is up to the specified precision level away from actual curved length. Refer to path.length() documentation for more information about precision and curve flattening.

toString()

path.toString()

Return the path represented as a string.

Whenever a Path object needs to be converted to a string for the SVG d attribute, the path.serialize() function should be used. It provides additional error checking to make sure that the path data string is valid.

new g.Path('M 150 100 L 100 100 C 100 100 0 150 100 200 Z').toString() = "M 150 100 L 100 100 C 100 100 0 150 100 200 Z"

translate()

path.translate(tx [, ty])

Translate the path by tx on the x-axis and by ty on the y-axis.

If only tx is specified and is a number, ty is considered to be zero. If only tx is specified and is an object, it is considered to be a point or an object in the form { x: [number], y: [number] }

Modifies this path in-place, and returns it.

validate()

path.validate()

If the path is not valid (see path.isValid() for reference), make it valid by inserting an initial 'M 0 0' segment.

Valid paths are not changed. Empty paths are considered valid, so they are left unchanged by this function.

Modifies this path in-place, and returns it.

Static methods

createSegment()

g.Path.createSegment(type [, ...args])

Return a new path segment with specified type and (optionally) any further arguments.

The function throws an error if type is not recognized; only a limited subset of SVG path commands is supported (absolute versions of Moveto, Lineto, Curveto and Closepath).

Every path segment type expects a different number of arguments. Moveto expects 1 point, Lineto expects 1 point, Curveto expects 3 points, and Closepath expects no arguments. Chaining of arguments is allowed, so multiples of these numbers are accepted (e.g. 3 points for Lineto and 9 points for Curveto). An error is thrown if an incorrect number of points is provided (e.g. 2 points for Curveto). Examples:

var segment = g.Path.createSegment('M', new g.Point(100, 0));
var segment = g.Path.createSegment('L', new g.Point(100, 100), new g.Point(200, 200), new g.Point(300, 300));
var segment = g.Path.createSegment('C', new g.Point(10, 10), new g.Point(20, 10), new g.Point(20, 0), new g.Point(20, -10), new g.Point(30, -10), new g.Point(30, 0));
var segment = g.Path.createSegment('Z');

Instead of points, segments may be created with pairs of coordinates. That is, instead of providing 1 point to construct a Lineto segment, 2 strings or numbers may be provided. An error is thrown if an incorrect number of coordinates is provided. Examples:

var segment = g.Path.createSegment('M', 100, 0);
var segment = g.Path.createSegment('L', 100, 100, 200, 200, 300, 300);
var segment = g.Path.createSegment('C', 10, 10, 20, 10, 20, 0, 20, -10, 30, -10, 30, 0);
var segment = g.Path.createSegment('Z');

isDataSupported()

g.Path.isDataSupported(pathData)

Return true if the path data string provided consists of supported SVG Path commands (absolute versions of Moveto, Lineto, Curveto and Closepath).

parse()

g.Path.parse(pathData)

Return a new path object with path segments created from provided path data string.

The path data string does not require normalization, but it is restricted to subset of SVG path commands (absolute versions of Moveto, Lineto, Curveto and Closepath).

The string does not need to start with a Moveto command. (Empty string is accepted and creates an empty path.) Chaining of coordinates (e.g. providing a Moveto command with 4 parameters) is allowed.

The function throws an error if an unrecognized path command is encountered. Additionally, an error is thrown when an incorrect number of arguments is found with a command (e.g. a Curveto command with 5 coordinates).

constructor​

Methods​

appendSegment()​

bbox()​

clone()​

closestPoint()​

closestPointLength()​

closestPointNormalizedLength()​

closestPointT()​

closestPointTangent()​

containsPoint()​

divideAt()​

divideAtLength()​

equals()​

getSegment()​

getSegmentSubdivisions()​

insertSegment()​

intersectionWithLine()​

isDifferentiable()​

isValid()​

length()​

lengthAtT()​

pointAt()​

pointAtLength()​

pointAtT()​

removeSegment()​

replaceSegment()​

round()​

scale()​

segmentAt()​

segmentAtLength()​

segmentIndexAt()​

segmentIndexAtLength()​

serialize()​

tangentAt()​

tangentAtLength()​

tangentAtT()​

toPoints()​

toPolylines()​

toString()​

translate()​

validate()​

Static methods​

createSegment()​

isDataSupported()​

parse()​

Stay in the know

constructor

Methods

appendSegment()

bbox()

clone()

closestPoint()

closestPointLength()

closestPointNormalizedLength()

closestPointT()

closestPointTangent()

containsPoint()

divideAt()

divideAtLength()

equals()

getSegment()

getSegmentSubdivisions()

insertSegment()

intersectionWithLine()

isDifferentiable()

isValid()

length()

lengthAtT()

pointAt()

pointAtLength()

pointAtT()

removeSegment()

replaceSegment()

round()

scale()

segmentAt()

segmentAtLength()

segmentIndexAt()

segmentIndexAtLength()

serialize()

tangentAt()

tangentAtLength()

tangentAtT()

toPoints()

toPolylines()

toString()

translate()

validate()

Static methods

createSegment()

isDataSupported()

parse()