Point, Size and Rectangle

In Paper.js, basic types such as Point, Size and Rectangle are objects that describe geometric attributes of graphical items. They are an abstract representation of geometric values such as location and dimension, but do not directly represent a graphical item within a project.

This means that when we create a Point object in code, we are in fact only creating a description of a location in the view, but we are not creating a path item that contains this point as a segment:

var myPoint = new Point(10, 20); 
console.log(myPoint); // { x: 10, y: 20 }

In order to create a path item that contains this point as a segment, we would need to explicitly use the new Path() constructor to create a path and add the point as a first segment to it. The Working with Path Items tutorial describes paths and segments in more detail.

var myPath = new Path();
myPath.add(myPoint);

Running this script would produce a 'physical' path item in the Paper.js project with one segment at the location of myPoint.

The Point object describes a two dimensional location. It has two properties x and y, representing the x and y coordinate of the location.

Point objects can be created either by directly providing the coordinates for x and y or by omitting them, in which case they are initialized with 0. The x and y coordinate properties can be accessed and changed separately too.

Here we are creating a new point without providing values for x and y, and then change the values after. The console.log() function is used to log the resulting values to the console.

var myPoint = new Point();
console.log(myPoint); // { x: 0, y: 0 }

// Now let's change the x coordinate to 10...
myPoint.x = 10;

// ...and the y coordinate to x + 10
myPoint.y = myPoint.x + 10;
console.log(myPoint); // { x: 10, y: 20 }

Here we are creating a new point with defined coordinates, which are then modified.

var myPoint = new Point(20, 40);
console.log(myPoint); // { x: 20, y: 40 }

// Now we are doubling the x coordinate by multiplying it with 2.
myPoint.x = myPoint.x * 2;
console.log(myPoint); // { x: 40, y: 40 }

Another way of creating a point object is by passing its constructor an existing point, of which the new point becomes a copy. Changing the new point will not modify the original point:

var firstPoint = new Point(20, 40);
var secondPoint = new Point(firstPoint);
console.log(secondPoint); // { x: 20, y: 40 }

secondPoint.y = 20;
console.log(secondPoint); // { x: 20, y: 20 }

// Note that firstPoint has not changed:
console.log(firstPoint); // { x: 20, y: 40 }

This is not the same as a simple variable reference, which does not make a copy:

var firstPoint = new Point(20, 40);
var secondPoint = firstPoint;
secondPoint.y = 20;
console.log(secondPoint); // { x: 20, y: 20 }

// Note that firstPoint has changed as well:
console.log(firstPoint); // { x: 20, y: 20 }

var firstPoint = new Point(20, 40);
var secondPoint = firstPoint.clone();

The Point object offers an alternative numeric way of describing the location, in opposition to the cartesian coordinate x, y: The properties angle and length, which describe the location in the polar coordinate system, defined by the distance (length) and angle to the coordinate sytstem's origin.

The Size object describes abstract dimensions in two dimensional space. It has two properties width and height, representing the width and height values of the size.

Just like with Point objects, Size objects can be created either by directly providing the values for width and height or by omitting them, in which case they are initialized with 0. The width and height properties can be accessed and changed separately too. As an example, the same steps from the Point object are executed with a Size object here. Anything that was said about the Point object applies to the Size object too, the only difference being the different property names.

var mySize = new Size();
console.log(mySize); // { width: 0, height: 0 }

mySize.width = 10;
mySize.height = mySize.width + 10;
console.log(mySize); // { width: 10, height: 20 }

var mySize = new Size(20, 40);
console.log(mySize); // { width: 20, height: 40 }

mySize.width = mySize.width * 2;
console.log(mySize); // { width: 40, height: 40 }

The Rectangle object can be described as the combination of a Point object and a Size object, describing both a two dimensional location and a size. Therefore it posseses the four properties x, y, width and height. The properties x and y describe the coordinates of the top left point of the rectangle, width and height describe its dimensions. Additionally, it also defines the point and size properties, giving access to these values in form of Point and Size objects.

Rectangle objects can be created in a multitude of ways. One possibility is to pass a Point and a Size object to the new Rectangle(point, size) constructor:

var topLeft = new Point(10, 20);
var rectSize = new Size(200, 100);
var rect = new Rectangle(topLeft, rectSize);
console.log(rect); // { x: 10, y: 20, width: 200, height: 100 }
console.log(rect.point); // { x: 10, y: 20 }
console.log(rect.size); // { width: 200, height: 100 }

The same Rectangle object can be created using the new Rectangle(x, y, width, height) constructor:

var rect = new Rectangle(10, 20, 200, 100);
console.log(rect); // { x: 10, y: 20, width: 200, height: 100 }

A third possibility is to use the new Rectangle(point1, point2) constructor, which receives two corner points of the Rectangle object. These do not necessarily need to be the top left and bottom right corners, the constructor figures out how to fit a rectangle between them:

var bottomLeft = new Point(10, 120);
var topRight = new Point(210, 20);
var rect = new Rectangle(bottomLeft, topRight);
console.log(rect); // { x: 10, y: 20, width: 200, height: 100 }

var rect = new Rectangle(new Point(10, 120),
		new Point(210, 20));

The Rectangle object is a bit more complex than Point and Size objects and exposes a series of additional center and corner point objects: center, topLeft, topRight, bottomLeft, bottomRight, leftCenter, topCenter, rightCenter and bottomCenter.

All these values can be changed after a rectangle is created, offering an easy ways to specify the geometric qualities of rectangles:

// We start by creating a rectangle of dimension and
// location set to 0
var rect = new Rectangle();
console.log(rect); // { x: 0, y: 0, width: 0, height: 0 }

// Now we can for example define its size...
rect.size = new Size(100, 200);

// and its center
rect.center = new Point(100, 100);
console.log(rect); // { x: 50, y: 0, width: 100, height: 200 }

As an alternative numeric way to define the rectangle's dimensions, the Rectangle object also exposes the following properties, in opposition to x, y, width and height: left, top, right and bottom:

var rect = new Rectangle();
rect.left = 100;
rect.right = 200;
rect.bottom = 400;
rect.top = 200;
console.log(rect); // { x: 100, y: 200, width: 100, height: 200 }