# @nphyx/vectrix

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.

# 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.

*currently out of date, sorry

## Install

`npm install --only=production`

`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```

MIT

## Package Sidebar

### Install

`npm i @nphyx/vectrix`

### Repository

github.com/nphyx/vectrix

0

0.2.1

MIT