# Line

## constructor

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

## Methods

### angle()

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

### bbox()

`line.bbox()`

Return a rectangle that is the bounding box of the line.

### bearing()

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

### clone()

`line.clone()`

Return another line which is a clone of the line.

### closestPoint()

`line.closestPoint(point)`

Return the point on the line that lies closest to `point`

.

### closestPointLength()

`line.closestPointLength(point)`

Return the length of the line up to the point that lies closest to `point`

.

### closestPointNormalizedLength()

`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`

.

### closestPointTangent()

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

### containsPoint()

`line.containsPoint(p)`

Return `true`

if the point `p`

lies on the line. Return `false`

otherwise.

### divideAt()

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

### divideAtLength()

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

### equals()

`line.equals(otherLine)`

Return `true`

if the line equals the other line.

### intersect()

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

### intersection()

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

### intersectionWithLine()

`line.intersectionWithLine(line)`

Return an array of the intersection points of the line and another line `line`

. Return `null`

if no intersection exists.

### isDifferentiable()

`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).

### length()

`line.length()`

Return the length of the line.

### midpoint()

`line.midpoint()`

Return the point that is in the middle of the line.

### parallel()

`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"

### pointAt()

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

### pointAtLength()

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

### pointOffset()

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

### rotate()

`line.scale(origin, angle)`

Rotate the line by `angle`

around `origin`

.

### round()

`line.round([precision])`

Round all coordinates of the line to the given precision.

Default precision is `0`

.

Modifies this line in-place, and returns it.

### scale()

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

### serialize()

`line.serialize()`

Returns the line represented as an SVG points string.

`new g.Line('10 10', '20 20').serialize() = "10,10 20,20"`

### setLength()

`line.setLength(length)`

Scale the line so that it has the requested `length`

. The start point of the line is preserved.

### squaredLength()

`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).

### tangentAt()

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

### tangentAtLength()

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

### toString()

`line.toString()`

Returns the line represented as a string.

`new g.Line('10 10', '20 20').toString() = "10@10 20@20"`

### translate()

`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] }`

### vector()

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