# Point

## constructor

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

## Methods

### adhereToRect()

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

.

### angleBetween()

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

### bearing()

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

.

### changeInAngle()

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

).

### chooseClosest()

`point.chooseClosest(points)`

Choose the point closest to this point from among `points`

. If `points`

is an empty array, `null`

is returned.

### clone()

`point.clone()`

Return another point which is a clone of the point.

### cross()

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

### difference()

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

### distance()

`point.distance(p)`

Return the distance between the point and another point `p`

.

### dot()

`point.dot(p)`

Return the dot product of this vector (point) and vector `p`

.

### equals()

`point.equals(p)`

Return `true`

if the point equals another point `p`

. Return `false`

otherwise.

### lerp()

`point.lerp(p, t)`

Return an interpolation between the point and point `p`

for a parameter`t`

in the closed interval *[0, 1]*

### magnitude()

`point.magnitude()`

Return the magnitude of the point vector.

### manhattanDistance()

`point.manhattanDistance(p)`

Return the manhattan distance between the point and another point `p`

.

### move()

`point.move(ref, distance)`

Move the point on a line that leads to another point `ref`

by a certain `distance`

.

### normalize()

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

### offset()

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

### reflection()

`point.reflection(p)`

Return a point that is a reflection of the point with the center of reflection at point `p`

.

### rotate()

`point.rotate(origin, angle)`

Rotate the point by `angle`

around `origin`

.

### round()

`point.round([precision])`

Round the coordinates of the point to the given precision.

Default precision is `0`

.

Modifies this point in-place, and returns it.

### scale()

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

### serialize()

`point.serialize()`

Returns the point represented as an SVG point string.

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

### snapToGrid()

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

### squaredDistance()

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

### theta()

`point.theta(p)`

Return the angle (in degrees) between the point, another point `p`

and the x-axis.

### toJSON()

`point.toJSON()`

Return the point as a simple JSON object. For example: `{ "x": 0, "y": 0 }`

.

### toPolar()

`point.toPolar([origin])`

Convert rectangular to polar coordinates.

If `origin`

is not specified, it is considered to be 0,0.

### toString()

`point.toString()`

Returns the point as a string.

`new g.Point('10 10').toString() = "10@10"`

### translate()

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

### update()

`point.update(x, y)`

`point.update(p)`

Update the point's `x`

and `y`

coordinates with new values and return the point itself. Useful for chaining.

Also accepts a single argument in the form of an object `{ x: [number], y: [number] }`

.

### vectorAngle()

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

## Static methods

### fromPolar()

`g.Point.fromPolar(distance, angle, origin)`

Returns a new Point object from the given polar coordinates.

### random()

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

.