vec-la-fp
v1.9.0
Published
A tiny (function) 2d linear algebra library
Downloads
62
Readme
vec-la-fp
Vec-la-fp
is the functional version of the vec-la
library. All functions are curried with arguments reordered to support composition. MatrixBuilder is replaced with composable calls to mRotate
, mTranslate
, mScale
, mShear
, and mCompose
for arbitrary matrix concatenations.
Includes typescript types.
Installation
npm install --save vec-la-fp
and import or require as needed. If you need to use a standalone windowed version in a script tag:
<script src="node_modules/vec-la-fp/dist/vec.window.js"></script>
Features
- Immutable functions for manipulating vectors and matrices
- Vectors and matrices represented as pure, single dimensional arrays
- Composable and fully (auto) curried
- Typescript typings for all overloadings
API
vec.add(v, v2)
- adds v
and v2
vec.add3(v, v2, v3)
- adds v
, v2
, v3
vec.addAll([v1, v2, ..., vN])
- adds all vectors together
vec.sub(v, v2)
- subtracts v2
from v1
vec.sub3(v, v2, v3)
- subtracts v
, v2
, v3
vec.subAll([v1, v2, ..., vN])
- subtracts all vectors together
vec.mag(v)
- gets magnitude of v
vec.normal(v)
- gets normal vector of v
vec.scale(sc, v)
- scales v
by sc
vec.towards(t, v, v2)
- gets the vector at "time" t
between v
and v2
vec.lerp(v, v2, t)
- towards
, but with the t
argument last
vec.scalarNear(e, n, n2)
- true if n is within epsilon of n2
vec.near(e, v, v2)
- true if every elment of v is near the same in v2
vec.clampMag(min, max, v)
- a vector in the same direction as v with magnitude clamped to at least min and at most max
vec.norm(v)
- normalises v
vec.mId
- immutable identity matrix
vec.createMatrix(a, b, c, d, tx, ty)
- helper function for creating matrices
vec.transform(m, v)
- transform v
by matrix m
vec.compose(m, m2)
- compose matrices m
and m2
vec.mRotate(a, m)
- compose matrix m
with a rotation matrix using angle a
vec.mTranslate(v, m)
- compose matrix m
with a translation matrix using vector v
for x and y
vec.mId
- The identity matrix
vec.mScale(v, m)
- compose matrix m
with a scale matrix using vector v
for x and y
vec.mShear(v, m)
- compose matrix m
with a shear matrix using vector v
for x and y
vec.rotate(a, v)
- rotates v
by angle a
vec.rotatePointAround(a, cp, v)
- rotates v
by angle a
around control point vector cp
vec.midpoint(v, v2)
- gets midpoint between v
and v2
vec.alongAngle(a, r, v)
- gets a vector r
units along angle a
from vector v
vec.dist(v, v2)
- gets distance from v
to v2
vec.fastDist(v, v2)
- gets "fast" distance from v
to v2
(no square root)
vec.dot(v, v2)
- gets dot product of v
and v2
vec.perpDot(v, v2)
- the perpendicular dot product of v
and v2
(sometimes called cross)
vec.triangleArea(a, b, c)
- signed area of triangle abc
vec.colinear(a, b, c)
- true if a b and c are colinear
vec.det(m)
- calculates the determine of matrix m
Tree shaking
All the functions are exported for better tree shaking:
- vAdd
- vAdd3
- vAddAll
- vSub
- vSub3
- vSubAll
- vMag
- vNormal
- vScale
- vTowards
- vLerp
- vNorm
- mId
- vCreateMatrix
- vTransform
- mCompose
- mRotate
- mTranslate
- mScale
- mShear
- vRotate
- vRotatePointAround
- vMidpoint
- vAngle
- vAlongAngle
- vFastDist
- vDist
- vDot
- vDet
Finally, when using the window version you can call vec.polute()
to insert these functions into the global scope with the naming convention:
vFunctionName
e.g vAdd
, vMidpoint
, vDot
etc
and mCompose
, mRotate
etc for functions associated with matrices
Composing matrices
vec-la provided a dot-chain style API for building matrices, but since matrices compose the same as functions, this API can be captured via regular function composition. For example:
Note! The compose
function below is function compose, not the vec.mCompose
function for matrices
const M = compose(
mTranslate([10, 20]),
mShear([0.2, 0.3]),
mScale([3.2, 2.3]),
mRotate(1.5)
)(mId);
is equivilent to vec-la's:
const M = vMatrixBuilder()
.rotate(1.5)
.scale(3.2, 2.3)
.shear(0.2, 0.3)
.translate(10, 20)
.get();
Tests
Clone the repository, and then run npm install && npm test
.
Examples
(all examples assume vec is imported under vec
)
Addition
const v1 = [0, 1];
const v2 = [1, 0];
const v3 = vec.add(v1, v2); // [1, 1]
Scaling
const v1 = [0, 1];
const scaler = 10;
const v2 = vec.scale(scaler, v1); // [0, 10]
Normalising
const v1 = [6.32, -23.1];
const v2 = vec.norm(v1); // [0.2638946146581466, -0.9645515187663272]
Magnitude
const v1 = [6.32, -23.1];
const mag = vec.mag(v1); // 23.948954048141644
Matrix Transform
const v1 = [10, 10];
// Inversion matrix
const m = [
-1, 0, 0
0, -1, 0,
0, 0, 1
];
const v2 = vec.transform(m, v1); // [-10, -10]
Computing determinants
const m = [
10, 0, 0,
0, 10, 0,
0, 0, 1
];
const d = vec.det(m); // 100