This project is part of the @thi.ng/umbrella monorepo.

• About
  • Features
  • Status
  • Breaking changes in v6.0.0
  • Breaking changes in v3.0.0
  • Related packages
• Installation
• Dependencies
• Usage examples
• API
  • Naming conventions
  • Constants
  • Component setters & copying
  • Component swizzling
  • Vector creation
  • Basic vector math
    • Vector / vector
    • Vector / scalar
  • Combined operations
  • Constraints
  • Cross product
  • Dot product
  • Interpolation
  • Normalization / magnitude
  • Distances
  • Orientation
  • Rotations
  • Polar / cartesian conversion
  • Randomness
  • Unary vector math ops
  • Vector array batch processing
  • Comparison / equality
  • Bitwise operations (int / uint vec)
  • Vector conversions / coercions
  • Boolean vector logic
  • Componentwise comparisons
  • Hashing
  • Code generator
• Authors
• License

Optimized 2d/3d/4d and arbitrary length vector operations.

Likely the most comprehensive vector library for TypeScript / JavaScript currently available.

This package provides over 800(!) largely code generated functions and supporting types to perform vector operations on fixed and arbitrary-length vectors, both packed and strided (i.e. where individual vector components are not successive array elements, for example in SOA memory layouts).

Includes componentwise logic operations for boolean vectors, componentwise comparisons for numeric vectors and componentwise binary ops for signed & unsigned integer vectors.

• Small & fast: The vast majority of functions are code generated with fixed-sized versions not using any loops. Minified + gzipped, the entire package is ~11.8KB (though you'll hardly ever use all functions).
• Unified API: Any ArrayLike type can be used as vector containers (e.g. JS arrays, typed arrays, custom impls). Most functions are implemented as multi-methods, dispatching to any potentially optimized versions based on given vector arguments.
• Highly modular: Each function is defined in its own submodule / file. In addition to each generic multi-method base function, all fixed-length optimized versions are exported too. E.g. If add performs vector addition on arbitrary-length vectors, add2, add3, add4 are the optimized version for fixed-length vectors...
• Extensible: Custom vector ops can be defined in a similar manner using the provided code generation helpers (see vop.ts and emit.ts for details).
• Immutable by default: Each operation producing a vector result takes an output vector as first argument. If null, the vector given as 2nd argument will (usually) be used as output (i.e. for mutation).
• Strided vector support is handled via the lightweight Vec2/3/4 class wrappers and the gvec() proxy (for generic, arbitrary-length vectors). These types behave like normal arrays (for read/write operations) and are also iterable. A subset of functions (suffixed with S, e.g. addS vs. add) also support striding without the need for extra class wrappers. This is handled via additional index and stride arguments for each input/output vector. These functions are only available for sizes 2 / 3 / 4, though.
• Random vector functions support the IRandom interface defined by @thi.ng/random to work with custom (P)RNGs. If omitted, the built-in Math.random() will be used.

Partially ported from thi.ng/geom-clj (Clojure) and c.thi.ng (C11).

STABLE - used in production

Search or submit any issues for this package

The introduction of seveveral standard libc math functions to the @thi.ng/math package caused a behavior change of existing fmod() function. For symmetry reasons the same changes have been applied to this package...

• swap fmod() ⇄ mod(), to align the latter with its GLSL counterpart
• the new fmod() has standard libc behavior (same as JS % operator)
• add remainder() with standard libc behavior

• to avoid confusion, the arg order of madd and maddN functions have been updated to be compatible with the OpenCL mad function and to generally follow the expanded name, i.e. multiply-add:
  • madd([], a, b, c): before a + b * c, now: a * b + c
  • maddN([], a, b, n) => maddN([], a, n, b) (i.e. a * n + b)
• rename perpendicularLeft2 => perpendicularCCW
• rename perpendicularRight2 => perpendicularCW
• rename normalLeft2/ normalRight2 => normalCCW / normalCW

• @thi.ng/color - Array-based color types, CSS parsing, conversions, transformations, declarative theme generation, gradients, presets
• @thi.ng/distance - N-dimensional distance metrics & K-nearest neighborhoods for point queries
• @thi.ng/ecs - Entity Component System based around typed arrays & sparse sets
• @thi.ng/geom - Functional, polymorphic API for 2D geometry types & SVG generation
• @thi.ng/hdom-canvas - @thi.ng/hdom component wrapper for declarative canvas scenegraphs
• @thi.ng/imgui - Immediate mode GUI with flexible state handling & data only shape output
• @thi.ng/matrices - Matrix & quaternion operations for 2D/3D geometry processing
• @thi.ng/simd - WASM based SIMD vector operations for batch processing
• @thi.ng/soa - SOA & AOS memory mapped structured views with optional & extensible serialization
• @thi.ng/shader-ast-js - Customizable JS codegen, compiler & runtime for @thi.ng/shader-ast
• @thi.ng/vector-pools - Data structures for managing & working with strided, memory mapped vectors
• @thi.ng/webgl - WebGL & GLSL abstraction layer

yarn add @thi.ng/vectors

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/vectors"></script>

Skypack documentation

For Node.js REPL:

# with flag only for < v16
node --experimental-repl-await

> const vectors = await import("@thi.ng/vectors");

Package sizes (gzipped, pre-treeshake): ESM: 12.86 KB

• @thi.ng/api
• @thi.ng/binary
• @thi.ng/checks
• @thi.ng/equiv
• @thi.ng/errors
• @thi.ng/math
• @thi.ng/memoize
• @thi.ng/random
• @thi.ng/strings
• @thi.ng/transducers

Several demos in this repo's /examples directory are using this package.

A selection:

Screenshot	Description	Live demo	Source
	Canvas based dial widget	Demo	Source
	Interactive visualization of closest points on ellipses	Demo	Source
	Doodle w/ K-nearest neighbor search result visualization	Demo	Source
	Mouse gesture / stroke analysis, simplification, corner detection	Demo	Source
	Realtime analog clock demo	Demo	Source
	Interactive pattern drawing demo using transducers	Demo	Source
	2D Bezier curve-guided particle system	Demo	Source
	Various hdom-canvas shape drawing examples & SVG conversion / export	Demo	Source
	Canvas based Immediate Mode GUI components	Demo	Source
	Animated sine plasma effect visualized using contour lines	Demo	Source
	CLI util to visualize umbrella pkg stats		Source
	Unison wavetable synth with waveform editor	Demo	Source
	Animated Voronoi diagram, cubic splines & SVG download	Demo	Source
	2D scenegraph & shape picking	Demo	Source
	2D scenegraph & image map based geometry manipulation	Demo	Source
	Minimal shader graph developed during livestream #2	Demo	Source
	Entity Component System w/ 100k 3D particles	Demo	Source
	Compute cubic spline position & tangent using Dual Numbers	Demo	Source
	3D wireframe textmode demo	Demo	Source
	WebGL multi-colored cube mesh	Demo	Source
	WebGL instancing, animated grid	Demo	Source
	WebGL MSDF text rendering & particle system	Demo	Source

import * as v from "@thi.ng/vectors";

// immutable vector addition (1st arg is result)
v.add([], [1, 2, 3, 4], [10, 20, 30, 40]);
// [11, 22, 33, 44]

// mutable addition
// (if first arg (output) is null writes result to 2nd arg)
a = [1, 2, 3];
v.add(null, a, a);
// [2, 4, 6]

// multiply-add (o = a * b + c)
v.madd([], [10, 20], [0.5, 0.25], [1, 2]);
// [6, 7]

// multiply-add w/ scalar (o = a * n + b)
v.maddN([], [10, 20], 0.5, [1, 2]);
// [6, 12]

// scalar addition w/ arbitrary length & strided vector
v.addN([], gvec([0, 1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0], 3, 1, 4), 10);
// [11, 12, 13]

// or operate on raw arrays directly...
// here the last 4 args define:
// out index, src index, out stride, src stride
v.addNS3(null, [0, 1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0], 10, 1, 1, 4, 4)
// [0, 11, 0, 0, 0, 12, 0, 0, 0, 13, 0, 0, 0]

v.dist([1, 2], [100, 200]);
// 221.37072977247917

v.distManhattan([1, 2], [100, 200]);
// 297

v.distChebyshev([1, 2], [100, 200]);
// 198

v.mixN([], [1, 2], [10, 20], 0.5);
// [5.5, 11]

v.fromHomogeneous([], [100, 200, 0.5]);
// [200, 400]

v.swizzle4([], [1, 2], 1, 1, 0, 0);
// [ 2, 2, 1, 1 ]

v.hash([1, 2, 3])
// 2383338936

Generated API docs

Wherever possible, each operation comes in different variations. All fixed size versions use optimized, loop-free implementations.

• MAX2 / MAX3 / MAX4 - each component +Infinity
• MIN2 / MIN3 / MIN4 - each component -Infinity
• ONE2 / ONE3 / ONE4 - each component 1
• ZERO2 / ZERO3 / ZERO4 - each component 0
• X2 / X3 / X4 - positive X axis
• Y2 / Y3 / Y4 - positive Y axis
• Z3 / Z4 - positive Z axis
• W4 - positive W axis

• set / set2 / set3 / set4
• setC / setC2 / setC3 / setC4 / setC6
• setN / setN2 / setN3 / setN4
• setS / setS2 / setS3 / setS4
• setCS2 / setCS3 / setCS4
• setNS2 / setNS3 / setNS4
• copy
• empty
• one
• zero

• swizzle2 / swizzle3 / swizzle4
• setSwizzle1 / setSwizzle2 / setSwizzle3 / setSwizzle4
• swapXY / swapXZ / swapYZ

Functions to create wrapped (strided) vector instances:

• vec2 / vec2n
• vec3 / vec3n
• vec4 / vec4n
• gvec

Wrap existing vanilla vectors:

• asVec2 / asVec3 / asVec4

Vanilla vector (array) factories:

• ones
• zeroes
• vecOf
• setVN3 / setVN4
• setVV4 / setVV6 / setVV9 / setVV16

Component wise op with 2 input vectors:

// generic
add([], [1, 2, 3, 4, 5], [10, 20, 30, 40, 50]);
// [11, 22, 33, 44, 55]

// fixed size & packed
add2([], [1, 2], [10, 20])
// [11, 22]

// unsigned int
addU2([], [1, -2], [-10, 20])
// [4294967287, 18]

// strided
addS2([], [1,0,2,0], [0,10,0,0,0,20], 0, 0, 1, 1, 2, 4)
// [11, 22]

Component wise op with one input vector and single scalar:

(Also see rotation matrices provided by @thi.ng/matrices)

All ops support custom PRNG impls based on the @thi.ng/random IRandom interface and use Math.random by default:

Functions to transform flat / strided buffers w/ vector operations:

• mapV / mapVN / mapVV / mapVVN / mapVVV
• mean / median
• minBounds / maxBounds

• comparator2 / comparator3 / comparator4
• equals / equals2 / equals3 / equals4
• eqDelta / eqDelta2 / eqDelta3 / eqDelta4
• eqDeltaS
• eqDeltaArray

Arguments are assumed to be signed / unsigned ints. Results will be forced accordingly.

• asIVec (2-4) - signed int vector
• asUVec (2-4) - unsigned int vector
• asBVec (2-4) - boolean vector
• fromBVec (2-4) - coerces each component to 0/1

All resulting in boolean vectors:

• hash

• compile / compileG / compileGHOF / compileHOF
• defOp / defOpS / defFnOp / defHofOp
• defMathNOp / defMathOp
• vop

For more information about the code generator see:

• emit.ts
• templates.ts
• vop.ts

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-vectors,
  title = "@thi.ng/vectors",
  author = "Karsten Schmidt",
  note = "https://thi.ng/vectors",
  year = 2015
}

© 2015 - 2021 Karsten Schmidt // Apache Software License 2.0