# A hidden gold of JointJS, the geometry library

September 12th, 2013
The JointJS diagramming library contains a not-yet-documented **standalone pure JavaScript** mini library that implements many useful **geometry operations**.
This post shows all the primitives that the geometry library exposes. The geometry library does not have
any dependencies, is AMD complient and can be used outside of JointJS. The source code of the library can
be found on Github.

It's important to note that many of the methods of the geometry library are inspired by their Squeak Smalltalk implementations.

## List of primitives

This is the complete list of primitives that the geometry library exposes:

- point
- line
- rect
- ellipse
- bezier

## Point

Methods of the `point`

primitve are:

If the point lies outside the rectangle`adhereToRect(r)`

`r`

, return the nearest point on the boundary of`r`

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

`p`

and the x-axis.Return the distance between the point and another point`distance(p)`

`p`

.Return the manhatten distance between the point and another point`manhattenDistance(p)`

`p`

.Offset the point (change its x and y coordinates) by`offset(dx, dy)`

`dx`

and`dy`

.Return the magnitude of the point vector.`magnitude()`

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

Round the point (optionally on`round([decimals])`

`decimal`

places) and return the point itself.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`normalize([len])`

`len`

. If`len`

is not passed, it is considered to be`1`

in which case a unit vector is computed.Return a point that has coordinates computed as a difference between the point and another point`difference(p)`

`p`

.Convert rectangular to polar coordinates. If the origin`toPolar(o)`

`o`

is not specified, it is considered to be at (0,0).Rotate the point by`rotate(o, angle)`

`angle`

around the origin`o`

.Move the point on a line that leads to another point`move(ref, distance)`

`ref`

by distance`distance`

.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`changeInAngle(dx, dy, ref)`

`ref`

point and x axis.

Methods of the point constructor:

Construct a point from polar coordinates.`fromPolar(r, angle, o)`

Construct a point with random coordinates that fall into the range`random(x1, x2, y1, y2)`

`[x1, x2]`

and`[y1, y2]`

.

### Examples

```
var p1 = point(20, 50);
var p2 = point('150 200');
p1.distance(p2);
p1.theta(p2);
p1.normalize(2);
console.log(p1 + ''); // prints 20@50
```

## Line

Methods of the `line`

primitive are:

Return the length of the line.`length()`

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

Return the point that is in the middle of the line.`midpoint()`

Return the point that the line is intersecting another line`intersection(l)`

`l`

. Return`null`

if there is no such point.

### Examples

```
var l1 = line(point(20, 50), point(150, 200));
var l2 = line(point(320, 150), point(20, 20));
l1.length();
l1.intersection(l2);
l1.midpoint();
console.log(l1 + ''); // prints 20@50 150@200
```

## Rectangle

Methods of the `rect`

primitive are:

Return the point that is the top left corner of the rectangle.`origin()`

Return the point that is the bottom right corner of the rectangle.`corner()`

Return the point that is the top right corner of the rectangle.`topRight()`

Return the point that is the bottom left corner of the rectangle.`bottomLeft()`

Return the point that is the center of the rectangle.`center()`

Return`intersect(r)`

`true`

if the rectangle intersects another rectangle`r`

.Return the`sideNearestToPoint(p)`

`"top", "left", "right" or "bottom"`

string denoting the side which is nearest to the point`p`

.Return`containsPoint(p)`

`true`

if the rectangle contains the point`p`

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

`p`

.Return the point on the boundary of the rectangle that is the intersection of the rectangle with the line starting in the center of the rectangle ending in the point`intersectionWithLineFromCenterToPoint(p, angle)`

`p`

. If`angle`

is specified, the intersection will take into account a rotation of the rectangle by`angle`

degrees around its center.Offset the rectangle by`moveAndExpand(r)`

`r.x`

and`r.y`

and expand it by`r.width`

and`r.height`

.Round the rectangle (optionally on`round(decimals)`

`decimal`

places) and return the rectangle itself.

### Examples

```
var r1 = rect(20, 50, 200, 100); // x, y, width, height
var r2 = rect(80, 70, 300, 200);
r1.origin();
r1.intersect(r2); // true
console.log(r1 + ''); // prints 20@50 220@150
```

## Ellipse

Methods of the `ellipse`

primitive are:

Return the rectangle that is the bounding box of the ellipse.`bbox()`

Return the point on the boundary of the ellipse that is the intersection of the ellipse with the line starting in the center of the ellipse ending in the point`intersectionWithLineFromCenterToPoint(p, angle)`

`p`

. If`angle`

is specified, the intersection will take into account a rotation of the ellipse by`angle`

degrees around its center.

### Examples

```
var e1 = ellipse(point(100, 50), 50, 80); // center, a, b
e1.bbox();
console.log(e1 + ''); // prints 100@50 50 80
```

## Bezier

Methods of the `bezier`

primitive are:

Return SVG path commands that define a cubic bezier curve going through the`curveThroughPoints(points)`

`points`

.

## Other exported methods of the module

The geometry module (in AMD environment terms) or the `g`

global variable (without AMD), contains
these additional methods:

Convert radians`toDeg(rad)`

`rad`

to degrees.Convert degrees`toRad(deg)`

`deg`

to radians.Snap the value`snapToGrid(val, gridSize)`

`val`

to a grid of size`gridSize`

.

## Conclusion

The geometry library of JointJS is a handy tool for applications that deal with geometry primitives. As this library does not have any dependencies and is implemented purely in JavaScript without using the browser DOM, it can run even on the server (e.g. in NodeJS).

## Discussion

comments powered by Disqus