geometric

A JavaScript library with geometric functions.

Usage no npm install needed!

<script type="module">
  import geometric from 'https://cdn.skypack.dev/geometric';
</script>

README

Geometric.js

A JavaScript library for doing geometry. Build Status

Installation

Web browser

In vanilla, a geometric global is exported. You can use the latest version from unpkg.

<script src="https://unpkg.com/geometric@2.2.8/build/geometric.js"></script>
<script src="https://unpkg.com/geometric@2.2.8/build/geometric.min.js"></script>

If you'd rather host it yourself, download the latest release from the build directory.

npm

npm i geometric -S

const geometric = require("geometric");

API

Geometric.js uses the geometric primitives points, lines, and polygons.

  • Points are represented as arrays of two numbers, such as [0, 0].
  • Lines are represented as arrays of two points, such as [[0, 0], [1, 0]]. Because they have endpoints, these are technically line segments, but Geometric.js refers to them as lines for simplicity's sake.
  • Polygons are represented as arrays of vertices, each of which is a point, such as [[0, 0], [1, 0], [1, 1], [0, 1]]. Polygons can be closed – the first and last vertex are the same – or open.
  • There are also functions to calculate relationships between these primitives.

You will also encounter angles, areas, distances, and lengths.

  • Angles are represented as numbers, measured in degrees. Geometric.js also provides functions to convert angles from degrees to radians or vice versa.
  • Areas, distances, and lengths are represented as numbers, measured in pixels.

Points

# geometric.pointRotate(point, angle[, origin]) · Source, Example

Returns the coordinates resulting from rotating a point about an origin by an angle in degrees. If origin is not specified, the origin defaults to [0, 0].

# geometric.pointTranslate(point, angle, distance) · Source, Example

Returns the coordinates resulting from translating a point by an angle in degrees and a distance.

Lines

# geometric.lineAngle(line) · Source, Example

Returns the angle of a line, in degrees, with respect to the horizontal axis.

# geometric.lineInterpolate(line) · Source, Example

Returns an interpolator function given a line [a, b]. The returned interpolator function takes a single argument t, where t is a number ranging from 0 to 1; a value of 0 returns a, while a value of 1 returns b. Intermediate values interpolate from a to b along the line segment.

# geometric.lineLength(line) · Source, Example

Returns the length of a line.

# geometric.lineMidpoint(line) · Source, Example

Returns the midpoint of a line.

Polygons

# geometric.polygonArea(polygon[, signed]) · Source, Example

Returns the area of a polygon. You can pass a boolean indicating whether the returned area is signed, which defaults to false.

# geometric.polygonBounds(polygon) · Source, Example

Returns the bounds of a polygon, ignoring points with invalid values (null, undefined, NaN, Infinity). The returned bounds are represented as an array of two points, where the first point is the top-left corner and the second point is the bottom-right corner. For example:

const rectangle = [[0, 0], [0, 1], [1, 1], [1, 0]];
const bounds = geometric.polygonBounds(rectangle); // [[0, 0], [1, 1]]

Returns null if the polygon has fewer than three points.

# geometric.polygonCentroid(polygon) · Source, Example

Returns the weighted centroid of a polygon. Not to be confused with a mean center.

# geometric.polygonHull(points) · Source, Example

Returns the convex hull, represented as a polygon, for an array of points. Returns null if the input array has fewer than three points. Uses Andrew’s monotone chain algorithm.

# geometric.polygonLength(polygon) · Source, Example

Returns the length of a polygon's perimeter.

# geometric.polygonMean(polygon) · Source, Example

Returns the arithmetic mean of the vertices of a polygon. Keeps duplicate vertices, resulting in different values for open and closed polygons. Not to be confused with a centroid.

# geometric.polygonRegular([sides[, area[, center]]]) · Source, Example

Returns the vertices of a regular polygon of the specified number of sides, area, and center coordinates. If sides is not specified, defaults to 3. If area is not specified, defaults to 100. If center is not specified, defaults to [0, 0].

# geometric.polygonRotate(polygon, angle[, origin]) · Source, Example

Returns the vertices resulting from rotating a polygon about an origin by an angle in degrees. If origin is not specified, the origin defaults to [0, 0].

# geometric.polygonScale(polygon, scaleFactor[, origin]) · Source, Example

Returns the vertices resulting from scaling a polygon by a scaleFactor (where 1 is the polygon's current size) from an origin point. If origin is not specified, the origin defaults to the polygon's centroid.

# geometric.polygonScaleX(polygon, scaleFactor[, origin]) · Source, Example

Returns the vertices resulting from scaling the horizontal coordinates of a polygon by a scaleFactor (where 1 is the polygon's current size) from an origin point. The vertical coordinates remain unchanged. If origin is not specified, the origin defaults to the polygon's centroid.

# geometric.polygonScaleY(polygon, scaleFactor[, origin]) · Source, Example

Returns the vertices resulting from scaling the vertical coordinates of a polygon by a scaleFactor (where 1 is the polygon's current size) from an origin point. The horizontal coordinates remain unchanged. If origin is not specified, the origin defaults to the polygon's centroid.

# geometric.polygonTranslate(polygon, angle, distance) · Source, Example

Returns the vertices resulting from translating a polygon by an angle in degrees and a distance.

Relationships

# geometric.lineIntersectsLine(lineA, lineB) · Source, Example

Returns a boolean representing whether lineA intersects lineB.

# geometric.lineIntersectsPolygon(line, polygon) · Source, Example

Returns a boolean representing whether a line intersects a polygon.

# geometric.pointInPolygon(point, polygon) · Source, Example

Returns a boolean representing whether a point is inside of a polygon. Uses ray casting.

# geometric.pointOnPolygon(point, polygon[, epsilon]) · Source, Example

Returns a boolean representing whether a point is located on one of the edges of a polygon. An optional epsilon number, such as 1e-6, can be passed to reduce the precision with which the relationship is measured.

# geometric.pointOnLine(point, line[, epsilon]) · Source, Example

Returns a boolean representing whether a point is collinear with a line and is also located on the line segment. An optional epsilon number, such as 1e-6, can be passed to reduce the precision with which the relationship is measured. See also pointWithLine.

# geometric.pointWithLine(point, line[, epsilon]) · Source, Example

Returns a boolean representing whether a point is collinear with a line. An optional epsilon number, such as 1e-6, can be passed to reduce the precision with which the relationship is measured. See also pointOnLine.

# geometric.pointLeftofLine(point, line) · Source, Example

Returns a boolean representing whether a point is to the left of a line.

# geometric.pointRightofLine(point, line) · Source, Example

Returns a boolean representing whether a point is to the right of a line.

# geometric.polygonInPolygon(polygonA, polygonB) · Source, Example

Returns a boolean representing whether polygonA is contained by polygonB.

# geometric.polygonIntersectsPolygon(polygonA, polygonB) · Source, Example

Returns a boolean representing whether polygonA intersects but is not contained by polygonB.

Angles

# geometric.angleReflect(incidence, surface) · Source, Example

Returns the angle of reflection given a starting angle, also known as the angle of incidence, and the angle of the surface off of which it is reflected.

# geometric.angleToDegrees(angle) · Source

Returns the result of a converting an angle in radians to the same angle in degrees.

# geometric.angleToRadians(angle) · Source

Returns the result of a converting an angle in degrees to the same angle in radians.