Polyline
constructor
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.
Methods
bbox()
polyline.bbox()
Return a rectangle that is the bounding box of the polyline.
If the polyline contains no points, null
is returned.
clone()
polyline.clone()
Return another polyline which is a clone of the polyline.
closestPoint()
polyline.closestPoint(point)
Return the point on the path that lies closest to point
.
If the polyline contains no points, null
is returned.
closestPointLength()
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.
closestPointNormalizedLength()
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.
closestPointTangent()
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.
containsPoint()
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.
convexHull()
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.
equals()
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.
intersectionWithLine()
polyline.intersectionWithLine(line)
Return an array of the intersection points of the polyline and the line. Return null
if no intersection exists.
isDifferentiable()
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.
length()
polyline.length()
Return the length of the polyline.
If the polyline contains no points, 0
is returned.
pointAt()
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.
pointAtLength()
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.
round()
polyline.round([precision])
Round all coordinates of the polyline to the given precision.
Default precision is 0
.
Modifies this polyline in-place, and returns it.
scale()
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.
serialize()
polyline.serialize()
Returns the polyline represented as an SVG points string.
new g.Polyline('10,10 20,20 30,30').serialize() = "10,10 20,20 30,30"
simplify()
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 (the default is 1e-10
). 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.
tangentAt()
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.
tangentAtLength()
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.
toString()
polyline.toString()
Returns the polyline as a string.
new g.Polyline('10,10 20,20 30,30').toString() = "10@10,20@20,30@30"
translate()
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] }
Static methods
fromRect()
g.Polyline.fromRect(rect)
Return a new polyline object with points created from provided rect
.
parse()
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.