Geometric.js
A JavaScript library for doing geometry.
[
](https://bl.ocks.org/HarryStevens/5fe49df19892c04dfb9883c217571409)[
](https://bl.ocks.org/HarryStevens/c4eddfb97535e8e01643325cb43175ff)[
](https://bl.ocks.org/HarryStevens/37287b23b345f394f8276dc87a9c2bc6)
Installation
Web browser
In vanilla, a geometric global is exported. You can use the latest version from unpkg.
- ``` html
- <script src="https://unpkg.com/geometric@2.5.0/build/geometric.js"></script>
- <script src="https://unpkg.com/geometric@2.5.0/build/geometric.min.js"></script>
- ```
If you'd rather host it yourself, download the latest release from the [build directory](https://github.com/HarryStevens/geometric/tree/master/build).
npm
- ``` sh
- npm i geometric -S
- ```
- ``` js
- const geometric = require("geometric");
- ```
API
Geometric.js uses the geometric primitives
points,
lines, and
polygons.* [
Points](#points) are represented as arrays of two numbers, such as [0, 0].* [
Lines](#lines) are represented as arrays of two points, such as [[0, 0], [1, 0]]. Because they have endpoints, these are technically [line
segments](https://web.archive.org/web/20170829200252/https://www.mhschool.com/math/mathconnects/wa/assets/docs/394_397_wa_gr3_adllsn_onln.pdf), but Geometric.js refers to them as lines for simplicity's sake.* [
Polygons](#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.
You will also encounter
angles,
areas,
distances, and
lengths.* [
Angles](#angles) are represented as numbers, measured in degrees. Geometric.js also provides functions to convert angles from [degrees to radians](#angleToRadians) or [vice versa](#angleToDegrees).*
Areas,
distances, and
lengths are represented as numbers, measured in pixels.
###
Points
# geometric.
pointRotate(
point,
angle[,
origin]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/points/pointRotate.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-pointrotate "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](https://github.com/HarryStevens/geometric/blob/master/src/points/pointTranslate.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-pointtranslate "Example")
Returns the coordinates resulting from translating a
point by an
angle in degrees and a
distance.
###
Lines
# geometric.
lineAngle(
line) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/lines/lineAngle.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-lineangle "Example")
Returns the angle of a
line, in degrees, with respect to the horizontal axis.
# geometric.
lineInterpolate(
line) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/lines/lineInterpolate.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-lineinterpolate "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](https://github.com/HarryStevens/geometric/blob/master/src/lines/lineLength.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-linelength "Example")
Returns the length of a
line.
# geometric.
lineMidpoint(
line) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/lines/lineMidpoint.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-linemidpoint "Example")
Returns the midpoint of a
line.
# geometric.
lineRotate(
line,
angle[,
origin]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/lines/lineRotate.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-linerotate "Example")
Returns the coordinates resulting from rotating a
line about an origin by an
angle in degrees. If
origin is not specified, the origin defaults to the
midpoint of the line.
# geometric.
lineTranslate(
line,
angle,
distance) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/lines/lineTranslate.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-linetranslate "Example")
Returns the coordinates resulting from translating a
line by an
angle in degrees and a
distance.
###
Polygons
# geometric.
polygonArea(
polygon[,
signed]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonArea.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonarea "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](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonBounds.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonbounds "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:
- ``` js
- 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](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonCentroid.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygoncentroid-geometric-polygonmean "Example")
Returns the weighted centroid of a
polygon. Not to be [confused](https://github.com/Turfjs/turf/issues/334) with a [mean center](#polygonMean).
# geometric.
polygonHull(
points) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonHull.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonhull "Example")
Returns the [convex hull](https://en.wikipedia.org/wiki/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](https://en.wikibooks.org/wiki/Algorithm_Implementation/Geometry/Convex_hull/Monotone_chain#JavaScript).
# geometric.
polygonInterpolate(
polygon) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonInterpolate.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygoninterpolate "Example")
Returns an interpolator function given a
polygon of vertices [a, ..., n]. 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 n. Intermediate values interpolate from a to n along the polygon's perimeter.
# geometric.
polygonLength(
polygon) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonLength.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonlength "Example")
Returns the length of a
polygon's perimeter.
# geometric.
polygonMean(
polygon) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonMean.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygoncentroid-geometric-polygonmean "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.
polygonRandom([
sides[,
area[,
centroid]]]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonRandom.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonrandom "Example")
Returns the vertices of a random convex polygon of the specified number of
sides,
area, and
centroid coordinates. If
sides is not specified, defaults to 3. If
area is not specified, defaults to 100. If
centroid is not specified, defaults to [0, 0]. The returned polygon's winding order will be counter-clockwise. Based on an algorithm by Pavel Valtr and an [implementation by Maneesh Agrawala](https://observablehq.com/@magrawala/random-convex-polygon).
# geometric.
polygonReflectX(
polygon[,
reflectFactor]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonReflectX.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonreflectx "Example")
Reflects a
polygon over its vertical midline. Pass an optional
reflectFactor between 0 and 1, where 1 indicates a full reflection, 0 leaves the polygon unchanged, and 0.5 collapses the polygon on its vertical midline.
# geometric.
polygonReflectY(
polygon[,
reflectFactor]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonReflectY.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonreflecty "Example")
Reflects a
polygon over its horizontal midline. Pass an optional
reflectFactor between 0 and 1, where 1 indicates a full reflection, 0 leaves the polygon unchanged, and 0.5 collapses the polygon on its horizontal midline.
# geometric.
polygonRegular([
sides[,
area[,
center]]]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonRegular.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonregular "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]. The returned polygon's winding order will be counter-clockwise.
# geometric.
polygonRotate(
polygon,
angle[,
origin]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonRotate.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonrotate "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](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonScale.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonscale "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.
The returned polygon's area is equal to the input polygon's area multiplied by the square of the
scaleFactor. To scale the polygon's area by the
scaleFactor itself, see
geometric.polygonScaleArea.
# geometric.
polygonScaleArea(
polygon,
scaleFactor[,
origin]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonScaleArea.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonscalearea "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.
The returned polygon's area is equal to the input polygon's area multiplied by the
scaleFactor. To scale the polygon's area by the square of the
scaleFactor, see
geometric.polygonScale.
# geometric.
polygonScaleX(
polygon,
scaleFactor[,
origin]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonScaleX.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonscalex "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.
The returned polygon's area is equal to the input polygon's area multiplied by the
scaleFactor.
# geometric.
polygonScaleY(
polygon,
scaleFactor[,
origin]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonScaleY.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonscaley "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.
The returned polygon's area is equal to the input polygon's area multiplied by the
scaleFactor.
# geometric.
polygonTranslate(
polygon,
angle,
distance) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonTranslate.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygontranslate "Example")
Returns the vertices resulting from translating a
polygon by an
angle in degrees and a
distance.
# geometric.
polygonWind(
polygon[,
order]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/polygons/polygonWind.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonwind "Example")
Returns a
polygon in the specified winding order. If an
order string is passed as either "cw" or "clockwise", returns a polygon with a clockwise winding order. Otherwise, returns a polygon with a counter-clockwise winding order. Returns null if the
polygon has fewer than three points.
On computer screens where the top-left corner is at [0, 0], a polygon with a negative signed area has a counter-clockwise winding order.
###
Relationships
# geometric.
lineIntersectsLine(
lineA,
lineB) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/lineIntersectsLine.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-lineintersectsline "Example")
Returns a boolean representing whether
lineA intersects
lineB.
# geometric.
lineIntersectsPolygon(
line,
polygon) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/lineIntersectsPolygon.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-lineintersectspolygon "Example")
Returns a boolean representing whether a
line intersects a
polygon.
# geometric.
pointInPolygon(
point,
polygon) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/pointInPolygon.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-pointinpolygon "Example")
Returns a boolean representing whether a
point is inside of a
polygon. Uses [ray casting](https://en.wikipedia.org/wiki/Point_in_polygon#Ray_casting_algorithm).
# geometric.
pointOnPolygon(
point,
polygon[,
epsilon]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/pointOnPolygon.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-pointonpolygon "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](https://github.com/HarryStevens/geometric/blob/master/src/relationships/pointOnLine.js#L17 "Source"), [Example](https://observablehq.com/@harrystevens/geometric-pointonline-geometric-pointwithline "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](#pointWithLine).
[
](https://observablehq.com/d/c463ce4b7cbcd048)
# geometric.
pointWithLine(
point,
line[,
epsilon]) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/pointOnLine.js#L21 "Source"), [Example](https://observablehq.com/@harrystevens/geometric-pointonline-geometric-pointwithline "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](#pointOnLine).
# geometric.
pointLeftofLine(
point,
line) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/pointOnLine.js#L9 "Source"), [Example](https://observablehq.com/@harrystevens/geometric-pointleftofline-geometric-pointrightofline-g "Example")
Returns a boolean representing whether a
point is to the left of a
line.
# geometric.
pointRightofLine(
point,
line) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/pointOnLine.js#L13 "Source"), [Example](https://observablehq.com/@harrystevens/geometric-pointleftofline-geometric-pointrightofline-g "Example")
Returns a boolean representing whether a
point is to the right of a
line.
# geometric.
polygonInPolygon(
polygonA,
polygonB) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/polygonInPolygon.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygoninpolygon "Example")
Returns a boolean representing whether
polygonA is contained by
polygonB.
# geometric.
polygonIntersectsPolygon(
polygonA,
polygonB) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/relationships/polygonIntersectsPolygon.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-polygonintersectspolygon "Example")
Returns a boolean representing whether
polygonA intersects but is not contained by
polygonB.
Angles
# geometric.
angleReflect(
incidence,
surface) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/angles/angleReflect.js "Source"), [Example](https://observablehq.com/@harrystevens/geometric-anglereflect "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](https://github.com/HarryStevens/geometric/blob/master/src/angles/angleToDegrees.js "Source")
Returns the result of converting an
angle in radians to the same angle in degrees.
# geometric.
angleToRadians(
angle) · [Source](https://github.com/HarryStevens/geometric/blob/master/src/angles/angleToRadians.js "Source")
Returns the result of converting an
angle in degrees to the same angle in radians.