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