 # Geometry API

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

``g.normalizeAngle(angle)``

Convert the `angle` to the range `[0, 360]`.

### g.snapToGrid

``g.snapToGrid(val, gridSize)``

Snap the value `val` to a grid of size `gridSize`.

### g.toDeg

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

``g.bezier.curveThroughPoints(points)``

Return the SVG path commands that define a cubic bezier curve going through the `points`. This method automatically computes the cubic bezier control points necessary to create a smooth curve crossing `points`.

#### g.bezier.getCurveControlPoints

``g.bezier.getCurveControlPoints(knots)``

Get open-ended Bezier Spline Control Points. `knots` should be Bezier spline points (at least two 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

``g.bezier.getCurveDivider(p0, p1, p2, p3)``

Divide a Bezier curve into two at point defined by value `t ∈ <0,1>`. Uses the deCasteljau algorithm.

#### g.bezier.getFirstControlPoints

``g.bezier.getFirstControlPoints(rhs)``

Solves a tridiagonal system for one of coordinates (x or y) of first Bezier control points. `rhs` is a right hand side vector. Returns a solution vector.

#### g.bezier.getInversionSolver

``g.bezier.getInversionSolver(p0, p1, p2, p3)``

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.ellipse.constructor

``g.ellipse(c, a, b)``

Return a new ellipse object with center at point `c` and parameters `a` and `b`.

#### g.ellipse.fromRect

``g.ellipse.fromRect(rect)``

Returns a new ellipse object from the given rect.

##### g.ellipse.prototype.bbox
``ellipse.bbox()``

Return the rectangle that is the bounding box of the ellipse.

##### g.ellipse.prototype.center
``ellipse.center()``

Return a point that is the center of the ellipse.

##### g.ellipse.prototype.clone
``ellipse.clone()``

Return another ellipse which is a clone of the ellipse.

##### g.ellipse.prototype.containsPoint
``ellipse.containsPoint(p)``

Return `true` if the point `p` is inside the ellipse (inclusive). Return `false` otherwise.

##### g.ellipse.prototype.equals
``ellipse.equals(otherEllipse)``

Returns `true` if the ellipse equals the other ellipse.

##### g.ellipse.prototype.inflate
```    `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.

##### g.ellipse.prototype.intersectionWithLineFromCenterToPoint
``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.

##### g.ellipse.prototype.normalizedDistance
``ellipse.normalizedDistance(p)``
Returns a normalized distance from the ellipse center to a point `p`. Returns a number `n` ( `n < 1` for points inside the ellipse, `n = 1` for points laying at the ellipse boundary and `n > 1` for points outside the ellipse).
##### g.ellipse.prototype.tangentTheta
``ellipse.tangentTheta(point)``

Returns the angle between the x axis and the tangent from a `point`. It is valid for points laying on the ellipse boundary only.

##### g.ellipse.prototype.toString
``ellipse.toString()``

Returns the ellipse represented as a string.

#### g.line.constructor

``g.line(p1, p2)``

Return a new line object with starting at point `p1` ending at point `p2`. `p1` and `p2` are first passed through the `point` constructor so they can also be passed in the string forms. Examples:

``````var l = g.line(g.point(10, 20), g.point(50, 60));
var l = new g.line('10 20', '50 60');
var l = g.line('10@20', '50@60');``````
##### g.line.prototype.bearing
``line.bearing()``

Return the bearing (cardinal direction) of the line. The return value is a one of the following strings: `'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW' and 'N'`.

##### g.line.prototype.clone
``line.clone()``

Return another line which is a clone of the line.

##### g.line.prototype.closestPoint
``line.closestPoint(p)``

Return the closest point laying on the line to the point `p`.

##### g.line.prototype.closestPointNormalizedLength
``line.closestPointNormalizedLength(p)``

Return the normalized length (distance from the start of the line / total line length) of the closest point laying on the line to the point `p`.

##### g.line.prototype.equals
``line.equals(otherLine)``

Return `true` if the line equals the other line.

##### g.line.prototype.intersect
``line.intersect(l)``

Return the intersection point of the line with another line `l`. A rectangle can also be passed in as the parameter, in which case, an array of intersection points with the line is returned. Return `null` if there is no such point.

##### g.line.prototype.intersection
``line.intersection(l)``

Return the intersection point of the line with another line `l`. Return `null` if there is no such point.

This has been `deprecated` in favor of intersect.

##### g.line.prototype.length
``line.length()``

Return the length of the line.

##### g.line.prototype.midpoint
``line.midpoint()``

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

##### g.line.prototype.pointAt
``line.pointAt(t)``

Return a point on the line at length specified by a floating point number `t` from the interaval `[0,1]`. For example, if `t` equals `0.5`, the function returns the midpoint of the line.

##### g.line.prototype.pointOffset
``line.pointOffset(point)``

Return the perpendicular distance between the line and the point. The distance is positive if the point lies to the right from the line, negative if the point lies to the left from the line, and 0 if the point lies on the line.

##### g.line.prototype.squaredLength
``line.squaredLength()``

Return the squared length of the line. Useful in cases the real length is not necessary (saves the Math.sqrt() operation).

##### g.line.prototype.toString
``line.toString()``

Returns the line represented as a string.

##### g.line.prototype.vector
``line.vector()``

Return the vector (point) of the line with length equals to length of the line.

#### g.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 x coordinate and the second is 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

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

Returns a new point object from the given polar coordinates.

#### g.point.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]`.

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

##### g.point.prototype.angleBetween
``point.angleBetween(p1, p2)``

Computes the angle (in degrees) between the line passing through the point and point `p1` and the line passing through the point and point `p2`. The ordering of points `p1` and `p2` is important. The function returns a value between 0 and 180 degrees when the angle is counterclockwise, and a value between 180 and 360 degrees when the angle is clockwise. The function returns NaN if any of the points `p1` and `p2` are coincident with this point.

##### g.point.prototype.bearing
``point.bearing(p)``

Return the bearing (cardinal direction) of the line between the point and another point `p`. The return value is a one of the following strings: `'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW' and 'N'`.

##### g.point.prototype.changeInAngle
``point.changeInAngle(dx, dy, ref)``

Return the change in angle that is the result of moving the point from its previous position (`-dx`, `-dy`) to its new position. This move is relative to the `ref` point and x axis.

##### g.point.prototype.clone
``point.clone()``

Return another point which is a clone of the point.

##### g.point.prototype.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.

##### g.point.prototype.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] }`

##### g.point.prototype.distance
``point.distance(p)``

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

##### g.point.prototype.dot
``point.dot(p)``

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

##### g.point.prototype.equals
``point.equals(p)``

Return `true` if the point equals another point `p` Return `false` otherwise.

##### g.point.prototype.magnitude
``point.magnitude()``

Return the magnitude of the point vector.

##### g.point.prototype.manhattanDistance
``point.manhattanDistance(p)``

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

##### g.point.prototype.move
``point.move(ref, distance)``

Move the point on a line that leads to another point `ref` by a certain `distance`.

##### g.point.prototype.normalize
``point.normalize(len)``

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 a length of `len`. If len is not specified, it is considered to be `1` in which case a unit vector is computed.

##### g.point.prototype.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] }`

##### g.point.prototype.reflection
``point.reflection(p)``

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

##### g.point.prototype.rotate
``point.rotate(o, angle)``

Rotate the point by `angle` around the origin `o`.

##### g.point.prototype.round
``point.round([precision])``

Rounds the point to the given precision.

##### g.point.prototype.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.

##### g.point.prototype.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).

##### g.point.prototype.squaredDistance
``point.squaredDistance(p)``

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

##### g.point.prototype.theta
``point.theta(p)``

Return the angle (in degrees) between the point, another point `p` and the x-axis.

##### g.point.prototype.toJSON
``point.toJSON()``

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

##### g.point.prototype.toPolar
``point.toPolar(o)``

Convert rectangular to polar coordinates. If the origin `o` is not specified, it is considered to be at (0,0).

##### g.point.prototype.toString
``point.toString()``

Returns the point as a string `x@y`.

##### g.point.prototype.update
``point.update(x, y)``

Update the point `x` and `y` coordinates with new values and return the point itself. Useful for chaining.

##### g.point.prototype.vectorAngle
``point.vectorAngle(p)``

Computes the angle (in degrees) between the line passing through the point (0,0) and this point and the line passing through the point (0,0) and point `p`. The function returns a value between 0 and 180 degrees when the angle is counterclockwise, and a value between 180 and 360 degrees when the angle is clockwise. The function returns NaN if called from point (0,0) or if `p` is (0,0).

#### g.polyline.constructor

``g.polyline([points])``

Return a new polyline object with points given by the `points` array. If `points` are not provided or are not an Array, an empty Polyline is created. 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.

##### g.polyline.prototype.closestPoint
``g.polyline.closestPoint(point)``

Return a point on the polyline that is the closest to the given point.

##### g.polyline.prototype.closestPointLength
``g.polyline.closestPointLength(point)``

Return the length at which the perpendicular distance is minimized between the polyline and the given point.

##### g.polyline.prototype.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.

##### g.polyline.prototype.length
``g.polyline.length()``

Return the length of the polyline.

##### g.polyline.prototype.pointAtLength
``g.polyline.pointAtLength(length)``

Return a point on the polyline that lies a specified `length` away from the start point along the polyline's path.

##### g.polyline.prototype.toString
``polyline.toString()``

Returns the polyline as a string in the form `x1@y1,x2@y2,...`.

#### g.rect.constructor

``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`. If only `x` is specified, it is considered to be an object in the form `{ x: [number], y: [number], width: [number], height: [number] }` in which case a copy of the rectangle is returned.

#### g.rect.fromEllipse

``g.rect.fromEllipse(ellipse)``

Returns a new rectangle object from the given ellipse.

##### g.rect.prototype.bbox
``rect.bbox(angle)``

Return a rectangle that is the bounding box of the rectangle taking into account its rotation around center specified by `angle` degrees.

##### g.rect.prototype.bottomLeft
``rect.bottomLeft()``

Return the point that is the bottom left corner of the rectangle.

##### g.rect.prototype.bottomLine
``rect.bottomLine()``

Return the bottom line of the rectangle.

##### g.rect.prototype.bottomMiddle
``rect.bottomMiddle()``

Return the point that is at the bottom middle of the rectangle.

##### g.rect.prototype.center
``rect.center()``

Return the point that is the center of the rectangle.

##### g.rect.prototype.clone
``rect.clone()``

Return another rectangle which is a clone of the rectangle.

##### g.rect.prototype.containsPoint
``rect.containsPoint(p)``

Return `true` if the point `p` is inside the rectangle (inclusive). Return `false` otherwise.

##### g.rect.prototype.containsRect
``rect.containsRect(r)``

Return `true` if the rectangle `r` is inside the rectangle (inclusive). Return `false` otherwise.

##### g.rect.prototype.corner
``rect.corner()``

Return the point that is the bottom right corner of the rectangle.

##### g.rect.prototype.equals
``rect.equals(r)``

Return `true` if the rectangle equals another rectangle `r` Return `false` otherwise.

##### g.rect.prototype.inflate
```    `rect.inflate(dx [, dy])`
```

Return a rectangle inflated in axis x by 2 * dx and in axis y by 2 * dy. When method is called with a single parameter, the resulting rectangle is inflated by 2 * dx in both x and y axis.

##### g.rect.prototype.intersect
``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 `false` otherwise.

##### g.rect.prototype.intersectionWithLineFromCenterToPoint
``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.

##### g.rect.prototype.leftLine
``rect.leftLine()``

Return the left line of the rectangle.

##### g.rect.prototype.leftMiddle
``rect.leftMiddle()``

Return the point that is at the left middle of the rectangle.

##### g.rect.prototype.maxRectScaleToFit
``rect.maxRectScaleToFit(limitRectangle [, origin])``

Returns an object where `sx` and `sy` give the maximum scaling that can be applied to rect so that it would still fit into limitRectangle. If origin is specified, rect is scaled around it; otherwise, rect is scaled around its center.

##### g.rect.prototype.maxRectUniformScaleToFit
``rect.maxRectUniformScaleToFit(limitRectangle [, origin])``

Returns a number that specifies the maximum scaling that can be applied to rect along both axes so that it would still fit into limitRectangle. If origin is specified, rect is scaled around it; otherwise, rect is scaled around its center.

##### g.rect.prototype.moveAndExpand
``rect.moveAndExpand(r)``

Offset the rectangle by `r.x` and `r.y` and expand it by `r.width` and `r.height`.

##### g.rect.prototype.normalize
``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.

##### g.rect.prototype.offset
``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] }`

##### g.rect.prototype.origin
``rect.origin()``

Return the point that is the top left corner of the rectangle.

##### g.rect.prototype.pointNearestToPoint
``rect.pointNearestToPoint(p)``

Return the point on the boundary of the rectangle nearest to the point `p`.

##### g.rect.prototype.rightLine
``rect.rightLine()``

Return the right line of the rectangle.

##### g.rect.prototype.rightMiddle
``rect.rightMiddle()``

Return the point that is at the right middle of the rectangle.

##### g.rect.prototype.round
``rect.round([precision])``

Rounds the rectangle to the given precision.

##### g.rect.prototype.scale
``rect.scale(sx, sy [, origin])``

Scale the rectangle by `sx`,`sy` around the given origin point. If origin is not specified, the rectangle is scaled around the point 0,0.

##### g.rect.prototype.sideNearestToPoint
``rect.sideNearestToPoint(p)``

Return the `"top"`, `"left"`, `"right"` or `"bottom"` string denoting the side of the rectangle which is nearest to the point `p`.

##### g.rect.prototype.snapToGrid
``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.

##### g.rect.prototype.toJSON
``rect.toJSON()``

Return the rectangle as a simple JSON object. For example: `{ "x": 0, "y": 0, "width": 40, "height": 40 }`.

##### g.rect.prototype.topLine
``rect.topLine()``

Return the top line of the rectangle.

##### g.rect.prototype.topMiddle
``rect.topMiddle()``

Return the point that is at the top middle of the rectangle.

##### g.rect.prototype.topRight
``rect.topRight()``

Return the point that is the top right corner of the rectangle.

##### g.rect.prototype.toString
``point.toString()``

Returns the rectangle as a string `x@y x@y`.

##### g.rect.prototype.union
``rect.union(r)``

Return a rectangle object that is a union of the two rectangles.

#### g.scale.linear

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