@altpsyche/maths 0.2.0

package/dist/values/ease.js

@@ -0,0 +1,35 @@
+/**
+ * The four curves a value can travel along between two moments.
+ *
+ * They are the whole of the shape a track can hold. A key is either flat where
+ * it sits or it is not, and two keys give four pairings: straight through,
+ * still at the start, still at the end, and still at both.
+ *
+ * Every one of them takes and returns zero to one, so a caller decides what the
+ * value at each end is and this decides only the pace between them.
+ */
+/** No easing at all: the value moves at one rate the whole way. */
+export const linear = (along) => along;
+/** Quadratic ease in: flat at the start, so the value leaves from rest and
+ * arrives at speed. */
+export const easeIn = (along) => along * along;
+/** Quadratic ease out: flat at the end, so the value leaves at speed and
+ * settles rather than stopping dead. */
+export const easeOut = (along) => 1 - (1 - along) * (1 - along);
+/** Smoothstep: the cubic that is flat at both ends, Ken Perlin. */
+export const smoothstep = (along) => along * along * (3 - 2 * along);
+/**
+ * The curve for a span whose ends are flat or not.
+ *
+ * This is the only place the four are chosen between, so a track and a figure's
+ * timeline pace a change the same way rather than each deciding for itself.
+ */
+export function curveFor(fromFlat, toFlat) {
+    if (fromFlat && toFlat)
+        return smoothstep;
+    if (fromFlat)
+        return easeIn;
+    if (toFlat)
+        return easeOut;
+    return linear;
+}

package/dist/values/mat3.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The transform a group of marks carries, and the one that maps a figure's own
+ * units onto whatever it is being drawn at.
+ *
+ * Nine numbers, column-major, matching the engine's layout: the first three are
+ * the first column rather than the first row, and the entry at flat index
+ * `col * 3 + row` is the one in that column and row. A flat picture needs only
+ * the top two rows, and the third exists so that a translation is a
+ * multiplication like every other move rather than an addition bolted on after.
+ */
+import type { Vec2 } from './vec2.js';
+export type Mat3 = readonly [number, number, number, number, number, number, number, number, number];
+/** Column-major product, so `multiply(a, b)` applies `b` to a point first and
+ * then `a`, which is the order a group's transform sits outside its child's. */
+declare function multiply(a: Mat3, b: Mat3): Mat3;
+/** The last column carries the offset, so this moves a point and leaves a
+ * direction where it was. */
+declare function translation(v: Vec2): Mat3;
+declare function scaling(v: Vec2): Mat3;
+declare function rotation(radians: number): Mat3;
+/** Applies the matrix to a point, which takes the translation with it. */
+declare function transformPoint(m: Mat3, v: Vec2): Vec2;
+/** Applies the rotation and scale and not the translation, which is what a
+ * direction wants: moving the picture must not move where an arrow points. */
+declare function transformDirection(m: Mat3, v: Vec2): Vec2;
+/**
+ * How much longer a length becomes under this transform.
+ *
+ * A stroke is given in figure units and drawn in pixels, and a transform that
+ * scales differently along each axis has no single answer, so this takes the
+ * mean of the two axes rather than pretending there is one.
+ */
+declare function scaleFactor(m: Mat3): number;
+export declare const mat3: {
+    IDENTITY: Mat3;
+    multiply: typeof multiply;
+    translation: typeof translation;
+    scaling: typeof scaling;
+    rotation: typeof rotation;
+    transformPoint: typeof transformPoint;
+    transformDirection: typeof transformDirection;
+    scaleFactor: typeof scaleFactor;
+};
+export {};

package/dist/values/mat3.js

@@ -0,0 +1,63 @@
+const IDENTITY = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+/** Column-major product, so `multiply(a, b)` applies `b` to a point first and
+ * then `a`, which is the order a group's transform sits outside its child's. */
+function multiply(a, b) {
+    const [a0, a1, a2, a3, a4, a5, a6, a7, a8] = a;
+    const [b0, b1, b2, b3, b4, b5, b6, b7, b8] = b;
+    return [
+        a0 * b0 + a3 * b1 + a6 * b2,
+        a1 * b0 + a4 * b1 + a7 * b2,
+        a2 * b0 + a5 * b1 + a8 * b2,
+        a0 * b3 + a3 * b4 + a6 * b5,
+        a1 * b3 + a4 * b4 + a7 * b5,
+        a2 * b3 + a5 * b4 + a8 * b5,
+        a0 * b6 + a3 * b7 + a6 * b8,
+        a1 * b6 + a4 * b7 + a7 * b8,
+        a2 * b6 + a5 * b7 + a8 * b8,
+    ];
+}
+/** The last column carries the offset, so this moves a point and leaves a
+ * direction where it was. */
+function translation(v) {
+    return [1, 0, 0, 0, 1, 0, v.x, v.y, 1];
+}
+function scaling(v) {
+    return [v.x, 0, 0, 0, v.y, 0, 0, 0, 1];
+}
+function rotation(radians) {
+    const c = Math.cos(radians);
+    const s = Math.sin(radians);
+    return [c, s, 0, -s, c, 0, 0, 0, 1];
+}
+/** Applies the matrix to a point, which takes the translation with it. */
+function transformPoint(m, v) {
+    const [m0, m1, , m3, m4, , m6, m7] = m;
+    return { x: m0 * v.x + m3 * v.y + m6, y: m1 * v.x + m4 * v.y + m7 };
+}
+/** Applies the rotation and scale and not the translation, which is what a
+ * direction wants: moving the picture must not move where an arrow points. */
+function transformDirection(m, v) {
+    const [m0, m1, , m3, m4] = m;
+    return { x: m0 * v.x + m3 * v.y, y: m1 * v.x + m4 * v.y };
+}
+/**
+ * How much longer a length becomes under this transform.
+ *
+ * A stroke is given in figure units and drawn in pixels, and a transform that
+ * scales differently along each axis has no single answer, so this takes the
+ * mean of the two axes rather than pretending there is one.
+ */
+function scaleFactor(m) {
+    const [m0, m1, , m3, m4] = m;
+    return (Math.hypot(m0, m1) + Math.hypot(m3, m4)) / 2;
+}
+export const mat3 = {
+    IDENTITY,
+    multiply,
+    translation,
+    scaling,
+    rotation,
+    transformPoint,
+    transformDirection,
+    scaleFactor,
+};

package/dist/values/scalar.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The one-dimensional arithmetic everything else here is built out of.
+ *
+ * These take and return plain numbers so that a vector, a colour channel and a
+ * uniform can all be walked by the same four lines rather than by three copies
+ * of them.
+ */
+/** Held inside the two bounds, whichever way round they are given. */
+export declare function clamp(value: number, low: number, high: number): number;
+/** Part way from one number to another, and past either end when `along` is
+ * outside zero to one. */
+export declare function lerp(from: number, to: number, along: number): number;
+/**
+ * How far along the span a value sits, which is `lerp` read backwards.
+ *
+ * A span of no width has no answer, so it reports the start rather than
+ * dividing by zero and handing back an infinity that spreads.
+ */
+export declare function inverseLerp(from: number, to: number, value: number): number;
+/** The same position in a second span as it held in the first. */
+export declare function remap(value: number, fromLow: number, fromHigh: number, toLow: number, toHigh: number): number;

package/dist/values/scalar.js

@@ -0,0 +1,31 @@
+/**
+ * The one-dimensional arithmetic everything else here is built out of.
+ *
+ * These take and return plain numbers so that a vector, a colour channel and a
+ * uniform can all be walked by the same four lines rather than by three copies
+ * of them.
+ */
+/** Held inside the two bounds, whichever way round they are given. */
+export function clamp(value, low, high) {
+    return low < high ? Math.min(Math.max(value, low), high) : Math.min(Math.max(value, high), low);
+}
+/** Part way from one number to another, and past either end when `along` is
+ * outside zero to one. */
+export function lerp(from, to, along) {
+    return from + (to - from) * along;
+}
+/**
+ * How far along the span a value sits, which is `lerp` read backwards.
+ *
+ * A span of no width has no answer, so it reports the start rather than
+ * dividing by zero and handing back an infinity that spreads.
+ */
+export function inverseLerp(from, to, value) {
+    if (from === to)
+        return 0;
+    return (value - from) / (to - from);
+}
+/** The same position in a second span as it held in the first. */
+export function remap(value, fromLow, fromHigh, toLow, toHigh) {
+    return lerp(toLow, toHigh, inverseLerp(fromLow, fromHigh, value));
+}

package/dist/values/vec2.d.ts

@@ -0,0 +1,48 @@
+export type Vec2 = {
+    x: number;
+    y: number;
+};
+declare function makeVec2(x: number, y: number): Vec2;
+declare function add(a: Vec2, b: Vec2): Vec2;
+declare function sub(a: Vec2, b: Vec2): Vec2;
+declare function scale(v: Vec2, s: number): Vec2;
+declare function dot(a: Vec2, b: Vec2): number;
+/** The z of the three-dimensional cross product, which is the signed area of
+ * the parallelogram and tells which side of `a` the vector `b` falls. */
+declare function cross(a: Vec2, b: Vec2): number;
+declare function length(v: Vec2): number;
+declare function distance(a: Vec2, b: Vec2): number;
+/** A zero-length vector normalises to zero rather than to not-a-number, so a
+ * degenerate direction leaves a mark where it was instead of removing it. */
+declare function normalize(v: Vec2): Vec2;
+/** Turned a quarter turn anticlockwise, which is the direction an arrow head
+ * and a line's thickness are both measured along. */
+declare function perpendicular(v: Vec2): Vec2;
+declare function rotate(v: Vec2, radians: number): Vec2;
+/** The direction the vector points, anticlockwise from the positive x axis, in
+ * radians between minus pi and pi. */
+declare function angle(v: Vec2): number;
+declare function lerp(a: Vec2, b: Vec2, along: number): Vec2;
+/**
+ * The constructor and the family under one name, so building a vector stays
+ * short and an import line says what these operate on.
+ *
+ * The magnitude is not called `length`: a function's own `length` is how many
+ * arguments it takes, it is not writable, and assigning one throws.
+ */
+export declare const vec2: typeof makeVec2 & {
+    ZERO: Vec2;
+    add: typeof add;
+    sub: typeof sub;
+    scale: typeof scale;
+    dot: typeof dot;
+    cross: typeof cross;
+    magnitude: typeof length;
+    distance: typeof distance;
+    normalize: typeof normalize;
+    perpendicular: typeof perpendicular;
+    rotate: typeof rotate;
+    angle: typeof angle;
+    lerp: typeof lerp;
+};
+export {};

package/dist/values/vec2.js

@@ -0,0 +1,82 @@
+/**
+ * Points and directions on a flat picture.
+ *
+ * The shape is the one the engine already uses for its own vectors, named
+ * fields rather than a tuple, so that if the two libraries ever meet neither
+ * has to convert.
+ */
+import { lerp as lerpNumber } from './scalar.js';
+function makeVec2(x, y) {
+    return { x, y };
+}
+function add(a, b) {
+    return { x: a.x + b.x, y: a.y + b.y };
+}
+function sub(a, b) {
+    return { x: a.x - b.x, y: a.y - b.y };
+}
+function scale(v, s) {
+    return { x: v.x * s, y: v.y * s };
+}
+function dot(a, b) {
+    return a.x * b.x + a.y * b.y;
+}
+/** The z of the three-dimensional cross product, which is the signed area of
+ * the parallelogram and tells which side of `a` the vector `b` falls. */
+function cross(a, b) {
+    return a.x * b.y - a.y * b.x;
+}
+function length(v) {
+    return Math.sqrt(dot(v, v));
+}
+function distance(a, b) {
+    return length(sub(a, b));
+}
+/** A zero-length vector normalises to zero rather than to not-a-number, so a
+ * degenerate direction leaves a mark where it was instead of removing it. */
+function normalize(v) {
+    const len = length(v);
+    if (len === 0)
+        return { x: 0, y: 0 };
+    return scale(v, 1 / len);
+}
+/** Turned a quarter turn anticlockwise, which is the direction an arrow head
+ * and a line's thickness are both measured along. */
+function perpendicular(v) {
+    return { x: -v.y, y: v.x };
+}
+function rotate(v, radians) {
+    const c = Math.cos(radians);
+    const s = Math.sin(radians);
+    return { x: v.x * c - v.y * s, y: v.x * s + v.y * c };
+}
+/** The direction the vector points, anticlockwise from the positive x axis, in
+ * radians between minus pi and pi. */
+function angle(v) {
+    return Math.atan2(v.y, v.x);
+}
+function lerp(a, b, along) {
+    return { x: lerpNumber(a.x, b.x, along), y: lerpNumber(a.y, b.y, along) };
+}
+/**
+ * The constructor and the family under one name, so building a vector stays
+ * short and an import line says what these operate on.
+ *
+ * The magnitude is not called `length`: a function's own `length` is how many
+ * arguments it takes, it is not writable, and assigning one throws.
+ */
+export const vec2 = Object.assign(makeVec2, {
+    ZERO: makeVec2(0, 0),
+    add,
+    sub,
+    scale,
+    dot,
+    cross,
+    magnitude: length,
+    distance,
+    normalize,
+    perpendicular,
+    rotate,
+    angle,
+    lerp,
+});

package/dist/values/vec3.d.ts

@@ -0,0 +1,27 @@
+export type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+declare function makeVec3(x: number, y: number, z: number): Vec3;
+declare function add(a: Vec3, b: Vec3): Vec3;
+declare function sub(a: Vec3, b: Vec3): Vec3;
+declare function scale(v: Vec3, s: number): Vec3;
+declare function dot(a: Vec3, b: Vec3): number;
+declare function cross(a: Vec3, b: Vec3): Vec3;
+declare function length(v: Vec3): number;
+/** A zero-length vector normalises to zero rather than to not-a-number. */
+declare function normalize(v: Vec3): Vec3;
+declare function lerp(a: Vec3, b: Vec3, along: number): Vec3;
+export declare const vec3: typeof makeVec3 & {
+    ZERO: Vec3;
+    add: typeof add;
+    sub: typeof sub;
+    scale: typeof scale;
+    dot: typeof dot;
+    cross: typeof cross;
+    magnitude: typeof length;
+    normalize: typeof normalize;
+    lerp: typeof lerp;
+};
+export {};

package/dist/values/vec3.js

@@ -0,0 +1,58 @@
+/**
+ * Points and directions in space, for the values a figure carries that are not
+ * positions on the page, such as a colour or a direction being explained.
+ *
+ * The names and the shape match the engine's own vectors exactly, so the two
+ * can be merged later without either side converting.
+ */
+import { lerp as lerpNumber } from './scalar.js';
+function makeVec3(x, y, z) {
+    return { x, y, z };
+}
+function add(a, b) {
+    return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+}
+function sub(a, b) {
+    return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+}
+function scale(v, s) {
+    return { x: v.x * s, y: v.y * s, z: v.z * s };
+}
+function dot(a, b) {
+    return a.x * b.x + a.y * b.y + a.z * b.z;
+}
+function cross(a, b) {
+    return {
+        x: a.y * b.z - a.z * b.y,
+        y: a.z * b.x - a.x * b.z,
+        z: a.x * b.y - a.y * b.x,
+    };
+}
+function length(v) {
+    return Math.sqrt(dot(v, v));
+}
+/** A zero-length vector normalises to zero rather than to not-a-number. */
+function normalize(v) {
+    const len = length(v);
+    if (len === 0)
+        return { x: 0, y: 0, z: 0 };
+    return scale(v, 1 / len);
+}
+function lerp(a, b, along) {
+    return {
+        x: lerpNumber(a.x, b.x, along),
+        y: lerpNumber(a.y, b.y, along),
+        z: lerpNumber(a.z, b.z, along),
+    };
+}
+export const vec3 = Object.assign(makeVec3, {
+    ZERO: makeVec3(0, 0, 0),
+    add,
+    sub,
+    scale,
+    dot,
+    cross,
+    magnitude: length,
+    normalize,
+    lerp,
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@altpsyche/maths",
+  "version": "0.2.0",
+  "description": "The mathematics AltPsyche's figures are drawn from: vectors, matrices, curves, and a value walked over time.",
+  "license": "MIT",
+  "author": "Siva",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/altpsyche/altpsyche-maths.git"
+  },
+  "homepage": "https://github.com/altpsyche/altpsyche-maths",
+  "bugs": "https://github.com/altpsyche/altpsyche-maths/issues",
+  "keywords": [
+    "maths",
+    "animation",
+    "easing",
+    "keyframes",
+    "vector",
+    "matrix"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}