partforge 0.96.0 → 0.97.0

package/src/framework/panel/widgets/image.js

@@ -0,0 +1,164 @@
+// The `type: "image"` control. Its VALUE is an image source — either a URL
+// string (the same grammar `PartDefinition.images` already accepts) or raw PNG
+// bytes (an ArrayBuffer/typed array): the partforge-cloud sandbox cannot fetch
+// URLs, so it puts the bytes straight in the param. Everything downstream
+// (presets, undo, the params hash, `when`) works with either shape, no special
+// case — this widget is the only place on the main thread that has to look at
+// the difference.
+//
+// Two renderings, mirroring widgets/font.js exactly. With a host-supplied
+// `imageCatalog` it is a button — a thumbnail + label — opening the picker.
+// Without one it degrades to a URL text field, so a standalone partforge app
+// (which ships no catalog) still exposes the parameter.
+//
+// Main-thread only: the preview is a plain `<img>` bound to the source URL —
+// the browser decodes the PNG natively. Do NOT import `png-decode.js` (or
+// anything from images.js) here; that decoder belongs to the worker's build
+// path, not the panel.
+import { attachInfo } from "../info.js";
+import { IMAGE_ALLOW_DEFAULT, imageSourceAllowed } from "../../image-source.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+const isBytes = (v) => v instanceof ArrayBuffer || ArrayBuffer.isView(v);
+
+// A URL source → its filename, for a label with no catalog to ask. A byte
+// value has no filename — callers check `isBytes` first and never reach this
+// for one. Not a source to fetch, never a source to warn about: `isNoImageSource`
+// values (unset/"") read as "No image" rather than a broken link.
+export function imageLabel(source) {
+  if (typeof source !== "string" || !source) return "No image";
+  let path = source;
+  try { path = new URL(source).pathname; } catch { /* not a URL — use the raw string */ }
+  const file = path.split("/").filter(Boolean).pop();
+  return file || source;
+}
+
+// Point (or unpoint) the live preview. A byte-valued param has no URL to hand
+// the browser, so the image stays hidden rather than trying to render it or
+// showing a broken-image glyph — same rule an empty/unset value gets. `onerror`
+// covers the other broken-image case: a URL that 404s or that CORS refuses.
+function paintPreview(img, source) {
+  if (typeof source === "string" && source) {
+    img.hidden = false;
+    img.src = source;
+  } else {
+    img.hidden = true;
+    img.removeAttribute("src");
+  }
+}
+
+export function makeImage(node, params, { onChange, onCommit, info, imageCatalog } = {}) {
+  const allow = Array.isArray(node.allow) && node.allow.length ? node.allow : IMAGE_ALLOW_DEFAULT;
+  const wrap = el("div", "slider");
+  const row = el("div", "row");
+  const label = el("label", "", node.label ?? node.key);
+  attachInfo(label, node.description, info);
+  row.append(label);
+  wrap.append(row);
+
+  const preview = document.createElement("img");
+  preview.className = "image-preview";
+  preview.alt = "";
+  preview.hidden = true;
+  // A URL that fails to load (404, CORS, revoked link) must degrade to hidden,
+  // not the browser's broken-image glyph.
+  preview.addEventListener("error", () => { preview.hidden = true; });
+  wrap.append(preview);
+
+  if (!imageCatalog) {
+    // Degraded path: a URL field. Unlike `text`, it does NOT write on every
+    // keystroke — a half-typed URL is a guaranteed failed fetch, and the
+    // rebuild loop would chase every one of them.
+    const field = document.createElement("input");
+    field.type = "text";
+    field.className = "text-input";
+    const paintField = () => {
+      const v = params[node.key];
+      // Bytes cannot round-trip through a text field — `String(arrayBuffer)`
+      // is "[object ArrayBuffer]", not a value anyone typed. Show an honest
+      // placeholder instead of that, and leave the field free to type a
+      // replacement URL over it.
+      field.value = isBytes(v) ? "" : String(v ?? "");
+      field.placeholder = isBytes(v) ? "Uploaded image" : "";
+      field.classList.remove("warn");
+      paintPreview(preview, v);
+    };
+    field.addEventListener("change", () => {
+      if (!imageSourceAllowed(field.value, allow)) { field.classList.add("warn"); return; }
+      field.classList.remove("warn");
+      params[node.key] = field.value;
+      onChange?.();
+      onCommit?.();
+    });
+    paintField();
+    wrap.append(field);
+    return { el: wrap, sync: paintField };
+  }
+
+  const btn = el("button", "image-btn");
+  btn.type = "button";
+  const thumb = document.createElement("img");
+  thumb.className = "image-btn-thumb";
+  thumb.alt = "";
+  thumb.hidden = true;
+  thumb.addEventListener("error", () => { thumb.hidden = true; });
+  const iname = el("span", "iname");
+  btn.append(thumb, iname);
+  btn.insertAdjacentHTML("beforeend",
+    '<svg class="caret" width="8" height="7" viewBox="0 0 8 7" aria-hidden="true"><polygon points="0,0 8,0 4,7" fill="currentColor"/></svg>');
+  wrap.append(btn);
+
+  // The value alone cannot describe a byte-valued source, and even a URL's
+  // filename is a guess a catalog can improve on. `describe` is optional and
+  // may be async, so the label is painted twice: an immediate honest guess,
+  // then the catalog's answer when it lands (same two-pass shape as font.js's
+  // `paint`, `paintSeq` included so a stale describe() can't win a race
+  // against a newer one).
+  let paintSeq = 0;
+  const paint = () => {
+    const src = params[node.key];
+    const seq = ++paintSeq;
+    paintPreview(preview, src);
+    paintPreview(thumb, src);
+    const show = ({ label: text, width, height }) => {
+      if (seq !== paintSeq) return;                  // a newer paint already won
+      iname.textContent = width && height ? `${text} (${width}×${height})` : text;
+    };
+    show(isBytes(src) ? { label: "Uploaded image" } : { label: imageLabel(src) });
+    if (typeof imageCatalog.describe !== "function") return;
+    Promise.resolve()
+      .then(() => imageCatalog.describe(src))
+      .then((d) => {
+        if (!d) return;
+        show({ label: d.label ?? (isBytes(src) ? "Uploaded image" : imageLabel(src)), width: d.width, height: d.height });
+      })
+      .catch(() => { /* a failed lookup keeps the immediate label */ });
+  };
+  paint();
+
+  // The picker registers itself through setImagePicker (see below); with no
+  // picker in the bundle the button is inert rather than broken.
+  //
+  // The handle is kept because the picker is a TAKEOVER: it appends itself to
+  // the rail, outside the panel root, so tearing the panel down does not take it
+  // with it. Without dispose() the element — and the `document` keydown listener
+  // that only close() unhooks — would outlive the panel holding a stale `params`.
+  let picker = null;
+  btn.addEventListener("click", () => {
+    picker = openImagePicker?.({ node, params, allow, imageCatalog, anchor: wrap, onPicked: () => { paint(); onChange?.(); onCommit?.(); } }) ?? null;
+  });
+
+  return { el: wrap, sync: paint, dispose: () => { picker?.close(); picker = null; } };
+}
+
+// Assigned by image-picker.js, which widgets/index.js imports for the side
+// effect. Kept as a mutable binding rather than a static import so this file
+// stays usable — and testable — without dragging the whole picker in.
+export let openImagePicker = null;
+export const setImagePicker = (fn) => { openImagePicker = fn; };

package/src/framework/panel/widgets/index.js

@@ -5,12 +5,15 @@ import { makeText } from "./text.js";
 import { makeCheckbox } from "./checkbox.js";
 import { makeSelect, makeRadio } from "./select.js";
 import { makeFont } from "./font.js";
-// Side-effect import: font-picker.js calls setFontPicker() at module scope, so
-// the font widget's button finds a picker to open. It lives HERE and not in
-// font.js because the dependency has to run picker → widget and never back —
-// font.js must stay importable (and testable) without dragging the whole
-// DOM-heavy picker in. See the note at the bottom of font.js.
+import { makeImage } from "./image.js";
+// Side-effect imports: font-picker.js / image-picker.js call setFontPicker() /
+// setImagePicker() at module scope, so each widget's button finds a picker to
+// open. They live HERE and not in font.js/image.js because the dependency has
+// to run picker → widget and never back — those files must stay importable
+// (and testable) without dragging the whole DOM-heavy picker in. See the note
+// at the bottom of font.js.
 import "../font-picker.js";
+import "../image-picker.js";
 
 export const WIDGET_FACTORIES = {
   slider: makeNumeric,
@@ -21,4 +24,5 @@ export const WIDGET_FACTORIES = {
   select: makeSelect,
   radio: makeRadio,
   font: makeFont,
+  image: makeImage,
 };

package/src/framework/param-deps.js

@@ -3,6 +3,7 @@
 // affect what's visible. Pure — no DOM, no real geometry (reuses the geometry-free
 // probe kernel). Errs toward RELEVANT_ALL whenever it can't analyze a build.
 import { createProbeKernel } from "./geometry/probe.js";
+import { byteAwareReplacer } from "./geometry/solid-hash.js";
 import { viewSubParts } from "./part-model.js";
 import { resolveDerived } from "./derive.js";
 
@@ -125,7 +126,11 @@ export function subPartReadKeys(part, view, params) {
 }
 
 // Stable string of the given param keys' current values — the cache-validity key
-// for one sub-part. Sorted so key order never affects the result.
+// for one sub-part. Sorted so key order never affects the result. `byteAwareReplacer`
+// substitutes a content fingerprint for a byte-valued param (an ArrayBuffer/typed-array
+// image source — see its own header) so JSON.stringify's default handling doesn't
+// collapse every image to the same "{}" (cache never invalidates) or expand a typed
+// array to one JSON number per byte (see solid-hash.js).
 export function relevanceHash(keys, params) {
-  return JSON.stringify(keys.slice().sort().map((k) => [k, params[k]]));
+  return JSON.stringify(keys.slice().sort().map((k) => [k, params[k]]), byteAwareReplacer);
 }

package/src/index.js

@@ -4,3 +4,4 @@
 // Part build functions import geometry helpers from "partforge/geometry" instead.
 export { mount } from "./framework/index.js";
 export { viewSubParts } from "./framework/part-model.js";
+export { imageToPng } from "./framework/image-ingest.js";

package/src/parts/relief.js

@@ -0,0 +1,84 @@
+// Reference part for the `images` field / `type: "image"` control / `k.heightfield`
+// (docs/AUTHORING-PARTS.md "Image controls"): a depth map becomes a printable relief
+// plate. `relief` is a `type: "image"` control — pick a replacement PNG from the
+// panel, or leave it empty and the bundled `assets/relief-demo.png` (a synthetic
+// concentric-ripple depth map) is used, so the part builds with no network access
+// and `partforge measure`/CI never need to fetch anything. `pitch` trades sampling
+// detail against triangle count — and therefore STEP size, since a fine pitch on a
+// high-frequency image produces many non-coplanar faces (see heightfieldMesh's own
+// STEP-size warning in the OCCT backend).
+//
+// DEMO_RELIEF_RANGE: the bundled asset's luminance only spans ~39–75% of the
+// 16-bit sample range (measured: 25443–48830 of 65535) — the ripple formula that
+// generated it decays toward its 50%-gray baseline away from the first ring, so
+// most pixels sit close to mid-gray. `k.heightfield`'s default `range: [0, 1]` is
+// an IDENTITY map (raw sample value straight to 0..1), not an auto-normalize, so
+// left alone the demo would use well under half of `maxZ`. This stretches the
+// default asset's own measured extent to the full 0..1 span so the shipped demo
+// shows the full relief amplitude. Applied only when the bundled default is in
+// use (`p.relief` empty) — a picked custom image's tonal range is unknown ahead
+// of build time, so it gets the identity range instead.
+export const DEMO_RELIEF_RANGE = [25443 / 65535, 48830 / 65535];
+
+export default {
+  meta: { title: "Relief plate", units: "mm", background: 0x15181d },
+  parameters: [
+    {
+      id: "image",
+      title: "Image",
+      description: "The depth map the relief is sampled from. Bright = high, dark = low, unless inverted.",
+      controls: [
+        { key: "relief", type: "image", label: "Depth map",
+          description: "Pick a PNG from the catalog or paste a URL. Empty falls back to the bundled sample ripple." },
+        { key: "invert", type: "checkbox", label: "Invert",
+          description: "Swap which end of the image is raised — bright becomes low, dark becomes high." },
+      ],
+    },
+    {
+      id: "plate",
+      title: "Plate",
+      description: "Footprint and relief depth of the printed plate.",
+      advanced: [
+        { key: "w", label: "Width", unit: "mm", min: 20, max: 200, step: 1,
+          description: "Plate footprint along X." },
+        { key: "d", label: "Depth", unit: "mm", min: 20, max: 200, step: 1,
+          description: "Plate footprint along Y." },
+        { key: "base", label: "Base", unit: "mm", min: 0.5, max: 10, step: 0.1,
+          description: "Solid slab thickness under the relief — keep it thick enough to print flat and stay rigid." },
+        { key: "maxZ", label: "Relief height", unit: "mm", min: 0.2, max: 10, step: 0.1,
+          description: "How far the tallest sample rises above the base." },
+        { key: "pitch", label: "Detail", unit: "mm", min: 0.2, max: 2, step: 0.1,
+          description: "Grid spacing of the height sampling. Smaller is crisper but costs more triangles — see the file header." },
+      ],
+    },
+  ],
+  defaults: { relief: "", invert: 0, w: 60, d: 60, base: 1.5, maxZ: 3, pitch: 0.5 },
+  // The default is the bundled asset, so the part builds offline; a picked value
+  // (a URL or catalog source from the `type: "image"` control) replaces it.
+  images: (p) => ({
+    relief: p.relief || new URL("./assets/relief-demo.png", import.meta.url),
+  }),
+  parts: {
+    plate: {
+      label: "Relief plate",
+      views: ["relief"],
+      export: { name: "relief" },
+      build: (k, p) => k.heightfield("relief", {
+        w: p.w, d: p.d, base: p.base, maxZ: p.maxZ, pitch: p.pitch, invert: p.invert,
+        ...(p.relief ? {} : { range: DEMO_RELIEF_RANGE }),
+      }),
+    },
+  },
+  views: { relief: { label: "Relief" } },
+  // Self-verification: a heightfield solid is watertight and hole-free by
+  // construction (grid + skirt + cap, no cuts) — this pins that invariant rather
+  // than asserting anything image-specific. bbox bounds catch a runaway parameter;
+  // fdm-pla opts into the bed-fit gate for a plate meant to actually be printed.
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      plate: { watertight: true, holes: 0, bbox: "<=[200,200,20]" },
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/src/relief-worker.js

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

package/src/testing/manifold.js

@@ -6,11 +6,12 @@ import { createManifoldKernel } from "../framework/geometry/manifold-backend.js"
 import { resolveFonts } from "../framework/fonts.js";
 import { normalizeOpentype, parseFont } from "../framework/geometry/opentype-interop.js";
 import { ensureImports } from "../framework/imports.js";
+import { ensureImages } from "../framework/images.js";
 import { ensureVectors } from "../framework/vectors.js";
 import { nodeAssetSources } from "./assets.js";
 import { tessellateStepAssets } from "./step-mesh.js";
 
-export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes, vectors } = {}) {
+export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes, images, vectors } = {}) {
   const wasm = await Module();
   wasm.setup();
   const kernel = createManifoldKernel(wasm, { quality });
@@ -25,6 +26,11 @@ export async function bootManifoldKernel({ quality = "preview", fonts, imports,
     const meshes = importMeshes ?? (stepEntries.length ? await tessellateStepAssets(stepEntries) : null);
     await ensureImports(kernel, decl, meshes);
   }
+  // Third asset sibling: register declared images the same way as fonts/imports
+  // above, so a part using `k.heightfield` builds headlessly instead of hitting
+  // `heightfield: unknown image "…"` — file: sources need the same Node mapping
+  // (global fetch can't read them) that fonts/imports get from nodeAssetSources.
+  if (images && Object.keys(images).length) await ensureImages(kernel, nodeAssetSources(images));
   if (vectors) await ensureVectors(kernel, nodeAssetSources(vectors));
   return kernel;
 }

package/src/testing/occt.js

@@ -8,10 +8,11 @@ import { createOcctKernel } from "../framework/geometry/occt-backend.js";
 import { resolveFonts } from "../framework/fonts.js";
 import { normalizeOpentype, parseFont } from "../framework/geometry/opentype-interop.js";
 import { ensureImports } from "../framework/imports.js";
+import { ensureImages } from "../framework/images.js";
 import { ensureVectors } from "../framework/vectors.js";
 import { nodeAssetSources } from "./assets.js";
 
-export async function bootOcctKernel({ fonts, imports, importMeshes, vectors } = {}) {
+export async function bootOcctKernel({ fonts, imports, importMeshes, images, vectors } = {}) {
   const require = createRequire(import.meta.url);
   globalThis.require = globalThis.require ?? require;
   globalThis.__dirname = globalThis.__dirname ?? path.dirname(fileURLToPath(import.meta.url));
@@ -23,6 +24,8 @@ export async function bootOcctKernel({ fonts, imports, importMeshes, vectors } =
   if (fonts) { const opentype = normalizeOpentype(await import("opentype.js"));
     for (const [name, buf] of await resolveFonts(nodeAssetSources(fonts))) kernel._fonts.set(name, parseFont(opentype, buf, name)); }
   if (imports) await ensureImports(kernel, nodeAssetSources(imports), importMeshes ?? null);
+  // Third asset sibling: see bootManifoldKernel's matching comment.
+  if (images && Object.keys(images).length) await ensureImages(kernel, nodeAssetSources(images));
   if (vectors) await ensureVectors(kernel, nodeAssetSources(vectors));
   return kernel;
 }

package/types/index.d.ts

@@ -454,3 +454,16 @@ export function viewSubParts(
   view: string,
   params: Record<string, ParamValue>,
 ): string[];
+
+export interface ImageToPngOptions {
+  /** Long-edge cap in px; an image already under this is not upscaled. Default 1024. */
+  maxSize?: number;
+}
+
+/**
+ * Convert any image the browser can decode into a PNG `Blob`, downsampling the
+ * long edge to `maxSize` on the way. Main-thread only (uses `createImageBitmap`
+ * and a canvas) — for a host normalising uploads before storing them, since a
+ * part's `images` field decodes PNG only. Never call from a part's `build`.
+ */
+export function imageToPng(fileOrBlob: Blob | File, options?: ImageToPngOptions): Promise<Blob>;

package/types/kernel.d.ts

@@ -481,6 +481,31 @@ export interface Vector2dOptions {
 /** Anything `k.hull`/`k.hullChain` accepts as one input. */
 export type HullInput = Shape2D | Contour;
 
+/** An inline depth-map grid, row-major, 0..65535 per sample. */
+export interface HeightfieldGrid {
+  width: number;
+  height: number;
+  data: Uint16Array;
+}
+
+/** k.heightfield — a depth map as a relief solid. */
+export interface HeightfieldOptions {
+  w: number;
+  d: number;
+  /** Slab thickness under the relief (mm, > 0). Default 1. */
+  base?: number;
+  /** Relief height above `base` at a full-scale (1.0) sample. Default 1. */
+  maxZ?: number;
+  /** Sample spacing (mm, > 0); clamped to a vertex budget with a build warning. Default 0.5. */
+  pitch?: number;
+  /** Flip sampled value as `1 - v`, applied after `range`. */
+  invert?: boolean;
+  /** Remap with clamped ends: `range[0]` -> 0, `range[1]` -> 1. Default [0, 1]. */
+  range?: [number, number];
+  /** Footprint placement in XY only — the base always sits at z = 0. Default "center". */
+  origin?: "center" | "corner";
+}
+
 // --- the kernel -------------------------------------------------------------
 
 /**
@@ -541,6 +566,13 @@ export interface GeometryKernel {
    * side-channel (not a part author's calling surface).
    */
   import(name: string): Solid;
+  /**
+   * A depth map as a relief solid. `nameOrGrid` is a name declared in the part's
+   * `images` field, or an inline grid — the name path is registered pre-build by
+   * the framework via the underscore-prefixed `_registerImage` side-channel (not
+   * a part author's calling surface).
+   */
+  heightfield(nameOrGrid: string | HeightfieldGrid, opts: HeightfieldOptions): Solid;
 
   // Backend-optional: the sub-part cache brackets and WASM lifetime hooks. Every
   // framework caller reaches these through `?.`, so a third-party backend may

package/types/part.d.ts

@@ -257,6 +257,21 @@ export type FontSource =
 
 type FontSourceValue = string | ArrayBuffer | ArrayBufferView | { default: string };
 
+// --- images -----------------------------------------------------------------
+
+/**
+ * One entry of a part's `images` map: raw bytes, a URL string, or a thunk
+ * returning either (a Vite `() => import("./x.png")` resolves to
+ * `{ default: url }`). Resolved to a decoded luminance grid before the
+ * synchronous `build` runs — the source `k.heightfield()` samples.
+ */
+export type ImageSource =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | (() => ImageSourceValue | Promise<ImageSourceValue>);
+
+type ImageSourceValue = string | ArrayBuffer | ArrayBufferView | { default: string };
 // --- imports and vectors ------------------------------------------------------
 
 /**
@@ -604,6 +619,12 @@ export interface PartDefinition<P = ResolvedParams, D = Derived> {
   defaults: Defaults;
   /** Outline fonts a part's `k.text2d()` calls need, as `{ name: source }`. */
   fonts?: Record<string, FontSource>;
+  /**
+   * Depth-map images a part's `k.heightfield()` calls need, as
+   * `{ name: source }` — or a function of the resolved params returning that
+   * map, which is what lets a `type: "image"` control drive the source.
+   */
+  images?: Record<string, ImageSource> | ((p: P) => Record<string, ImageSource>);
   /** STEP/STL/3MF files a part's `k.import()` calls need, as `{ name: source }`. */
   imports?: Record<string, ImportSource>;
   /** Vector artwork a part's `k.vector2d()` calls place, as `{ name: source }`. */