trid3d 0.4.0 → 0.6.0

package/trid/modeling/subdivide.js

@@ -0,0 +1,215 @@
+/**
+ * Catmull-Clark subdivision: a rough cage of a few faces becomes a smooth
+ * surface, the way modelers use a subdivision surface modifier.
+ */
+import { newell } from "../render/normals.js";
+import { samePlace, defaultEps, distinctCorners } from "./cleanup.js";
+
+const edgeKey = (a, b) => (a < b ? `${a},${b}` : `${b},${a}`);
+
+/**
+ * One level of Catmull-Clark on points of any size (3D positions or 2D
+ * texture coordinates): every face becomes one quad per corner.
+ *
+ * Sharp edges (in `sharp`, plus open borders and edges shared by 3 faces or
+ * more) stay creased: their new points are midpoints, a vertex on 2 of them
+ * slides only along them, and a vertex on 3 or more stays put (a corner).
+ * Sharp edges stay sharp in the result.
+ *
+ * @param {number[][]} P Points
+ * @param {number[][]} F Faces (indices into P)
+ * @param {Set<string>} sharp Sharp edges as "a,b" keys (a < b)
+ * @param {boolean} smooth false: only split the faces
+ */
+function step(P, F, sharp, smooth) {
+  const dims = P[0]?.length ?? 0;
+  const avg = (pts) => {
+    const out = new Array(dims).fill(0);
+    for (const p of pts) for (let d = 0; d < dims; d++) out[d] += p[d] / pts.length;
+    return out;
+  };
+  const facePts = F.map((f) => avg(f.map((i) => P[i])));
+
+  // Edges, with the faces on each side
+  const edges = new Map();
+  F.forEach((f, n) => f.forEach((a, c) => {
+    const b = f[(c + 1) % f.length];
+    const k = edgeKey(a, b);
+    const e = edges.get(k);
+    if (e) e.faces.push(n);
+    else edges.set(k, { a: Math.min(a, b), b: Math.max(a, b), faces: [n] });
+  }));
+  const isSharp = (k, e) => sharp.has(k) || e.faces.length !== 2;
+
+  // New points: the old ones moved, then one per face, then one per edge
+  const vFaces = P.map(() => []), vEdges = P.map(() => []);
+  F.forEach((f, n) => f.forEach((i) => vFaces[i].push(n)));
+  for (const [k, e] of edges) {
+    vEdges[e.a].push(k);
+    vEdges[e.b].push(k);
+  }
+  const out = P.map((p, i) => {
+    if (!smooth || !vFaces[i].length) return p.slice();
+    const creased = vEdges[i].filter((k) => isSharp(k, edges.get(k)));
+    // A corner: 3 sharp edges or more, or the corner of an open sheet (one face only)
+    if (creased.length > 2 || (creased.length === 2 && vFaces[i].length === 1)) return p.slice();
+    if (creased.length === 2) {
+      const [a, b] = creased.map((k) => { const e = edges.get(k); return P[e.a === i ? e.b : e.a]; });
+      return p.map((x, d) => 0.75 * x + 0.125 * (a[d] + b[d]));
+    }
+    const n = vFaces[i].length;
+    const q = avg(vFaces[i].map((f) => facePts[f]));
+    const r = avg(vEdges[i].map((k) => { const e = edges.get(k); return avg([P[e.a], P[e.b]]); }));
+    return p.map((x, d) => (q[d] + 2 * r[d] + (n - 3) * x) / n);
+  });
+  const faceBase = out.length;
+  out.push(...facePts);
+  const edgeIndex = new Map();
+  for (const [k, e] of edges) {
+    const pt = smooth && !isSharp(k, e) ? avg([P[e.a], P[e.b], facePts[e.faces[0]], facePts[e.faces[1]]]) : avg([P[e.a], P[e.b]]);
+    edgeIndex.set(k, out.push(pt) - 1);
+  }
+
+  // One quad per corner, in the face's own direction
+  const faces = [], parent = [];
+  F.forEach((f, n) => {
+    const k = f.length;
+    for (let c = 0; c < k; c++) {
+      const prev = f[(c + k - 1) % k], next = f[(c + 1) % k];
+      faces.push([f[c], edgeIndex.get(edgeKey(f[c], next)), faceBase + n, edgeIndex.get(edgeKey(prev, f[c]))]);
+      parent.push(n);
+    }
+  });
+
+  // Sharp edges are split in two, both halves sharp
+  const nextSharp = new Set();
+  for (const k of sharp) {
+    const e = edges.get(k);
+    if (!e) continue;
+    const m = edgeIndex.get(k);
+    nextSharp.add(edgeKey(e.a, m));
+    nextSharp.add(edgeKey(m, e.b));
+  }
+  return { P: out, F: faces, sharp: nextSharp, parent };
+}
+
+/**
+ * Smooths a mesh by subdividing it (Catmull-Clark): each level splits every
+ * face into one quad per corner (about 4 times the faces) and rounds the
+ * surface, so a rough cage of a few boxes becomes a smooth organic shape.
+ * Returns a new mesh; the original isn't changed.
+ *
+ * - Creases: edges sharper than `creaseAngle` (degrees), and edges in
+ *   `creases`, stay hard. Open borders stay where they are (smoothed along
+ *   the border only).
+ * - Texture coordinates are smoothed with the surface, keeping their seams
+ *   (`uvs: "linear"` only splits them). Faces without them drop them all.
+ * - Materials: each new face keeps its face's material. The mesh's own
+ *   normals are dropped (the renderers compute new ones).
+ * - Vertices at the same place are treated as one, so an unwelded mesh is
+ *   still smoothed as one surface; the result is welded.
+ *
+ * @example
+ * // A rough cage: a box with a box on top, smoothed twice
+ * const cage = mergeMeshes([makeShape("box", { w: 0.6, h: 0.4, d: 0.4 }), { mesh: makeShape("cube", { size: 0.3 }), pos: { x: 0, y: 0.35, z: 0 } }]);
+ * const body = subdivideMesh(cage, { levels: 2 });
+ *
+ * @param {import("../index.d.ts").Mesh} mesh
+ * @param {{ levels?: number, smooth?: boolean, creaseAngle?: number, creases?: number[][], uvs?: "smooth"|"linear" }} [opts]
+ * @returns {import("../index.d.ts").Mesh}
+ */
+export function subdivideMesh(mesh, { levels = 1, smooth = true, creaseAngle, creases, uvs: uvMode = "smooth" } = {}) {
+  const vs = mesh?.vertices ?? [];
+  const ok = (i) => Number.isInteger(i) && i >= 0 && i < vs.length && Number.isFinite(vs[i].x + vs[i].y + vs[i].z);
+
+  // Vertices at the same place become one point
+  const rep = samePlace(vs, defaultEps(vs));
+  const index = new Map();
+  const P = [];
+  const at = (i) => {
+    const r = rep[i];
+    if (!index.has(r)) index.set(r, P.push([vs[r].x, vs[r].y, vs[r].z]) - 1);
+    return index.get(r);
+  };
+
+  // Faces that can be subdivided (others are dropped), with their texture corners and material
+  const F = [], src = [];
+  (mesh?.faces ?? []).forEach((f, n) => {
+    if (!Array.isArray(f) || !f.every(ok)) return;
+    const keep = distinctCorners(f.map(at));
+    if (keep.length < 3 || new Set(keep.map(([v]) => v)).size !== keep.length) return;
+    F.push(keep.map(([v]) => v));
+    src.push({ n, corners: keep.map(([, c]) => c) });
+  });
+  if (!F.length) return { vertices: [], faces: [] };
+
+  // Sharp edges: given ones (pairs or polylines of vertex indices), and ones sharper than the angle
+  let sharp = new Set();
+  for (const line of creases ?? []) {
+    if (!Array.isArray(line)) continue;
+    for (let i = 0; i + 1 < line.length; i++) {
+      if (!ok(line[i]) || !ok(line[i + 1])) continue;
+      const a = at(line[i]), b = at(line[i + 1]);
+      if (a !== b) sharp.add(edgeKey(a, b));
+    }
+  }
+  if (Number.isFinite(creaseAngle)) {
+    const minDot = Math.cos((creaseAngle * Math.PI) / 180);
+    const normals = F.map((f) => {
+      const n = newell(f.map((i) => ({ x: P[i][0], y: P[i][1], z: P[i][2] })));
+      const l = Math.hypot(n.x, n.y, n.z) || 1;
+      return { x: n.x / l, y: n.y / l, z: n.z / l };
+    });
+    const onEdge = new Map();
+    F.forEach((f, n) => f.forEach((a, c) => {
+      const k = edgeKey(a, f[(c + 1) % f.length]);
+      (onEdge.get(k) ?? onEdge.set(k, []).get(k)).push(n);
+    }));
+    for (const [k, fs] of onEdge) {
+      if (fs.length !== 2) continue;
+      const [p, q] = [normals[fs[0]], normals[fs[1]]];
+      if (p.x * q.x + p.y * q.y + p.z * q.z < minDot - 1e-9) sharp.add(k);
+    }
+  }
+
+  // Texture coordinates: their own surface, joined where corners share a vertex and the same coordinates
+  const hasUV = Array.isArray(mesh.uvs) && Array.isArray(mesh.faceUVs) && src.every(({ n, corners }) => {
+    const c = mesh.faceUVs[n];
+    return Array.isArray(c) && c.length === mesh.faces[n].length && corners.every((k) => mesh.uvs[c[k]] && Number.isFinite(mesh.uvs[c[k]].u + mesh.uvs[c[k]].v));
+  });
+  let UP = null, UF = null;
+  if (hasUV) {
+    UP = [];
+    const uvIndex = new Map();
+    UF = src.map(({ n, corners }, f) => corners.map((k, c) => {
+      const uv = mesh.uvs[mesh.faceUVs[n][k]];
+      const key = `${F[f][c]}/${uv.u.toFixed(9)},${uv.v.toFixed(9)}`;
+      if (!uvIndex.has(key)) uvIndex.set(key, UP.push([uv.u, uv.v]) - 1);
+      return uvIndex.get(key);
+    }));
+  }
+
+  // Subdivide, keeping track of which original face each new face comes from
+  let origin = src.map((_, f) => f);
+  let geo = { P, F, sharp };
+  let tex = hasUV ? { P: UP, F: UF, sharp: new Set() } : null;
+  const count = Math.max(0, Math.min(6, Math.round(levels)));
+  for (let l = 0; l < count; l++) {
+    const g = step(geo.P, geo.F, geo.sharp, smooth);
+    if (tex) tex = step(tex.P, tex.F, tex.sharp, smooth && uvMode !== "linear");
+    origin = g.parent.map((p) => origin[p]);
+    geo = g;
+  }
+
+  const out = {
+    vertices: geo.P.map(([x, y, z]) => ({ x, y, z })),
+    faces: geo.F,
+  };
+  if (tex) {
+    out.uvs = tex.P.map(([u, v]) => ({ u, v }));
+    out.faceUVs = tex.F;
+  }
+  if (mesh.faceMaterials) out.faceMaterials = origin.map((f) => mesh.faceMaterials[src[f].n] ?? 0);
+  if (mesh.materialNames) out.materialNames = [...mesh.materialNames];
+  return out;
+}

package/trid/modeling/sweep.js

@@ -0,0 +1,169 @@
+import { triangulate } from "../render/shapes.js";
+import { vec, add, sub, mul, dot, cross, rotateAround, signedArea2 } from "./vec.js";
+import { across, cleanPath, pathFrames } from "./frames.js";
+
+const EMPTY = () => ({ vertices: [], edges: [], faces: [], uvs: [], faceUVs: [] });
+
+/**
+ * A size along the path: a number, a list of numbers spread evenly from the
+ * start (first) to the end (last), or a function of t (0 at the start, 1 at the end).
+ */
+function sizeAt(opt, t, fallback) {
+  let v = fallback;
+  if (typeof opt === "function") v = opt(t);
+  else if (typeof opt === "number") v = opt;
+  else if (Array.isArray(opt) && opt.length) {
+    const x = t * (opt.length - 1), i = Math.min(opt.length - 2, Math.floor(x));
+    v = opt.length === 1 ? opt[0] : opt[i] + (opt[i + 1] - opt[i]) * (x - i);
+  }
+  return Number.isFinite(v) ? v : fallback;
+}
+
+/** A circle of `n` points of radius 1, counter-clockwise, starting at the bottom. */
+function circle(n) {
+  return Array.from({ length: n }, (_, j) => {
+    const a = -Math.PI / 2 + (j / n) * Math.PI * 2;
+    return { x: Math.cos(a), y: Math.sin(a) };
+  });
+}
+
+/**
+ * Moves a cross-section along a 3D path: tails, horns, tentacles, handles,
+ * pipes, cables, rails, picture frames. The section is a 2D outline: its x
+ * goes to the path's side and its y to the path's "up". By default the
+ * section is carried along the path without spinning (so it never flips at
+ * bends); with `up`, its y stays pointed that way (roads, rails, frames).
+ *
+ * Without `profile`, the section is a circle of `radius` (a tube). An end
+ * whose size is 0 closes into a point (a horn, a tail tip).
+ *
+ * Faces are clockwise from outside, like the built-in shapes. Texture
+ * coordinates: u goes around the section (by length), v along the path (by
+ * length). Caps map the section's box.
+ *
+ * @example
+ * // A tail: thick at the base, a point at the tip
+ * const tail = sweep(spline(controlPoints, { count: 40 }), { radius: (t) => 0.08 * (1 - t) });
+ *
+ * @param {{x:number, y:number, z:number}[]} path Points the section follows (use `spline` for a smooth path)
+ * @param {object} [opts]
+ * @returns {import("../index.d.ts").Mesh}
+ */
+export function sweep(path, opts = {}) {
+  const {
+    profile, radius = 0.1, scale = 1, segments = 16, twist = 0,
+    closed = false, caps = true, up = null, miter = true, profileClosed = true,
+  } = opts;
+
+  // The path, without bad points and repeats
+  const { pts, loop } = cleanPath(path, closed);
+
+  // The section: counter-clockwise when closed, so the outside is on its right
+  const ring = profile ? profileClosed !== false : true;
+  const sec = [];
+  for (const q of profile ?? circle(Math.max(3, Math.floor(segments)))) {
+    if (!q || !Number.isFinite(q.x) || !Number.isFinite(q.y)) continue;
+    const last = sec[sec.length - 1];
+    if (!last || Math.hypot(q.x - last.x, q.y - last.y) > 1e-12) sec.push({ x: q.x, y: q.y });
+  }
+  if (ring && sec.length > 2 && Math.hypot(sec[0].x - sec[sec.length - 1].x, sec[0].y - sec[sec.length - 1].y) <= 1e-12) sec.pop();
+  if (ring && signedArea2(sec) < 0) sec.reverse();
+  const m = sec.length;
+  const n = pts.length;
+  if (n < 2 || m < (ring ? 3 : 2)) return EMPTY();
+
+  // Frames along the path; t (0 to 1) for sizes and twist, by length
+  const { dirs, tangents, ups, along, total } = pathFrames(pts, loop, up);
+  const sides = loop ? n : n - 1;
+  const tOf = (i) => along[i] / total;
+
+  // At a corner, the section is stretched toward the bend so the tube keeps its thickness (miter)
+  const miters = tangents.map((t, i) => {
+    const din = loop ? dirs[(i + n - 1) % n] : dirs[i - 1];
+    const dout = dirs[i];
+    if (!miter || !din || !dout) return null;
+    const k = Math.min(3, 1 / Math.max(dot(t, dout), 1 / 3));
+    const bend = across(sub(dout, din), t);
+    return k > 1 + 1e-9 && bend ? { bend, k } : null;
+  });
+
+  // On a loop, the twist is rounded to whole turns so the ends still meet
+  const turn = loop ? Math.round((twist || 0) / (2 * Math.PI)) * 2 * Math.PI : twist || 0;
+
+  // Rings of vertices; a ring of size 0 is a single point
+  const vertices = [];
+  const rings = pts.map((p, i) => {
+    const t = tOf(i);
+    const k = sizeAt(scale, t, 1) * (profile ? 1 : sizeAt(radius, t, 0.1));
+    if (Math.abs(k) < 1e-9) {
+      const tip = vertices.push(vec(p.x, p.y, p.z)) - 1;
+      return new Array(m).fill(tip);
+    }
+    const tan = tangents[i];
+    const nrm = rotateAround(ups[i], tan, turn * t);
+    const side = cross(nrm, tan);
+    const mt = miters[i];
+    return sec.map((q) => {
+      let o = add(mul(side, q.x * k), mul(nrm, q.y * k));
+      if (mt) o = add(o, mul(mt.bend, (mt.k - 1) * dot(o, mt.bend)));
+      return vertices.push(add(p, o)) - 1;
+    });
+  });
+  const isTip = (r) => r[0] === r[m - 1] && m > 1 && r[0] === r[1];
+
+  // Texture grid: an extra column for the section's seam, an extra row for the path's
+  const secLen = [0];
+  const secSides = ring ? m : m - 1;
+  for (let j = 0; j < secSides; j++) secLen.push(secLen[j] + Math.hypot(sec[(j + 1) % m].x - sec[j].x, sec[(j + 1) % m].y - sec[j].y));
+  const secTotal = secLen[secSides] || 1;
+  const cols = secSides + 1, rows = sides + 1;
+  const uvs = [];
+  for (let i = 0; i < rows; i++) for (let j = 0; j < cols; j++) uvs.push({ u: secLen[j] / secTotal, v: along[i] / total });
+  const uvAt = (i, j) => i * cols + j;
+
+  // Sides: one quad per section side and path step (a triangle next to a point)
+  const faces = [], faceUVs = [];
+  for (let i = 0; i < sides; i++) {
+    const a = rings[i], b = rings[(i + 1) % n];
+    for (let j = 0; j < secSides; j++) {
+      const j1 = (j + 1) % m;
+      const corners = [[a[j], uvAt(i, j)], [a[j1], uvAt(i, j + 1)], [b[j1], uvAt(i + 1, j + 1)], [b[j], uvAt(i + 1, j)]];
+      const keep = corners.filter(([v], c) => v !== corners[(c + 3) % 4][0]);
+      if (keep.length < 3) continue;
+      faces.push(keep.map(([v]) => v));
+      faceUVs.push(keep.map(([, u]) => u));
+    }
+  }
+
+  // Caps: the start faces back along the path, the end forward
+  if (!loop && ring && caps !== false) {
+    const xs = sec.map((q) => q.x), ys = sec.map((q) => q.y);
+    const x0 = Math.min(...xs), y0 = Math.min(...ys);
+    const w = Math.max(...xs) - x0 || 1, h = Math.max(...ys) - y0 || 1;
+    const first = uvs.length;
+    for (const q of sec) uvs.push({ u: (q.x - x0) / w, v: (q.y - y0) / h });
+    const tris = triangulate(sec);
+    for (const [r, flip] of [[rings[0], true], [rings[n - 1], false]]) {
+      if (isTip(r)) continue;
+      for (const tri of tris) {
+        const t = flip ? [tri[2], tri[1], tri[0]] : tri;
+        faces.push(t.map((j) => r[j]));
+        faceUVs.push(t.map((j) => first + j));
+      }
+    }
+  }
+
+  // Edges: each section, and a line along the path from each section point
+  const edges = [];
+  for (const r of rings) {
+    if (isTip(r)) continue;
+    if (ring) edges.push(r.slice());
+    else for (let j = 0; j < m - 1; j++) edges.push([r[j], r[j + 1]]);
+  }
+  for (let j = 0; j < m; j++) {
+    if (loop) edges.push(rings.map((r) => r[j]));
+    else for (let i = 0; i < n - 1; i++) if (rings[i][j] !== rings[i + 1][j]) edges.push([rings[i][j], rings[i + 1][j]]);
+  }
+
+  return { vertices, edges, faces, uvs, faceUVs };
+}

package/trid/modeling/vec.js

@@ -0,0 +1,35 @@
+/** Small vector helpers shared by the modeling tools (not exported from the library). */
+
+export const vec = (x = 0, y = 0, z = 0) => ({ x, y, z });
+export const add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z });
+export const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z });
+export const mul = (a, k) => ({ x: a.x * k, y: a.y * k, z: a.z * k });
+export const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+export const cross = (a, b) => ({ 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 });
+export const len = (a) => Math.hypot(a.x, a.y, a.z);
+export const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+
+/** `a` at length 1, or `fallback` when it has no length. */
+export function norm(a, fallback = null) {
+  const l = len(a);
+  return l > 1e-12 ? mul(a, 1 / l) : fallback;
+}
+
+/** `a` turned by `angle` radians around the unit axis `k` (Rodrigues). */
+export function rotateAround(a, k, angle) {
+  const c = Math.cos(angle), s = Math.sin(angle);
+  return add(add(mul(a, c), mul(cross(k, a), s)), mul(k, dot(k, a) * (1 - c)));
+}
+
+/** A valid 3D point: three finite numbers. */
+export const isPoint = (p) => !!p && Number.isFinite(p.x) && Number.isFinite(p.y) && Number.isFinite(p.z);
+
+/** Twice the signed area of a 2D outline: > 0 when counter-clockwise (x right, y up). */
+export function signedArea2(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;
+}

package/trid/render/canvasRenderer.js

@@ -125,7 +125,7 @@ export class CanvasRenderer {
     // For effects
     const camPos = { x: camera.x ?? 0, y: camera.y ?? 0, z: camera.z ?? 0 };
     const time = (performance.now() - this._start) / 1000;
-    const background = this._rgba(ctx, scene.background);
+    const background = this._rgba(ctx, scene.background ?? "transparent");
 
     for (const obj of drawn) {
       const mats = materialsOf(obj);

package/trid/render/draw.js

@@ -2,19 +2,29 @@ import { localToWorld, worldToCamera, cameraToScreen, clipNear, DEFAULT_NEAR } f
 import { transformPoint } from "../math/matrix.js";
 
 /**
- * Clears the entire canvas with a solid background color.
+ * Clears the entire canvas, then paints it with a background color.
  * This should usually be called once per frame before drawing.
  *
+ * A see-through color (`"transparent"`, or `rgba(...)` with an alpha below 1),
+ * or no color (`null`), lets the page behind the canvas show through.
+ *
  * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
  * @param {number} w - Canvas width
  * @param {number} h - Canvas height
- * @param {string} color - Background color (CSS color)
+ * @param {string|null} [color] - Background color (CSS color); none: left see-through
  */
 export function clear(ctx, w, h, color) {
+  ctx.clearRect(0, 0, w, h);
+  if (!isVisible(color)) return;
   ctx.fillStyle = color;
   ctx.fillRect(0, 0, w, h);
 }
 
+/** Whether a background color paints anything (not null, empty or "transparent"). */
+function isVisible(color) {
+  return color != null && color !== "" && String(color).trim().toLowerCase() !== "transparent";
+}
+
 /**
  * Draws a square point centered at a given 2D position.
  * Useful for debugging or drawing vertices.

package/trid/render/post.js

@@ -91,7 +91,7 @@ export function runCanvasPost(scene, list, start) {
     canvas,
     rgba: (v) => (typeof v === "string" ? parseColor(ctx, v).map((x, i) => (i < 3 ? x / 255 : x)) : v),
   };
-  frame.background = frame.rgba(scene.background ?? "#000000");
+  frame.background = frame.rgba(scene.background ?? "transparent");
   for (const e of effects) {
     ctx.save();
     try {