README
@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
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]
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 }