trid3d 0.2.0 → 0.3.1

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);
+  }
+}

package/trid/render/canvasRenderer.js

@@ -1,8 +1,10 @@
-import { localToWorld, worldToCamera, cameraToScreen, clipNear, rotateXYZ, DEFAULT_NEAR } from "../math/transform.js";
+import { worldToCamera, cameraToScreen, clipNear, DEFAULT_NEAR } from "../math/transform.js";
+import { transformPoint, normalMatrix, transformNormal, determinantMat4 } from "../math/matrix.js";
+import { worldObjects } from "../sceneGraph.js";
 import { clear, drawInstance, edgeSegments, wireEdges } from "./draw.js";
 import { parseColor } from "./color.js";
 import { newell, cornerNormals, creaseOf } from "./normals.js";
-import { textureReady, textureSize, textureIsLive } from "../loaders/texture.js";
+import { textureReady, textureSize, textureIsLive, textureVersion } from "../loaders/texture.js";
 import { uvsFor, uvTransform, applyUVTransform } from "./uvMapping.js";
 
 export { newell };
@@ -44,6 +46,8 @@ export const DEFAULT_AMBIENT = 0.25;
  *   shapes look round. `true` keeps edges sharper than 60° hard; a number sets that angle.
  * @property {CanvasImageSource} [texture] - Image drawn on the faces (needs texture coordinates:
  *   built-in shapes and OBJ files with `vt` have them). `fill` tints it (default white).
+ * @property {boolean} [liveTexture] - Read the texture again every frame (default: only for videos).
+ *   For a canvas redrawn every frame; for one redrawn now and then, call `updateTexture(canvas)` instead
  * @property {boolean} [pixelated=false] - Keep texture pixels sharp instead of smoothing them
  * @property {import("./uvMapping.js").Mapping} [mapping="uv"] - Where texture coordinates come
  *   from: the mesh's own ("uv"), or made from its shape ("planar", "box", "sphere", "cylinder")
@@ -86,7 +90,7 @@ export class CanvasRenderer {
     this._splits = new WeakMap();
     this._colors = new Map();
     this._start = performance.now();
-    this._patterns = new Map(); // texture source → canvas pattern
+    this._patterns = new WeakMap(); // texture source → canvas pattern (freed with the source)
     this._warned = new WeakSet();
     this._frame = 0;
   }
@@ -102,11 +106,15 @@ export class CanvasRenderer {
     clear(ctx, w, h, scene.background);
     this._frame++;
 
+    // Every object with a mesh, groups' children included, with its world matrix
+    const drawn = worldObjects(scene).filter((o) => o.mesh);
+
     // Wireframes only: nothing to sort
-    if (!scene.objects.some((o) => materialsOf(o))) {
-      for (const obj of scene.objects) {
-        drawInstance(ctx, obj, camera, w, h, obj.color ?? scene.color, obj.lineWidth ?? scene.lineWidth);
+    if (!drawn.some((o) => materialsOf(o))) {
+      for (const obj of drawn) {
+        drawInstance(ctx, obj, camera, w, h, obj.color ?? scene.color, obj.lineWidth ?? scene.lineWidth, obj.world);
       }
+      for (const obj of drawn) if (obj.mesh.dirty) obj.mesh.dirty = false;
       return;
     }
 
@@ -120,12 +128,12 @@ export class CanvasRenderer {
     const time = (performance.now() - this._start) / 1000;
     const background = this._rgba(ctx, scene.background);
 
-    for (const obj of scene.objects) {
+    for (const obj of drawn) {
       const mats = materialsOf(obj);
       // Split big faces (cached per mesh); extra vertices are midpoints of existing ones
       const split = mats && this.maxFaceSize ? this._split(obj.mesh) : null;
       const verts = split ? withMidpoints(obj.mesh.vertices, split.mids) : obj.mesh.vertices;
-      const world = verts.map((v) => localToWorld(v, obj));
+      const world = verts.map((v) => transformPoint(obj.world, v));
       const cam = world.map((p) => worldToCamera(p, camera));
       const color = obj.color ?? scene.color;
       const lineWidth = obj.lineWidth ?? scene.lineWidth;
@@ -145,6 +153,13 @@ export class CanvasRenderer {
 
       const sourceFaces = obj.mesh.faces ?? [];
       const base = obj.mesh.vertices.length;
+      // Normals turn with the object (stretched and mirrored ones too); a mirror reverses face winding
+      const nm = normalMatrix(obj.world);
+      const flip = determinantMat4(obj.world) < 0 ? -1 : 1;
+      const flatNormal = (face) => {
+        const n = normalize(newell(face.map((i) => world[i])));
+        return { x: n.x * flip, y: n.y * flip, z: n.z * flip };
+      };
 
       // Smooth shading: a normal per face corner (split faces get midpoints' normals by averaging)
       const normalAt = (corners, F, i) => {
@@ -154,18 +169,16 @@ export class CanvasRenderer {
         return normalize({ x: na.x + nb.x, y: na.y + nb.y, z: na.z + nb.z });
       };
       const lightAt = (n, back) => {
-        // Same steps as the vertices: undo the scale, then rotate (keeps normals right on stretched objects)
-        const r = normalize(rotateXYZ({ x: n.x / obj.scale.x, y: n.y / obj.scale.y, z: n.z / obj.scale.z }, obj.rot));
+        const r = transformNormal(nm, n);
         const d = (back ? -1 : 1) * (r.x * light.x + r.y * light.y + r.z * light.z);
         return ambient + (1 - ambient) * Math.max(0, d);
       };
       const flatLight = (face, back) => {
-        const nw = normalize(newell(face.map((i) => world[i])));
+        const nw = flatNormal(face);
         const d = (back ? -1 : 1) * (nw.x * light.x + nw.y * light.y + nw.z * light.z);
         return ambient + (1 - ambient) * Math.max(0, d);
       };
-      const toWorldNormal = (n) =>
-        normalize(rotateXYZ({ x: n.x / obj.scale.x, y: n.y / obj.scale.y, z: n.z / obj.scale.z }, obj.rot));
+      const toWorldNormal = (n) => transformNormal(nm, n);
 
       // Everything a material needs, worked out once per object and frame
       const prepare = (mat) => {
@@ -220,7 +233,7 @@ export class CanvasRenderer {
         // Seen from behind? (camera sits at the origin of camera space)
         const n = newell(pts);
         const c = centroid(pts);
-        const back = n.x * c.x + n.y * c.y + n.z * c.z >= 0;
+        const back = (n.x * c.x + n.y * c.y + n.z * c.z >= 0) !== (flip < 0);
         if (back && !L.mat.doubleSided) continue;
 
         const clipped = clipPolygon(pts, near);
@@ -244,7 +257,7 @@ export class CanvasRenderer {
               items.push({
                 depth: c.z,
                 poly: [screen[0], screen[k], screen[k + 1]],
-                texture: { src: L.tex, uvs: [ts[0], ts[k], ts[k + 1]], pixelated: !!L.mat.pixelated, tint: fill },
+                texture: { src: L.tex, uvs: [ts[0], ts[k], ts[k + 1]], pixelated: !!L.mat.pixelated, live: textureIsLive(L.tex, L.mat), tint: fill },
                 lit: [lit[0], lit[k], lit[k + 1]],
                 outline, lineWidth,
                 edges: n === 3 ? edges : fan,
@@ -263,7 +276,7 @@ export class CanvasRenderer {
               .reduce((a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }), { x: 0, y: 0, z: 0 });
             nw = normalize(sum);
           } else {
-            nw = normalize(newell(face.map((i) => world[i])));
+            nw = flatNormal(face);
           }
           if (back) nw = { x: -nw.x, y: -nw.y, z: -nw.z };
 
@@ -380,7 +393,7 @@ export class CanvasRenderer {
     }
 
     // Meshes marked as changed have been redrawn from their new data
-    for (const obj of scene.objects) if (obj.mesh.dirty) obj.mesh.dirty = false;
+    for (const obj of drawn) if (obj.mesh.dirty) obj.mesh.dirty = false;
   }
 
   /**
@@ -493,7 +506,7 @@ export class CanvasRenderer {
    * triangle's corners, tinted by the fill color, then darkened by the light.
    */
   _drawTextured(ctx, it) {
-    const { src, uvs, pixelated, tint } = it.texture;
+    const { src, uvs, pixelated, live, tint } = it.texture;
     const { w: W, h: H } = textureSize(src);
     const [p0, p1, p2] = it.poly;
 
@@ -519,7 +532,7 @@ export class CanvasRenderer {
       const dx1 = p1.x - p0.x, dy1 = p1.y - p0.y, dx2 = p2.x - p0.x, dy2 = p2.y - p0.y;
       const a = (dx1 * dv2 - dx2 * dv1) / det, b = (dy1 * dv2 - dy2 * dv1) / det;
       const c = (dx2 * du1 - dx1 * du2) / det, d = (dy2 * du1 - dy1 * du2) / det;
-      const pattern = this._pattern(ctx, src);
+      const pattern = this._pattern(ctx, src, live);
       pattern.setTransform(new DOMMatrix([a, b, c, d, p0.x - a * U[0] - c * V[0], p0.y - b * U[0] - d * V[0]]));
       ctx.imageSmoothingEnabled = !pixelated;
       ctx.fillStyle = pattern;
@@ -553,11 +566,15 @@ export class CanvasRenderer {
     ctx.fill();
   }
 
-  /** A repeating pattern for a texture (made again each frame for canvases and videos). */
-  _pattern(ctx, src) {
+  /**
+   * A repeating pattern for a texture. A pattern is a copy of the image, so
+   * it's made again after `updateTexture`, and every frame for live ones.
+   */
+  _pattern(ctx, src, live) {
     let p = this._patterns.get(src);
-    if (!p || (textureIsLive(src) && p.frame !== this._frame)) {
-      p = { pattern: ctx.createPattern(src, "repeat"), frame: this._frame };
+    const version = textureVersion(src);
+    if (!p || p.version !== version || (live && p.frame !== this._frame)) {
+      p = { pattern: ctx.createPattern(src, "repeat"), frame: this._frame, version };
       this._patterns.set(src, p);
     }
     return p.pattern;

package/trid/render/draw.js

@@ -1,4 +1,5 @@
 import { localToWorld, worldToCamera, cameraToScreen, clipNear, DEFAULT_NEAR } from "../math/transform.js";
+import { transformPoint } from "../math/matrix.js";
 
 /**
  * Clears the entire canvas with a solid background color.
@@ -136,10 +137,13 @@ export function drawWireframe(ctx, points2, edges, color, width = 4) {
  * @param {number} h - Canvas height
  * @param {string} color - Wireframe color
  * @param {number} lineWidth - Wireframe width
+ * @param {number[]} [world] - World matrix to place it with (e.g. `obj.world` inside a group).
+ *   Default: the instance's own pos / rot / scale
  */
-export function drawInstance(ctx, inst, camera, w, h, color, lineWidth = 3) {
+export function drawInstance(ctx, inst, camera, w, h, color, lineWidth = 3, world) {
   const near = camera.near ?? DEFAULT_NEAR;
-  const ptsCam = inst.mesh.vertices.map(v => worldToCamera(localToWorld(v, inst), camera));
+  const toWorld = world ? (v) => transformPoint(world, v) : (v) => localToWorld(v, inst);
+  const ptsCam = inst.mesh.vertices.map((v) => worldToCamera(toWorld(v), camera));
 
   ctx.lineWidth = lineWidth;
   ctx.strokeStyle = color;

package/trid/render/meshUtils.js

@@ -0,0 +1,257 @@
+import { localToWorld, rotateXYZ } from "../math/transform.js";
+import { transformPoint, normalMatrix, transformNormal, determinantMat4 } from "../math/matrix.js";
+import { forEachPlaced, worldMatrix } from "../sceneGraph.js";
+
+/** Deep copy of one mesh field: arrays and plain objects are copied, the rest kept. */
+const copy = (x) => (Array.isArray(x) ? x.map(copy) : x && typeof x === "object" ? { ...x } : x);
+
+/** A transform with every part filled in. */
+const fullTransform = ({ pos, rot, scale } = {}) => ({
+  pos: { x: 0, y: 0, z: 0, ...pos },
+  rot: { x: 0, y: 0, z: 0, ...rot },
+  scale: { x: 1, y: 1, z: 1, ...scale },
+});
+
+/** A copy of a mesh with a world matrix baked in (normals turned, faces flipped for mirrors). */
+function bake(mesh, world) {
+  const out = cloneMesh(mesh);
+  for (const v of out.vertices) Object.assign(v, transformPoint(world, v));
+  if (out.normals) {
+    const nm = normalMatrix(world);
+    out.normals = out.normals.map((n) => transformNormal(nm, n));
+  }
+  if (determinantMat4(world) < 0 && out.faces) {
+    const flip = (list) => list?.map((f) => (f ? [...f].reverse() : f));
+    out.faces = flip(out.faces);
+    if (out.faceUVs) out.faceUVs = flip(out.faceUVs);
+    if (out.faceNormals) out.faceNormals = flip(out.faceNormals);
+  }
+  return out;
+}
+
+/**
+ * Deep copy of a mesh: vertices, edges, faces, texture coordinates, normals
+ * and materials. Change the copy without touching the original (or the other
+ * objects that share it).
+ *
+ * @template M
+ * @param {M} mesh
+ * @returns {M} A new mesh
+ */
+export function cloneMesh(mesh) {
+  const out = {};
+  for (const k of Object.keys(mesh)) if (k !== "dirty") out[k] = copy(mesh[k]);
+  return out;
+}
+
+/**
+ * Bakes a transform into a mesh's vertices, in place: scale, then rotate
+ * (X, then Y, then Z), then move, the same order objects use. Its own normals
+ * turn with it, and a mirroring scale (an odd number of negative factors)
+ * reverses the faces so they still face outward.
+ *
+ * Pass a scene object to bake its `pos`, `rot` and `scale` (then reset them
+ * on the object, or it's transformed twice).
+ *
+ * @example
+ * // A handle standing on the side of a mug
+ * transformMesh(handle, { pos: { x: 0.3, y: 0, z: 0 }, rot: { x: 0, y: 0, z: Math.PI / 2 } });
+ *
+ * @template M
+ * @param {M} mesh - Mesh to change
+ * @param {{ pos?:{x:number,y:number,z:number}, rot?:{x:number,y:number,z:number}, scale?:{x:number,y:number,z:number} }} transform
+ *   Parts left out don't change anything
+ * @returns {M} The same mesh
+ */
+export function transformMesh(mesh, transform) {
+  const t = fullTransform(transform);
+  for (const v of mesh.vertices) Object.assign(v, localToWorld(v, t));
+
+  // Normals: divide by the scale (keeps them perpendicular to stretched faces), turn, then normalize
+  if (mesh.normals) {
+    const s = t.scale;
+    mesh.normals = mesh.normals.map((n) => {
+      const r = rotateXYZ({ x: n.x / (s.x || 1), y: n.y / (s.y || 1), z: n.z / (s.z || 1) }, t.rot);
+      const len = Math.hypot(r.x, r.y, r.z) || 1;
+      return { x: r.x / len, y: r.y / len, z: r.z / len };
+    });
+  }
+
+  // A mirror turns clockwise faces counter-clockwise: reverse them (and their corner lists)
+  if (t.scale.x * t.scale.y * t.scale.z < 0 && mesh.faces) {
+    const flip = (list) => list?.map((f) => (f ? [...f].reverse() : f));
+    mesh.faces = flip(mesh.faces);
+    if (mesh.faceUVs) mesh.faceUVs = flip(mesh.faceUVs);
+    if (mesh.faceNormals) mesh.faceNormals = flip(mesh.faceNormals);
+  }
+
+  mesh.dirty = true;
+  return mesh;
+}
+
+/**
+ * Moves every vertex to `fn(vertex, index)`, in place: noise on a rock,
+ * waves on a plane, a bend or a twist.
+ *
+ * The mesh's own normals (from an OBJ file) no longer fit the new shape, so
+ * they're removed and the renderers compute new ones.
+ *
+ * @example
+ * // A lumpy rock
+ * displaceMesh(makeShape("sphere"), (v) => {
+ *   const k = 1 + 0.3 * (fbm3(v.x * 3, v.y * 3, v.z * 3) - 0.5);
+ *   return { x: v.x * k, y: v.y * k, z: v.z * k };
+ * });
+ *
+ * @template M
+ * @param {M} mesh - Mesh to change
+ * @param {(v:{x:number,y:number,z:number}, index:number) => {x:number,y:number,z:number}} fn - New position of a vertex
+ * @returns {M} The same mesh
+ */
+export function displaceMesh(mesh, fn) {
+  mesh.vertices.forEach((v, i) => {
+    const p = fn({ x: v.x, y: v.y, z: v.z }, i);
+    v.x = p.x;
+    v.y = p.y;
+    v.z = p.z;
+  });
+  delete mesh.normals;
+  delete mesh.faceNormals;
+  mesh.dirty = true;
+  return mesh;
+}
+
+/**
+ * Joins meshes into one: one object to draw instead of many, or one mesh to
+ * export. Faces, edges, texture coordinates, normals and materials are kept,
+ * with their indices shifted.
+ *
+ * An object (`{ mesh, pos, rot, scale }`, added to a scene or not) in the
+ * list is merged where it stands, with its transform baked in (its mesh
+ * isn't changed). A group is merged with all its children, placed by the
+ * group's own transform (not its parents').
+ *
+ * With `materialPerMesh`, the faces of the i-th mesh use material i, so an
+ * object with `material: [blade, guard, grip]` paints each part its own way.
+ * Otherwise each mesh's `faceMaterials` are kept; material names (from OBJ
+ * files) are joined into one list when every mesh with materials has them.
+ *
+ * The meshes are copied, never changed.
+ *
+ * @example
+ * const sword = mergeMeshes([blade, guard, grip], { materialPerMesh: true });
+ * scene.add({ mesh: sword, material: [{ fill: "#ccd" }, { fill: "#c90" }, { fill: "#642" }] });
+ *
+ * @param {Object[]} items - Meshes, or scene objects with a `mesh`
+ * @param {Object} [opts]
+ * @param {boolean} [opts.materialPerMesh=false] - Faces of the i-th mesh use material i
+ * @returns {import("../index.d.ts").Mesh} A new mesh
+ */
+export function mergeMeshes(items, { materialPerMesh = false } = {}) {
+  // Meshes as they are; objects and groups baked where they stand, one entry per item
+  const meshes = items.map((it) => {
+    if (it.vertices) return it;
+    const parts = [];
+    forEachPlaced([it], () => null, (obj, world) => {
+      if (obj.mesh) parts.push(bake(obj.mesh, world));
+    });
+    return parts.length === 1 ? parts[0] : mergeMeshes(parts);
+  });
+  const some = (k) => meshes.some((m) => m[k]);
+
+  const out = { vertices: [], faces: [] };
+  const hasEdges = some("edges");
+  const hasUVs = some("faceUVs") && some("uvs");
+  const hasNormals = some("faceNormals") && some("normals");
+  const hasMats = materialPerMesh || some("faceMaterials");
+  const withMats = meshes.filter((m) => m.faceMaterials);
+  const names = !materialPerMesh && withMats.length > 0 && withMats.every((m) => m.materialNames) ? [] : null;
+  if (hasEdges) out.edges = [];
+  if (hasUVs) Object.assign(out, { uvs: [], faceUVs: [] });
+  if (hasNormals) Object.assign(out, { normals: [], faceNormals: [] });
+  if (hasMats) out.faceMaterials = [];
+
+  meshes.forEach((m, mi) => {
+    const vo = out.vertices.length, uo = out.uvs?.length ?? 0, no = out.normals?.length ?? 0;
+    const shift = (list, o) => list.map((i) => i + o);
+    out.vertices.push(...m.vertices.map((v) => ({ x: v.x, y: v.y, z: v.z })));
+    // A mesh without edges keeps showing its face outlines next to meshes that have some
+    if (hasEdges) out.edges.push(...(m.edges ?? m.faces ?? []).map((e) => shift(e, vo)));
+    if (hasUVs) out.uvs.push(...(m.uvs ?? []).map((t) => ({ u: t.u, v: t.v })));
+    if (hasNormals) out.normals.push(...(m.normals ?? []).map((n) => ({ x: n.x, y: n.y, z: n.z })));
+
+    // Material names: this mesh's index k → the index of its name in the joined list
+    const remap = names && m.materialNames
+      ? m.materialNames.map((n) => (names.includes(n) ? names.indexOf(n) : names.push(n) - 1))
+      : null;
+
+    (m.faces ?? []).forEach((f, fi) => {
+      out.faces.push(shift(f, vo));
+      if (hasUVs) {
+        const fu = m.uvs && m.faceUVs?.[fi];
+        out.faceUVs.push(fu ? shift(fu, uo) : null);
+      }
+      if (hasNormals) {
+        const fn = m.normals && m.faceNormals?.[fi];
+        out.faceNormals.push(fn ? shift(fn, no) : null);
+      }
+      if (hasMats) {
+        const k = m.faceMaterials?.[fi] ?? 0;
+        out.faceMaterials.push(materialPerMesh ? mi : remap ? (remap[k] ?? 0) : k);
+      }
+    });
+  });
+
+  if (names) out.materialNames = names;
+  return out;
+}
+
+/**
+ * The box around one or more meshes: `min` and `max` corners, plus its
+ * `center` and `size`. Scene objects (and a whole Scene) are measured where
+ * they stand, with their transform.
+ *
+ * @example
+ * const { center, size } = meshBounds(scene);
+ * orbit.target = center;
+ * orbit.distance = Math.max(size.x, size.y, size.z) * 2;
+ *
+ * @param {Object|Object[]} input - A mesh, a scene object, a list of them, or a Scene
+ * @returns {{ min:{x:number,y:number,z:number}, max:{x:number,y:number,z:number},
+ *   center:{x:number,y:number,z:number}, size:{x:number,y:number,z:number} } | null}
+ *   null when there are no vertices
+ */
+export function meshBounds(input) {
+  const items = Array.isArray(input) ? input : Array.isArray(input?.objects) ? input.objects : [input];
+  const min = { x: Infinity, y: Infinity, z: Infinity };
+  const max = { x: -Infinity, y: -Infinity, z: -Infinity };
+  let any = false;
+  // Plain meshes as they are; objects (and their children) where they're drawn
+  const placed = [];
+  const objects = [];
+  for (const it of items) {
+    if (it?.vertices) placed.push({ mesh: it, world: null });
+    else if (it) objects.push(it);
+  }
+  forEachPlaced(objects, (root) => (root.parent ? worldMatrix(root.parent) : null), (obj, world) => {
+    if (obj.mesh?.vertices) placed.push({ mesh: obj.mesh, world });
+  });
+  for (const { mesh, world } of placed) {
+    for (const v of mesh.vertices) {
+      const p = world ? transformPoint(world, v) : v;
+      any = true;
+      if (p.x < min.x) min.x = p.x;
+      if (p.y < min.y) min.y = p.y;
+      if (p.z < min.z) min.z = p.z;
+      if (p.x > max.x) max.x = p.x;
+      if (p.y > max.y) max.y = p.y;
+      if (p.z > max.z) max.z = p.z;
+    }
+  }
+  if (!any) return null;
+  return {
+    min, max,
+    center: { x: (min.x + max.x) / 2, y: (min.y + max.y) / 2, z: (min.z + max.z) / 2 },
+    size: { x: max.x - min.x, y: max.y - min.y, z: max.z - min.z },
+  };
+}