partforge 0.1.0 → 0.4.0

package/src/parts/demo.js

@@ -1,38 +1,56 @@
-// Example PartDefinition — a parametric spacer. Proof that a new part is just a new
-// script: the framework (viewer, controls, workers, STL/STEP export) is reused
-// unchanged. Mount it with its own app/worker entry exactly as the drum does.
+// Example PartDefinition — a parametric spacer. Doubles as the worked example for
+// docs/AUTHORING-PARTS.md "Designing the control panel": a description on every
+// control, a hidden internal constant, and a derive() that turns raw inputs into the
+// dependent dimensions the build consumes. The framework (viewer, controls, workers,
+// STL/STEP export) is reused unchanged.
 export default {
   meta: { title: "Spacer", units: "mm", background: 0x15181d },
   parameters: [
     {
       id: "body",
       title: "Body",
+      description: "The spacer barrel and its through-bore. Pick a preset for a common screw size, or open **Advanced** to set exact dimensions.",
       presets: { M3: { od: 8, bore: 3.4, h: 10 }, M5: { od: 12, bore: 5.4, h: 16 } },
       advanced: [
-        { key: "od", label: "Outer diameter", unit: "mm", min: 4, max: 40, step: 0.5 },
-        { key: "bore", label: "Bore", unit: "mm", min: 1, max: 30, step: 0.1, control: "number" },
-        { key: "h", label: "Height", unit: "mm", min: 2, max: 60, step: 1 },
+        { key: "od", label: "Outer diameter", unit: "mm", min: 4, max: 40, step: 0.5,
+          description: "Barrel outer diameter. Keep it comfortably larger than the bore so a wall remains. See the [authoring guide](https://github.com/scottsykora/partforge/blob/main/docs/AUTHORING-PARTS.md)." },
+        { key: "bore", label: "Bore", unit: "mm", min: 1, max: 30, step: 0.1, control: "number",
+          description: "Nominal screw clearance hole. A fixed print clearance is added automatically (see `derive`), so enter the *nominal* size." },
+        { key: "h", label: "Height", unit: "mm", min: 2, max: 60, step: 1,
+          description: "Spacer length along the axis." },
+        { key: "flange_h", label: "Flange thickness", unit: "mm", min: 1, max: 5, step: 0.5, hidden: true,
+          description: "Internal: flange plate thickness, fixed by the design. Hidden from the end user, but still drives the geometry." },
       ],
     },
     {
       id: "flange",
       title: "Flange",
+      description: "Optional base flange — a wider seating plate at one end.",
       features: [
         { label: "Base flange", key: "flange_d", on: 16,
-          sliders: [{ key: "flange_d", label: "Flange diameter", unit: "mm", min: 8, max: 50, step: 1 }] },
+          description: "Adds a `flange_h`-thick plate of this diameter at the base.",
+          sliders: [{ key: "flange_d", label: "Flange diameter", unit: "mm", min: 8, max: 50, step: 1,
+            description: "Outer diameter of the base flange." }] },
       ],
     },
   ],
-  defaults: { od: 8, bore: 3.4, h: 10, flange_d: 0 },
+  defaults: { od: 8, bore: 3.4, h: 10, flange_d: 0, flange_h: 2 },
+  // derive(): turn raw inputs into the dependent dimensions the build needs, so one
+  // input drives the geometry consistently — here the bore gains a fixed print
+  // clearance and the cut tool is sized to pierce the whole part.
+  derive: (p) => ({
+    boreR: (p.bore + 0.2) / 2, // nominal bore + 0.2 mm print clearance, as a radius
+    cutH: p.h + 4,             // through-cut tool, taller than the part
+  }),
   parts: {
     spacer: {
       label: "Spacer",
       views: ["spacer"],
       export: { name: "spacer" },
-      build: (k, p) => {
+      build: (k, p, d) => {
         let s = k.cylinder(p.od / 2, p.od / 2, p.h);
-        if (p.flange_d > 0) s = k.union([s, k.cylinder(p.flange_d / 2, p.flange_d / 2, 2)]);
-        return s.cut(k.cylinder(p.bore / 2, p.bore / 2, p.h + 4).translate([0, 0, -2]));
+        if (p.flange_d > 0) s = k.union([s, k.cylinder(p.flange_d / 2, p.flange_d / 2, p.flange_h)]);
+        return s.cut(k.cylinder(d.boreR, d.boreR, d.cutH).translate([0, 0, -2]));
       },
     },
   },

package/src/parts/filleted-box.js

@@ -0,0 +1,46 @@
+// Example part exercising native CAD ops — it auto-routes to the OCCT backend
+// because it uses fillet (and chamfer when enabled). Vertical edges are rounded
+// and an optional bore drilled; the base chamfer is off by default (turn it up to
+// try chamfering, kept off in defaults so the gating build uses only the fillet).
+export default {
+  meta: { title: "Filleted Box", units: "mm", background: 0x15181d },
+  parameters: [
+    {
+      id: "box", title: "Box",
+      advanced: [
+        { key: "w", label: "Width", unit: "mm", min: 10, max: 80, step: 1 },
+        { key: "d", label: "Depth", unit: "mm", min: 10, max: 80, step: 1 },
+        { key: "h", label: "Height", unit: "mm", min: 5, max: 40, step: 1 },
+        { key: "fillet", label: "Edge fillet", unit: "mm", min: 0, max: 10, step: 0.5 },
+        { key: "top", label: "Top fillet", unit: "mm", min: 0, max: 5, step: 0.5 },
+        { key: "chamfer", label: "Base chamfer", unit: "mm", min: 0, max: 10, step: 0.5 },
+        { key: "bore", label: "Bore", unit: "mm", min: 0, max: 24, step: 0.5 },
+      ],
+    },
+  ],
+  defaults: { w: 40, d: 30, h: 16, fillet: 3, top: 2, chamfer: 0, bore: 8 },
+  parts: {
+    body: {
+      label: "Body",
+      views: ["box"],
+      build: (k, p) => {
+        let s = k.box([0, 0, 0], [p.w, p.d, p.h]);
+        const half = Math.min(p.w, p.d) / 2;
+        // Round the vertical edges, then the top rim — each clamped to the box so a
+        // radius can't exceed the available material.
+        const vFillet = Math.min(p.fillet, half - 0.5, p.h - 0.5);
+        if (vFillet > 0) s = s.fillet(vFillet, { dir: "Z" });                   // 4 vertical edges
+        const topFillet = Math.min(p.top, half - vFillet - 0.5, p.h / 2 - 0.5);
+        if (topFillet > 0) s = s.fillet(topFillet, { inPlane: "XY", at: p.h });  // top rim — curves all the way around
+        // Base chamfer AFTER the fillets, so it cuts a clean curve across the rounded
+        // corners. No manual limit needed: the backend auto-clamps a chamfer to half
+        // the shortest edge it touches (here the fillets' bottom arcs), so it stops at
+        // its valid maximum instead of mangling the bottom face.
+        if (p.chamfer > 0) s = s.chamfer(p.chamfer, { inPlane: "XY", at: 0 });    // base edges
+        if (p.bore > 0) s = s.cut(k.cylinder(p.bore / 2, p.bore / 2, p.h + 2).translate([p.w / 2, p.d / 2, -1]));
+        return s;
+      },
+    },
+  },
+  views: { box: { label: "Box" } },
+};

package/src/testing/build.js

@@ -0,0 +1,17 @@
+import { viewSubParts } from "../framework/jobs.js";
+
+// Build every sub-part of a view in its display (assembly) pose with the given
+// Manifold kernel, returning live solids + copied-out meshes. Mirrors the
+// `generate` path in jobs.js, but keeps solids LIVE (does NOT call
+// kernel.cleanup()) so callers can read exact solid facts (volume/genus/empty)
+// before they free the kernel. Meshes are JS-owned arrays and survive cleanup.
+export function buildView(kernel, part, view, params = {}) {
+  const p = { ...part.defaults, ...params };
+  const d = part.derive ? part.derive(p) : {};
+  return viewSubParts(part, view, p).map((name) => {
+    const sp = part.parts[name];
+    let solid = sp.build(kernel, p, d);
+    if (sp.place) solid = sp.place(solid, { view, purpose: "display", p, d });
+    return { name, solid, mesh: solid.toMesh() };
+  });
+}

package/src/testing/measure.js

@@ -0,0 +1,53 @@
+import { buildView } from "./build.js";
+import { assemblyOverlaps } from "../framework/assembly.js";
+import { bounds, meshArea } from "./mesh.js";
+
+const size = ({ min, max }) => [max[0] - min[0], max[1] - min[1], max[2] - min[2]];
+const unionBounds = (list) => list.reduce(
+  (acc, b) => ({ min: acc.min.map((v, i) => Math.min(v, b.min[i])), max: acc.max.map((v, i) => Math.max(v, b.max[i])) }),
+  { min: [Infinity, Infinity, Infinity], max: [-Infinity, -Infinity, -Infinity] },
+);
+
+// Headless geometric report for one view of a part (Manifold-only). Reads exact
+// solid facts (volume/genus/emptiness) and mesh facts (bbox/area/triangles), plus
+// the assembly overlap check. All solid facts are read BEFORE assemblyOverlaps,
+// which frees the shared kernel's objects at its end.
+//   → { part, view, subparts[], aggregate, overlaps[], ok }
+export function measure(kernel, part, view = Object.keys(part.views)[0], params = {}) {
+  const built = buildView(kernel, part, view, params);
+  const subBounds = [];
+  const subparts = built.map(({ name, solid, mesh }) => {
+    const b = bounds(mesh.positions);
+    subBounds.push(b);
+    return {
+      name,
+      bbox: size(b),
+      volume: solid.volume(),
+      surfaceArea: meshArea(mesh.positions, mesh.indices),
+      triangleCount: mesh.triangles,
+      watertight: typeof solid.isEmpty === "function" ? !solid.isEmpty() : null,
+      holes: typeof solid.genus === "function" ? solid.genus() : null,
+    };
+  });
+
+  // Rebuilds with the same kernel and cleans up at its end — every solid fact
+  // above is already read, so this is safe.
+  const canIntersect = built.length > 0 && typeof built[0].solid.intersect === "function";
+  const overlaps = canIntersect ? assemblyOverlaps(kernel, part, view, params) : [];
+  kernel.cleanup?.();
+
+  const aggregate = {
+    bbox: subparts.length ? size(unionBounds(subBounds)) : [0, 0, 0],
+    volume: subparts.reduce((a, s) => a + s.volume, 0),
+    surfaceArea: subparts.reduce((a, s) => a + s.surfaceArea, 0),
+    triangleCount: subparts.reduce((a, s) => a + s.triangleCount, 0),
+  };
+  return {
+    part: part.meta?.title ?? view,
+    view,
+    subparts,
+    aggregate,
+    overlaps,
+    ok: subparts.every((s) => s.watertight !== false) && overlaps.length === 0,
+  };
+}

package/src/testing/mesh.js

@@ -19,3 +19,30 @@ export function bboxSize(positions) {
   }
   return [hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]];
 }
+
+// Axis-aligned bounds of a flat position array (x,y,z per vertex).
+export function bounds(positions) {
+  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < positions.length; i += 3) for (let a = 0; a < 3; a++) {
+    const v = positions[i + a];
+    if (v < min[a]) min[a] = v;
+    if (v > max[a]) max[a] = v;
+  }
+  return { min, max };
+}
+
+// Surface area (mm²) of a triangle mesh. `indices` is optional: when omitted the
+// positions are a non-indexed soup (3 consecutive verts per triangle, Manifold);
+// when given, positions is a vertex array indexed by triangle (OCCT/replicad).
+export function meshArea(positions, indices) {
+  let area = 0;
+  const n = indices ? indices.length : positions.length / 3;
+  for (let i = 0; i < n; i += 3) {
+    const a = (indices ? indices[i] : i) * 3, b = (indices ? indices[i + 1] : i + 1) * 3, c = (indices ? indices[i + 2] : i + 2) * 3;
+    const ux = positions[b] - positions[a], uy = positions[b + 1] - positions[a + 1], uz = positions[b + 2] - positions[a + 2];
+    const vx = positions[c] - positions[a], vy = positions[c + 1] - positions[a + 1], vz = positions[c + 2] - positions[a + 2];
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+    area += Math.hypot(nx, ny, nz) / 2;
+  }
+  return area;
+}

package/src/testing/render.js

@@ -0,0 +1,159 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { buildView } from "./build.js";
+import { bounds } from "./mesh.js";
+
+// Canonical view directions in MODEL space (Z-up). `dir` is the direction from
+// the part centre toward the camera; `up` is the camera up vector.
+const ANGLES = {
+  iso:   { dir: [1, 1, 1],  up: [0, 0, 1] },
+  front: { dir: [0, -1, 0], up: [0, 0, 1] },
+  top:   { dir: [0, 0, 1],  up: [0, 1, 0] },
+};
+
+const slug = (s) => String(s).toLowerCase().replace(/\s+/g, "-");
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const norm = (a) => { const l = Math.hypot(a[0], a[1], a[2]) || 1; return [a[0] / l, a[1] / l, a[2] / l]; };
+
+// Render canonical-angle PNGs of one view of a part with a pure-JS software
+// rasterizer (orthographic, z-buffered, Lambert-shaded, with depth-tested edge
+// overlays). No native module, no browser. Returns the written file paths.
+// pngjs is lazy-imported so importing the testing barrel for measure never loads it.
+export async function renderViews(kernel, part, view = Object.keys(part.views)[0], {
+  views = ["iso", "front", "top"], out = "render", size = [800, 600], edges = true, params = {},
+} = {}) {
+  const { PNG } = await import("pngjs");
+  const [W, H] = size;
+  const meshes = buildView(kernel, part, view, params).map((b) => b.mesh); // copied out
+
+  // scene bounds over all sub-parts (positions are JS-owned; safe after cleanup)
+  const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+  for (const m of meshes) {
+    const b = bounds(m.positions);
+    for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i], b.min[i]); hi[i] = Math.max(hi[i], b.max[i]); }
+  }
+  kernel.cleanup?.();
+
+  const center = [(lo[0] + hi[0]) / 2, (lo[1] + hi[1]) / 2, (lo[2] + hi[2]) / 2];
+  const radius = Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) / 2 || 5;
+
+  const bg = [0x15, 0x18, 0x1d], base = [0x9f, 0xb4, 0xcc], edgeColor = [0x1c, 0x23, 0x2d];
+  const light = norm([0.4, 0.5, 0.8]); // world-space key direction (toward the light)
+  const ambient = 0.35, diffuse = 0.75;
+  const bias = radius * 0.02;           // edge depth bias so visible edges win ties
+
+  mkdirSync(out, { recursive: true });
+  const name = slug(part.meta?.title ?? view);
+  const written = [];
+
+  for (const angle of views) {
+    const a = ANGLES[angle];
+    if (!a) throw new Error(`unknown angle "${angle}" (use: ${Object.keys(ANGLES).join(", ")})`);
+    // orthographic camera basis: zc toward camera, xc right, yc up
+    const zc = norm(a.dir), xc = norm(cross(a.up, zc)), yc = cross(zc, xc);
+    const ppu = Math.min(W, H) / (2 * radius * 1.25); // pixels per mm (uniform; margin)
+    const project = (p) => {
+      const r = sub(p, center);
+      return [W / 2 + dot(r, xc) * ppu, H / 2 - dot(r, yc) * ppu, dot(r, zc)]; // [sx, sy, depth]
+    };
+
+    const color = new Uint8Array(W * H * 3);
+    for (let i = 0; i < W * H; i++) { color[i * 3] = bg[0]; color[i * 3 + 1] = bg[1]; color[i * 3 + 2] = bg[2]; }
+    const zbuf = new Float32Array(W * H).fill(-Infinity); // larger depth = nearer camera
+
+    for (const m of meshes) {
+      const P = m.positions, N = m.normals, ind = m.indices;
+      // Manifold meshes are a non-indexed soup (3 consecutive verts/triangle) with
+      // per-vertex normals; OCCT meshes are indexed and carry no normals.
+      const triCount = ind?.length ? ind.length / 3 : P.length / 9;
+      for (let t = 0; t < triCount; t++) {
+        const ai = ind?.length ? ind[t * 3] * 3 : t * 9;
+        const bi = ind?.length ? ind[t * 3 + 1] * 3 : t * 9 + 3;
+        const ci = ind?.length ? ind[t * 3 + 2] * 3 : t * 9 + 6;
+        const va = [P[ai], P[ai + 1], P[ai + 2]], vb = [P[bi], P[bi + 1], P[bi + 2]], vc = [P[ci], P[ci + 1], P[ci + 2]];
+        const sp = [va, vb, vc].map(project);
+        let inten;
+        if (N?.length) {
+          // per-vertex normals (same layout/offset as positions)
+          inten = [ai, bi, ci].map((o) =>
+            Math.min(1, ambient + diffuse * Math.max(0, N[o] * light[0] + N[o + 1] * light[1] + N[o + 2] * light[2])));
+        } else {
+          // no normals → flat face normal, two-sided so it lights regardless of winding
+          const ux = vb[0] - va[0], uy = vb[1] - va[1], uz = vb[2] - va[2];
+          const wx = vc[0] - va[0], wy = vc[1] - va[1], wz = vc[2] - va[2];
+          const nx = uy * wz - uz * wy, ny = uz * wx - ux * wz, nz = ux * wy - uy * wx;
+          const L = Math.hypot(nx, ny, nz) || 1;
+          const I0 = Math.min(1, ambient + diffuse * Math.abs((nx * light[0] + ny * light[1] + nz * light[2]) / L));
+          inten = [I0, I0, I0];
+        }
+        rasterTri(sp, inten, base, color, zbuf, W, H);
+      }
+    }
+
+    if (edges) {
+      for (const m of meshes) {
+        const E = m.edges;
+        if (!E?.length) continue;
+        for (let i = 0; i < E.length; i += 6)
+          drawLine(project([E[i], E[i + 1], E[i + 2]]), project([E[i + 3], E[i + 4], E[i + 5]]), edgeColor, color, zbuf, W, H, bias);
+      }
+    }
+
+    const png = new PNG({ width: W, height: H });
+    for (let i = 0; i < W * H; i++) {
+      png.data[i * 4] = color[i * 3]; png.data[i * 4 + 1] = color[i * 3 + 1]; png.data[i * 4 + 2] = color[i * 3 + 2]; png.data[i * 4 + 3] = 255;
+    }
+    const file = join(out, `${name}-${view}-${angle}.png`);
+    writeFileSync(file, PNG.sync.write(png));
+    written.push(file);
+  }
+  return written;
+}
+
+// signed area of the 2-D edge from a to b evaluated at p (for barycentric coords)
+const edgeFn = (a, b, p) => (b[0] - a[0]) * (p[1] - a[1]) - (b[1] - a[1]) * (p[0] - a[0]);
+
+// Fill one projected triangle, z-buffered, with Gouraud-interpolated Lambert shading.
+function rasterTri(sp, inten, base, color, zbuf, W, H) {
+  const [a, b, c] = sp;
+  const area = edgeFn(a, b, c);
+  if (Math.abs(area) < 1e-9) return;
+  const minX = Math.max(0, Math.floor(Math.min(a[0], b[0], c[0])));
+  const maxX = Math.min(W - 1, Math.ceil(Math.max(a[0], b[0], c[0])));
+  const minY = Math.max(0, Math.floor(Math.min(a[1], b[1], c[1])));
+  const maxY = Math.min(H - 1, Math.ceil(Math.max(a[1], b[1], c[1])));
+  for (let y = minY; y <= maxY; y++) {
+    for (let x = minX; x <= maxX; x++) {
+      const p = [x + 0.5, y + 0.5];
+      const w0 = edgeFn(b, c, p), w1 = edgeFn(c, a, p), w2 = edgeFn(a, b, p);
+      // inside if all the same sign (handle either winding from the projection)
+      if (!((w0 >= 0 && w1 >= 0 && w2 >= 0) || (w0 <= 0 && w1 <= 0 && w2 <= 0))) continue;
+      const l0 = w0 / area, l1 = w1 / area, l2 = w2 / area;
+      const depth = l0 * a[2] + l1 * b[2] + l2 * c[2];
+      const idx = y * W + x;
+      if (depth <= zbuf[idx]) continue;
+      zbuf[idx] = depth;
+      const I = l0 * inten[0] + l1 * inten[1] + l2 * inten[2];
+      color[idx * 3] = Math.min(255, base[0] * I);
+      color[idx * 3 + 1] = Math.min(255, base[1] * I);
+      color[idx * 3 + 2] = Math.min(255, base[2] * I);
+    }
+  }
+}
+
+// Depth-tested line for edge overlays: drawn only where it isn't behind the
+// surface (within `bias`), so the silhouette and feature edges read as crisp lines.
+function drawLine(p0, p1, col, color, zbuf, W, H, bias) {
+  const steps = Math.max(1, Math.ceil(Math.max(Math.abs(p1[0] - p0[0]), Math.abs(p1[1] - p0[1]))));
+  for (let s = 0; s <= steps; s++) {
+    const t = s / steps;
+    const x = Math.round(p0[0] + (p1[0] - p0[0]) * t), y = Math.round(p0[1] + (p1[1] - p0[1]) * t);
+    if (x < 0 || x >= W || y < 0 || y >= H) continue;
+    const depth = p0[2] + (p1[2] - p0[2]) * t;
+    const idx = y * W + x;
+    if (depth + bias < zbuf[idx]) continue; // occluded
+    color[idx * 3] = col[0]; color[idx * 3 + 1] = col[1]; color[idx * 3 + 2] = col[2];
+  }
+}

package/src/testing.js

@@ -6,3 +6,6 @@ export { handle, viewSubParts } from "./framework/jobs.js";
 export { assemblyOverlaps } from "./framework/assembly.js";
 export { bootOcctKernel } from "./testing/occt.js";
 export { meshVolume, bboxSize } from "./testing/mesh.js";
+export { buildView } from "./testing/build.js";
+export { measure } from "./testing/measure.js";
+export { renderViews } from "./testing/render.js";