Features

• Lightweight.
• Pure functions.
• TypeScript declarations included.
• ESM package.

Installation

bun add @haydn/geometry-fns
deno add npm:@haydn/geometry-fns
npm install @haydn/geometry-fns
pnpm add @haydn/geometry-fns
yarn add @haydn/geometry-fns

Usage

import { createCircle } from "@haydn/geometry-fns";

const circle = createCircle([1, 2], 2);
//=> Circle { center: [1, 2], radius: 2 }

translate(circle, [1, 2]);
//=> Circle { center: [2, 4], radius: 2 }

:toolbox: Functions

• anchorToPoint
• angleBetween
• brandCircle
• brandRectangle
• createCircle
• createRectangle
• distance
• intersectRectangle
• isWithinCircle
• isWithinPolygon
• isWithinRectangle
• isWithinSegment
• polygonFromRectangle
• polygonFromCircle
• normalizeCircle
• normalizeRectangle
• print
• sizeOfCircle
• sizeOfRectangle
• translate

:gear: anchorToPoint

Converts shorthand anchor strings (e.g. "tl" or "cr") to the equivalent point or, if a point is provided, normalizes it.

| Function | Type | | ---------- | ---------- | | anchorToPoint | (anchor: Anchor) => Vec2 |

Parameters:

• anchor: Either a shorthand string (e.g. "tl" or "cr") or a point (e.g. [1, 0]).

Returns:

A normalized point where the x and y values are between 0 and 1.

Examples:

anchorToPoint("tl");
//=> [0, 0]

anchorToPoint("bc");
//=> [0.5, 1]

anchorToPoint([100, 0]);
//=> [1, 0]

anchorToPoint([-100, 0]);
//=> [0, 0]

:gear: angleBetween

Calculates the angle between point a and point b.

| Function | Type | | ---------- | ---------- | | angleBetween | (a: Vec2, b: Vec2) => number |

Parameters:

• a: The first point.
• b: The second point.

Returns:

The angle between the two points in radians where 0 is the three o'clock position.

Examples:

angleBetween([0, 0], [1, 0]);
//=> 0

angleBetween([0, 0], [0, 1]);
//=> Math.PI / 2

angleBetween([0, 0], [-1, 0]);
//=> Math.PI

angleBetween([0, 0], [0, -1]);
//=> -Math.PI / 2

:gear: brandCircle

Brands a circle primitive for type safety.

| Function | Type | | ---------- | ---------- | | brandCircle | (circle: [Vec2, Vec2]) => Circle |

Parameters:

• circle: The circle to brand.

Returns:

The branded circle primitive.

Examples:

brandCircle([[0, 0], [1, 0]]);
//=> Circle { center: (0,0), radius: 1 }

:gear: brandRectangle

Brands a rectangle primitive for type safety.

| Function | Type | | ---------- | ---------- | | brandRectangle | (rectangle: [Vec2, Vec2]) => Rectangle |

Parameters:

• rectangle: The rectangle to brand.

Returns:

The branded rectangle primitive.

Examples:

brandRectangle([[0, 0], [1, 1]]);
//=> Rectangle { position: (0,0), width: 1, height: 1 }

:gear: createCircle

Constructs a circle primitive.

| Function | Type | | ---------- | ---------- | | createCircle | (center: Vec2, radius: number, anchor?: Anchor) => Circle |

Parameters:

• radius: The radius of the circle.

Returns:

A circle object where the first vector is the center and the second is offset to the right by the radius amount.

Examples:

createCircle([0, 0], 1);
//=> Circle { center: (0,0), radius: 1 }

:gear: createRectangle

Constructs a rectangle primitive.

| Function | Type | | ---------- | ---------- | | createRectangle | (position: Vec2, width: number, height: number, anchor?: Anchor) => Rectangle |

Parameters:

• width: The width of the rectangle. If a negative value is provided, its absolute value will be used.
• height: The height of the rectangle. If a negative value is provided, its absolute value will be used.

Returns:

A normalized rectangle.

Examples:

createRectangle([0, 0], 2, 3);
//=> Rectangle { position: (0,0), width: 2, height: 3 }

:gear: distance

Calculates the absolute distance between two points.

| Function | Type | | ---------- | ---------- | | distance | (a: Vec2, b: Vec2) => number |

Parameters:

• a: The first point.
• b: The second point.

Returns:

The absolute distance between the two points.

Examples:

distance([0, 0], [3, 4]);
//=> 5

:gear: intersectRectangle

Calculates the intersection of two rectangles.

| Function | Type | | ---------- | ---------- | | intersectRectangle | (a: Rectangle, b: Rectangle) => Rectangle or null |

Parameters:

• a: The first rectangle.
• b: The second rectangle.

Returns:

The intersection of the two rectangles, or null if they do not intersect.

Examples:

intersectRectangle(createRectangle([0, 0], 10, 10), createRectangle([5, 5], 15, 15));
//=> Rectangle { position: (5,5), width: 10, height: 10 }

:gear: isWithinCircle

Determines if a point is within a circle. Points on the circumference are considered within the circle.

| Function | Type | | ---------- | ---------- | | isWithinCircle | (point: Vec2, circle: Circle) => boolean |

Parameters:

• point: The point to check.
• circle: The circle to check against.

Returns:

True if the point is within the circle, false otherwise.

Examples:

isWithinCircle([0, 0], createCircle([0, 0], 10));
//=> true

:gear: isWithinPolygon

Determines if a point is within a polygon. Points on the boundary are considered within the polygon. Will always return false if the polygon is empty. Points on the boundary are considered within the polygon.

| Function | Type | | ---------- | ---------- | | isWithinPolygon | (point: Vec2, polygon: Polygon) => boolean |

Parameters:

• point: The point to check.
• polygon: The polygon to check against.

Returns:

True if the point is within the polygon, false otherwise.

Examples:

isWithinPolygon([5, 5], [[0, 0], [10, 0], [10, 10], [0, 10]]);
//=> true

:gear: isWithinRectangle

Determines if a point is within a rectangle. Points on the boundary are considered within the rectangle.

| Function | Type | | ---------- | ---------- | | isWithinRectangle | (point: Vec2, rectangle: Rectangle) => boolean |

Parameters:

• point: The point to check.
• rectangle: The rectangle to check against.

Returns:

True if the point is within the rectangle, false otherwise.

Examples:

isWithinRectangle([5, 5], createRectangle([0, 0], 10, 10));
//=> true

:gear: isWithinSegment

Determines if a point falls somewhere along a segment.

| Function | Type | | ---------- | ---------- | | isWithinSegment | (point: Vec2, segment: Segment) => boolean |

Parameters:

• point: The point to check.
• segment: The segment to check against.

Returns:

True if the point is on the segment, false otherwise.

Examples:

isWithinSegment([5, 5], [[0, 0], [10, 10]]);
//=> true

:gear: polygonFromRectangle

Converts a rectangle primitive into a polygon. The points in the resulting polygon are ordered clockwise starting from the top-left corner.

| Function | Type | | ---------- | ---------- | | polygonFromRectangle | (rectangle: Rectangle) => Polygon |

Parameters:

• rectangle: The rectangle to convert.

Returns:

A polygon representation of the rectangle.

Examples:

polygonFromRectangle(createRectangle([0, 0], 10, 10));
//=> [[0, 0], [10, 0], [10, 10], [0, 10]]

:gear: polygonFromCircle

Converts a circle primitive into a polygon with the specified number of edges. The points in the resulting polygon are ordered clockwise starting from the three o'clock position.

| Function | Type | | ---------- | ---------- | | polygonFromCircle | (circle: Circle, numEdges?: number) => Polygon |

Parameters:

• circle: The circle to convert.
• numEdges: The number of edges on the polygon.

Returns:

A polygon representation of the circle.

Examples:

polygonFromCircle(createCircle([0, 0], 5), 4);
//=> [[5, 0], [0, 5], [-5, 0], [0, -5]]

:gear: normalizeCircle

Normalizes a circle primitive by moving the circumference point to a position directly right of the origin point (while preserving the radius).

| Function | Type | | ---------- | ---------- | | normalizeCircle | (circle: Circle) => Circle |

Parameters:

• circle: The circle to normalize.

Returns:

The normalized circle.

Examples:

normalizeCircle(brandCircle([[0, 0], [0, 5]]));
//=> [[0, 0], [5, 0]]

:gear: normalizeRectangle

Normalizes a rectangle primitive by ensuring the first point represents the top-left corner and the second point represents the bottom-right corner.

| Function | Type | | ---------- | ---------- | | normalizeRectangle | (rectangle: Rectangle) => Rectangle |

Parameters:

• rectangle: The rectangle to normalize.

Returns:

The normalized rectangle.

Examples:

normalizeRectangle(brandRectangle([[5, 5], [0, 0]]));
//=> [[0, 0], [5, 5]]

:gear: print

Prints a human-readable representation of a geometric value. Primitives are labeled with their name and properties.

| Function | Type | | ---------- | ---------- | | print | (value: number or Vec2 or Circle or Vec2[] or Rectangle) => string |

Parameters:

• value: The geometric primitive to print.

Returns:

A string representation of value.

Examples:

print(createCircle([0, 0], 1));
//=> Circle { center: (0,0), radius: 1 }

print(createRectangle([0, 0], 1, 1));
//=> Rectangle { position: (0,0), width: 1, height: 1 }

print([0, 0]);
//=> (0,0)

print([[0, 0], [1, 1]]);
//=> [(0,0), (1,1)]

print(1);
//=> 1

print(Math.PI);
//=> π

:gear: sizeOfCircle

Calculates the radius of a circle primitive. This is the distance between the two points representing the circle.

| Function | Type | | ---------- | ---------- | | sizeOfCircle | (circle: [Vec2, Vec2]) => number |

Parameters:

• circle: A circle represented as a pair of points.

Returns:

The radius of the circle.

Examples:

sizeOfCircle(createCircle([0, 0], 5));
//=> 5

:gear: sizeOfRectangle

Calculates the width and height of a rectangle. This is the absolute difference between the x-coordinates and y-coordinates of the two points representing the rectangle.

| Function | Type | | ---------- | ---------- | | sizeOfRectangle | (rectangle: [Vec2, Vec2]) => Vec2 |

Parameters:

• rectangle: A rectangle represented as a pair of points.

Returns:

The width and height of the rectangle.

Examples:

sizeOfRectangle(createRectangle([5, 5], 3, 4));
//=> [3, 4]

:gear: translate

Translates a figure by a given amount.

| Function | Type | | ---------- | ---------- | | translate | <F extends Figure>(figure: F, offset: Vec2) => F |

Parameters:

• figure: The figure to translate.
• offset: The amount to translate the figure.

Returns:

The translated figure.

Examples:

translate(createRectangle([5, 6], 3, 4), [1, 2]);
//=> Rectangle { position: [6, 7], width: 3, height: 4 }

:cocktail: Types

• Anchor
• Circle
• Figure
• Point
• Polygon
• Primitive
• Rectangle
• Segment

:gear: Anchor

A value used to describe an anchor point within a bounding rectangle. This can be either a two-dimensional vector between 0 and 1 (where 0 is the left or top edge and 1 is the right or bottom edge), or a shorthand string representing a predefined anchor point (where "tl" is the top-left corner, "cc" is the center, "br" is the bottom-right corner etc).

| Type | Type | | ---------- | ---------- | | Anchor | tl" or "tc" or "tr" or "cl" or "cc" or "cr" or "bl" or "bc" or "br" or Vec2 |

Examples:

const anchorA: Anchor = [0, 0.8];
const anchorB: Anchor = "bc";
const anchorC: Anchor = [1, 34];

:gear: Circle

A circle primitive represented by the point at the center of the circle and a point on the circumference. If the point on the circumference is directly to the right of the center point, then the circle is considered to be normalized.

| Type | Type | | ---------- | ---------- | | Circle | [Point, Point] and { [__primitive]: { type: "Circle" } } |

:gear: Figure

Any geometric construction represented by an array of points.

| Type | Type | | ---------- | ---------- | | Figure | Circle or Polygon or Rectangle or Segment |

:gear: Point

A point in 2D space where the first value is the x-coordinate and the second value is the y-coordinate.

| Type | Type | | ---------- | ---------- | | Point | Vec2 |

Examples:

const point: Point = [12.5, -40.2];

:gear: Polygon

A polygon represented by an array of points.

| Type | Type | | ---------- | ---------- | | Polygon | Array<Point> |

Examples:

const polygon: Polygon = [[45.67, 12.34], [-23.5, 0], [33.52, -24.6]];

:gear: Primitive

A geometric construction that is an abstract representation of a shape. Extra information beyond the dimensions of the shape are stored in a hidden property (e.g. the number of edges for a regular polygon).

| Type | Type | | ---------- | ---------- | | Primitive | { [__primitive]: { type: string } } and (Circle or Rectangle) |

:gear: Rectangle

A rectangle primitive represented by two points at opposite corners. If the first point represents the top-left corner and the second point represents the bottom-right corner, then the rectangle is considered to be normalized.

| Type | Type | | ---------- | ---------- | | Rectangle | [Point, Point] and { [__primitive]: { type: "Rectangle" } } |

:gear: Segment

A segment represented by two points.

| Type | Type | | ---------- | ---------- | | Segment | [Point, Point] |

Examples:

const segment: Segment = [[25, 2], [76, 88]];