Noteworthy Placebo Mongers


    0.2.1 • Public • Published

    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.


    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, [7,3]); // vec2(7,4)
    // find the dot product of two vectors, [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, xyz); // vec3(-3.6859018802642822,-3.3784799575805664,11)

    It doesn't mutate its operands:, [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();, [7,3], out); // vec2(7,4)
    out; // vec2(7,4), [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);[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


    npm install --only=production




    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



    Dependencies (0)

      Dev Dependencies (15)


      npm i @nphyx/vectrix

      DownloadsWeekly Downloads






      Last publish


      • nphyx