mathue

mathue

A high-performance TypeScript math library specially optimized for WebGL applications.

Pronounced as "Matthew" ( mˈæθjuː ).

🔗 Links

• Docs
• npm

🚀 Why mathue?

Standard math libraries often create new objects for every calculation, causing Garbage Collection (GC) spikes that ruin the performance of real-time rendering loops (60fps+).

mathue is designed to be "Zero-Allocation" by default.

Key Features

• ⚡ Zero-Allocation Design: Minimizes GC overhead by using mutable operations (in-place modification) and reusing static internal temporaries for complex calculations.
• 🛠️ Flexible: While optimized for mutation, every class implements .clone() and factory methods (e.g., .identity(), .zero()) for when you need immutable behavior.
• ⛓️ Method Chaining: All mutable methods return this, allowing for concise and readable code similar to modern engines.
• ts TypeScript First: Built completely in TypeScript with full type definitions (.d.ts) included.
• 🟢 Standalone: No external dependencies.

📦 Installation

npm install mathue

📖 Usage

// Applies matrix to vector
import {Vector3, Matrix4, Quaternion} from 'mathue';

const v = new Vector3(1, 2, 3);

const axis = new Vector3(0, 0, 1);
const angle = Math.PI / 3;
const q = Quaternion.fromAxisAndAngle(axis, angle);

const m = Matrix4.identity();
m.setQuaternion(q);

v.applyMatrix4(m);

// Calculates model matrix
const position = new Vector3(1, 2, 3);
const rotation = Quaternion.identity();
const scale = new Vector3(2, 2, 2);

const model = Matrix4.identity();

model.setIdentity()
  .multiplyTranslation(position)
  .multiplyRotation(rotation)
  .multiplyScale(scale);

// Calculates view matrix
const phi = 0.25 * Math.PI;
const theta = 0.5 * Math.PI;
const radius = 2;
const polar = new PolarCoordinate3(phi, theta, radius);

// A camera on a sphere looking at the origin
const target = Vector3.zero();
const position = Vector3.zero();
const up = Vector3.zero();
polar.toVector3(position);
polar.toTangentZ(tangent);

const view = Matrix4.identity();
view.lookAt(position, target, up);

// Calculates projection matrix (Perspective camera)
const {projection, clientSize, _verticalFov, _near, _far} = this;
const verticalFov = 0.5 * Math.PI;
const near = 0.1;
const far = 4.0;
const aspect = 1.5; // width / height

// for WebGL, OpenGL, ...
const projection = Matrix4.identity();
projection.perspective(verticalFov, near, far, aspect);

// for WebGPU, Vulkan, DirectX, Metal, ...
const options = { depthZeroToOne: true };
projection.perspective(verticalFov, near, far, aspect, options);

// Calculates projection matrix (Orthographic camera)
const left = -3;
const right = 3;
const bottom = -2;
const top = 2;
const near = 0.1;
const far = 4.0;

// for WebGL, OpenGL, ...
const projection = Matrix4.identity();
projection.orthographic(left, right, bottom, top, near, far);

// for WebGPU, Vulkan, DirectX, Metal, ...
const options = { depthZeroToOne: true };
projection.orthographic(left, right, bottom, top, near, far, options);

📚 API Overview

• Vector
  • Vector1
  • Vector2
  • Vector3
  • Vector4
• Matrix (Column-major order, WebGL compatible)
  • Matrix3
  • Matrix4
• PolarCoordinate3
• Quaternion (For rotation without gimbal lock)

See the Full Documentation for details.

📄 License

MIT License

📐 Logo

The logo features two upward vectors arranged to form the letter "M".
Conceptually, the right vector represents the left vector transformed by a Matrix or Quaternion.