@es3d/es3d 0.0.0-stage → 1.0.0

package/src/geometry/revolve.js

@@ -0,0 +1,136 @@
+// Revolution (lathe) of a 2D profile around the Y axis.
+//
+// The profile lives in the XY plane: x is the distance from the axis, y the
+// height. Open profiles are oriented automatically so their normals face away
+// from the axis region they enclose; closed profiles become solids of
+// revolution and get end caps when the angle is below 360 degrees.
+
+import { MeshBuilder } from './mesh.js';
+import { signedArea, reverseContour } from '../path/path-flatten.js';
+import { contourFrames } from './contour.js';
+import { triangulate } from '../path/triangulate.js';
+
+/** Orient an open profile so that (profile + axis) forms a counter-clockwise loop. */
+function orientOpen(c) {
+  const p = c.points;
+  const n = p.length / 2;
+  const loop = new Float64Array(p.length + 4);
+  loop.set(p);
+  loop[p.length] = 0;
+  loop[p.length + 1] = p[(n - 1) * 2 + 1];
+  loop[p.length + 2] = 0;
+  loop[p.length + 3] = p[1];
+  return signedArea(loop) >= 0 ? c : reverseContour(c);
+}
+
+/**
+ * @param {object[]} contours flattened 2D contours
+ * @param {{angle:number, segments:number}} o angle in degrees
+ * @returns {{mesh: import('./mesh.js').Mesh, doubleSided: boolean}}
+ */
+export function revolveMesh(contours, o, report) {
+  const full = o.angle >= 360 - 1e-9;
+  const A = (Math.min(o.angle, 360) * Math.PI) / 180;
+  const S = Math.max(2, o.segments);
+  let open = false;
+
+  // profiles first, so the mesh can be allocated once at its final size
+  const profiles = [];
+  for (const raw of contours) {
+    const pts0 = raw.points;
+    for (let i = 0; i < pts0.length; i += 2) {
+      if (pts0[i] < -1e-9) {
+        if (report) report('error', 'E_REVOLVE_AXIS', `The revolve profile crosses the axis: point (${pts0[i]}, ${pts0[i + 1]}) has x < 0. Profiles must stay at x ≥ 0.`);
+        break;
+      }
+    }
+    const closed = raw.closed;
+    if (!closed) open = true;
+    const c = closed ? (signedArea(raw.points) > 0 ? raw : reverseContour(raw)) : orientOpen(raw);
+    const pts = c.points;
+    const n = pts.length / 2;
+    if (n < 2) continue;
+    const f = contourFrames(pts, c.smooth, closed);
+    const total = f.length || 1;
+    // profile entries (x, y, nx, ny, v): per vertex, entryIn (end of the
+    // previous edge) and entryOut (start of the next edge)
+    const entries = [];
+    const entryIn = new Int32Array(n).fill(-1);
+    const entryOut = new Int32Array(n).fill(-1);
+    const add = (x, y, nx, ny, v) => entries.push(x, y, nx, ny, v) / 5 - 1;
+    for (let i = 0; i < n; i++) {
+      const pe = closed ? (i - 1 + n) % n : i - 1;
+      const ne = closed || i < n - 1 ? i : -1;
+      const x = Math.max(0, pts[i * 2]), y = pts[i * 2 + 1];
+      const v = f.arc[i] / total;
+      if (pe >= 0 && ne >= 0 && f.corner[i]) {
+        entryIn[i] = add(x, y, f.edgeN[pe * 2], f.edgeN[pe * 2 + 1], v);
+        entryOut[i] = add(x, y, f.edgeN[ne * 2], f.edgeN[ne * 2 + 1], v);
+      } else {
+        const e = ne >= 0 ? ne : pe;
+        const k = f.corner[i] ? add(x, y, f.edgeN[e * 2], f.edgeN[e * 2 + 1], v) : add(x, y, f.vertN[i * 2], f.vertN[i * 2 + 1], v);
+        entryIn[i] = k;
+        entryOut[i] = k;
+      }
+    }
+    const tri = !full && closed ? triangulate(pts) : null;
+    profiles.push({ closed, pts, n, entries, entryIn, entryOut, tri });
+  }
+  let vertices = 0, indices = 0;
+  for (const p of profiles) {
+    vertices += (p.entries.length / 5) * (S + 1);
+    indices += (p.closed ? p.n : p.n - 1) * S * 6;
+    if (p.tri) {
+      vertices += 2 * p.n;
+      indices += 2 * p.tri.length;
+    }
+  }
+  const b = new MeshBuilder('triangles', vertices, indices);
+  // the angle of each column is the same for every profile entry
+  const cosCol = new Float64Array(S + 1), sinCol = new Float64Array(S + 1);
+  for (let j = 0; j <= S; j++) {
+    const th = (A * j) / S;
+    cosCol[j] = Math.cos(th);
+    sinCol[j] = Math.sin(th);
+  }
+
+  for (const { closed, pts, n, entries, entryIn, entryOut, tri } of profiles) {
+    // closing seam of closed contours: v wraps to 1 at the last edge end
+    const base = b.vertexCount;
+    const cols = S + 1;
+    for (let k = 0; k < entries.length; k += 5) {
+      const x = entries[k], y = entries[k + 1], nx = entries[k + 2], ny = entries[k + 3], v = entries[k + 4];
+      for (let j = 0; j <= S; j++) {
+        const ct = cosCol[j], st = sinCol[j];
+        b.vertex(x * ct, y, -x * st, nx * ct, ny, -nx * st, j / S, v);
+      }
+    }
+    const edges = closed ? n : n - 1;
+    for (let e = 0; e < edges; e++) {
+      const s0 = entryOut[e];
+      const t0 = entryIn[(e + 1) % n];
+      for (let j = 0; j < S; j++) {
+        const a = base + s0 * cols + j;
+        const d = base + t0 * cols + j;
+        b.quad(a, a + 1, d + 1, d);
+      }
+    }
+    // caps for partial revolutions of closed profiles
+    if (tri) {
+      for (const [th, sign] of [[0, 1], [A, -1]]) {
+        const ct = Math.cos(th), st = Math.sin(th);
+        // start cap faces +Z (against the sweep); the end cap faces the sweep direction (-sin A, 0, -cos A)
+        const cb = b.vertexCount;
+        for (let i = 0; i < n; i++) {
+          const x = Math.max(0, pts[i * 2]), y = pts[i * 2 + 1];
+          b.vertex(x * ct, y, -x * st, sign > 0 ? 0 : -st, 0, sign > 0 ? 1 : -ct, x, y);
+        }
+        for (let i = 0; i < tri.length; i += 3) {
+          if (sign > 0) b.tri(cb + tri[i], cb + tri[i + 1], cb + tri[i + 2]);
+          else b.tri(cb + tri[i], cb + tri[i + 2], cb + tri[i + 1]);
+        }
+      }
+    }
+  }
+  return { mesh: b.build(), doubleSided: open };
+}

package/src/geometry/sweep.js

@@ -0,0 +1,441 @@
+// Sweeping a 2D profile along a 3D spine.
+//
+// Frames along the spine are rotation minimising (double reflection method,
+// Wang et al. 2008), so tubes do not twist unexpectedly; closed spines get the
+// residual twist distributed evenly so the seam matches. Sharp spine corners
+// are mitered (the profile is stretched along the bend so the tube keeps its
+// thickness). Optional twist and taper are applied along the arc length.
+
+import { Mesh, MeshBuilder } from './mesh.js';
+import { triangulateRegions, reportTriangulation } from './extrude.js';
+import { contourFrames } from './contour.js';
+import { flattenPath } from '../path/path-flatten.js';
+import { perpendicular } from '../math/vec3.js';
+import { sweepWasm, catmullRomWasm } from '../wasm/kernels.js';
+
+const TAU = Math.PI * 2;
+
+/** Helix around +Y starting at (r, 0, 0). */
+export function helixPoints(radius, pitch, turns, segmentsPerTurn) {
+  const n = Math.max(2, Math.ceil(turns * segmentsPerTurn));
+  const pts = new Float64Array((n + 1) * 3);
+  const total = turns * TAU;
+  for (let i = 0; i <= n; i++) {
+    const t = (i / n) * total;
+    pts[i * 3] = radius * Math.cos(t);
+    pts[i * 3 + 1] = (pitch * t) / TAU;
+    pts[i * 3 + 2] = -radius * Math.sin(t);
+  }
+  return pts;
+}
+
+/** Centripetal Catmull-Rom spline through 3D points. */
+export function catmullRom(points, closed, subdivisions) {
+  const n = points.length / 3;
+  if (n < 2) return Float64Array.from(points);
+  const fast = catmullRomWasm(points, closed, subdivisions);
+  if (fast) return fast;
+  const P = (i) => {
+    if (closed) {
+      const k = ((i % n) + n) % n;
+      return [points[k * 3], points[k * 3 + 1], points[k * 3 + 2]];
+    }
+    if (i < 0) {
+      const a = P(0), b = P(1);
+      return [2 * a[0] - b[0], 2 * a[1] - b[1], 2 * a[2] - b[2]];
+    }
+    if (i > n - 1) {
+      const a = P(n - 1), b = P(n - 2);
+      return [2 * a[0] - b[0], 2 * a[1] - b[1], 2 * a[2] - b[2]];
+    }
+    return [points[i * 3], points[i * 3 + 1], points[i * 3 + 2]];
+  };
+  const out = [];
+  const segs = closed ? n : n - 1;
+  const knot = (a, b) => Math.max(Math.sqrt(Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2])), 1e-6);
+  for (let s = 0; s < segs; s++) {
+    const p0 = P(s - 1), p1 = P(s), p2 = P(s + 1), p3 = P(s + 2);
+    const t0 = 0;
+    const t1 = t0 + knot(p0, p1);
+    const t2 = t1 + knot(p1, p2);
+    const t3 = t2 + knot(p2, p3);
+    for (let k = 0; k < subdivisions; k++) {
+      const u = t1 + ((t2 - t1) * k) / subdivisions;
+      const lerp = (a, b, ta, tb) => {
+        const w = (u - ta) / (tb - ta);
+        return [a[0] + (b[0] - a[0]) * w, a[1] + (b[1] - a[1]) * w, a[2] + (b[2] - a[2]) * w];
+      };
+      const A1 = lerp(p0, p1, t0, t1);
+      const A2 = lerp(p1, p2, t1, t2);
+      const A3 = lerp(p2, p3, t2, t3);
+      const B1 = lerp(A1, A2, t0, t2);
+      const B2 = lerp(A2, A3, t1, t3);
+      const C = lerp(B1, B2, t1, t2);
+      out.push(C[0], C[1], C[2]);
+    }
+  }
+  if (!closed) {
+    const last = P(n - 1);
+    out.push(last[0], last[1], last[2]);
+  }
+  return Float64Array.from(out);
+}
+
+/** Spine polylines from a parsed `along` value. Returns [{points, closed}]. */
+export function spinePolylines(spine, { tolerance, segmentsPerTurn, smooth, subdivisions }) {
+  if (spine.kind === 'helix') {
+    return [{ points: helixPoints(spine.radius, spine.pitch, spine.turns, spine.segmentsPerTurn || segmentsPerTurn), closed: false }];
+  }
+  if (spine.kind === 'path') {
+    return flattenPath(spine.segments, { dim: 3, tolerance }).map((c) => ({ points: c.points, closed: c.closed }));
+  }
+  let pts = spine.points;
+  const n = pts.length / 3;
+  let closed = false;
+  if (n > 2 && Math.hypot(pts[0] - pts[(n - 1) * 3], pts[1] - pts[(n - 1) * 3 + 1], pts[2] - pts[(n - 1) * 3 + 2]) < 1e-12) {
+    closed = true;
+    pts = pts.slice(0, (n - 1) * 3);
+  }
+  if (smooth) pts = catmullRom(pts, closed, subdivisions);
+  return [{ points: pts, closed }];
+}
+
+function dedupe(points, closed) {
+  const out = [];
+  const n = points.length / 3;
+  for (let i = 0; i < n; i++) {
+    const x = points[i * 3], y = points[i * 3 + 1], z = points[i * 3 + 2];
+    const k = out.length;
+    if (k && Math.hypot(out[k - 3] - x, out[k - 2] - y, out[k - 1] - z) < 1e-9) continue;
+    out.push(x, y, z);
+  }
+  if (closed && out.length > 6) {
+    const k = out.length;
+    if (Math.hypot(out[0] - out[k - 3], out[1] - out[k - 2], out[2] - out[k - 1]) < 1e-9) out.length -= 3;
+  }
+  return out;
+}
+
+/**
+ * Stations along a spine: position, tangent T, normal N, binormal B, arc length,
+ * and miter data (bend axis K and stretch factor) at each point. Vectors are
+ * flat arrays, x y z per station.
+ */
+export function spineFrames(points, closed) {
+  const p = dedupe(points, closed);
+  const n = p.length / 3;
+  if (n < 2) return null;
+  const count = closed ? n + 1 : n;
+  const pos = new Float64Array(count * 3);
+  for (let i = 0; i < count; i++) {
+    const k = (i % n) * 3;
+    pos[i * 3] = p[k];
+    pos[i * 3 + 1] = p[k + 1];
+    pos[i * 3 + 2] = p[k + 2];
+  }
+  const nd = count - 1;
+  const dirs = new Float64Array(nd * 3);
+  for (let i = 0; i < nd; i++) normalizeInto(dirs, i * 3, pos[i * 3 + 3] - pos[i * 3], pos[i * 3 + 4] - pos[i * 3 + 1], pos[i * 3 + 5] - pos[i * 3 + 2]);
+  const T = new Float64Array(count * 3);
+  const K = new Float64Array(count * 3);
+  const stretch = new Float64Array(count);
+  for (let i = 0; i < count; i++) {
+    const d0 = 3 * (closed ? (i - 1 + nd) % nd : Math.max(0, i - 1));
+    const d1 = 3 * (closed ? i % nd : Math.min(nd - 1, i));
+    const o = i * 3;
+    normalizeInto(T, o, dirs[d0] + dirs[d1], dirs[d0 + 1] + dirs[d1 + 1], dirs[d0 + 2] + dirs[d1 + 2]);
+    if (T[o] === 0 && T[o + 1] === 0 && T[o + 2] === 0) {
+      T[o] = dirs[d1];
+      T[o + 1] = dirs[d1 + 1];
+      T[o + 2] = dirs[d1 + 2];
+    }
+    const c = Math.max(T[o] * dirs[d1] + T[o + 1] * dirs[d1 + 1] + T[o + 2] * dirs[d1 + 2], 0.25);
+    normalizeInto(K, o, dirs[d1] - dirs[d0], dirs[d1 + 1] - dirs[d0 + 1], dirs[d1 + 2] - dirs[d0 + 2]);
+    stretch[i] = 1 / c;
+  }
+  // initial normal: the world up direction projected onto the plane of T0
+  const N = new Float64Array(count * 3);
+  const tx = T[0], ty = T[1], tz = T[2];
+  const ux = Math.abs(ty) < 0.99 ? 0 : 1, uy = Math.abs(ty) < 0.99 ? 1 : 0, uz = 0;
+  const wx = ty * uz - tz * uy, wy = tz * ux - tx * uz, wz = tx * uy - ty * ux;
+  normalizeInto(N, 0, wy * tz - wz * ty, wz * tx - wx * tz, wx * ty - wy * tx);
+  if (N[0] === 0 && N[1] === 0 && N[2] === 0) N.set(perpendicular([tx, ty, tz]));
+  // rotation minimising frames: double reflection
+  for (let i = 0; i < count - 1; i++) {
+    const o = i * 3;
+    const v1x = pos[o + 3] - pos[o], v1y = pos[o + 4] - pos[o + 1], v1z = pos[o + 5] - pos[o + 2];
+    const c1 = v1x * v1x + v1y * v1y + v1z * v1z;
+    let rx = N[o], ry = N[o + 1], rz = N[o + 2];
+    let lx = T[o], ly = T[o + 1], lz = T[o + 2];
+    if (c1 > 0) {
+      const sr = (2 / c1) * (v1x * rx + v1y * ry + v1z * rz);
+      rx = rx - v1x * sr;
+      ry = ry - v1y * sr;
+      rz = rz - v1z * sr;
+      const st = (2 / c1) * (v1x * lx + v1y * ly + v1z * lz);
+      lx = lx - v1x * st;
+      ly = ly - v1y * st;
+      lz = lz - v1z * st;
+    }
+    const v2x = T[o + 3] - lx, v2y = T[o + 4] - ly, v2z = T[o + 5] - lz;
+    const c2 = v2x * v2x + v2y * v2y + v2z * v2z;
+    if (c2 > 1e-20) {
+      const s2 = (2 / c2) * (v2x * rx + v2y * ry + v2z * rz);
+      rx = rx - v2x * s2;
+      ry = ry - v2y * s2;
+      rz = rz - v2z * s2;
+    }
+    normalizeInto(N, o + 3, rx, ry, rz);
+  }
+  if (closed) {
+    // distribute the residual rotation so the last frame matches the first
+    const o = (count - 1) * 3;
+    const ax = N[o + 1] * N[2] - N[o + 2] * N[1], ay = N[o + 2] * N[0] - N[o] * N[2], az = N[o] * N[1] - N[o + 1] * N[0];
+    const ang = Math.atan2(ax * T[0] + ay * T[1] + az * T[2], N[o] * N[0] + N[o + 1] * N[1] + N[o + 2] * N[2]);
+    for (let i = 0; i < count; i++) {
+      // Rodrigues rotation of N[i] around T[i]
+      const angle = (ang * i) / (count - 1);
+      const c = Math.cos(angle), s = Math.sin(angle);
+      const k = i * 3;
+      const vx = N[k], vy = N[k + 1], vz = N[k + 2];
+      const kx = T[k], ky = T[k + 1], kz = T[k + 2];
+      const cx = ky * vz - kz * vy, cy = kz * vx - kx * vz, cz = kx * vy - ky * vx;
+      const kd = (kx * vx + ky * vy + kz * vz) * (1 - c);
+      N[k] = vx * c + cx * s + kx * kd;
+      N[k + 1] = vy * c + cy * s + ky * kd;
+      N[k + 2] = vz * c + cz * s + kz * kd;
+    }
+    N[o] = N[0];
+    N[o + 1] = N[1];
+    N[o + 2] = N[2];
+  }
+  const B = new Float64Array(count * 3);
+  for (let i = 0; i < count * 3; i += 3) {
+    B[i] = T[i + 1] * N[i + 2] - T[i + 2] * N[i + 1];
+    B[i + 1] = T[i + 2] * N[i] - T[i] * N[i + 2];
+    B[i + 2] = T[i] * N[i + 1] - T[i + 1] * N[i];
+  }
+  const arc = new Float64Array(count);
+  for (let i = 1; i < count; i++) arc[i] = arc[i - 1] + Math.hypot(pos[i * 3] - pos[i * 3 - 3], pos[i * 3 + 1] - pos[i * 3 - 2], pos[i * 3 + 2] - pos[i * 3 - 1]);
+  return { count, pos, T, N, B, K, stretch, arc, length: arc[count - 1], closed };
+}
+
+/** Unit vector of (x, y, z) into out[o..o+2] (zero when degenerate), as vec3 normalize. */
+function normalizeInto(out, o, x, y, z) {
+  const l = Math.hypot(x, y, z);
+  if (l > 1e-20) {
+    out[o] = x / l;
+    out[o + 1] = y / l;
+    out[o + 2] = z / l;
+  } else out[o] = out[o + 1] = out[o + 2] = 0;
+}
+
+/** Position of profile point (px, py) at station i, written to out[o..o+2]. */
+function placeAt(out, o, i, px, py, ks, cas, sas, Nf, Bf, Pf, Kf, stretch) {
+  const k = ks[i], ca = cas[i], sa = sas[i];
+  const x = (px * ca - py * sa) * k;
+  const y = (px * sa + py * ca) * k;
+  const i3 = i * 3;
+  let ox = Nf[i3] * x + Bf[i3] * y, oy = Nf[i3 + 1] * x + Bf[i3 + 1] * y, oz = Nf[i3 + 2] * x + Bf[i3 + 2] * y;
+  // miter stretch along the bend axis
+  const st = stretch[i];
+  if (st > 1.0001) {
+    const d = (ox * Kf[i3] + oy * Kf[i3 + 1] + oz * Kf[i3 + 2]) * (st - 1);
+    ox = ox + Kf[i3] * d;
+    oy = oy + Kf[i3 + 1] * d;
+    oz = oz + Kf[i3 + 2] * d;
+  }
+  out[o] = Pf[i3] + ox;
+  out[o + 1] = Pf[i3 + 1] + oy;
+  out[o + 2] = Pf[i3 + 2] + oz;
+}
+
+/** Normal at station i of profile point (px, py) whose 2D normal is (nx, ny), into out[0..2]. */
+function stationNormal(out, i, px, py, nx, ny, cas, sas, Nf, Bf, Tf, dScale) {
+  const ca = cas[i], sa = sas[i];
+  const qx = nx * ca - ny * sa;
+  const qy = nx * sa + ny * ca;
+  const i3 = i * 3;
+  let n0 = Nf[i3] * qx + Bf[i3] * qy, n1 = Nf[i3 + 1] * qx + Bf[i3 + 1] * qy, n2 = Nf[i3 + 2] * qx + Bf[i3 + 2] * qy;
+  if (dScale !== 0) {
+    // taper tilts the surface along the spine
+    const slope = dScale * (px * nx + py * ny);
+    const a0 = n0 - Tf[i3] * slope, a1 = n1 - Tf[i3 + 1] * slope, a2 = n2 - Tf[i3 + 2] * slope;
+    const l = Math.hypot(a0, a1, a2);
+    if (l > 1e-20) {
+      n0 = a0 / l;
+      n1 = a1 / l;
+      n2 = a2 / l;
+    } else n0 = n1 = n2 = 0;
+  }
+  out[0] = n0;
+  out[1] = n1;
+  out[2] = n2;
+}
+
+/** Positions of every profile point at every station (station-major), into ring. */
+function sweepRing(ring, pts, n, count, ks, cas, sas, Nf, Bf, Pf, Kf, stretch) {
+  for (let s = 0; s < count; s++) {
+    for (let j = 0; j < n; j++) placeAt(ring, (s * n + j) * 3, s, pts[j * 2], pts[j * 2 + 1], ks, cas, sas, Nf, Bf, Pf, Kf, stretch);
+  }
+}
+
+/**
+ * Wall of one contour along one spine: for each profile edge, a strip of
+ * quads from the first station to the last. The hot loop of a sweep, in a
+ * function of its own so the engine optimizes it early and on its own.
+ */
+function sweepWalls(b, ring, f, pts, count, arc, cas, sas, Nf, Bf, Tf, dScale, out) {
+  const n = f.n;
+  const perim = f.length || 1;
+  for (let e = 0; e < n; e++) {
+    const i0 = e, i1 = (e + 1) % n;
+    const c0 = f.corner[i0], c1 = f.corner[i1];
+    const n0x = c0 ? f.edgeN[e * 2] : f.vertN[i0 * 2], n0y = c0 ? f.edgeN[e * 2 + 1] : f.vertN[i0 * 2 + 1];
+    const n1x = c1 ? f.edgeN[e * 2] : f.vertN[i1 * 2], n1y = c1 ? f.edgeN[e * 2 + 1] : f.vertN[i1 * 2 + 1];
+    const u0 = f.arc[e] / perim, u1 = f.arc[e + 1] / perim;
+    const p0x = pts[i0 * 2], p0y = pts[i0 * 2 + 1], p1x = pts[i1 * 2], p1y = pts[i1 * 2 + 1];
+    let prevA = -1, prevB = -1;
+    for (let s = 0; s < count; s++) {
+      const v = arc[s] / perim;
+      stationNormal(out, s, p0x, p0y, n0x, n0y, cas, sas, Nf, Bf, Tf, dScale);
+      let o = (s * n + i0) * 3;
+      const a = b.vertex(ring[o], ring[o + 1], ring[o + 2], out[0], out[1], out[2], u0, v);
+      stationNormal(out, s, p1x, p1y, n1x, n1y, cas, sas, Nf, Bf, Tf, dScale);
+      o = (s * n + i1) * 3;
+      const c2 = b.vertex(ring[o], ring[o + 1], ring[o + 2], out[0], out[1], out[2], u1, v);
+      if (prevA >= 0) b.quad(prevA, prevB, c2, a);
+      prevA = a;
+      prevB = c2;
+    }
+  }
+}
+
+/**
+ * Sweep a profile along spines.
+ * @param {object} profile {kind:'circle', radius, segments} | {kind:'shape', regions, walls}
+ * @param {{points:Float64Array, closed:boolean}[]} spines
+ * @param {{twist?:number, taper?:number, caps?:boolean}} o twist in degrees
+ */
+export function sweepMesh(profile, spines, o, report) {
+  const twist = ((o.twist || 0) * Math.PI) / 180;
+  const taper = o.taper === undefined ? 1 : o.taper;
+  const caps = o.caps !== false;
+  let open = false;
+
+  // profile contours with per-vertex normals (2D)
+  let contours;
+  let capTris = null;
+  if (profile.kind === 'circle') {
+    const m = Math.max(3, profile.segments);
+    const pts = new Float64Array(m * 2);
+    for (let j = 0; j < m; j++) {
+      const a = (j / m) * TAU;
+      pts[j * 2] = Math.cos(a) * profile.radius;
+      pts[j * 2 + 1] = Math.sin(a) * profile.radius;
+    }
+    contours = [{ points: pts, smooth: new Uint8Array(m).fill(1), closed: true }];
+    capTris = { circle: true, pts };
+  } else contours = profile.walls;
+  const w = spines.every((sp) => sp.points.length % 3 === 0) ? sweepWasm(spines, contours, capTris && capTris.pts, profile.regions, twist, taper, caps) : null;
+  if (w) {
+    for (const e of w.errors) reportTriangulation(e, report);
+    for (const d of w.degenerate) if (d && report) report('error', 'E_DEGENERATE_SPINE', 'The sweep spine needs at least two distinct points.');
+    return { mesh: new Mesh({ positions: w.positions, normals: w.normals, uvs: w.uvs, indices: w.indices, kind: 'triangles' }), doubleSided: w.open };
+  }
+  if (!capTris) capTris = triangulateRegions(profile.regions, report);
+  const contourInfo = contours.map((c) => ({ pts: c.points, f: contourFrames(c.points, c.smooth, true) }));
+
+  // frames first, so the mesh can be allocated once at its final size
+  const frames = [];
+  let vertices = 0, indices = 0;
+  for (const sp of spines) {
+    const fr = spineFrames(sp.points, sp.closed);
+    if (!fr) {
+      if (report) report('error', 'E_DEGENERATE_SPINE', 'The sweep spine needs at least two distinct points.');
+      continue;
+    }
+    frames.push(fr);
+    for (const { f } of contourInfo) {
+      vertices += f.n * fr.count * 2;
+      indices += f.n * (fr.count - 1) * 6;
+    }
+    if (!fr.closed && caps) {
+      if (capTris.circle) {
+        const m = capTris.pts.length / 2;
+        vertices += 2 * (m + 1);
+        indices += 2 * m * 3;
+      } else {
+        for (const t of capTris) {
+          vertices += t.positions.length;
+          indices += 2 * t.indices.length;
+        }
+      }
+    }
+  }
+  const b = new MeshBuilder('triangles', vertices, indices);
+  const out = new Float64Array(3);
+
+  for (const fr of frames) {
+    const count = fr.count;
+    const L = fr.length || 1;
+    const dScale = (taper - 1) / L;
+    const Nf = fr.N, Bf = fr.B, Tf = fr.T, Pf = fr.pos, Kf = fr.K;
+    const stretch = fr.stretch, arc = fr.arc;
+    // twist and taper only depend on the station
+    const ks = new Float64Array(count), cas = new Float64Array(count), sas = new Float64Array(count);
+    for (let i = 0; i < count; i++) {
+      const s = arc[i] / L;
+      ks[i] = 1 + (taper - 1) * s;
+      const ang = twist * s;
+      cas[i] = Math.cos(ang);
+      sas[i] = Math.sin(ang);
+    }
+
+    for (const { pts, f } of contourInfo) {
+      // every profile point at every station, computed once for both of its edges
+      const ring = new Float64Array(count * f.n * 3);
+      sweepRing(ring, pts, f.n, count, ks, cas, sas, Nf, Bf, Pf, Kf, stretch);
+      sweepWalls(b, ring, f, pts, count, arc, cas, sas, Nf, Bf, Tf, dScale, out);
+    }
+
+    if (!fr.closed) {
+      if (!caps) open = true;
+      else {
+        for (const [s, dir] of [[0, -1], [count - 1, 1]]) {
+          const nx = Tf[s * 3] * dir, ny = Tf[s * 3 + 1] * dir, nz = Tf[s * 3 + 2] * dir;
+          if (capTris.circle) {
+            placeAt(out, 0, s, 0, 0, ks, cas, sas, Nf, Bf, Pf, Kf, stretch);
+            const ci = b.vertex(out[0], out[1], out[2], nx, ny, nz, 0.5, 0.5);
+            const m = capTris.pts.length / 2;
+            const first = b.vertexCount;
+            for (let j = 0; j < m; j++) {
+              placeAt(out, 0, s, capTris.pts[j * 2], capTris.pts[j * 2 + 1], ks, cas, sas, Nf, Bf, Pf, Kf, stretch);
+              b.vertex(out[0], out[1], out[2], nx, ny, nz, 0.5 + Math.cos((j / m) * TAU) / 2, 0.5 + Math.sin((j / m) * TAU) / 2);
+            }
+            for (let j = 0; j < m; j++) {
+              const a = first + j, c2 = first + ((j + 1) % m);
+              if (dir > 0) b.tri(ci, a, c2);
+              else b.tri(ci, c2, a);
+            }
+          } else {
+            for (const t of capTris) {
+              const base = b.vertexCount;
+              const p = t.positions;
+              for (let k = 0; k < p.length; k += 2) {
+                placeAt(out, 0, s, p[k], p[k + 1], ks, cas, sas, Nf, Bf, Pf, Kf, stretch);
+                b.vertex(out[0], out[1], out[2], nx, ny, nz, p[k], p[k + 1]);
+              }
+              const idx = t.indices;
+              for (let k = 0; k < idx.length; k += 3) {
+                if (dir > 0) b.tri(base + idx[k], base + idx[k + 1], base + idx[k + 2]);
+                else b.tri(base + idx[k], base + idx[k + 2], base + idx[k + 1]);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  return { mesh: b.build(), doubleSided: open };
+}

package/src/index.js

@@ -0,0 +1,47 @@
+// Public API of the ES3D reference implementation.
+//
+//   import { compile, createRenderer, Camera } from '@es3d/es3d';
+//
+//   const result = compile(text);              // parse + validate + build + flatten
+//   if (!result.ok) console.error(result.diagnostics.map((d) => d.format()).join('\n\n'));
+//   const renderer = await createRenderer(canvas);   // WebGPU, else WebGL2
+//   renderer.setScene(result.scene, (entry, lod) => result.cache.mesh(entry, lod));
+//   const camera = new Camera().frame(result.scene.bounds);
+//   renderer.render(camera, { width: canvas.clientWidth, height: canvas.clientHeight });
+//
+//   const svg = await importFiles([{ name: 'logo.svg', bytes }]);   // SVG, OBJ, STL, STEP, glTF → ES3D
+//   const { files } = exportFormat(svg.text, 'glb');                 // ES3D → glTF, OBJ, STL, STEP
+//
+// The format, scene, geometry and I/O modules run in Node as well; only the
+// renderer and controls need a browser.
+
+// documents
+export { parse, parseStrict, detectSyntax, formatDiagnostics } from './format/parse.js';
+export { serialize, SERIALIZE_PRESETS } from './format/serializer.js';
+export { Document, Element, Attr, Comment, walk, h } from './format/ast.js';
+export { Diagnostic, ES3DError } from './format/errors.js';
+export { ELEMENTS, elementSpec, attrSpec } from './format/schema.js';
+
+// scene pipeline
+export { compile, generateGeometry, GeometryCache } from './pipeline.js';
+export { openGeometryStore, indexedDBStore, memoryStore, restoreGeometry, saveGeometry, persistGeometry, geometryKey, GEOMETRY_REVISION } from './cache/geometry-store.js';
+export { RenderScene, updateDynamic, FLAG_MIRRORED, FLAG_NO_COLLIDE } from './scene/flatten.js';
+export { pick, raycast } from './scene/picking.js';
+export { applyLimits, sweepCamera, constrainCamera } from './scene/camera-constraints.js';
+
+// rendering (browser)
+export { createRenderer, Renderer } from './render/renderer.js';
+export { Camera } from './render/camera.js';
+export { OrbitControls } from './render/orbit-controls.js';
+export { ScrollTimeline } from './render/scroll-timeline.js';
+export { createStage, ancestorNames } from './render/stage.js';
+
+// conversion and optimization
+export { importFiles, exportFormat, detectKind, INPUT_KINDS, OUTPUT_FORMATS } from './io/convert.js';
+export { svgToES3D } from './io/svg-import.js';
+export { exportOBJ, parseOBJ, objToScene } from './io/obj.js';
+export { exportGLB, parseGLB, glbToScene, isGLB, parseGLTF, gltfToScene } from './io/gltf.js';
+export { exportSTL, parseSTL, stlToScene } from './io/stl.js';
+export { exportSTEP, parseSTEP, stepToScene, isSTEP } from './io/step.js';
+export { sceneToMeshDocument } from './io/mesh-import.js';
+export { optimize, expandProcedural } from './optimize/optimizer.js';

package/src/io/compression.js

@@ -0,0 +1,67 @@
+// Compression helpers that work in browsers (CompressionStream) and in Node
+// (zlib, which also provides brotli). Used for file-size statistics and the
+// benchmark, and for loading .gz files.
+
+const isNode = typeof process !== 'undefined' && !!(process.versions && process.versions.node) && typeof window === 'undefined';
+
+let zlibPromise = null;
+function zlib() {
+  // Node only; the variable keeps bundlers from trying to resolve it for browsers
+  const specifier = 'node:zlib';
+  if (!zlibPromise) zlibPromise = import(/* @vite-ignore */ specifier);
+  return zlibPromise;
+}
+
+function toBytes(data) {
+  if (typeof data === 'string') return new TextEncoder().encode(data);
+  if (data instanceof Uint8Array) return data;
+  return new Uint8Array(data);
+}
+
+async function streamBytes(bytes, transform) {
+  const stream = new Blob([bytes]).stream().pipeThrough(transform);
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/** gzip (level 9 in Node, browser default otherwise). */
+export async function gzip(data) {
+  const bytes = toBytes(data);
+  if (isNode) {
+    const z = await zlib();
+    return new Uint8Array(z.gzipSync(bytes, { level: 9 }));
+  }
+  return streamBytes(bytes, new CompressionStream('gzip'));
+}
+
+export async function gunzip(data) {
+  const bytes = toBytes(data);
+  if (isNode) {
+    const z = await zlib();
+    return new Uint8Array(z.gunzipSync(bytes));
+  }
+  return streamBytes(bytes, new DecompressionStream('gzip'));
+}
+
+/** Brotli (quality 11). Returns null where unavailable (browsers lack a brotli compressor API). */
+export async function brotli(data) {
+  const bytes = toBytes(data);
+  if (isNode) {
+    const z = await zlib();
+    return new Uint8Array(z.brotliCompressSync(bytes, { params: { [z.constants.BROTLI_PARAM_QUALITY]: 11, [z.constants.BROTLI_PARAM_SIZE_HINT]: bytes.length } }));
+  }
+  try {
+    return await streamBytes(bytes, new CompressionStream('br'));
+  } catch {
+    return null;
+  }
+}
+
+export async function compressedSizes(data) {
+  const bytes = toBytes(data);
+  const [g, b] = await Promise.all([gzip(bytes), brotli(bytes)]);
+  return { raw: bytes.length, gzip: g.length, brotli: b ? b.length : null };
+}
+
+export function isGzip(bytes) {
+  return bytes.length > 2 && bytes[0] === 0x1f && bytes[1] === 0x8b;
+}