Vectrix is a vector math library for Javascript intended for use in a mixed functional and object oriented style. It aims to support all the usual features you'd expect of vectors (2d, 3d, and 4d), vector manipulation matrices, and quaternions, but with an API more familiar to Javascript developers than the C-style libraries currently available.

Documentation for the Matrices module

Documentation for the Vectors module

Documentation for the Quaternions module

To date the best matrix math libraries are Toji's gl-matrix and Math.js. They work perfectly well, but I found them frustrating and cumbersome to use. I want vector math that is composable and expressive without sacrificing efficiency.

Vectrix should perform well under most circumstances. Some overhead is always created by using Babel to polyfill ES6 functionality, which I use pretty extensively here. That should solve itself over time, but if there are any serious performance hitches please report them as bugs with a test case and I'll see what I can do about it.

Internal functions tend to use clunkier code when it will have a substantial performance impact, but if it came down to a lower performance vs. more cumbersome API I chose lower performance. If you absolutely, positively, must squeeze the the most out of every frame stick with gl-matrix or math.js.

All functions are written first in a functional style, then added as methods to objects with the object bound to the first parameter. "this" is not used. Thus,

let a = vectors.vec2([0,2]);
let b = vectors.vec2([3,4]);
let c = vectors.vec2([2,3]);
a.times(b).times(c);

is equivalent to:

[...]
vectors.times(vectors.times(a,b),c);

Functions are written to be fairly ambivalent about their input values, so you can use array-like objects in place of Vectrix objects in most cases:

vectors.plus([2,3], [3,4]); // works just fine, but you get a vec2 back

Objects are composed in factory functions, using Float32Array as the base object. This is both for consistency with Javascript best practices, and because array-like objects can't be easily extended in Javascript. "new" is not used for object instantiation!

Since the internal representation is a Float32Array they are currently mutable, but probably won't stay that way when I can figure out a good way to make them static. Treat them asif they are immutable when using the library. Vectrix functions do not mutate their operands internally.

Vectrix functions are written using the Design by Contract approach, meaning they assume that you've provided valid parameters rather than doing a bunch of extraneous error checking. If you put garbage in, you will get garbage out, and Vectrix will not go to a lot of trouble to tell you how you messed up! This is for both performance and sanity reasons. Unit testing your code and paying attention to the documentation will save you a lot of headaches.

All functions and methods are 100% unit tested. In order of priority test assertions are based on:

• canonical sources (Wikipedia, textbooks, well-documented examples)
• results from other well-established math libraries
• hand calculations

There's still a chance some of the test cases are wrong, but the intent is to improve that with time.

All statements, functions and lines have 100% coverage. Branch coverage shoots for >90% due to a couple unreachable else conditions.

Will make more sense when it's supported natively. I don't want this library to have any dependencies for normal use (not counting build tools). It already uses Float32Arrays internally, so turning those into SIMD and making things officially immutable won't be a huge step.

I'm relatively new to matrix math and libraries for doing it. As such I don't know exactly what is and isn't useful or expected. I'm happy to accept feature requests, bug reports, and better yet pull requests for new features or fixes. The only thing I ask is that pull requets are unit tested with good coverage (for which mocha and istanbul are included in the dev dependencies and gulp file).