partforge 0.20.2 → 0.22.0

package/docs/AUTHORING-PARTS.md

@@ -504,10 +504,15 @@ body = body.cutAll(circularPattern(hole, 8, { axis: "Z" }));   // 8 bolt holes o
 // Keyhole plate: union a disc onto a rect, punch a slot, extrude.
 const plate = k.shape2d(roundedRectPolygon(40, 24, 4))
   .union(circleProfile(8))
-  .cut(slotPolygon(16, 3));
-k.extrude({ profile: plate, h: 3 });
+  .cut(slotPolygon(16, 3))
+  .extrude({ h: 3 });   // sugar for k.extrude({ profile: …, h: 3 }); .revolve({ degrees }) too
 ```
 
+A `Shape2D` also carries `.extrude({ h, twist?, scaleTop? })` and `.revolve({ degrees? })`
+sugar (equivalent to the `k.extrude`/`k.revolve` forms), and `.regions()` — scission, which
+returns each disjoint region as its own live `Shape2D` (vs `.toRegions()`, which returns raw
+`{outer, holes}` data).
+
 ```js
 // A 0.2 mm printer clearance around a bore, then a 2 mm wall inset:
 const bore  = k.shape2d(circleProfile(3)).offset(0.2);            // looser
@@ -518,6 +523,19 @@ const wall  = k.shape2d(outer).offset(-2, { corners: "sharp" });  // inset, mite
 
 `Shape2D.offset(delta, {corners})` grows (`delta>0`) or insets (`delta<0`) a shape with round/chamfer/sharp corners — curve-preserving on OCCT, faceted at mesh LOD on Manifold; it throws if the offset collapses the shape. (For `derive()`/main-thread clearance math on plain point lists, use the pure `offsetPolygon` helper instead.)
 
+## Convex hull
+
+`k.hull([a, b, …])` wraps its inputs (Shape2Ds, curve contours, or point lists) in a
+convex `Shape2D`. `k.hullChain([a, b, c, …])` sweeps the hull along an ordered sequence
+(≥2 inputs) — the union of `hull([a,b])`, `hull([b,c])`, … — for capsules, rounded slots,
+and organic tapers. Faceted (curved inputs facet at mesh LOD): the hull is a pure-JS
+monotone-chain computation, never a native backend op.
+
+```js
+const capsule = k.hull([circleProfile(4, [0, 0]), circleProfile(4, [20, 0])]);   // a stadium
+const slot = k.hullChain([circleProfile(3, [0, 0]), circleProfile(3, [15, 0]), circleProfile(2, [25, 5])]);
+```
+
 ## Text (`text2d`)
 
 `k.text2d(string, { size, font?, align?, valign?, lineHeight?, tracking?, kerning? })` renders outline-font text as a `Shape2D` — a 2-D boolean you can compose with other shapes (union / cut / offset) and extrude into 3-D geometry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.20.2",
+  "version": "0.22.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/app-hull-sweep.js

@@ -0,0 +1,9 @@
+import part from "./parts/hull-sweep.js";
+import { mount } from "./framework/index.js";
+
+// Dev example app for the hull-sweep demo (src/parts/hull-sweep.js). The
+// `new Worker(new URL(...))` call must stay inline here so Vite bundles the worker.
+mount(part, {
+  createWorker: (name) =>
+    new Worker(new URL("./hull-sweep-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/framework/geometry/curve-fill.js

@@ -9,12 +9,16 @@
 //   4. unite(self) to normalize overlaps and crossings into simple paths.
 import paper from "paper/dist/paper-core.js";
 
-// Never use paper's package-global project: another consumer in the same worker may import
-// paper too. This resolver owns and clears only this private, headless scope.
-const scope = new paper.PaperScope();
-scope.setup(new scope.Size(1, 1));
+// Lazy, private PaperScope: built on first use (not at module load), so parts that never
+// call k.text2d don't pull paper-core's setup onto the geometry worker. Never paper's
+// package-global project — another consumer in the same worker may import paper too.
+let _scope = null;
+function paperScope() {
+  if (!_scope) { _scope = new paper.PaperScope(); _scope.setup(new _scope.Size(1, 1)); }
+  return _scope;
+}
 
-function toPaperPath(contour) {
+function toPaperPath(scope, contour) {
   const path = new scope.Path({ insert: false });
   path.moveTo(new scope.Point(contour.start[0], contour.start[1]));
   for (const s of contour.segments) {
@@ -67,10 +71,11 @@ export function resolveCurveFill(contours, { fillRule = "nonzero" } = {}) {
   if (fillRule !== "nonzero" && fillRule !== "evenodd")
     throw new Error('curve-fill: fillRule must be "nonzero" or "evenodd"');
   if (!contours || contours.length === 0) return [];
+  const scope = paperScope();
   try {
     const simple = [];
     for (const ct of contours) {
-      const resolved = toPaperPath(ct).resolveCrossings();
+      const resolved = toPaperPath(scope, ct).resolveCrossings();
       const kids = resolved.className === "CompoundPath" ? resolved.children : [resolved];
       for (const k of kids) if (k.segments && k.segments.length >= 2) simple.push(k.clone({ insert: false }));
     }

package/src/framework/geometry/hull.js

@@ -0,0 +1,50 @@
+// Pure, backend-free 2-D convex hull (Andrew's monotone chain) + input sampling for
+// k.hull / k.hullChain (wired in kernel-front). No WASM, no kernel — a pure function
+// of its inputs, so hull output for point-list/contour inputs is backend-independent.
+import { tessellateContour } from "./profile.js";
+
+// Fixed LOD for curve-contour inputs. Sampling in pure JS (not via a backend's
+// materialization) is what makes point/contour hull results bit-identical across backends.
+const HULL_SEGS = 64;
+
+// One HullInput → its contributing points.
+//   Shape2D          → its materialized boundary rings (outer + holes; holes are interior
+//                      to a convex hull, harmless);
+//   curve contour    → tessellated at a fixed LOD (pure JS);
+//   point list       → used as-is (any length ≥ 1; e.g. circleProfile's 48-gon).
+export function hullPoints(input) {
+  if (input && input._shape2d)
+    return input.toRegions().flatMap((r) => [...r.outer, ...r.holes.flat()]);
+  if (Array.isArray(input) && input.length > 0 && Array.isArray(input[0]))
+    return input;
+  if (input && Array.isArray(input.segments))
+    return tessellateContour(input, HULL_SEGS);
+  throw new Error("hull: each input must be a Shape2D, a curve contour, or an [[x,y],…] point list");
+}
+
+// Convex hull of a point set → CCW convex polygon [[x,y],…]. Andrew's monotone chain,
+// O(n log n). Drops interior and on-edge points (strict turns only), so a collinear set
+// collapses to < 3 vertices → throw (it cannot bound a 2-D region).
+export function convexHull(points) {
+  const seen = new Set();
+  const pts = [];
+  for (const p of points) {
+    const key = `${p[0]},${p[1]}`;
+    if (!seen.has(key)) { seen.add(key); pts.push([p[0], p[1]]); }
+  }
+  if (pts.length < 3) throw new Error(`hull: need ≥3 distinct points, got ${pts.length}`);
+  pts.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+  const half = (src) => {
+    const out = [];
+    for (const p of src) {
+      while (out.length >= 2 && cross(out[out.length - 2], out[out.length - 1], p) <= 0) out.pop();
+      out.push(p);
+    }
+    out.pop(); // last point is shared with the other half's first
+    return out;
+  };
+  const hull = half(pts).concat(half([...pts].reverse()));
+  if (hull.length < 3) throw new Error("hull: points are collinear — no 2-D region");
+  return hull;
+}

package/src/framework/geometry/kernel-front.js

@@ -17,6 +17,7 @@ import { KernelCapabilityError } from "./errors.js";
 import { isPlainOptions, KERNEL_OP_SPECS } from "./op-options.js";
 import { textGlyphs } from "./text2d.js";
 import { DEFAULT_FONT_BYTES } from "./fonts/default-font.js";
+import { convexHull, hullPoints } from "./hull.js";
 
 export function finishKernel(k) {
   // Compound default: bored-through cylinder (tool overshoots 2 mm each end for
@@ -88,5 +89,24 @@ export function finishKernel(k) {
     return regions.map((r) => k.shape2d(r)).reduce((a, b) => a.union(b));
   };
 
+  // Convex hull → Shape2D. Backend-agnostic: pure-JS monotone-chain hull of the inputs'
+  // sampled points, lifted via k.shape2d. Faceted (curved inputs at a fixed LOD).
+  k.hull = (inputs) => {
+    if (!Array.isArray(inputs) || inputs.length === 0)
+      throw new Error("hull: inputs must be a non-empty array");
+    return k.shape2d(convexHull(inputs.flatMap(hullPoints)));
+  };
+  // Swept hull over an ordered sequence (≥2): union of the hull of each consecutive pair.
+  k.hullChain = (inputs) => {
+    if (!Array.isArray(inputs) || inputs.length < 2)
+      throw new Error("hullChain: needs at least 2 inputs");
+    let acc = null;
+    for (let i = 0; i < inputs.length - 1; i++) {
+      const seg = k.hull([inputs[i], inputs[i + 1]]);
+      acc = acc ? acc.union(seg) : seg;
+    }
+    return acc;
+  };
+
   return k;
 }

package/src/framework/geometry/kernel.js

@@ -19,7 +19,7 @@ export const CONTRACT_VERSION = 1;
 // Ops every backend kernel must implement.
 export const KERNEL_OPS = [
   "cylinder", "boredCylinder", "sphere", "box", "prism", "extrude", "revolve",
-  "loft", "sweep", "helixSweptTube", "union", "shape2d", "text2d", "toSTEP",
+  "loft", "sweep", "helixSweptTube", "union", "shape2d", "text2d", "hull", "hullChain", "toSTEP",
 ];
 
 // Backend-optional kernel ops: the Manifold cache brackets + WASM lifetime hooks.
@@ -42,7 +42,8 @@ export const SOLID_OPTIONAL_OPS = ["genus", "isEmpty"];
 
 // Public methods every Shape2D exposes (2-D boolean value; contract-linted).
 export const SHAPE2D_OPS = [
-  "union", "cut", "cutAll", "intersect", "offset", "area", "boundingBox", "toRegions", "simple", "clone",
+  "union", "cut", "cutAll", "intersect", "offset", "area", "boundingBox", "toRegions", "simple", "regions", "clone",
+  "extrude", "revolve",
 ];
 
 // Solid ops only OCCT implements natively. Single source of truth: probe.js routes
@@ -105,6 +106,8 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(solids:Solid[]) => Solid} union
  * @property {(profile: number[][]|{outer:number[][],holes?:number[][][]}|Shape2D) => Shape2D} shape2d   2-D boolean value (both backends: Manifold wraps a CrossSection, OCCT a replicad Drawing)
+ * @property {(inputs: (Shape2D|number[][]|{start:number[],segments:object[]})[]) => Shape2D} hull   convex hull of all inputs → a convex Shape2D (faceted; pure-JS monotone chain)
+ * @property {(inputs: (Shape2D|number[][]|{start:number[],segments:object[]})[]) => Shape2D} hullChain   swept hull over an ordered sequence (≥2): union of hull([inᵢ,inᵢ₊₁])
  * @property {(named:{name:string,solid:Solid}[]) => Promise<ArrayBuffer>} toSTEP   OCCT only (Manifold throws KernelCapabilityError)
  * @property {(name:string) => void} [beginSubPart]   open a per-sub-part solid-cache round (Manifold only)
  * @property {() => void} [endSubPart]                close the cache round (always pair with beginSubPart)

package/src/framework/geometry/manifold-backend.js

@@ -98,7 +98,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     boundingBox: () => { const r = cs.bounds(); return { min: [r.min[0], r.min[1]], max: [r.max[0], r.max[1]] }; },
     toRegions: () => assembleRegions(cs.toPolygons()),
     clone: () => wrapShape2d(cs, hash),
-  });
+  }, { shape2d, extrude: kernel.extrude, revolve: kernel.revolve });
   const shape2d = (profile) => {
     if (profile && profile._shape2d) return profile;                // idempotent
     const hash = h("shape2d", profile, segs);
@@ -184,7 +184,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     toIndexedMesh: () => indexedMeshOut(m),
   });
 
-  return finishKernel({
+  const kernel = finishKernel({
     cylinder: (rb, rt, h2, { center = false } = {}) =>
       wrap(T(Manifold.cylinder(h2, rb, rt, segs, center)), h("cylinder", rb, rt, h2, center, segs)),
     // Compound op: hashed ATOMICALLY from its own args, so it is a single cache
@@ -251,6 +251,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // still pins (they must survive for the next build to resume from them).
     cleanup: () => { for (const o of tracked) if (!cache.isPinned(o)) o.delete?.(); tracked.length = 0; },
   });
+  return kernel;
 }
 
 // Build a non-indexed mesh with normals that are smooth within a single original

package/src/framework/geometry/occt-backend.js

@@ -189,7 +189,7 @@ export function createOcctKernel(replicad) {
       boundingBox: () => { const b = drawing.boundingBox; return { min: [b.bounds[0][0], b.bounds[0][1]], max: [b.bounds[1][0], b.bounds[1][1]] }; },
       toRegions,
       clone: () => wrapShape2d(drawing.clone()),
-    });
+    }, { shape2d, extrude: kernel.extrude, revolve: kernel.revolve });
   };
   const shape2d = (profile) => (profile && profile._shape2d ? profile : wrapShape2d(drawingFromProfile(profile)));
 
@@ -265,7 +265,7 @@ export function createOcctKernel(replicad) {
     return wrap(genericSweep(profile, spine, { frenet: true }));
   };
 
-  return finishKernel({
+  const kernel = finishKernel({
     cylinder, // boredCylinder: the kernel front's default composition is exactly right here
     box: (min, max) => wrap(makeBox(min, max)), prism, extrude, revolve, loft: loftOp, sweep, helixSweptTube,
     sphere: (r) => wrap(makeSphere(r)),
@@ -276,4 +276,5 @@ export function createOcctKernel(replicad) {
     shape2d,
     toSTEP: (named) => exportSTEP(named.map(({ name, solid }) => ({ name, shape: solid._s }))).arrayBuffer(),
   });
+  return kernel;
 }

package/src/framework/geometry/shape2d-sugar.js

@@ -1,11 +1,22 @@
-// Backend-shared Shape2D front. Like solid-sugar for Solids, but the 2-D shared
-// surface is small: .simple() unwraps a single-region materialization or throws.
-// Backends attach the geometry ops (booleans, area, boundingBox, toRegions).
-export function addShape2dSugar(s) {
+// Backend-shared Shape2D front. Like solid-sugar for Solids: backends attach the geometry
+// ops (booleans, area, boundingBox, toRegions); this layers on the backend-agnostic sugar.
+// `deps` are the backend's own functions the sugar defers to: `shape2d` (lift a region back
+// into a Shape2D) and `extrude`/`revolve` (build a Solid from this shape).
+export function addShape2dSugar(s, { shape2d, extrude, revolve }) {
+  // .simple() → the single {outer,holes} region, or throw (a raw region, not a Shape2D).
   s.simple = () => {
     const regions = s.toRegions();
     if (regions.length !== 1) throw new Error(`Shape2D.simple: result has ${regions.length} regions, not 1 (use toRegions())`);
     return regions[0];
   };
+  // .regions() → scission: each disjoint region as its own live Shape2D (booleanable further).
+  s.regions = () => s.toRegions().map((r) => shape2d(r));
+  // .extrude({ h, twist?, scaleTop? }) / .revolve({ degrees? }) → Solid. Sugar for
+  // k.extrude({ profile: shape, … }) / k.revolve({ profile: shape, … }). Passed as an
+  // options object (not positional) so the kernel op's key/required-arg validation still
+  // fires — e.g. a missing `h` throws "extrude: h is required" rather than silently
+  // producing empty geometry.
+  s.extrude = ({ h, twist, scaleTop } = {}) => extrude({ profile: s, h, twist, scaleTop });
+  s.revolve = ({ degrees } = {}) => revolve({ profile: s, degrees });
   return s;
 }

package/src/hull-sweep-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/hull-sweep.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/parts/hull-sweep.js

@@ -0,0 +1,70 @@
+// Demo part — a hull sweep. Showcases k.hull / k.hullChain: a row of circles of
+// varying radius along an arched spine becomes either one convex blob (k.hull) or a
+// smooth swept strap/taper (k.hullChain) — the capsule/rounded-slot/organic-taper
+// payoff. Optionally bores a hole at each node (Shape2D.cutAll) to make a linkage.
+// Open /hull-sweep.html after `npm run dev`. Toggle "Convex wrap" to see hull vs
+// hullChain side by side.
+import { circleProfile } from "partforge/geometry";
+
+export default {
+  meta: { title: "Hull sweep", units: "mm", background: 0x15181d },
+  parameters: [
+    {
+      id: "sweep",
+      title: "Sweep",
+      description: "A row of circles along an arched spine. `k.hullChain` sweeps the hull from one to the next (a strap/taper); `k.hull` wraps them all in one convex outline (see the Mode toggle).",
+      advanced: [
+        { key: "nodes", label: "Nodes", unit: "", min: 2, max: 6, step: 1,
+          description: "How many circles along the spine (2 = a single capsule)." },
+        { key: "length", label: "Length", unit: "mm", min: 20, max: 120, step: 1,
+          description: "Span from the first node to the last." },
+        { key: "r0", label: "Start radius", unit: "mm", min: 2, max: 16, step: 0.5,
+          description: "Radius of the first node." },
+        { key: "r1", label: "End radius", unit: "mm", min: 1, max: 16, step: 0.5,
+          description: "Radius of the last node — set it below the start for a taper." },
+        { key: "bow", label: "Arch", unit: "mm", min: 0, max: 30, step: 1,
+          description: "Vertical bow of the middle nodes. 0 = a straight strap; higher = a banana/arch." },
+      ],
+    },
+    {
+      id: "solid",
+      title: "Solid",
+      advanced: [
+        { key: "thickness", label: "Thickness", unit: "mm", min: 1.5, max: 10, step: 0.5,
+          description: "Extrude height." },
+      ],
+    },
+    {
+      id: "mode",
+      title: "Mode",
+      toggles: [
+        { key: "wrap", label: "Convex wrap (k.hull instead of k.hullChain)", on: 1,
+          description: "On: one convex hull of every node (a single convex blob). Off: the swept chain — the hull of each consecutive pair, unioned." },
+        { key: "holes", label: "Bore a hole at each node", on: 1,
+          description: "Cut a circular hole at every node (Shape2D.cutAll) — turns the strap into a linkage." },
+      ],
+    },
+  ],
+  defaults: { nodes: 3, length: 60, r0: 8, r1: 4, bow: 8, thickness: 4, wrap: 0, holes: 0 },
+  parts: {
+    sweep: {
+      label: "Hull sweep",
+      views: ["sweep"],
+      export: { name: "hull-sweep" },
+      build: (k, p) => {
+        const n = Math.max(2, Math.round(p.nodes));
+        const nodes = [];
+        for (let i = 0; i < n; i++) {
+          const t = i / (n - 1);
+          nodes.push({ x: -p.length / 2 + t * p.length, y: p.bow * Math.sin(Math.PI * t), r: p.r0 + (p.r1 - p.r0) * t });
+        }
+        const circles = nodes.map((nd) => circleProfile(nd.r, [nd.x, nd.y]));
+        let shape = p.wrap ? k.hull(circles) : k.hullChain(circles);
+        if (p.holes)
+          shape = shape.cutAll(nodes.map((nd) => circleProfile(Math.max(0.8, nd.r * 0.45), [nd.x, nd.y])));
+        return k.extrude({ profile: shape, h: p.thickness });
+      },
+    },
+  },
+  views: { sweep: { label: "Hull sweep" } },
+};