Mid level API

Mid level API (shapes)

At a higher level of abstraction, we have some simple shapes. A module for a shape defines a function that takes as input some geometric data and returns a shape object. Shape objects have the two properties path and centroid. The first one contains a Path, in the sense of the previous paragraph, while the second one is a point that is somehow central to the figure - for instance, it can be used to place a label. Thus a shape object has the structure:

{
  path: <path object>
  centroid: [<x>, <y>]
}

Polygon

The first shape is paths.polygon, and it can be used like:

var Polygon = require('paths/polygon');
var points = [[1, 3], [2, 5], [3, 4], [2, 0]];
var polygon = Polygon({
  points: points,
  closed: true
});

As shown in the example, it expects as input an object with the property points, which is an array of points. The optional property closed defined whether the polygon is closed (false by default).

Semi-regular polygon

A special case of the above is a polygon whose points are placed on half-lines starting from a fixed center and forming constant angles between each other; we call these kinds of polygons semi-regular. In the even more special case where all points have the same distance from the center, the polygon is regular.

A semi-regular polygon is defined by its center and the distance of each of its points from the center, like:

var SemiRegularPolygon = require('paths/semi-regular-polygon');
var polygon = SemiRegularPolygon({
  center: [0, 0],
  radii: [2, 3, 5, 7, 9, 12]
});
var regularPolygon = SemiRegularPolygon({
  center: [1, 2],
  radii: [3, 3, 3, 3, 3]
});

In the above example, polygon is semi-regular and centered at the origin, while regularPolygon is a regular pentagon centered at [1, 2].

Rectangle

Another special case of Polygon is a rectangle having sides parallel to the axes. It can be generated with:

var Rectangle = require('paths/rectangle');
var rectangle = Rectangle({
  top: 10,
  bottom: 3,
  left: -2,
  right: 5
});

The SVG spec includes <rect> elements, so usually there is no need to use a <path> element to draw a rectangle, but it can be useful from time to time, in particular when generating bar charts.

Bezier

Similar to paths.polygon, the module paths.bezier defines a curve that passes through a given list of vertices, but does so with a line that interpolates smoothly between the data points. Unlike polygons, curves produced in this way are always open.

An example is:

var Bezier = require('paths/bezier');
var points = [[1, 3], [2, 5], [3, 4], [4, 0]];
var curve = Bezier({
  points: points,
  tension: 0.4
});

The parameter tension is optional and defaults to 0.3; curves with smaller tension will look more pointy at the vertices.

Sector

A circular sector can be defined with paths.sector:

var Sector = require('paths/sector');
var sector = Sector({
  center: [10, 20],
  r: 5,
  R: 15,
  start: 0,
  end: Math.PI / 2
});

The Sector function takes as input an object having the following properties. center contains the coordinates of the center of the circles defining the sector; r and R are the internal and external radii; start and end are the start and end angle in radians. One can put r = 0 to get a degenerate sector.

Connector

A connector is an S-shaped path between two given points and lives in paths.connector:

var Connector = require('paths/connector');
var connector = Connector({
  start: [1, 12],
  end: [6, 3]
});

The Connector function takes as input an object having the start and end properties, both of which are points in the plane.

Curved Rectangle

A curved rectangle looks like a rectangle after Dalì has passed. It is a shape with vertical straight lines connected by two S-shaped connectors on the top and bottom. See the demo of the [Sankey Diagram] to see some examples of this shape. It lives in paths.curved-rectangle:

var CurvedRectangle = require('paths/curved-rectangle');
var curvedRectangle = CurvedRectangle({
  topleft: [1, 12],
  topright: [5, 10],
  bottomleft: [1, 7],
  bottomright: [5, 6]
});

The CurvedRectangle function takes as input an object having the four points topleft, topright, bottomleft and bottomright.