uvacoder / maath

yarn add maath

This is a collection of useful math helpers, random generators, bits and bobs.

The library is mostly meant to be used with three.js, so if you are using it outside of a three project, make sure you check the source and - if you don't need the dep - just copy paste!

Check out the demos on Codesandbox: 🪶

🟡 The library is still heavily WIP, don't use it for production work until a stable API is relased in a ^1.0.0

But why?

Yes, there are a lot of these libraries. The more the merrier! We are all here to learn, and maintaining a dedicated library for our creative endeavors at Poimandres just made sense.

Contributing

Do you want to add something? No rules, but keep these in mind:

• try to add explainers to whatever function you add, if you saw it in a tweet link that!
• add a cool example! Make it a sandbox or whatever, just show how the function can be used creatively
• keep copy-paste simple. Try not to add too many inter-dependencies so the functions are copy-paste friendly
• loose typing. Try to add typing, but don't go crazy with generics and complexity

If you are not sure how to help, check out the 🟡 Roadmap below.

🪶 Reference

Buffer

import * as buffer from 'maath/buffer'

🪶 toVectorArray(buffer, stride)

Converts an [..., x, y, z, ...] typed array to a Vector[]

const myBuffer = new Float32Array(100 * 3)
const myArray = toVectorArray(myBuffer, 3) 

🪶 swizzleBuffer(buffer, axes)

Swizzle the individual vectors in a vector buffer

const myBuffer = new Float32Array(100 * 3)
myBuffer.push(0, 1, 2)

swizzleBuffer(myBuffer, 'xzy') // buffer is now [0, 2, 1] 

This is a way to make simple rotations.

🪶 addAxis(buffer, size, getZValue)

Adds a z axis to an [..., x, y, ...] typed array:

const my2DBuffer = new Float32Array(100 * 2)
const my3DBuffer = addAxis(my2DBuffer, 2, () => Math.random()) // zAxis will now be a random value between 0 and 1
const my4DBuffer = addAxis(my3DBuffer, 3, () => 1) // 4th value (imagine a in rgba) will be 1 

🪶 lerpBuffers(bufferA, bufferB, destinationBuffer, t)

Linearly interpolate two buffers, writing on a third one.

const mySphere = inSphere(new Float32Array(100 * 3), { radius: 4 })
const myBox = inBox(new Float32Array(100 * 3), { side: 4 })

const interpolationTarget = myBox.slice(0)

lerpBuffers(mySphere, myBox, interpolationTarget, Math.sin(performance.now()))

Easing

import * as easing from 'maath/easing'

TBD

Matrix

import * as matrix from 'maath/matrix'

🪶 determinant2(...matrixInRowMajorOrder)

Returns the determinant of a passed 2x2 matrix:

const d = determinant2(
  1, 1,
  2, 2
)

🪶 determinant3(...matrixInRowMajorOrder)

Returns the determinant of a passed 3x3 matrix:

const d = determinant3(
  1, 1, 1,
  2, 2, 2
)

🪶 determinant4(...matrixInRowMajorOrder) // TBD

🪶 getMinor(matrix, column, row)

Returns the minor of a given matrix.

const minor = getMinor([
  1, 2, 1,
  2, 1, 1,
  3, 2, 3
], 1, 1)

// minor will be the determinant of the submatrix without row 1 and colum 1
// | 1 1 |
// | 2 3 |

Misc

import * as misc from 'maath/misc'

TBD

Random

import * as random from 'maath/random'

🪶 onTorus(buffer, { innerRadius, outerRadius })

TODO

🪶 inTorus(buffer, { innerRadius, outerRadius })

TODO

Triangle

import * as triangle from 'maath/triangle'

TBD

Inspiration

The kitchen-sink nature of the library was inspired by other projects that manage to bring together an immense amount of knowledge from different domains that would otherwise be fragmented in many places or even lost:

• drei 🌭 useful helpers for react-three-fiber
• lygia a granular and multi-language shader library designed for performance and flexibility

🟡 Roadmap

• Make the random generator seedable for every function
• Figure out a good API for vectors
• Figure out a good API for functions that might work on both buffers and arrays of vectors
• Fix type errors that might come from using different vector libs
• Keep adding tests
• Figure out if we can get rid of the Three.js dependency. While useful, it feels superfluous