A small collection of 2D Cartesian and graphics related data structures and algorithms. Built on @rickosborne/typical for types, @rickosborne/guard for guards, and @rickosborne/foundation for basic data structures and algorithms.
Install via your favorite package manager.
Each package supports CommonJS require, ESM import, and TypeScript usage.
You also have a choice: barrel imports or direct imports.
Barrel imports mean you're going to require/import everything from the same package-level namespace:
// CommonJS
const { isPlainObject, isListOf } = require("@rickosborne/guard");
// ESM / TypeScript
import { isPlainObject, isListOf } from "@rickosborne/guard";Implications:
- Nice and simple.
- Your build system needs to do tree-shaking well ... or you'll end up adding the entire package even if you only import two functions.
The other option is to use direct imports:
// CommonJS
const { isPlainObject } = require("@rickosborne/guard/is-object");
const { isListOf } = require("@rickosborne/guard/is-list-of");
// ESM / TypeScript
import { isPlainObject } from "@rickosborne/guard/is-object.js";
import { isListOf } from "@rickosborne/guard/is-list-of.js";Implications:
- You (probably) don't have to worry about tree-shaking as your build (likely) ends up with only the functions you need.
If you're using a modern build system, there aren't any strong reasons to prefer one way over the other. It's really just down to your personal preference.
Do you need to use file extensions? And if so, which extensions?
Honestly ... this is a dumpster fire question. It really comes down to your own setup and configuration.
Within each package itself:
- The CommonJS files all have
.cjsextensions. - The ESM files all have
.mjsextensions. - Node subpath exports have been set up to send
.jsimports to the.cjs(viarequire) or.mjs(viaimport) files, depending on your setup.
So, in theory, the only extension which won't work would be .ts because the source isn't included.
If you run into a problem with a particular configuration, file a GitHub issue with:
- Your
tsconfig.json'smodule,moduleResolution, andtargetsettings. - Your
package.json'stypeandimportssettings. - An example of another package which imports correctly for you.
This package is licensed as CC-BY-NC-SA-4.0 unless otherwise noted. That is, Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.
enum Orientation Measure of the turn of an angle, based on the order of the three points which define it.
angle: (area: number, orientation: Orientation, rad: number) => AngleangleMeasures: (a: Point, b: Point, c: Point) => AngleMeasuresCalculate the intermediary values used in measuring an angle defined by the intersection of two line segments along three points: A, B, and C.
boundingBoxOf: (shape: Shape | LineSegment) => RectCalculate the bounding box of the given shape, meaning a minimum point plus a width and height. Note that the x and y values will be the numeric minimums, which will be bottom-left in Cartesian space and top-left in pixel space.
boundingBoxOfCircle: (circle: Circle) => RectCalculate the bounding box of the given circle, meaning a minimum point plus a width and height. Note that the x and y values will be the numeric minimums, which will be bottom-left in Cartesian space and top-left in pixel space.
boundingBoxOfLineSegment: (segment: LineSegment) => RectCalculate the bounding box which would contain the given line segment.
boundingBoxOfPath: (path: Path) => RectCalculate the bounding box which would contain the points in the given path.
cartesianOrientationOfPolygon: (poly: Polygon) => OrientationCalculate the orientation of a polygon as defined by the order of its points and its signed area. This does not necessarily imply the polygon is convex. This version uses Cartesian coordinates, where the origin is in the bottom left. See also gfxOrientationOfPolygon.
centroidOfPolygon: (poly: Polygon) => PointCalculate the centroid of a polygon, which is the weighted mean of its points. If the polygon has zero signed area, the centroid of the polygon's bounding box will be returned. The centroid is not guaranteed to be within the polygon if it is not convex.
detailedIsConvex: (poly: Polygon) => IsConvexMore detailed check to see if a polygon is convex. Tracks "bad" points and returns them if found. Slower than fastIsConvex, and doesn't necessarily return a better result, though it may give more information in scenarios where you want to try to split the polygon into smaller convex polygons.
fastIsConvex: (poly: Polygon) => booleanPerforms a rudimentary check of a polygon, calculating angles at each vertex and checking for sign flips in the line segment cross products. The result may not be reliable for symmetric shapes where the signed areas cancel out. This version also does not track "bad" points.
gfxOrientationOfPolygon: (poly: Polygon) => OrientationCalculate the orientation of a polygon as defined by the order of its points and its signed area. This does not necessarily imply the polygon is convex. This version uses graphics coordinates, where the origin is in the top left. See also cartesianOrientationOfPolygon.
isCircle: (obj: unknown) => obj is CircleGuard for whether the given value has x and y coordinates plus a radius r measure. May have more!
isDirectedSegment: (obj: unknown) => obj is DirectedSegmentGuard for whether the given value has a and b Point properties. May have more!
isLineSegment: (obj: unknown) => obj is LineSegmentGuard for whether the given value has blue and gold Point properties. May have more!
isPath: (obj: unknown, deep?: boolean) => obj is PathGuard for whether the given value has a list of points. It will not exhaustively check the points for validity unless deep is true.
isPoint: (obj: unknown) => obj is PointGuard for whether the given value has x and y coordinates. May have more!
isRect: (obj: unknown) => obj is RectGuard for whether the given value has x and y coordinates plus w and h measures. May have more!
measureAngle: (a: Point, b: Point, c: Point) => AngleGiven three points which define the ordered intersection of two line segments, calculate the angle between them.
measureAngles: (poly: Polygon) => PolygonWithRadiansUpgrade a polygon to include angle measurements for its vertices.
perimeterOfPolygon: (poly: Polygon) => numberpoint: (x: number, y: number) => PointpointAdd: (a: Point, b: Point) => PointpointEq: (a: Point, b: Point) => booleanpolygonFromLineSegment: (segment: LineSegment) => PolygonConvert the given LineSegment to Polygon format. Arbitrarily places the left/bottom point first and right/top point second.
polygonFromRect: (rect: Rect) => PolygonConvert the given Rect to Polygon format.
prettyRad: (rad: number, epsilon?: number) => stringTry to figure out a reasonably human-readable fraction for the given angle in radians.
reversePolygon: <P extends Polygon>(poly: P) => PReverse the point order of a polygon, while keeping the starting point the same.
signedAreaOfPolygon: (poly: Polygon) => numberCalculate the signed area of a polygon.
signOf: (n: number) => SignReduce a number to a unit (1) with a sign.
type Angle = {
area: number;
orientation: Orientation;
rad: number;
};An angle between two line segments, often as an interior angle for a polygon.
type AngleMeasures = {
abx: number;
aby: number;
bcx: number;
bcy: number;
area: number;
orientation: Orientation;
};Mixin for the intermediary values used for calculating angles defined by the intersection of two line segments across three points: A, B, and C.
type Circle = Point & {
r: number;
};An equal radius out from a center point.
type ConvexWithOrientation = {
convex: true;
orientation: Orientation.Counter | Orientation.Clockwise;
};Result of a calculation of whether a polygon is convex indicating the polygon is complex.
type DirectedSegment = {
a: Point;
b: Point;
};A directed line segment joining two points in a specific order.
type IsConvex = Either<ConvexWithOrientation, NotConvex>;Result of a calculation of whether a polygon is convex.
type LineSegment = {
blue: Point;
gold: Point;
};An undirected line segment joining two points.
type NotConvex = {
badPoints?: number[];
convex: false;
firstOrientation?: Orientation | undefined;
overallOrientation?: Orientation | undefined;
};Result of a calculation of whether a polygon is convex, indicating that it does not seem to be, or is still unknown.
type Path = {
points: Point[];
};An ordered sequence of points.
type Point = {
x: number;
y: number;
};Coordinates in 2D space.
type Polygon = Path;An ordered sequence of points, generally assuming the last point connects back around to the first.
type PolygonWithRadians = {
points: WithAngles<Point>[];
};A sequence of points where the interior angle at each has been measured.
type Rect = Point & {
h: number;
w: number;
};A rectangle with no rotation. Note that this structure does not encode whether the origin point is in the bottom left (Cartesian) or top left (graphics).
type Shape = Polygon | Rect | Circle;For algorithms which work on basic shapes.
type Sign = -1 | 0 | 1;Could be an Orientation, or just a simple indication of the sign of a number.
type WithAngles<T extends object> = T & Angle;Mixin which adds angle information to some other type.
CCW = Orientation.CounterShorter version of Orientation.Counter.
CONVEX_TRUE_CCW: IsConvexBasic shared value for a true IsConvex result with a counterclockwise orientation.
CONVEX_TRUE_CW: IsConvexBasic shared value for a true IsConvex result with a clockwise orientation.
CW = Orientation.ClockwiseShorter version of Orientation.Clockwise.
EPSILON = 0.00001ORIGIN: Readonly<{
x: 0;
y: 0;
}>PI: numberPI_2: numberPI_2_3: numberPI_3: numberPI_3_4: numberPI_4: numberPI_5: numberPI_6: numberPI_7: numberPI_8: numberPI_9: numberSQRT_2: numberSQRT_3: numberSQRT_5: numberSTRAIGHT = Orientation.StraightShorter version of Orientation.Straight.
TWO_PI: number