🎉 JointJS has new documentation! 🥳
🎉 JointJS has new documentation! 🥳
Together with Vectorizer, Geometry is another lightweight library built-in to JointJS. This library implements many useful geometry operations. The geometry library does not have any dependencies and can be used standalone. Please see the download page that contains both the development and minified versions of this library.
g.normalizeAngle(angle)Convert the angle to the range [0, 360].
g.random(min, max)Return a random integer between min and max, inclusive.
g.random(max)Return a random integer between 0 and max, inclusive.
g.random()Return 0 or 1, chosen randomly.
g.snapToGrid(val, gridSize)Snap the value val to a grid of size gridSize.
g.toDeg(rad)Convert radians rad to degrees.
g.toRad(deg, over360)Convert degrees deg to radians. If over360 is true, do not modulate on 360 degrees.
g.bezier.curveThroughPoints(points)Deprecated. Use the g.Curve.throughPoints function instead.
Return the SVG path that defines a cubic bezier curve passing through points.
This method automatically computes the cubic bezier control points necessary to create a smooth curve with points as intermediary endpoints.
g.bezier.getCurveControlPoints(knots)Deprecated. Use the g.Curve.throughPoints function instead.
Get open-ended Bezier Spline Control Points.
The knots argument should be an array of (at least two) Bezier spline points. Returns an array where the first item is an array of the first control points and the second item is an array of second control points.
g.bezier.getCurveDivider(p0, p1, p2, p3)Deprecated. Use the curve.divide function instead.
Returns a function that divides a Bezier curve into two at point defined by value t between 0 and 1. Uses the deCasteljau algorithm.
g.bezier.getFirstControlPoints(rhs)Deprecated. Use the g.Curve.throughPoints function instead.
Solves a tridiagonal system for one of coordinates (x or y) of first Bezier control points.
The rhs argument is a right hand side vector. Returns a solution vector.
g.bezier.getInversionSolver(p0, p1, p2, p3)Deprecated. Use the curve.closestPointT function instead.
Solves an inversion problem -- Given the (x, y) coordinates of a point which lies on a parametric curve x = x(t)/w(t), y = y(t)/w(t), find the parameter value t which corresponds to that point. Returns a function that accepts a point and returns t.
g.Curve(p1 [, p2, p3, p4])Return a new curve object with start at point p1, control points at p2 and p3, and end at p4. All points are passed through the Point constructor so they can also be passed in string form. Examples:
var c = new g.Curve(new g.Point(10, 10), new g.Point(10, 40), new g.Point(50, 40), new g.Point(50, 10));
var c = new g.Curve('10 10', '10 40', '50 40', '50 10');
var c = new g.Curve('10@10', '10@40', '50@40', '50@10');The constructor also accepts a single Curve object as an argument; it creates a new curve with points cloned from the provided curve.
g.Curve.throughPoints(points)Return an array of cuic bezier curves that defines a curve passing through provided points.
This method automatically computes the cubic bezier control points necessary to create a smooth curve with points as intermediary endpoints. An error is thrown if an array with fewer than two points is provided.
The result of this function may be provided directly to the g.Path() constructor in order to create a Path object from these curves.
curve.bbox()Return a rectangle that is the tight bounding box of the curve (i.e. not including the curve control points).
curve.clone()Return another curve which is a clone of the curve.
curve.closestPoint(point [, opt])Return the point on the curve that lies closest to point.
The function uses the same algorithm as the curve.closestPointT() function. The point at t closest to point is returned.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions with which to begin the algorithm. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.closestPointLength(point [, opt])Return the length of the curve up to the point that lies closest to point.
The function uses the same algorithm as the curve.closestPointT() function. The length of the curve at t closest to point is returned.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions with which to begin the algorithm. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.closestPointNormalizedLength(point [, opt])Return the normalized length (distance from the start of the curve / total curve length) of the curve up to the point that lies closest to point.
The function uses the same algorithm as the curve.closestPointT() function. The normalized length of the curve at t closest to point is returned.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions with which to begin the algorithm. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.closestPointT(point [, opt])Return the t value of the point on the curve that lies closest to point.
The curve is first subdivided, according to opt.precision (refer to curve.length() documentation for more information about precision and curve flattening). Then, one subdivision is identified whose endpoints are the closest to point. A binary search is then performed on that subdivision, until a curve is found whose diffrence between endpoints' distance to point lies within opt.precision. The t value of the closest endpoint is returned by the function.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions with which to begin the algorithm. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.closestPointTangent(point [, opt])Return a line that is tangent to the curve at the point that lies closest to point.
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.
If the control points of the curve all lie at the same coordinates, null is returned (it is impossible to determine the slope of a point). The curve.isDifferentiable() function may be used in advance to determine whether tangents can exist for a given curve.
The function uses the same algorithm as the curve.closestPointT() function. The tangent at t closest to point is returned.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions with which to begin the algorithm. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.containsPoint(p [, opt])Return true if the point p is inside the area surrounded by the curve (inclusive). Return false otherwise. Uses the even-odd algorithm to resolve self-intersections.
Uses the curve.toPolyline() function in the background. The precision of the calculation may be adjusted by passing the opt.precision and opt.subdivisions properties.
curve.divideAt(ratio [, opt])Divide the curve into two curves at the point that lies ratio (normalized length) away from the beginning of the curve.
Returns an array with two new curves without modifying the original curve. The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
This function mirrors the functionality of the line.divideAt() function. If it is necessary to divide the curve at a certain t value instead, use the curve.divideAtT() function.
The function uses the same algorithm as the curve.divideAtLength() function.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.divideAtLength(length [, opt])Divide the curve into two curves at the point that lies length away from the beginning of the curve.
Returns an array with two new curves without modifying the original curve. If negative length is provided, the algorithm starts looking from the end of the curve. If length is higher than curve length, the curve is divided at the closest endpoint instead.
The curve is first subdivided, according to opt.precision (refer to curve.length() documentation for more information about precision and curve flattening). Then, one subdivision is identified which contains the point at length. A binary search is then performed on that subdivision, until a curve is found whose endpoint lies within opt.precision away from length. That endpoint is used by the function to divide the curve.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
As a rule of thumb, increasing precision by 1 doubles the number of operations needed to find the point to be returned (this is on top of the cost of curve subdivision); exact numbers vary for every individual curve, however.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.divideAtT(t)Divide the curve into two curves at the point specified by t.
Returns an array with two new curves without modifying the original curve. The function expects t to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
This function is not a counterpart to the line.divideAt() function. The relationship between t and distance along a curve is complex and non-linear. If it is necessary to divide the curve at a certain ratio (normalized length) away from beginning of the curve, use the curve.divideAt() function.
curve.endpointDistance()Return the distance between curve start and end points.
curve.equals(otherCurve)Return true if the curve exactly equals the other curve.
curve.getSkeletonPoints(t)Return an object that contains five points necessary for dividing curves.
The function expects t to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
The returned object has the following properties:
startControlPoint1 |
First curve's controlPoint1. |
|---|---|
startControlPoint2 |
First curve's controlPoint2. |
divider |
The point at t; end point of the first curve and start point of the second curve. |
dividerControlPoint1 |
Second curve's controlPoint1. |
dividerControlPoint2 |
Second curve's controlPoint2
|
If only the point at t is needed, use the curve.pointAtT() function.
If the two divided curves are needed, rather than their control points, use the curve.divide() function.
curve.getSubdivisions([opt])Return an array of curves obtained by recursive halving of the curve up to a given precision.
Halving is not defined in terms of length, but in terms of the t parameter. The curves are subdivided at t = 0.5.
This is an intermediary function. Curve functions that rely on length calculations must 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 the curve when several operations need to be performed at the same level of precision (for example, obtaining the length of the curve and then finding the point at 10% length). The returned array may be passed to all such functions as the opt.subdivisions property.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
curve.isDifferentiable()Return true if a tangent line can be found for the curve.
Tangents cannot be found if all of the curve control points are coincident (the curve appears to be a point).
curve.length([opt])Return the length of the curve.
The curve length is a flattened length. This means that there will always be a difference between the reported length and the real length of the curve. (The returned curve length is always lower than the actual curve length.) That being said, the observed error can be constrained to an arbitrary threshold - here determined by opt.precision.
The opt.precision property is logarithmic, which means that increasing precision by 1 decreases observed error in length by a factor of 10. (For example, precision 3 leads to an observed error of less than 0.1%, precision 4 guarantees an observed error of less than 0.01%, etc.)
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
As a rule of thumb, increasing precision by 1 quadruples the number of operations needed to determine the length; exact numbers vary for every individual curve, however. Precision 3 is considered good enough when drawing curve approximations, and precision 4 is considered good enough for mapping curve t values to curve length. (Precision 4 should be the highest necessary for any practical use.)
The measure used, observed error (difference between subsequent observed lengths), is not a measure of actual error (difference between observed length and the actual length); it is a necessary substitution, however. The actual curve length cannot be precisely determined in the general case, and obtaining flattened length at maximum precision is not feasible for every single length calculation. Still, actual error is generally 2-3 times lower than observed error, so opt.precision can be seen as an upper bound on the length error with a high degree of confidence.
Instead of opt.precision, the opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. This is useful when several operations need to be performed with the same curve at the same level of precision (for example, obtaining the length of the curve and then finding the point at 10% length). Use the curve.getSubdivisions() function to obtain an array of curve subdivisions.
curve.lengthAtT(t [, opt])Return the length of the curve up to the point specified by t.
The curve is divided at t and the length of the first subcurve is returned. For more information about curve length calculation refer to curve.length() documentation.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
This method does make use of the opt.subdivisions property.
curve.pointAt(ratio [, opt])Return a point on the curve that lies ratio (normalized length) away from the beginning of the curve.
The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
This function mirrors the functionality of the line.pointAt() function. If the point at a given t value is needed instead, use the curve.pointAtT() function.
The function uses the same algorithm as the curve.pointAtLength() function.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.pointAtLength(length [, opt])Return a point on the curve that lies length away from the beginning of the curve.
If negative length is provided, the algorithm starts looking from the end of the curve. If length is higher than curve length, the closest curve endpoint is returned instead.
The curve is first subdivided, according to opt.precision (refer to curve.length() documentation for more information about precision and curve flattening). Then, one subdivision is identified which contains the point at length. A binary search is then performed on that subdivision, until a curve is found whose endpoint lies within opt.precision away from length. That endpoint is returned by the function.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
As a rule of thumb, increasing precision by 1 doubles the number of operations needed to find the point to be returned (this is on top of the cost of curve subdivision); exact numbers vary for every individual curve, however.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.pointAtT(t)Return a point on the curve at a point specified by t.
The function expects t to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
This function is not a counterpart to the line.pointAt() function. The relationship between t and distance along a curve is complex and non-linear. If a point at a certain ratio (normalized length) away from beginning of the curve is needed, use the curve.pointAt() function.
curve.scale(sx, sy [, origin])Scale the curve by sx and sy about the given origin.
If origin is not specified, the curve is scaled around 0,0.
curve.tangentAt(ratio [, opt])Return a line that is tangent to the curve at a point that lies ratio (normalized length) away from the beginning of the curve.
The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
The tangent line starts at the specified point. The direction from start to end is the same as the direction of the curve at the specified point.
If the control points of the curve all lie at the same coordinates, null is returned (it is impossible to determine the slope of a point). The curve.isDifferentiable() function may be used in advance to determine whether tangents can exist for a given curve.
The function uses the same algorithm as the curve.tangentAtLength() function.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.tangentAtLength(length [, opt])Return a line that is tangent to the curve at a point that lies length away from the beginning of the curve.
If negative length is provided, the algorithm starts looking from the end of the curve. If length is higher than curve length, a line tangent to the closest curve endpoint is returned instead.
The tangent line starts at the specified point. The direction from start to end is the same as the direction of the curve at the specified point.
If the control points of the curve all lie at the same coordinates, null is returned (it is impossible to determine the slope of a point). The curve.isDifferentiable() function may be used in advance to determine whether tangents can exist for a given curve.
The curve is first subdivided, according to opt.precision (refer to curve.length() documentation for more information about precision and curve flattening). Then, one subdivision is identified which contains the point at length. A binary search is then performed on that subdivision, until a curve is found whose endpoint lies within opt.precision away from length. That endpoint is used as the start of the tangent line.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.tangentAtT(t)Return a line that is tangent to the curve at point specified by t.
The function expects t to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
The tangent line starts at the specified point. The direction from start to end is the same as the direction of the curve at the specified point.
If the control points of the curve all lie at the same coordinates, null is returned (it is impossible to determine the slope of a point). The curve.isDifferentiable() function may be used in advance to determine whether tangents can exist for a given curve.
curve.tAt(ratio [, opt])Return the t value of the point that lies ratio (normalized length) away from the beginning of the curve.
The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
The function uses the same algorithm as the curve.tAtLength() function.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.tAtLength(length [, opt])Return the t value of the point that lies length away from the beginning of the curve.
If negative length is provided, the algorithm starts looking from the end of the curve. If length requested is higher than curve length, the t of the closest curve endpoint (0 or 1) is returned instead.
The curve is first subdivided, according to opt.precision (refer to curve.length() documentation for more information about precision and curve flattening). Then, one subdivision is identified which contains the point at length. A binary search is then performed on that subdivision, until a curve is found whose endpoint lies within opt.precision away from length. The t value of that endpoint is returned by the function.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1%.
The opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to calculate curve length. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions. The opt.precision property is still necessary, however; it determines the precision of the point search algorithm.
curve.toPoints([opt])Return an array of points that approximate the curve at given precision.
The points obtained are endpoints of curve subdivisions whose flattened length is up to the specified precision level away from actual curve length. Refer to curve.length() documentation for more information about precision and curve flattening.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1% in flattened curve length.
Instead of opt.precision, the opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to obtain the array of points. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions.
curve.toPolyline([opt])Return a polyline that approximates the curve at given precision.
The polyline points are found as endpoints of curve subdivisions whose flattened length is up to the specified precision level away from actual curve length. Refer to curve.length() documentation for more information about precision and curve flattening.
The default value for opt.precision is 3; this corresponds to maximum observed error of 0.1% in flattened curve length.
Instead of opt.precision, the opt.subdivisions property may be specified, directly providing an array of pre-computed curve subdivisions from which to obtain the polyline. Use the curve.getSubdivisions() function to obtain an array of curve subdivisions.
curve.toString()Return the curve represented as a string.
curve.translate(tx [, ty])Translate the curve 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] }
g.Ellipse(c, rx, ry)Return a new ellipse object with center at point c and parameters rx and ry.
g.Ellipse.fromRect(rect)Return a new ellipse object from the given rect.
ellipse.bbox()Return a rectangle that is the bounding box of the ellipse.
ellipse.center()Return a point that is the center of the ellipse.
ellipse.clone()Return another ellipse which is a clone of the ellipse.
ellipse.containsPoint(p)Return true if the point p is inside the ellipse (inclusive). Return false otherwise.
ellipse.equals(otherEllipse)Return true if the ellipse equals the other ellipse.
ellipse.inflate(dx [, dy])Return an ellipse inflated in axis x by 2 * dx and in axis y by 2 * dy. When method is called with a single parameter, the resulting ellipse is inflated by 2 * dx in both x and y axis.
ellipse.intersectionWithLine(line)Return an array of the intersection points of the ellipse and the line. Return null if no intersection exists.
ellipse.intersectionWithLineFromCenterToPoint(p, angle)Return the point on the boundary of the ellipse that is the intersection of the ellipse with a line starting in the center of the ellipse ending in the point p. If angle is specified, the intersection will take into account the rotation of the ellipse by angle degrees around its center.
ellipse.normalizedDistance(p)Return a normalized distance from the ellipse center to point p.
Returns n < 1 for points inside the ellipse, n = 1 for points lying on the ellipse boundary and n > 1 for points outside the ellipse.
ellipse.tangentTheta(point)Returns the angle between the x axis and the tangent from a point. It is valid for points lying on the ellipse boundary only.
ellipse.toString()Returns the ellipse represented as a string.
g.Line(p1, p2)Return a new line object with start at point p1 and end at point p2. p1 and p2 are first passed through the Point constructor so they can also be passed in string form. Examples:
var l = new g.Line(new g.Point(10, 20), new g.Point(50, 60));
var l = new g.Line('10 20', '50 60');
var l = new g.Line('10@20', '50@60');The constructor also accepts a single Line object as an argument; it creates a new line with points cloned from the provided line.
line.angle()Return the angle of incline of the line.
The function returns NaN if the two endpoints of the line both lie at the same coordinates (it is impossible to determine the angle of incline of a line that appears to be a point). The line.isDifferentiable() function may be used in advance to determine whether the angle of incline can be computed for a given line.
line.bbox()Return a rectangle that is the bounding box of the line.
line.bearing()Return the bearing (cardinal direction) of the line. The return value is one of the following strings: 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW' and 'N'.
The function returns 'N' if the two endpoints of the line are coincident.
line.clone()Return another line which is a clone of the line.
line.closestPoint(point)Return the point on the line that lies closest to point.
line.closestPointLength(point)Return the length of the line up to the point that lies closest to point.
line.closestPointNormalizedLength(point)Return the normalized length (distance from the start of the line / total line length) of the line up to the point that lies closest to point.
line.closestPointTangent(point)Return a line that is tangent to the line at the point that lies closest to point.
The tangent line starts at the identified closest point. The direction from start to end is the same as the direction of the line at the closest point.
If the two endpoints of the line both lie at the same coordinates, null is returned (it is impossible to determine the slope of a point). The line.isDifferentiable() function may be used in advance to determine whether tangents can exist for a given line.
line.containsPoint(p)Return true if the point p lies on the line. Return false otherwise.
line.divideAt(t)Divide the line into two lines at the point that lies t (normalized length) away from the beginning of the line.
Returns an array with two new lines without modifying the original line. For example, if t equals 0.5, the function returns an array of two lines that subdivide the original line at its midpoint.
The function expects t to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
line.divideAtLength(length)Divide the line into two lines at the point that lies length away from the beginning of the line.
Returns an array with two new lines without modifying the original line. If negative length is provided, the algorithm starts looking from the end of the curve. If length is higher than line length, the line is divided at the closest line endpoint instead.
line.equals(otherLine)Return true if the line equals the other line.
line.intersect(shape)Return an array of the intersection points of the line with another geometry shape.
A single intersection point is returned, when the shape is a line.
Return null if no intersections are found.
line.intersection(l)Deprecated. Use the line.intersect() function instead.
Return the intersection point of the line with another line l.
A rectangle can also be passed in as the parameter. In that case, an array of intersection points with the line is returned.
Return null if no intersections are found.
line.intersectionWithLine(line)Return an array of the intersection points of the line and another line line. Return null if no intersection exists.
line.isDifferentiable()Return true if a tangent line can be found for the line.
Tangents cannot be found if both of the line endpoints are coincident (the line appears to be a point).
line.length()Return the length of the line.
line.midpoint()Return the point that is in the middle of the line.
line.parallel(distance)Return a new line which is parallel with this line. The new line is placed distance from this line in clockwise direction.
var line = new g.Line('0 0', '10 0');
line.parallel(10).toString(); // "0@10 10@10"
line.parallel(-5).toString(); // "0@-5 10@-5"
line.pointAt(t)Return a point on the line that lies t (normalized length) away from the beginning of the line.
For example, if t equals 0.5, the function returns the midpoint of the line.
The function expects t to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
line.pointAtLength(length)Return a point on the line that lies length away from the beginning of the line.
If negative length is provided, the algorithm starts looking from the end of the line. If length is higher than line length, the closest line endpoint is returned instead.
line.pointOffset(point)Return the perpendicular distance between the line and point. The distance is positive if the point lies to the right of the line, negative if the point lies to the left of the line, and 0 if the point lies on the line.
line.scale(origin, angle)Rotate the line by angle around origin.
line.round([precision])Rounds the line to the given precision.
Default precision is 0.
line.scale(sx, sy [, origin])Scale the line by sx and sy about the given origin.
If origin is not specified, the line is scaled around 0,0.
line.serialize()Returns the line represented as an SVG points string. Example: "10,20 40,40"
line.setLength(length)Scale the line so that it has the requested length. The start point of the line is preserved.
line.squaredLength()Return the squared length of the line.
Useful for distance comparisons in which real length is not necessary (saves one Math.sqrt() operation).
line.tangentAt(t)Return a line tangent to the line at point that lies t (normalized length) away from the beginning of the line.
The function expects t to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
The tangent line starts at the specified point. The direction from start to end is the same as the direction of the line.
If the two endpoints of the line both lie at the same coordinates, null is returned (it is impossible to determine the slope of a point). The line.isDifferentiable() function may be used in advance to determine whether tangents can exist for a given line.
line.tangentAtLength(length)Return a line tangent to the line at point that lies length away from the beginning of the line.
If negative length is provided, the algorithm starts looking from the end of the line. If length is higher than line length, a line tangent to the closest line endpoint is returned instead.
The tangent line starts at the specified point. The direction from start to end is the same as the direction of the line.
If the two endpoints of the line both lie at the same coordinates, null is returned (it is impossible to determine the slope of a point). The line.isDifferentiable() function may be used in advance to determine whether tangents can exist for a given line.
line.toString()Returns the line represented as a string.
line.translate(tx [, ty])Translate the line 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] }
line.vector()Return the vector (point) of the line with length equal to length of the line.
This function effectively translates the line so that its start lies at 0,0.
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.
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.
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');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).
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).
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.
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.
path.clone()Return another path which is a clone of the path.
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.
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.
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.
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.
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 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.
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.
path.closestPointT(point [, opt])Private helper method.
Returns a t object that simplifies calculations for other path.closestPoint functions.
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.
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.
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.
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.
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.
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.
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.
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.
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.
path.intersectionWithLine(line [, opt])Return an array of the intersection points of the path and the line. Return null if no intersection exists.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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 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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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] }
g.Point(x [, y])Return a new Point object with x and y coordinates. If x is a string, it is considered to be in the form "[number] [number]" or "[number]@[number]" where the first number is the x coordinate and the second is the y coordinate. Examples:
var p = g.Point(10, 20);
var p = new g.Point(10, 20);
var p = g.Point('10 20');
var p = g.Point('10@20');
var p = g.Point(g.Point(10, 20));g.Point.fromPolar(distance, angle, origin)Returns a new Point object from the given polar coordinates.
g.Point.random(x1, x2, y1, y2)Returns a new point object with random coordinates that fall within the range [x1, x2] and [y1, y2].
point.adhereToRect(r)If the point lies outside the rectangle r, adjust the point so that it becomes the nearest point on the boundary of r.
point.angleBetween(p1, p2)Compute the angle (in degrees) between the line from this point to p1 and the line from this point to p2.
The ordering of points p1 and p2 is important. The function returns a value between 0 and 180 when the angle (in the direction from p1 to p2) is clockwise, and a value between 180 and 360 when the angle is counterclockwise. The function returns NaN if either of the points p1 and p2 is coincident with this point.
point.bearing(p)Return the bearing (cardinal direction) of the line from this point to p. The return value is one of the following strings: 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW' and 'N'.
The function returns 'N' if this point is coincident with the point p.
point.changeInAngle(dx, dy, ref)Return the change in angle (in degrees) that is the result of moving the point from its previous position to its current position.
More specifically, this function computes the angle between the line from the ref point to the previous position of this point (i.e. current position -dx, -dy) and the line from the ref point to the current position of this point.
The function returns a positive value between 0 and 180 when the angle (in the direction from previous position of this point to its current position) is clockwise, and a negative value between 0 and -180 when the angle is counterclockwise. The function returns 0 if the previous and current positions of this point are the same (i.e. both dx and dy are 0).
point.chooseClosest(points)Choose the point closest to this point from among points. If points is an empty array, null is returned.
point.clone()Return another point which is a clone of the point.
point.cross(p1, p2)Return the cross product of the vector from the point passing through p1 and the vector from the point passing through p2.
The left-hand rule is used because the coordinate system is left-handed.
point.difference(dx [, dy])Return a point that has coordinates computed as a difference between the point and another point with coordinates dx and dy.
If only dx is specified and is a number, dy is considered to be zero. If only dx is specified and is an object, it is considered to be another point or an object in the form { x: [number], y: [number] }
point.distance(p)Return the distance between the point and another point p.
point.dot(p)Return the dot product of this vector (point) and vector p.
point.equals(p)Return true if the point equals another point p. Return false otherwise.
point.lerp(p, t)Return an interpolation between the point and point p for a parametert in the closed interval [0, 1]
point.magnitude()Return the magnitude of the point vector.
point.manhattanDistance(p)Return the manhattan distance between the point and another point p.
point.move(ref, distance)Move the point on a line that leads to another point ref by a certain distance.
point.normalize(length)Normalize the point vector and return the point itself.
In other words, scale the line segment between (0, 0) and the point in order for it to have the given length. If length is not specified, it is considered to be 1; in that case, a unit vector is computed.
point.offset(dx [, dy])Offset the point (change its x and y coordinates) by dx in x-axis and dy in y-axis.
If only dx is specified and is a number, dy is considered to be zero. If only dx is specified and is an object, it is considered to be another point or an object in the form { x: [number], y: [number] }
point.reflection(p)Return a point that is a reflection of the point with the center of reflection at point p.
point.rotate(origin, angle)Rotate the point by angle around origin.
point.round([precision])Rounds the point to the given precision.
Default precision is 0.
point.scale(sx, sy [, origin])Scale point by sx and sy about the given origin.
If origin is not specified, the point is scaled around 0,0.
point.serialize()Returns the point represented as an SVG point string. Example: "10,20"
point.snapToGrid(gridSize [, gridSizeY])Snap the point (change its x and y coordinates) to a grid of size gridSize (or gridSize x gridSizeY for non-uniform grid).
point.squaredDistance(p)Return the squared distance between the point and another point p.
Useful for distance comparisons in which real distance is not necessary (saves one Math.sqrt() operation).
point.theta(p)Return the angle (in degrees) between the point, another point p and the x-axis.
point.toJSON()Return the point as a simple JSON object. For example: { "x": 0, "y": 0 }.
point.toPolar([origin])Convert rectangular to polar coordinates.
If origin is not specified, it is considered to be 0,0.
point.toString()Returns the point as a string x@y.
point.translate(tx [, ty])Translate the point 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 another point or an object in the form { x: [number], y: [number] }
point.update(x, y)Update the point's x and y coordinates with new values and return the point itself. Useful for chaining.
point.vectorAngle(p)Compute the angle (in degrees) between the line from (0,0) and this point and the line from (0,0) to p.
The function returns a value between 0 and 180 when the angle (in the direction from this point to p) is clockwise, and a value between 180 and 360 when the angle is counterclockwise. The function returns NaN if called from point (0,0) or if p is (0,0).
g.Polyline(points)Return a new polyline object with points given by the points array.
The array can hold anything that can be understood by the Point constructor; Point objects, objects with x and y attributes, or strings in one of the two valid formats ("x y" or "x@y"). Array elements that cannot be understood as Points are replaced by 0,0 points.
If points are not provided, an empty Polyline is created.
Also accepts a polyline SVG string as an argument; then the g.Polyline.parse() function is used to generate points for the polyline.
g.Polyline.parse(svgString)Return a new polyline object with points created from provided polyline SVG string.
Empty string is accepted and creates an empty polyline.
polyline.bbox()Return a rectangle that is the bounding box of the polyline.
If the polyline contains no points, null is returned.
polyline.clone()Return another polyline which is a clone of the polyline.
polyline.closestPoint(point)Return the point on the path that lies closest to point.
If the polyline contains no points, null is returned.
polyline.closestPointLength(point)Return the length of the polyline up to the point that lies closest to point.
If the polyline contains no points, null is returned.
polyline.closestPointNormalizedLength(point)Return the normalized length (distance from the start of the path / total path length) of the polyline up to the point that lies closest to point.
If the polyline contains no points, null is returned.
polyline.closestPointTangent(point)Return a line tangent to the polyline at the point that lies closest to point.
The tangent line starts at the identified closest point. The direction from start to end is the same as the direction of the polyline segment at the identified point. If the identified closest point is a point of discontinuity (e.g. it is a point shared by two polyline segments with different slopes), the tangent line is constructed for the earlier segment (i.e. the segment closer to the beginning of the polyline).
The algorithm ignores polyline segments that have zero length. If the polyline contains no valid segments (i.e. all polyline points are coincident), null is returned. If the polyline has fewer than two points (exclusive), null is returned, as well. The polyline.isDifferentiable() function may be used in advance to determine whether the polyline contains at least one valid segment for wich a tangent may be found.
polyline.containsPoint(p)Return true if the point p is inside the area surrounded by the polyline (inclusive). Return false otherwise. Uses the even-odd algorithm to resolve self-intersections.
polyline.convexHull()Returns a polyline containing the convex hull of this polyline's points.
The output polyline begins with the first point of this polyline that is on the hull. The convex hull points then follow in clockwise order.
The minimum number of points is reported. This means that collinear points lying in the middle of hull edges are not reported. If a group of coincident points is encountered, only the first point (in order of the original polyline) is reported.
If the polyline contains no points, null is returned.
polyline.equals(otherPolyline)Return true if the polyline exactly equals the other polyline.
The two polylines are equal only if every point of one polyline exactly equals the corresponding point of the other polyline. The function returns true if points arrays of both polylines have no elements.
polyline.intersectionWithLine(line)Return an array of the intersection points of the polyline and the line. Return null if no intersection exists.
polyline.isDifferentiable()Return true if a tangent line can be found for at least one line of the polyline.
Tangents cannot be found if all points of the polyline are coincident. Additionally, return false if the polyline contains only one point or if it contains no points at all.
polyline.length()Return the length of the polyline.
If the polyline contains no points, 0 is returned.
polyline.pointAt(ratio)Return a point on the polyline that lies ratio (normalized length) away from the beginning of the polyline.
The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively. If the polyline contains no points, null is returned.
polyline.pointAtLength(length)Return a point on the polyline that lies length away from the beginning of the polyline.
If negative length is provided, the algorithm starts looking from the end of the polyline. If length is higher than the length of the polyline, the closest endpoint is returned instead. If the polyline contains no points, null is returned.
polyline.scale(sx, sy [, origin])Scale the polyline by sx and sy about the given origin.
If origin is not specified, the polyline is scaled around 0,0.
polyline.serialize()Returns the polyline represented as an SVG points string. Example: "10,20 40,40 32,29"
polyline.simplify[opt])Simplify the polyline by removing non-essential points (i.e. points lying along straight lines within the polyline).
This function modifies the original polyline and returns self. If the polyline has fewer than 3 points, the polyline is not modified.
By default, a point is considered non-essential only if it lies directly on the connection line between the previous and the following point. You can specify a tolerance range by providing a threshold value within the opt object. Polyline points that are closer to the connection line than this value (inclusive) are removed; points that are farther from the connection line (exclusive) are kept.
polyline.tangentAt(ratio)Return a line tangent to the polyline at point that lies ratio (normalized length) away from the beginning of the polyline.
The function expects ratio to lie between 0 and 1; values outside the range are constrained to 0 and 1, respectively.
The tangent line starts at the point at ratio. The direction from start to end is the same as the direction of the polyline segment at the specified point. If the specified point is a point of discontinuity (e.g. it is a point shared by two polyline segments with different slopes), the tangent line is constructed for the earlier segment (i.e. the segment closer to the beginning of the polyline).
The algorithm ignores polyline segments that have zero length. If the polyline contains no valid segments (i.e. all polyline points are coincident), null is returned. If the polyline has fewer than two points (exclusive), null is returned, as well. The polyline.isDifferentiable() function may be used in advance to determine whether the polyline contains at least one valid segment for wich a tangent may be found.
polyline.tangentAtLength(length)Return a line tangent to the polyline at point that lies length away from the beginning of the polyline.
If negative length is provided, the algorithm starts looking from the end of the polyline. If length is higher than the length of the polyline, a line tangent to the closest valid polyline endpoint is returned instead.
The tangent line starts at the point at length. The direction from start to end is the same as the direction of the polyline segment at the specified point. If the specified point is a point of discontinuity (e.g. it is a point shared by two polyline segments with different slopes), the tangent line is constructed for the earlier segment (i.e. the segment closer to the beginning of the polyline).
The algorithm ignores polyline segments that have zero length. If the polyline contains no valid segments (i.e. all polyline points are coincident), null is returned. If the polyline has fewer than two points (exclusive), null is returned, as well. The polyline.isDifferentiable() function may be used in advance to determine whether the polyline contains at least one valid segment for wich a tangent may be found.
polyline.toString()Returns the polyline as a string in the form x1@y1,x2@y2,....
polyline.translate(tx [, ty])Translate the polyline 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] }
g.Rect(x, y, width, height)Return a new rectangle object with top left corner at point with coordinates x, y and dimensions width and height.
Also accepts as a single argument an object in the form { x: [number], y: [number], width: [number], height: [number] }.
g.Rect.fromEllipse(ellipse)Returns a new rectangle object from the given ellipse.
rect.bbox([angle])Return a rectangle that is the bounding box of the rectangle.
If angle is specified, the bounding box calculation will take into account the rotation of the rectangle by angle degrees around its center.
rect.bottomLeft()Return the point that is the bottom left corner of the rectangle.
rect.bottomLine()Return the bottom line of the rectangle.
rect.bottomMiddle()Return the point that is at the bottom middle of the rectangle.
rect.bottomRight()Return the point that is the bottom right corner of the rectangle.
rect.center()Return the point that is the center of the rectangle.
rect.clone()Return another rectangle which is a clone of the rectangle.
rect.containsPoint(p)Return true if the point p is inside the rectangle (inclusive). Return false otherwise.
rect.containsRect(r)Return true if the rectangle r is (completely) inside the rectangle (inclusive). Return false otherwise.
rect.corner()Return the point that is the bottom right corner of the rectangle.
rect.equals(r)Return true if the rectangle equals another rectangle r Return false otherwise.
rect.inflate(dx [, dy])Return a rectangle inflated in axis x by 2 * dx and in axis y by 2 * dy.
When the function is called with a single parameter, the resulting rectangle is inflated by 2 * dx in both x and y axis.
rect.intersect(r)Return a rectangle object that is a subtraction of the two rectangles if such an object exists (the two rectangles intersect). Return null otherwise.
rect.intersectionWithLine(line)Return an array of the intersection points of the rectangle and the line. Return null if no intersection exists.
rect.intersectionWithLineFromCenterToPoint(p [, angle])Return the point on the boundary of the rectangle that is the intersection of the rectangle with a line starting in the center of the rectangle ending in the point p.
If angle is specified, the intersection will take into account the rotation of the rectangle by angle degrees around its center.
rect.leftLine()Return the left line of the rectangle.
rect.leftMiddle()Return the point that is at the left middle of the rectangle.
rect.maxRectScaleToFit(limitRectangle [, origin])Returns an object where sx and sy give the maximum scaling that can be applied to the rectangle so that it would still fit into limitRectangle.
If origin is specified, the rectangle is scaled around it; otherwise, it is scaled around its center.
rect.maxRectUniformScaleToFit(limitRectangle [, origin])Returns a number that specifies the maximum scaling that can be applied to the rectangle along both axes so that it would still fit into limitRectangle.
If origin is specified, the rectangle is scaled around it; otherwise, it is scaled around its center.
rect.moveAndExpand(r)Offset the rectangle by r.x and r.y and expand it by r.width and r.height.
rect.normalize()Normalize the rectangle, i.e. make it so that it has non-negative width and height.
If width is less than 0, the function swaps left and right corners and if height is less than 0, the top and bottom corners are swapped.
rect.offset(dx [, dy])Offset the rectangle (change its x and y coordinates) by dx in x-axis and dy in y-axis.
If only dx is specified and is a number, dy is considered to be zero. If only dx is specified and is an object, it is considered to be another point or an object in the form { x: [number], y: [number] }
rect.origin()Return the point that is the top left corner of the rectangle.
rect.pointNearestToPoint(p)Return the point on the boundary of the rectangle nearest to the point p.
rect.rightLine()Return the right line of the rectangle.
rect.rightMiddle()Return the point that is at the right middle of the rectangle.
rect.round([precision])Rounds the rectangle to the given precision.
Default precision is 0.
rect.scale(sx, sy [, origin])Scale the rectangle by sx,sy around the given origin.
If origin is not specified, the rectangle is scaled around the point 0,0.
rect.sideNearestToPoint(p)Return a string ("top", "left", "right" or "bottom") denoting the side of the rectangle which is nearest to the point p.
rect.snapToGrid(gx, gy)Adjust the position and dimensions of the rectangle such that its edges are on the nearest increment of gx on the x-axis and gy on the y-axis.
rect.toJSON()Return the rectangle as a simple JSON object. For example: { "x": 0, "y": 0, "width": 40, "height": 40 }.
rect.topLeft()Return the point that is the top left corner of the rectangle.
rect.topLine()Return the top line of the rectangle.
rect.topMiddle()Return the point that is at the top middle of the rectangle.
rect.topRight()Return the point that is the top right corner of the rectangle.
point.toString()Returns the rectangle as a string x@y x@y.
rect.translate(tx [, ty])Translate the rectangle by tx on the x-axis and 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] }
rect.union(r)Return a rectangle that is a union of this rectangle and rectangle r.
g.scale.linear(domain, range, value)Return the value from the domain interval linearly scaled to the range interval.
Both domain and range intervals must be specified as arrays with two numbers specifying start and end of the interval.