trid3d 0.2.0 → 0.3.0

package/trid/loaders/obj.js

@@ -1,9 +1,13 @@
+import { parseMTL } from "./mtl.js";
+import { loadTexture } from "./texture.js";
+
 /**
  * Wavefront OBJ loading.
  *
  * Reads vertex positions (`v`), texture coordinates (`vt`), normals
- * (`vn`), faces (`f`), polylines (`l`) and material names (`usemtl`).
- * Everything else (.mtl files, groups) is ignored for now.
+ * (`vn`), faces (`f`), polylines (`l`), material names (`usemtl`) and the
+ * material file's name (`mtllib`). `loadOBJ(url, { materials: true })` also
+ * reads that .mtl file and its textures. Groups (`g`, `o`) are ignored.
  *
  * OBJ files are right-handed with +Z toward the viewer. Trid is
  * left-handed with the camera looking down +Z, so Z is flipped on
@@ -24,10 +28,15 @@
  * @property {string[]} [materialNames] - Material names from `usemtl` lines, in the order they first appear
  * @property {number[]} [faceMaterials] - For each face, its index in `materialNames`. Give the
  *   object a list of materials in the same order to color or texture each part.
+ * @property {string} [mtllib] - The .mtl file the OBJ names (`mtllib`), if any
+ * @property {Object[]} [materials] - With `loadOBJ(url, { materials: true })`: one Trid material per
+ *   entry of `materialNames`, from the .mtl file (fill, texture). Use it as the object's `material`
  *
  * @typedef {Object} ObjOptions
  * @property {number} [fit] - If set, center the model on the origin and scale it
  *   so its largest side is this long. Handy because OBJ files come in any size.
+ * @property {boolean} [materials=false] - `loadOBJ` only: also load the .mtl file and its
+ *   textures, into `mesh.materials`
  */
 
 /**
@@ -49,6 +58,7 @@ export function parseOBJ(text, { fit } = {}) {
   const materialNames = [];
   const faceMaterials = []; // per face: index in materialNames
   let material = 0;
+  let mtllib;
 
   const src = text.split(/\r?\n/);
 
@@ -66,6 +76,8 @@ export function parseOBJ(text, { fit } = {}) {
       uvs.push({ u: +(parts[1] ?? 0), v: +(parts[2] ?? 0) });
     } else if (kind === "vn") {
       normals.push({ x: +(parts[1] ?? 0), y: +(parts[2] ?? 0), z: -(parts[3] ?? 0) });
+    } else if (kind === "mtllib") {
+      mtllib ??= parts.slice(1).join(" ");
     } else if (kind === "usemtl") {
       const name = parts.slice(1).join(" ");
       material = materialNames.indexOf(name);
@@ -138,11 +150,12 @@ export function parseOBJ(text, { fit } = {}) {
     mesh.uvs = uvs;
     mesh.faceUVs = faceUVs;
   }
-  // Parts using different materials
-  if (materialNames.length > 1) {
+  // Material names (a list of materials on the object then colors each part)
+  if (materialNames.length > 0) {
     mesh.materialNames = materialNames;
     mesh.faceMaterials = faceMaterials;
   }
+  if (mtllib) mesh.mtllib = mtllib;
   if (fit != null) fitMesh(mesh, fit);
   return mesh;
 }
@@ -187,10 +200,49 @@ export function fitMesh(mesh, size = 1) {
  * @param {ObjOptions} [opts]
  * @returns {Promise<ObjMesh>}
  */
-export async function loadOBJ(url, opts) {
+export async function loadOBJ(url, opts = {}) {
   const res = await fetch(url);
   if (!res.ok) throw new Error(`Could not load ${url} (${res.status})`);
-  return parseOBJ(await res.text(), opts);
+  const mesh = parseOBJ(await res.text(), opts);
+  if (opts.materials) mesh.materials = await loadMaterials(mesh, new URL(url, location.href));
+  return mesh;
+}
+
+/**
+ * The materials of a loaded OBJ, from its .mtl file: one per name in
+ * `mesh.materialNames`, with the texture images loaded. Missing files only
+ * give a warning (the part keeps a plain fill).
+ *
+ * @param {ObjMesh} mesh - Parsed with `parseOBJ`
+ * @param {URL|string} base - Where the OBJ file is (file names are relative to it)
+ * @returns {Promise<Object[]>}
+ */
+export async function loadMaterials(mesh, base) {
+  const names = mesh.materialNames ?? [];
+  if (!mesh.mtllib) return names.map((name) => ({ name, fill: "#cccccc" }));
+  let lib = {};
+  const mtlURL = new URL(mesh.mtllib, base);
+  try {
+    const res = await fetch(mtlURL);
+    if (!res.ok) throw new Error(`${res.status}`);
+    lib = parseMTL(await res.text());
+  } catch (err) {
+    console.warn(`Trid: couldn't load the material file ${mtlURL} (${err.message})`);
+  }
+  return Promise.all(names.map(async (name) => {
+    const m = lib[name] ?? {};
+    const material = { name, fill: m.fill ?? (m.textureFile ? "#ffffff" : "#cccccc") };
+    if (m.textureFile) {
+      const file = new URL(m.textureFile.replace(/\\/g, "/"), mtlURL);
+      try {
+        material.texture = await loadTexture(file.href);
+        material.fill = "#ffffff"; // MTL's Kd under a texture is usually a tint nobody meant
+      } catch (err) {
+        console.warn(`Trid: couldn't load the texture ${file} (${err.message})`);
+      }
+    }
+    return material;
+  }));
 }
 
 /**

package/trid/loaders/texture.js

@@ -3,9 +3,15 @@
  *
  * A material's `texture` can be anything the canvas can draw:
  * an `<img>`, a `<canvas>`, a `<video>` or an `ImageBitmap`.
- * Canvases and videos are read again every frame, so they can change.
+ *
+ * Videos are read again every frame. Everything else, canvases included,
+ * is read once: after redrawing a canvas, call `updateTexture(canvas)`, or
+ * give its material `liveTexture: true` to read it every frame.
  */
 
+/** How many times each source was updated with `updateTexture` (0 when never). */
+const versions = new WeakMap();
+
 /**
  * Loads an image to use as a texture.
  *
@@ -48,9 +54,44 @@ export function textureSize(src) {
   };
 }
 
-/** Whether a source can change over time (canvas, video), so it's read every frame. */
-export function textureIsLive(src) {
-  return (typeof HTMLCanvasElement !== "undefined" && src instanceof HTMLCanvasElement)
-    || (typeof HTMLVideoElement !== "undefined" && src instanceof HTMLVideoElement)
-    || (typeof OffscreenCanvas !== "undefined" && src instanceof OffscreenCanvas);
+/**
+ * Whether a texture is read again every frame: videos, and any source whose
+ * material has `liveTexture: true`. `liveTexture: false` freezes a video.
+ *
+ * @param {CanvasImageSource} src
+ * @param {{ liveTexture?: boolean }} [material] - The material using it
+ * @returns {boolean}
+ */
+export function textureIsLive(src, material) {
+  return material?.liveTexture ?? (typeof HTMLVideoElement !== "undefined" && src instanceof HTMLVideoElement);
+}
+
+/**
+ * Tells the renderers a texture source changed: call it after drawing on a
+ * canvas used as a texture. It's read again (once) on the next frame, by
+ * every renderer and every material using it.
+ *
+ * Canvases are read only once otherwise, which keeps them fast and sharp
+ * (they get mipmaps). For a canvas redrawn every frame, set
+ * `liveTexture: true` on its material instead.
+ *
+ * @example
+ * paintClouds(canvas, seed);
+ * updateTexture(canvas);
+ *
+ * @param {CanvasImageSource} src - The canvas (or image) that changed
+ */
+export function updateTexture(src) {
+  if (src && typeof src === "object") versions.set(src, (versions.get(src) ?? 0) + 1);
+}
+
+/**
+ * How many times `updateTexture` was called for a source (0 when never).
+ * Renderers compare it with the version they read last.
+ *
+ * @param {CanvasImageSource} src
+ * @returns {number}
+ */
+export function textureVersion(src) {
+  return versions.get(src) ?? 0;
 }

package/trid/math/matrix.js

@@ -0,0 +1,200 @@
+import { matFromEuler } from "./rotation.js";
+
+/**
+ * 4×4 transform matrices, for objects inside groups: an object's world
+ * matrix is its parent's world matrix times its own.
+ *
+ * A matrix is an array of 16 numbers in column-major order (the order
+ * WebGL uses): `m[col * 4 + row]`, translation in `m[12..14]`. They're
+ * built with `matFromEuler`, so they match `localToWorld` exactly.
+ *
+ * @typedef {number[]} Mat4
+ * @typedef {{x:number, y:number, z:number}} Vec3
+ */
+
+/** @returns {Mat4} The identity matrix (changes nothing). */
+export function identityMat4() {
+  return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+}
+
+/**
+ * The matrix of a transform: scale, then rotate (X, then Y, then Z), then
+ * move. Parts left out change nothing.
+ *
+ * @param {{ pos?:Vec3, rot?:Vec3, scale?:Vec3 }} t - A transform, or a scene object
+ * @returns {Mat4}
+ */
+export function mat4FromTransform({ pos, rot, scale } = {}) {
+  const r = rot ? matFromEuler(rot) : [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+  const sx = scale?.x ?? 1, sy = scale?.y ?? 1, sz = scale?.z ?? 1;
+  return [
+    r[0][0] * sx, r[1][0] * sx, r[2][0] * sx, 0,
+    r[0][1] * sy, r[1][1] * sy, r[2][1] * sy, 0,
+    r[0][2] * sz, r[1][2] * sz, r[2][2] * sz, 0,
+    pos?.x ?? 0, pos?.y ?? 0, pos?.z ?? 0, 1,
+  ];
+}
+
+/**
+ * Matrix product a · b: b is applied first. A child's world matrix is
+ * `mulMat4(parentWorld, childLocal)`.
+ *
+ * @param {Mat4} a
+ * @param {Mat4} b
+ * @returns {Mat4}
+ */
+export function mulMat4(a, b) {
+  const out = new Array(16);
+  for (let c = 0; c < 4; c++) {
+    for (let r = 0; r < 4; r++) {
+      out[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3];
+    }
+  }
+  return out;
+}
+
+/**
+ * Inverse of a transform matrix (scale, rotation and move; no perspective).
+ * Turns world positions into an object's local ones.
+ *
+ * @param {Mat4} m
+ * @returns {Mat4} The inverse, or the identity if `m` flattens space (a zero scale)
+ */
+export function invertMat4(m) {
+  const [a, b, c, , d, e, f, , g, h, i] = m;
+  // Inverse of the 3×3 part by cofactors
+  const A = e * i - f * h, B = -(d * i - f * g), C = d * h - e * g;
+  const det = a * A + b * B + c * C;
+  if (Math.abs(det) < 1e-12) return identityMat4();
+  const k = 1 / det;
+  const inv = [
+    A * k, -(b * i - c * h) * k, (b * f - c * e) * k,
+    B * k, (a * i - c * g) * k, -(a * f - c * d) * k,
+    C * k, -(a * h - b * g) * k, (a * e - b * d) * k,
+  ];
+  const tx = m[12], ty = m[13], tz = m[14];
+  return [
+    inv[0], inv[1], inv[2], 0,
+    inv[3], inv[4], inv[5], 0,
+    inv[6], inv[7], inv[8], 0,
+    -(inv[0] * tx + inv[3] * ty + inv[6] * tz),
+    -(inv[1] * tx + inv[4] * ty + inv[7] * tz),
+    -(inv[2] * tx + inv[5] * ty + inv[8] * tz),
+    1,
+  ];
+}
+
+/**
+ * Determinant of the 3×3 part: < 0 when the matrix mirrors (an odd number
+ * of negative scales), which turns faces inside out.
+ *
+ * @param {Mat4} m
+ * @returns {number}
+ */
+export function determinantMat4(m) {
+  return m[0] * (m[5] * m[10] - m[6] * m[9]) - m[4] * (m[1] * m[10] - m[2] * m[9]) + m[8] * (m[1] * m[6] - m[2] * m[5]);
+}
+
+/**
+ * A point through a matrix (scaled, turned and moved).
+ *
+ * @param {Mat4} m
+ * @param {Vec3} p
+ * @returns {Vec3}
+ */
+export function transformPoint(m, p) {
+  return {
+    x: m[0] * p.x + m[4] * p.y + m[8] * p.z + m[12],
+    y: m[1] * p.x + m[5] * p.y + m[9] * p.z + m[13],
+    z: m[2] * p.x + m[6] * p.y + m[10] * p.z + m[14],
+  };
+}
+
+/**
+ * A direction or offset through a matrix: scaled and turned, not moved.
+ *
+ * @param {Mat4} m
+ * @param {Vec3} v
+ * @returns {Vec3}
+ */
+export function transformDirection(m, v) {
+  return {
+    x: m[0] * v.x + m[4] * v.y + m[8] * v.z,
+    y: m[1] * v.x + m[5] * v.y + m[9] * v.z,
+    z: m[2] * v.x + m[6] * v.y + m[10] * v.z,
+  };
+}
+
+/**
+ * The 3×3 matrix that turns surface normals with an object (the inverse
+ * transpose of its matrix), column-major. It keeps normals perpendicular to
+ * stretched faces, and pointing outward on mirrored ones.
+ *
+ * @param {Mat4} m
+ * @returns {number[]} 9 numbers, column-major (ready for `gl.uniformMatrix3fv`)
+ */
+export function normalMatrix(m) {
+  const inv = invertMat4(m);
+  // Transpose of the inverse's 3×3 part
+  return [inv[0], inv[4], inv[8], inv[1], inv[5], inv[9], inv[2], inv[6], inv[10]];
+}
+
+/**
+ * A surface normal through a normal matrix (from `normalMatrix`), unit length.
+ *
+ * @param {number[]} nm - 3×3 column-major
+ * @param {Vec3} n
+ * @returns {Vec3}
+ */
+export function transformNormal(nm, n) {
+  const x = nm[0] * n.x + nm[3] * n.y + nm[6] * n.z;
+  const y = nm[1] * n.x + nm[4] * n.y + nm[7] * n.z;
+  const z = nm[2] * n.x + nm[5] * n.y + nm[8] * n.z;
+  const len = Math.hypot(x, y, z) || 1;
+  return { x: x / len, y: y / len, z: z / len };
+}
+
+/**
+ * Turns a world-space `TransformOp` (what `TransformGizmo` reports) into the
+ * space of an object's parent, so `applyTransformOp(child, op)` works on an
+ * object inside a group. Exact when the parents scale evenly (the same on
+ * every axis); with uneven scales, the turn is the closest a plain rotation
+ * can get.
+ *
+ * @example
+ * const local = obj.parent ? transformOpToLocal(op, worldMatrix(obj.parent)) : op;
+ * Object.assign(obj, applyTransformOp(saved, local));
+ *
+ * @param {Object} op - `{ mode: "move", delta }`, `{ mode: "rotate", axis, angle, center }`
+ *   or `{ mode: "scale", axis, factor, center }`
+ * @param {Mat4} parentWorld - The parent's world matrix
+ * @returns {Object} The same operation, in the parent's space
+ */
+export function transformOpToLocal(op, parentWorld) {
+  const inv = invertMat4(parentWorld);
+  const unit = (v) => {
+    const len = Math.hypot(v.x, v.y, v.z) || 1;
+    return { x: v.x / len, y: v.y / len, z: v.z / len };
+  };
+  switch (op.mode) {
+    case "move":
+      return { mode: "move", delta: transformDirection(inv, op.delta) };
+    case "rotate":
+      // A mirrored parent turns the other way
+      return {
+        mode: "rotate",
+        axis: unit(transformDirection(inv, op.axis)),
+        angle: determinantMat4(parentWorld) < 0 ? -op.angle : op.angle,
+        center: transformPoint(inv, op.center),
+      };
+    case "scale":
+      return {
+        mode: "scale",
+        axis: op.axis ? unit(transformDirection(inv, op.axis)) : null,
+        factor: op.factor,
+        center: transformPoint(inv, op.center),
+      };
+    default:
+      return op;
+  }
+}

package/trid/math/noise.js

@@ -0,0 +1,162 @@
+/**
+ * Seeded randomness and smooth noise, for procedural shapes and textures.
+ * The same seed always gives the same result, on every browser.
+ */
+
+/**
+ * A seeded random number generator (mulberry32): call the function it
+ * returns for the next number in [0, 1). Use it instead of Math.random when
+ * the same seed must build the same model again.
+ *
+ * @example
+ * const random = rng(42);
+ * const x = random(), y = random(); // the same two numbers every time
+ *
+ * @param {number} [seed=0] - Any whole number
+ * @returns {() => number}
+ */
+export function rng(seed = 0) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Hash of lattice coordinates and a seed, in [0, 1). */
+function hash3(x, y, z, seed) {
+  let h = Math.imul(x, 374761393) ^ Math.imul(y, 668265263) ^ Math.imul(z, 2147483647) ^ Math.imul(seed, 1442695041);
+  h = Math.imul(h ^ (h >>> 13), 1274126177);
+  h ^= h >>> 16;
+  return (h >>> 0) / 4294967296;
+}
+
+const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+const lerp = (a, b, t) => a + (b - a) * t;
+/** Wraps lattice coordinate n when the noise repeats every `period` (0: no wrap) */
+const wrap = (n, period) => (period > 0 ? ((n % period) + period) % period : n);
+/** A usable period: a whole number, or 0 for none */
+const periodOf = (p) => (p > 0 ? Math.max(1, Math.round(p)) : 0);
+
+function value2(x, y, seed, period) {
+  const xi = Math.floor(x), yi = Math.floor(y);
+  const fx = fade(x - xi), fy = fade(y - yi);
+  const x0 = wrap(xi, period), x1 = wrap(xi + 1, period);
+  const y0 = wrap(yi, period), y1 = wrap(yi + 1, period);
+  return lerp(
+    lerp(hash3(x0, y0, 0, seed), hash3(x1, y0, 0, seed), fx),
+    lerp(hash3(x0, y1, 0, seed), hash3(x1, y1, 0, seed), fx),
+    fy,
+  );
+}
+
+function value3(x, y, z, seed, period) {
+  const xi = Math.floor(x), yi = Math.floor(y), zi = Math.floor(z);
+  const fx = fade(x - xi), fy = fade(y - yi), fz = fade(z - zi);
+  const h = (dx, dy, dz) => hash3(wrap(xi + dx, period), wrap(yi + dy, period), wrap(zi + dz, period), seed);
+  return lerp(
+    lerp(lerp(h(0, 0, 0), h(1, 0, 0), fx), lerp(h(0, 1, 0), h(1, 1, 0), fx), fy),
+    lerp(lerp(h(0, 0, 1), h(1, 0, 1), fx), lerp(h(0, 1, 1), h(1, 1, 1), fx), fy),
+    fz,
+  );
+}
+
+/**
+ * Smooth 2D noise (value noise) in [0, 1): random at whole coordinates,
+ * blended smoothly in between. Multiply the coordinates to change the size
+ * of the blobs.
+ *
+ * With `period`, the noise repeats every `period` units on both axes, so a
+ * texture painted with it tiles with no seam (map the texture's width to
+ * `period` units).
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {Object} [opts]
+ * @param {number} [opts.seed=0] - Whole number; another seed gives other noise
+ * @param {number} [opts.period=0] - Repeat every this many units (a whole number; 0: never)
+ * @returns {number}
+ */
+export function noise2(x, y, { seed = 0, period = 0 } = {}) {
+  return value2(x, y, seed, periodOf(period));
+}
+
+/**
+ * Smooth 3D noise in [0, 1). Sample it at a mesh's vertex positions to
+ * displace a sphere with no seam. `period` repeats it on all three axes.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {Object} [opts]
+ * @param {number} [opts.seed=0] - Whole number; another seed gives other noise
+ * @param {number} [opts.period=0] - Repeat every this many units (a whole number; 0: never)
+ * @returns {number}
+ */
+export function noise3(x, y, z, { seed = 0, period = 0 } = {}) {
+  return value3(x, y, z, seed, periodOf(period));
+}
+
+/**
+ * Fractal 2D noise (fBm): `octaves` layers of noise2, each twice as fine and
+ * `gain` times as strong as the one before. Gives natural detail: terrain,
+ * clouds, rock, marble. Result in about [0, 1), averaging 0.5.
+ *
+ * @example
+ * // A tiling cloud texture
+ * const p = 4; // 4 blobs across
+ * for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+ *   const n = fbm2((x / size) * p, (y / size) * p, { period: p });
+ *   ctx.fillStyle = `rgb(${n * 255}, ${n * 255}, 255)`;
+ *   ctx.fillRect(x, y, 1, 1);
+ * }
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {Object} [opts]
+ * @param {number} [opts.octaves=5] - Layers of detail
+ * @param {number} [opts.gain=0.5] - Strength of each layer compared to the one before
+ * @param {number} [opts.seed=0] - Whole number; another seed gives other noise
+ * @param {number} [opts.period=0] - Repeat every this many units (a whole number; 0: never)
+ * @returns {number}
+ */
+export function fbm2(x, y, { octaves = 5, gain = 0.5, seed = 0, period = 0 } = {}) {
+  const p = periodOf(period);
+  let sum = 0, amp = 1, norm = 0, freq = 1;
+  for (let i = 0; i < octaves; i++) {
+    sum += amp * value2(x * freq, y * freq, seed + i * 31, p * freq);
+    norm += amp;
+    amp *= gain;
+    freq *= 2;
+  }
+  return norm > 0 ? sum / norm : 0;
+}
+
+/**
+ * Fractal 3D noise (fBm), like `fbm2` in three dimensions. Result in about
+ * [0, 1), averaging 0.5.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {Object} [opts]
+ * @param {number} [opts.octaves=5] - Layers of detail
+ * @param {number} [opts.gain=0.5] - Strength of each layer compared to the one before
+ * @param {number} [opts.seed=0] - Whole number; another seed gives other noise
+ * @param {number} [opts.period=0] - Repeat every this many units (a whole number; 0: never)
+ * @returns {number}
+ */
+export function fbm3(x, y, z, { octaves = 5, gain = 0.5, seed = 0, period = 0 } = {}) {
+  const p = periodOf(period);
+  let sum = 0, amp = 1, norm = 0, freq = 1;
+  for (let i = 0; i < octaves; i++) {
+    sum += amp * value3(x * freq, y * freq, z * freq, seed + i * 31, p * freq);
+    norm += amp;
+    amp *= gain;
+    freq *= 2;
+  }
+  return norm > 0 ? sum / norm : 0;
+}

package/trid/math/rotation.js

@@ -0,0 +1,152 @@
+import { rotateXYZ } from "./transform.js";
+
+/**
+ * Rotation matrices and move / rotate / scale operations on an object's
+ * transform ({ pos, rot, scale }, applied scale → rotate X, Y, Z → move).
+ *
+ * Matrices are 3×3, row-major (`m[row][col]`), applied as M · v. They're
+ * built from `rotateXYZ` itself, so they always match what the renderers draw.
+ *
+ * @typedef {[[number,number,number],[number,number,number],[number,number,number]]} Mat3
+ * @typedef {{x:number, y:number, z:number}} Vec3
+ * @typedef {{ pos:Vec3, rot:Vec3, scale:Vec3 }} Transform
+ *
+ * @typedef {{ mode:"move", delta:Vec3 }
+ *   | { mode:"rotate", axis:Vec3, angle:number, center:Vec3 }
+ *   | { mode:"scale", axis:Vec3|null, factor:number, center:Vec3 }} TransformOp
+ *   An operation in world space. Rotate: a right-handed turn of `angle`
+ *   radians around the unit `axis`, about `center`. Scale: `factor` about
+ *   `center`, uniform when `axis` is null, otherwise along that unit axis.
+ */
+
+const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+const add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z });
+const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z });
+const mul = (a, k) => ({ x: a.x * k, y: a.y * k, z: a.z * k });
+
+/**
+ * The matrix `rotateXYZ(p, rot)` applies.
+ *
+ * @param {Vec3} rot - Angles in radians (X, then Y, then Z)
+ * @returns {Mat3}
+ */
+export function matFromEuler(rot) {
+  const cx = rotateXYZ({ x: 1, y: 0, z: 0 }, rot);
+  const cy = rotateXYZ({ x: 0, y: 1, z: 0 }, rot);
+  const cz = rotateXYZ({ x: 0, y: 0, z: 1 }, rot);
+  return [
+    [cx.x, cy.x, cz.x],
+    [cx.y, cy.y, cz.y],
+    [cx.z, cy.z, cz.z],
+  ];
+}
+
+/**
+ * Angles for `rotateXYZ` (an object's `rot`) from a rotation matrix: the
+ * inverse of `matFromEuler`. Looking straight along Y (gimbal lock), X and
+ * Z turn the same way, so the whole turn goes into Z.
+ *
+ * @param {Mat3} m - A rotation matrix
+ * @returns {Vec3} Angles in radians
+ */
+export function eulerFromMat(m) {
+  // rotateXYZ's matrix is Rz·Ry·Rx: m[2][0] = sin(y), m[2][1] = cos(y)·sin(x), m[1][0] = sin(z)·cos(y)
+  const sy = Math.max(-1, Math.min(1, m[2][0]));
+  const y = Math.asin(sy);
+  if (Math.abs(sy) < 0.99999) {
+    return { x: Math.atan2(m[2][1], m[2][2]), y, z: Math.atan2(m[1][0], m[0][0]) };
+  }
+  return { x: 0, y, z: Math.atan2(-m[0][1], m[1][1]) };
+}
+
+/**
+ * A right-handed turn of `angle` radians around a unit `axis` (Rodrigues).
+ *
+ * @param {Vec3} axis - Unit vector
+ * @param {number} angle - Radians
+ * @returns {Mat3}
+ */
+export function matFromAxisAngle(axis, angle) {
+  const { x, y, z } = axis, c = Math.cos(angle), s = Math.sin(angle), t = 1 - c;
+  return [
+    [t * x * x + c, t * x * y - s * z, t * x * z + s * y],
+    [t * x * y + s * z, t * y * y + c, t * y * z - s * x],
+    [t * x * z - s * y, t * y * z + s * x, t * z * z + c],
+  ];
+}
+
+/**
+ * Matrix product a · b (b is applied first).
+ *
+ * @param {Mat3} a
+ * @param {Mat3} b
+ * @returns {Mat3}
+ */
+export function mulMat(a, b) {
+  return [0, 1, 2].map((i) => [0, 1, 2].map((j) => a[i][0] * b[0][j] + a[i][1] * b[1][j] + a[i][2] * b[2][j]));
+}
+
+/**
+ * Matrix times vector, m · v.
+ *
+ * @param {Mat3} m
+ * @param {Vec3} v
+ * @returns {Vec3}
+ */
+export function mulVec(m, v) {
+  return {
+    x: m[0][0] * v.x + m[0][1] * v.y + m[0][2] * v.z,
+    y: m[1][0] * v.x + m[1][1] * v.y + m[1][2] * v.z,
+    z: m[2][0] * v.x + m[2][1] * v.y + m[2][2] * v.z,
+  };
+}
+
+/**
+ * Applies a world-space operation to a transform and returns the new one
+ * (the input isn't changed). `TransformGizmo` reports these.
+ *
+ * - move: adds `delta` to `pos`
+ * - rotate: turns the object around `center`: its position orbits and its
+ *   orientation turns, both by the same rotation
+ * - scale: scales about `center`. Stretching a rotated object along a world
+ *   axis can't be stored as `scale` (it would shear), so it stretches the
+ *   object's own axis that points most along it
+ *
+ * @example
+ * Object.assign(obj, applyTransformOp(obj, { mode: "rotate", axis: { x: 0, y: 1, z: 0 }, angle: Math.PI / 2, center: { x: 0, y: 0, z: 0 } }));
+ *
+ * @param {Transform} t - The transform before the operation
+ * @param {TransformOp} op
+ * @returns {Transform}
+ */
+export function applyTransformOp(t, op) {
+  switch (op.mode) {
+    case "move":
+      return { pos: add(t.pos, op.delta), rot: { ...t.rot }, scale: { ...t.scale } };
+    case "rotate": {
+      const r = matFromAxisAngle(op.axis, op.angle);
+      return {
+        pos: add(op.center, mulVec(r, sub(t.pos, op.center))),
+        rot: eulerFromMat(mulMat(r, matFromEuler(t.rot))),
+        scale: { ...t.scale },
+      };
+    }
+    case "scale": {
+      const f = op.factor;
+      if (!op.axis) {
+        return { pos: add(op.center, mul(sub(t.pos, op.center), f)), rot: { ...t.rot }, scale: mul(t.scale, f) };
+      }
+      const a = op.axis;
+      const pos = add(t.pos, mul(a, (f - 1) * dot(sub(t.pos, op.center), a)));
+      // The object's own axis most aligned with the stretch (columns of its rotation)
+      const m = matFromEuler(t.rot);
+      const along = [0, 1, 2].map((j) => Math.abs(m[0][j] * a.x + m[1][j] * a.y + m[2][j] * a.z));
+      const j = along.indexOf(Math.max(...along));
+      const scale = { ...t.scale };
+      scale["xyz"[j]] *= f;
+      return { pos, rot: { ...t.rot }, scale };
+    }
+    default:
+      throw new Error("applyTransformOp: unknown mode " + op?.mode);
+  }
+}