@nphyx/vectrix

Vectrix 0.2.1

Vectrix is a matrix math library for javascript aimed at allowing the developer to make conscious tradeoffs between performance, flexibility, and expressiveness. Compared to alternatives, it is:

• more expressive and generalized than gl-matrix, but around 1.25 to 10x slower depending on operation and usage
• less general and less powerful than Math.js but easier to use and up to 30x faster

Vectrix is still a work in progress and is not recommended for production.

Usage

Vectrix supports commonjs modules:

const matrices = require("dist/vectrix.js").matrices;
const vectors = require("dist/vectrix.js").vectors;
const quaternions = require("dist/vectrix.js").quaternions;

It also supports ES6 modules, via the babel preprocessor

import {matrices, vectors, quaternions} from "src/vectrix";

Create vectors:

let xy = vectors.create.vec2(0,1); // 2d vector
let xyz = vectors.create.vec3(1,0,1); // 3d vector
let xyzw = vectors.create.vec4(1,0,0,1); // 4d vector

Create matrices:

let xyz = vectors.create.vec3(4,3,11);
let trans = matrices.create.translation(xyz); // a translation matrix
let rotX = matrices.create.rotateX(3.24); // a rotation matrix (angle in radians)

Create quaternions:

let q = quaternions.create.identity(); // quaternion(1.0,1.0,1.0,0.0);

Vectrix uses a functional style:

// add something to xy
vectors.plus(xy, [7,3]); // vec2(7,4)
// find the dot product of two vectors
vectors.dot(xy, [6,3]); // 3
// do a linear interpolation
vectors.lerp(xy, [4,5], 0.3); // vec2(1.2000000476837158, 2.200000047683716)
// multiply a vector by a rotation matrix to rotate it
vectors.dot(rotX, xyz); // vec3(-3.6859018802642822,-3.3784799575805664,11)

It doesn't mutate its operands:

vectors.plus(xy, [7,3]); // vec2(7,4)
xy; // vec2(0,1)

... except when you ask it to:

vectors.mut_plus(xy, [7,3]);
xy; // vec2(7,4)

... and it supports optional out parameters if you need to save on memory and garbage collection:

let out = vectors.create.vec2();
vectors.plus(xy, [7,3], out); // vec2(7,4)
out; // vec2(7,4)
vectors.plus(xy, [7,3], out) === out; // true

In fact, if you use out parameters wherever they're supported vectrix will almost never allocate memory, because it pre-allocates everything it needs during library initialization (and don't worry, it's a really small footprint).

Vectors, matrices, and quaternions can be wrapped as objects for more expressive usage, at the cost of performance:

// alternatively,
xy = vectors.wrap(xy);
xy.plus([7,3]).toArray(); // [7,4]
// wrapped objects also support GLSL-style aliases: 
xy.yx; // vec2(1,0);

When performance really matters, use the functional style with out parameters. When you need it to be easier to reason about and manipulate, the object oriented wrappers are helpful.

See the wiki for complete documentation*

*currently out of date, sorry

Install

npm install --only=production

Build

gulp

Testing

npm install --only=dev .
gulp test # test all modules
gulp test:vectors # only test vectors
gulp test:matrices # only test matrices
gulp test:quaterions # only test quaternions 
gulp test:coverage # run a coverage test with istanbul, lcov reports go in /coverage

License

MIT