trid3d 0.1.0 → 0.2.0

package/trid/render/shapes.js

@@ -45,6 +45,8 @@ function rectPrismWire(w = 0.6, h = 0.3, d = 0.4) {
       [0, 3, 7, 4], // right
       [1, 5, 6, 2], // left
     ],
+    // Which material each face uses when `material` is a list: one per side, in the order above
+    faceMaterials: [0, 1, 2, 3, 4, 5],
   };
   return withFaceUVs(mesh);
 }
@@ -161,6 +163,268 @@ function sphereWire(radius = 0.35, rings = 10, segments = 16) {
   return { vertices, edges, faces, uvs, faceUVs };
 }
 
+/**
+ * Spins a profile around the Y axis: vases, bottles, cups, columns, chess
+ * pieces. Cylinders, cones and tori are built with it.
+ *
+ * Walk the profile so the outside is on its right in the (r, y) plane:
+ * bottom to top for a vase. Faces are clockwise as seen from outside.
+ *
+ * Texture coordinates: u goes around, v follows the profile's length.
+ * Caps map the texture as a disc. Edges are the profile's rings plus one
+ * line along the profile per segment.
+ *
+ * @example
+ * // A vase
+ * const vase = lathe(
+ *   [{ r: 0.2, y: -0.5 }, { r: 0.35, y: -0.2 }, { r: 0.15, y: 0.3 }, { r: 0.2, y: 0.5 }],
+ *   { capBottom: true },
+ * );
+ *
+ * @param {{r:number, y:number}[]} profile - Points: distance from the Y axis and height
+ * @param {Object} [opts]
+ * @param {number} [opts.segments=32] - Points around the axis
+ * @param {boolean} [opts.capBottom=false] - Close the bottom with a flat cap
+ * @param {boolean} [opts.capTop=false] - Close the top with a flat cap
+ * @param {boolean} [opts.closed=false] - The last point joins the first (torus-like shapes)
+ * @returns {import("../index.d.ts").Mesh}
+ */
+export function lathe(profile, { segments = 32, capBottom = false, capTop = false, closed = false } = {}) {
+  segments = Math.max(3, Math.floor(segments));
+  const vertices = [];
+  const edges = [];
+  const faces = [];
+  const uvs = [];
+  const faceUVs = [];
+  const uv = (u, v) => uvs.push({ u, v }) - 1;
+
+  // v along the profile, by length
+  const pts = closed ? [...profile, profile[0]] : profile;
+  const lengths = [0];
+  for (let i = 1; i < pts.length; i++) {
+    lengths.push(lengths[i - 1] + Math.hypot(pts[i].r - pts[i - 1].r, pts[i].y - pts[i - 1].y));
+  }
+  const total = lengths[lengths.length - 1] || 1;
+
+  for (const p of profile) {
+    for (let s = 0; s < segments; s++) {
+      const t = (s / segments) * Math.PI * 2;
+      vertices.push({ x: Math.cos(t) * p.r, y: p.y, z: Math.sin(t) * p.r });
+    }
+  }
+
+  const rows = pts.length - 1;
+  for (let r = 0; r < rows; r++) {
+    const a = r * segments;
+    const b = ((r + 1) % profile.length) * segments;
+    for (let s = 0; s < segments; s++) {
+      const s1 = (s + 1) % segments;
+      faces.push([a + s, b + s, b + s1, a + s1]);
+      const u0 = s / segments, u1 = (s + 1) / segments;
+      const v0 = lengths[r] / total, v1 = lengths[r + 1] / total;
+      faceUVs.push([uv(u0, v0), uv(u0, v1), uv(u1, v1), uv(u1, v0)]);
+    }
+  }
+
+  // Rings (skipped where the profile touches the axis) and lines along the profile
+  profile.forEach((p, r) => {
+    if (p.r > 1e-5) edges.push(Array.from({ length: segments }, (_, s) => r * segments + s));
+  });
+  for (let s = 0; s < segments; s++) {
+    if (closed && profile.length > 2) edges.push(profile.map((_, r) => r * segments + s));
+    else for (let r = 0; r < profile.length - 1; r++) edges.push([r * segments + s, (r + 1) * segments + s]);
+  }
+
+  const disc = (s) => {
+    const t = (s / segments) * Math.PI * 2;
+    return uv(0.5 + Math.cos(t) * 0.5, 0.5 + Math.sin(t) * 0.5);
+  };
+  if (capBottom && !closed && profile[0].r > 0) {
+    const c = vertices.push({ x: 0, y: profile[0].y, z: 0 }) - 1;
+    for (let s = 0; s < segments; s++) {
+      faces.push([c, s, (s + 1) % segments]);
+      faceUVs.push([uv(0.5, 0.5), disc(s), disc(s + 1)]);
+    }
+  }
+  const last = profile.length - 1;
+  if (capTop && !closed && profile[last].r > 0) {
+    const c = vertices.push({ x: 0, y: profile[last].y, z: 0 }) - 1;
+    const a = last * segments;
+    for (let s = 0; s < segments; s++) {
+      faces.push([c, a + (s + 1) % segments, a + s]);
+      faceUVs.push([uv(0.5, 0.5), disc(s + 1), disc(s)]);
+    }
+  }
+
+  return { vertices, edges, faces, uvs, faceUVs };
+}
+
+/** A capped cylinder along Y, centered on the origin. */
+function cylinder(r = 0.3, h = 0.8, segments = 32) {
+  return lathe([{ r, y: -h / 2 }, { r, y: h / 2 }], { segments, capBottom: true, capTop: true });
+}
+
+/** A cone along Y with its tip up, or a tapered cylinder when `rTop` > 0. */
+function cone(r = 0.35, h = 0.8, segments = 32, rTop = 0) {
+  // A tiny top ring keeps the tip's faces non-degenerate for UVs and normals
+  const profile = [{ r, y: -h / 2 }, { r: rTop > 0 ? rTop : 1e-6, y: h / 2 }];
+  return lathe(profile, { segments, capBottom: true, capTop: rTop > 0 });
+}
+
+/** A ring in the XZ plane: `R` from the center to the middle of the tube. */
+function torus(R = 0.35, tube = 0.12, segments = 48, tubeSegments = 20) {
+  tubeSegments = Math.max(3, Math.floor(tubeSegments));
+  const profile = [];
+  for (let i = 0; i < tubeSegments; i++) {
+    const p = (i / tubeSegments) * Math.PI * 2;
+    profile.push({ r: R + Math.cos(p) * tube, y: Math.sin(p) * tube });
+  }
+  return lathe(profile, { segments, closed: true });
+}
+
+/**
+ * A flat grid in the XZ plane facing +Y, `size` wide, with `div` cells per
+ * side. `height(x, z)` lifts each vertex (terrain). The texture covers the
+ * whole grid once.
+ */
+function plane(size = 1, div = 8, height = null) {
+  div = Math.max(1, Math.floor(div));
+  const vertices = [];
+  const uvs = [];
+  const n = div + 1;
+  const k = (i, j) => j * n + i;
+  for (let j = 0; j < n; j++) {
+    for (let i = 0; i < n; i++) {
+      const x = (i / div - 0.5) * size, z = (j / div - 0.5) * size;
+      vertices.push({ x, y: height ? height(x, z) : 0, z });
+      uvs.push({ u: i / div, v: j / div });
+    }
+  }
+  const faces = [];
+  const edges = [];
+  for (let j = 0; j < div; j++) {
+    for (let i = 0; i < div; i++) faces.push([k(i + 1, j + 1), k(i + 1, j), k(i, j), k(i, j + 1)]);
+  }
+  for (let j = 0; j < n; j++) {
+    for (let i = 0; i < div; i++) {
+      edges.push([k(i, j), k(i + 1, j)]);
+      edges.push([k(j, i), k(j, i + 1)]);
+    }
+  }
+  // Grid vertices and UVs share indices
+  return { vertices, edges, faces, uvs, faceUVs: faces.map((f) => [...f]) };
+}
+
+/** Twice the signed area: > 0 when the points go counter-clockwise (x right, y up). */
+function signedArea(pts) {
+  let a = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i], q = pts[(i + 1) % pts.length];
+    a += p.x * q.y - q.x * p.y;
+  }
+  return a;
+}
+
+/**
+ * Cuts a simple polygon (no holes, sides don't cross) into triangles, by
+ * ear clipping. Works for concave outlines. Falls back to a fan if the
+ * outline crosses itself.
+ *
+ * @param {{x:number, y:number}[]} pts - The outline, counter-clockwise (x right, y up)
+ * @returns {number[][]} Index triples into `pts`, counter-clockwise too
+ */
+export function triangulate(pts) {
+  const idx = pts.map((_, i) => i);
+  const tris = [];
+  const cross = (a, b, c) => (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+  const inside = (p, a, b, c) => cross(a, b, p) >= 0 && cross(b, c, p) >= 0 && cross(c, a, p) >= 0;
+
+  let guard = idx.length * idx.length;
+  while (idx.length > 3 && guard-- > 0) {
+    let clipped = false;
+    for (let i = 0; i < idx.length; i++) {
+      const i0 = idx[(i + idx.length - 1) % idx.length], i1 = idx[i], i2 = idx[(i + 1) % idx.length];
+      const a = pts[i0], b = pts[i1], c = pts[i2];
+      if (cross(a, b, c) <= 1e-12) continue; // reflex or flat corner
+      if (idx.some((j) => j !== i0 && j !== i1 && j !== i2 && inside(pts[j], a, b, c))) continue;
+      tris.push([i0, i1, i2]);
+      idx.splice(i, 1);
+      clipped = true;
+      break;
+    }
+    if (!clipped) break;
+  }
+  if (idx.length === 3) tris.push([idx[0], idx[1], idx[2]]);
+  else for (let i = 1; i < idx.length - 1; i++) tris.push([idx[0], idx[i], idx[i + 1]]);
+  return tris;
+}
+
+/**
+ * Turns a flat outline in the XY plane into a solid `depth` thick along Z,
+ * centered on the origin: blades, axes, keys, stars, letters, floor plans.
+ * The outline may go either way round and may be concave (no holes).
+ *
+ * Texture coordinates: the front and back map the outline's bounding box,
+ * the sides wrap u along the outline and v across the depth. Edges are the
+ * front and back outlines plus a line at each corner.
+ *
+ * @example
+ * const star = Array.from({ length: 10 }, (_, i) => {
+ *   const a = (i / 10) * Math.PI * 2, r = i % 2 ? 0.2 : 0.5;
+ *   return { x: Math.cos(a) * r, y: Math.sin(a) * r };
+ * });
+ * scene.add({ mesh: extrude(star, 0.15), material: { fill: "#fc5" } });
+ *
+ * @param {{x:number, y:number}[]} outline - The flat shape (3 points or more)
+ * @param {number} [depth=0.2] - Thickness along Z
+ * @returns {import("../index.d.ts").Mesh}
+ */
+export function extrude(outline, depth = 0.2) {
+  const pts = signedArea(outline) < 0 ? [...outline].reverse() : outline;
+  const n = pts.length;
+  const vertices = [];
+  const faces = [];
+  const uvs = [];
+  const faceUVs = [];
+  const uv = (u, v) => uvs.push({ u, v }) - 1;
+
+  // 0..n-1 at the front (-z), n..2n-1 at the back (+z)
+  for (const p of pts) vertices.push({ x: p.x, y: p.y, z: -depth / 2 });
+  for (const p of pts) vertices.push({ x: p.x, y: p.y, z: depth / 2 });
+
+  const xs = pts.map((p) => p.x), ys = pts.map((p) => p.y);
+  const x0 = Math.min(...xs), y0 = Math.min(...ys);
+  const w = Math.max(...xs) - x0 || 1, h = Math.max(...ys) - y0 || 1;
+  const capUV = (i) => uv((pts[i].x - x0) / w, (pts[i].y - y0) / h);
+
+  // Caps: counter-clockwise outlines look clockwise from the back (+z), so the
+  // back cap keeps that order and the front cap (seen from -z) is reversed
+  for (const [a, b, c] of triangulate(pts)) {
+    faces.push([n + a, n + b, n + c]);
+    faceUVs.push([capUV(a), capUV(b), capUV(c)]);
+    faces.push([c, b, a]);
+    faceUVs.push([capUV(c), capUV(b), capUV(a)]);
+  }
+
+  // Sides, u by length along the outline
+  const len = [0];
+  for (let i = 0; i < n; i++) len.push(len[i] + Math.hypot(pts[(i + 1) % n].x - pts[i].x, pts[(i + 1) % n].y - pts[i].y));
+  const total = len[n] || 1;
+  for (let i = 0; i < n; i++) {
+    const j = (i + 1) % n;
+    const ua = len[i] / total, ub = len[i + 1] / total;
+    faces.push([n + j, n + i, i, j]);
+    faceUVs.push([uv(ub, 1), uv(ua, 1), uv(ua, 0), uv(ub, 0)]);
+  }
+
+  const edges = [
+    pts.map((_, i) => i),
+    pts.map((_, i) => n + i),
+    ...pts.map((_, i) => [i, n + i]),
+  ];
+  return { vertices, edges, faces, uvs, faceUVs };
+}
+
 /**
  * Scales a mesh along the X, Y, and Z axes.
  *
@@ -192,32 +456,26 @@ export function scaleMesh(mesh, sx = 1, sy = 1, sz = 1) {
 }
 
 /**
- * Factory function that creates a predefined wireframe shape.
- *
- * This provides a unified API for constructing different meshes
- * (cube, box, sphere) while keeping the rendering pipeline generic.
- *
- * Supported shapes:
- * - "cube"   → wireframe cube
- * - "box"    → rectangular prism (box)
- * - "sphere" → wireframe sphere
+ * Creates a built-in shape, centered on the origin.
  *
- * Each shape type accepts its own configuration options via `opts`.
- * Unspecified options fall back to sensible defaults.
+ * | Kind | Options (defaults) |
+ * | --- | --- |
+ * | `"cube"` | `size` (0.5) |
+ * | `"box"` | `w`, `h`, `d` (0.6 each) |
+ * | `"sphere"` | `r` (0.45), `rings` (12), `segments` (24) |
+ * | `"cylinder"` | `r` (0.3), `h` (0.8), `segments` (32) |
+ * | `"cone"` | `r` (0.35), `h` (0.8), `segments` (32), `rTop` (0: pointed; > 0: tapered cylinder) |
+ * | `"torus"` | `R` (0.35, center to tube middle), `tube` (0.12), `segments` (48), `tubeSegments` (20) |
+ * | `"plane"` | `size` (1), `div` (8 cells per side), `height` ((x, z) => y, optional) |
  *
- * @param {string} kind - Shape type identifier
- * @param {Object} opts - Shape configuration options
- * @param {number} [opts.size] - Cube size
- * @param {number} [opts.w] - Box width
- * @param {number} [opts.h] - Box height
- * @param {number} [opts.d] - Box depth
- * @param {number} [opts.r] - Sphere radius
- * @param {number} [opts.rings] - Number of latitude rings (sphere)
- * @param {number} [opts.segments] - Segments per ring (sphere)
- *
- * @returns {{ vertices: {x:number,y:number,z:number}[], edges: number[][] }}
- *          A wireframe mesh object
+ * Cylinders, cones and tori stand along Y; the plane lies in XZ facing +Y.
+ * Every shape has edges (for wireframes), faces (clockwise from outside)
+ * and texture coordinates. For other round or flat shapes, see `lathe`
+ * and `extrude`.
  *
+ * @param {string} kind - Shape name (case doesn't matter)
+ * @param {Object} [opts] - Size options for that shape (see the table)
+ * @returns {import("../index.d.ts").Mesh}
  * @throws {Error} If the shape type is not supported
  */
 export function makeShape(kind, opts = {}) {
@@ -225,6 +483,10 @@ export function makeShape(kind, opts = {}) {
     case "cube":  return cubeWire(opts.size ?? 0.5);
     case "box":   return rectPrismWire(opts.w ?? 0.6, opts.h ?? 0.6, opts.d ?? 0.6);
     case "sphere":return sphereWire(opts.r ?? 0.45, opts.rings ?? 12, opts.segments ?? 24);
+    case "cylinder": return cylinder(opts.r, opts.h, opts.segments);
+    case "cone":  return cone(opts.r, opts.h, opts.segments, opts.rTop);
+    case "torus": return torus(opts.R, opts.tube, opts.segments, opts.tubeSegments);
+    case "plane": return plane(opts.size, opts.div, opts.height);
     default: throw new Error("Unknown shape: " + kind);
   }
 }

package/trid/render/uvMapping.js

@@ -0,0 +1,225 @@
+/**
+ * Texture mapping: texture coordinates made from a mesh's shape, for
+ * meshes that don't have any (or to replace the ones they have).
+ *
+ * Every mode fits the image to the mesh's bounding box:
+ *
+ * - "planar":   the image is projected straight through the mesh along one axis
+ * - "box":      each face takes the image from the side of the box it faces most
+ * - "sphere":   wrapped around like a world map
+ * - "cylinder": wrapped around the sides like a label; the ends get a planar image
+ *
+ * A mapping is a mode name, or an object with options:
+ *
+ *   mapping: "box"
+ *   mapping: { type: "cylinder", axis: "x" }
+ *
+ * @typedef {"uv"|"planar"|"box"|"sphere"|"cylinder"} MappingType
+ * @typedef {MappingType | { type: MappingType, axis?: "x"|"y"|"z" }} Mapping
+ */
+
+const TAU = Math.PI * 2;
+
+/** Mapping modes accepted by `computeUVs` and `material.mapping`. */
+export const MAPPINGS = ["uv", "planar", "box", "sphere", "cylinder"];
+
+/**
+ * Texture coordinates for a mesh's faces, made from its shape.
+ * The mesh isn't changed. Every face corner gets its own entry in `uvs`.
+ *
+ * @param {{ vertices:{x:number,y:number,z:number}[], faces?:number[][] }} mesh
+ * @param {Mapping} mapping
+ * @returns {{ uvs:{u:number,v:number}[], faceUVs:number[][] }}
+ * @throws {Error} For an unknown mapping
+ */
+export function computeUVs(mesh, mapping) {
+  const { type, axis } = mappingOf(mapping);
+  const faces = mesh.faces ?? [];
+  const uvs = [], faceUVs = [];
+  if (type === "uv") {
+    return { uvs: mesh.uvs ?? [], faceUVs: mesh.faceUVs ?? [] };
+  }
+
+  // Sphere and cylinder wrap around Y; other axes are turned to Y first.
+  // Cyclic swaps are rotations, so the image isn't mirrored.
+  const turn = axis === "x" ? (p) => ({ x: p.z, y: p.x, z: p.y })
+    : axis === "z" ? (p) => ({ x: p.y, y: p.z, z: p.x })
+    : (p) => p;
+  const wraps = type === "sphere" || type === "cylinder";
+  const verts = wraps ? mesh.vertices.map(turn) : mesh.vertices;
+  const box = bounds(verts);
+  const center = { x: (box.min.x + box.max.x) / 2, y: (box.min.y + box.max.y) / 2, z: (box.min.z + box.max.z) / 2 };
+  const size = { x: box.max.x - box.min.x || 1, y: box.max.y - box.min.y || 1, z: box.max.z - box.min.z || 1 };
+
+  // A flat image seen from outside along +side of an axis ("y" with sign 1: from above)
+  const flat = (p, ax, sign) => {
+    const nx = (p.x - box.min.x) / size.x, ny = (p.y - box.min.y) / size.y, nz = (p.z - box.min.z) / size.z;
+    if (ax === "x") return { u: sign > 0 ? nz : 1 - nz, v: ny };
+    if (ax === "y") return { u: nx, v: sign > 0 ? nz : 1 - nz };
+    return { u: sign > 0 ? 1 - nx : nx, v: ny };
+  };
+
+  for (const f of faces) {
+    const p = f.map((i) => verts[i]);
+    let ts;
+    if (type === "planar") {
+      // From the front: along the axis, seen from its negative side
+      const ax = axis ?? "z";
+      ts = p.map((q) => flat(q, ax, -1));
+    } else if (type === "box") {
+      const n = faceNormal(p);
+      const ax = dominant(n);
+      ts = p.map((q) => flat(q, ax, Math.sign(n[ax]) || 1));
+    } else {
+      const n = faceNormal(p);
+      if (type === "cylinder" && Math.abs(n.y) > 0.7) {
+        // An end cap: planar from above or below
+        ts = p.map((q) => flat(q, "y", Math.sign(n.y)));
+      } else {
+        ts = p.map((q) => {
+          const d = { x: q.x - center.x, y: q.y - center.y, z: q.z - center.z };
+          const around = Math.hypot(d.x, d.z);
+          const u = around < 1e-9 ? NaN : (((Math.atan2(d.z, d.x) / TAU) % 1) + 1) % 1;
+          const v = type === "sphere"
+            ? 0.5 + Math.atan2(d.y, around) / Math.PI
+            : (q.y - box.min.y) / size.y;
+          return { u, v };
+        });
+        fixSeam(ts);
+      }
+    }
+    faceUVs.push(ts.map((t) => uvs.push(t) - 1));
+  }
+  return { uvs, faceUVs };
+}
+
+/**
+ * Replaces a mesh's texture coordinates with ones made from its shape,
+ * in place. Handy for OBJ files without any, or before exporting.
+ *
+ * @param {Object} mesh
+ * @param {Mapping} mapping
+ * @returns The same mesh
+ */
+export function mapUVs(mesh, mapping) {
+  const { uvs, faceUVs } = computeUVs(mesh, mapping);
+  mesh.uvs = uvs;
+  mesh.faceUVs = faceUVs;
+  mesh.dirty = true;
+  return mesh;
+}
+
+/** The mapping as `{ type, axis }`, checked. */
+export function mappingOf(mapping) {
+  const m = typeof mapping === "string" ? { type: mapping } : { ...(mapping ?? {}) };
+  m.type ??= "uv";
+  if (!MAPPINGS.includes(m.type)) throw new Error(`Unknown texture mapping: "${m.type}"`);
+  if (m.axis != null && !["x", "y", "z"].includes(m.axis)) throw new Error(`Unknown mapping axis: "${m.axis}"`);
+  return m;
+}
+
+/** A short string naming a mapping, for caches ("" for the mesh's own coordinates). */
+export function mappingKey(mapping) {
+  if (mapping == null) return "";
+  const { type, axis } = mappingOf(mapping);
+  return type === "uv" ? "" : type + (axis ? ":" + axis : "");
+}
+
+const cache = new WeakMap(); // mesh → Map(key → { counts, vertices, faces, result })
+
+/**
+ * Texture coordinates a renderer should use for a mesh: its own, or
+ * computed for `mapping` and cached until the mesh changes.
+ *
+ * @returns {{ uvs:{u:number,v:number}[]|undefined, faceUVs:(number[]|null)[]|undefined }}
+ */
+export function uvsFor(mesh, mapping) {
+  const key = mappingKey(mapping);
+  if (!key) return { uvs: mesh.uvs, faceUVs: mesh.faceUVs };
+  let byKey = cache.get(mesh);
+  if (!byKey) cache.set(mesh, (byKey = new Map()));
+  const counts = `${mesh.vertices.length}/${mesh.faces?.length ?? 0}`;
+  let c = byKey.get(key);
+  if (!c || mesh.dirty || c.counts !== counts || c.vertices !== mesh.vertices || c.faces !== mesh.faces) {
+    c = { counts, vertices: mesh.vertices, faces: mesh.faces, result: computeUVs(mesh, mapping) };
+    byKey.set(key, c);
+  }
+  return c.result;
+}
+
+/**
+ * The 2D transform a material's `textureRepeat`, `textureOffset` and
+ * `textureRotation` describe, as [a, b, c, d, e, f]:
+ * u' = a·u + c·v + e, v' = b·u + d·v + f. Null when it changes nothing.
+ *
+ * Rotation turns the image around its center, then repeat scales it
+ * (2 = the image twice across), then offset moves it.
+ */
+export function uvTransform(mat) {
+  const r = mat.textureRepeat ?? 1, o = mat.textureOffset, a = mat.textureRotation ?? 0;
+  const ru = typeof r === "number" ? r : r.u ?? 1, rv = typeof r === "number" ? r : r.v ?? 1;
+  const ou = o?.u ?? 0, ov = o?.v ?? 0;
+  if (ru === 1 && rv === 1 && !ou && !ov && !a) return null;
+  const c = Math.cos(a), s = Math.sin(a);
+  // Rotate around (0.5, 0.5): R·(t - 0.5) + 0.5, then scale and move
+  return [
+    ru * c, rv * s,
+    -ru * s, rv * c,
+    ru * (0.5 - 0.5 * c + 0.5 * s) + ou,
+    rv * (0.5 - 0.5 * s - 0.5 * c) + ov,
+  ];
+}
+
+/** Applies a `uvTransform` to one texture coordinate. */
+export function applyUVTransform(m, t) {
+  if (!m || !t) return t;
+  return { u: m[0] * t.u + m[2] * t.v + m[4], v: m[1] * t.u + m[3] * t.v + m[5] };
+}
+
+/**
+ * Corners that wrap past u = 1 get 1 added, so a face crossing the
+ * seam doesn't stretch the whole image across itself. Corners on the
+ * axis (u = NaN, like a sphere's poles) take the face's middle u.
+ */
+function fixSeam(ts) {
+  const known = ts.filter((t) => !Number.isNaN(t.u));
+  if (!known.length) {
+    for (const t of ts) t.u = 0.5;
+    return;
+  }
+  const us = known.map((t) => t.u);
+  if (Math.max(...us) - Math.min(...us) > 0.5) {
+    for (const t of known) if (t.u < 0.5) t.u += 1;
+  }
+  const mid = known.reduce((a, t) => a + t.u, 0) / known.length;
+  for (const t of ts) if (Number.isNaN(t.u)) t.u = mid;
+}
+
+/** Outward normal of a clockwise face (not normalized). */
+function faceNormal(p) {
+  let x = 0, y = 0, z = 0;
+  for (let i = 0; i < p.length; i++) {
+    const a = p[i], b = p[(i + 1) % p.length];
+    x += (a.y - b.y) * (a.z + b.z);
+    y += (a.z - b.z) * (a.x + b.x);
+    z += (a.x - b.x) * (a.y + b.y);
+  }
+  return { x, y, z };
+}
+
+/** The axis a vector points along most. */
+function dominant(n) {
+  const ax = Math.abs(n.x), ay = Math.abs(n.y), az = Math.abs(n.z);
+  return ay >= ax && ay >= az ? "y" : ax >= az ? "x" : "z";
+}
+
+function bounds(verts) {
+  const min = { x: Infinity, y: Infinity, z: Infinity }, max = { x: -Infinity, y: -Infinity, z: -Infinity };
+  for (const v of verts) {
+    if (v.x < min.x) min.x = v.x; if (v.x > max.x) max.x = v.x;
+    if (v.y < min.y) min.y = v.y; if (v.y > max.y) max.y = v.y;
+    if (v.z < min.z) min.z = v.z; if (v.z > max.z) max.z = v.z;
+  }
+  if (!verts.length) return { min: { x: 0, y: 0, z: 0 }, max: { x: 0, y: 0, z: 0 } };
+  return { min, max };
+}