@id-sdk/vector

@id-sdk/vector

📐 Vector (coordinate) math functions

Installing

npm install @id-sdk/vector

This library is distributed in ESM format only. It cannot be require()'d from CommonJS. For more, please read Sindre Sorhus’s FAQ.

import * as vec from '@id-sdk/vector';
import { vecEqual } from '@id-sdk/vector';

Contributing

This project is just getting started! 🌱

We're not able to support external contributors at this time, but check back in a bit when things have matured.

API Reference

Functions

• vecEqual(a: Vec2, b: Vec2, epsilon?: number): boolean
• vecAdd(a: Vec2, b: Vec2): Vec2
• vecSubtract(a: Vec2, b: Vec2): Vec2
• vecScale(a: Vec2, n: number): Vec2
• vecFloor(a: Vec2): Vec2
• vecInterp(a: Vec2, b: Vec2, t: number): Vec2
• vecLength(a: Vec2, b?: Vec2): number
• vecNormalize(a: Vec2): Vec2
• vecAngle(a: Vec2, b: Vec2): number
• vecDot(a: Vec2, b: Vec2, origin?: Vec2): number
• vecNormalizedDot(a: Vec2, b: Vec2, origin?: Vec2): number
• vecCross(a: Vec2, b: Vec2, origin?: Vec2): number
• vecProject(a: Vec2, points: Vec2[]): Edge | null

Types

• Vec2: [number, number]
• Edge: { index: number, distance: number, target: Vec2 }

Functions

# vecEqual(a: Vec2, b: Vec2, epsilon?: number): boolean <>

Test whether two given vectors are equal (optionally, to within epsilon).

vecEqual([1, 2], [1, 2]);                         // returns true
vecEqual([1, 2], [1.0000001, 2.0000001], 1e-5);   // returns true

# vecAdd(a: Vec2, b: Vec2): Vec2 <>

Adds two vectors, returns the vector sum of a + b.

vecAdd([1, 2], [3, 4]);   // returns [4, 6]

# vecSubtract(a: Vec2, b: Vec2): Vec2 <>

Subtracts two vectors, returns the vector difference of a - b.

vecSubtract([1, 2], [3, 4]);   // returns [-2, -2]

# vecScale(a: Vec2, n: number): Vec2 <>

Scale a vector uniformly by factor, returns the scaled vector.

vecScale([1, 2], 2);   // returns [2, 4]

# vecFloor(a: Vec2): Vec2 <>

Round down the coordinates of a vector.

vecFloor([0, 1.01]);   // returns [0, 1]

# vecInterp(a: Vec2, b: Vec2, t: number): Vec2 <>

Linear interpolate a point along a vector.

vecInterp([0, 0], [10, 10], 0.5);   // returns [5, 5]

# vecLength(a: Vec2, b?: Vec2): number <>

Returns the length of a vector. If b is not passed in, it defaults to [0,0].

vecLength([0, 0], [4, 3]);   // returns 5
vecLength([4, 3]);           // returns 5

# vecNormalize(a: Vec2): Vec2 <>

Normalize a vector (i.e. returns a unit vector).

vecNormalize([5, 0]);   // returns [1, 0]

# vecAngle(a: Vec2, b: Vec2): number <>

Returns the counterclockwise angle in the range (-pi, pi) between the positive X axis and the line intersecting a and b.

vecAngle([0, 0], [-1, 0]);   // returns π

# vecDot(a: Vec2, b: Vec2, origin?: Vec2): number <>

Returns the dot product of two vectors. If origin is not passed in, it defaults to [0,0].

vecDot([2, 0], [2, 0]);   // returns 4

# vecNormalizedDot(a: Vec2, b: Vec2, origin?: Vec2): number <>

Normalized Dot Product - normalizes input vectors before returning dot product. If origin is not passed in, it defaults to [0,0].

vecNormalizedDot([2, 0], [2, 0]);   // returns 1

# vecCross(a: Vec2, b: Vec2, origin?: Vec2): number <>

Returns the 2D cross product of OA and OB vectors, returns magnitude of Z vector. If origin is not passed in, it defaults to [0,0].

This returns a positive value, if OAB makes a counter-clockwise turn, negative for clockwise turn, and zero if the points are collinear.

vecCross([2, 0], [0, 2]);   // returns 4

# vecProject(a: Vec2, points: Vec2[]): Edge | null <>

Find closest orthogonal projection of point onto points array. Returns an Edge object containing info about the projected point, or null if points is a degenerate path (0- or 1- point).

//     c
//     |
// a --*--- b
//
// * = [2, 0]
//
const a = [0, 0];
const b = [5, 0];
const c = [2, 1];
vecProject(c, [a, b]);   // returns Edge { index: 1, distance: 1, target: [2, 0] }

Types

# Vec2

An array of two numbers.

[number, number]

# Edge

An Object containing index, distance, and target properties. Used as the return value for vecProject().

{ index: number, distance: number, target: Vec2 }