@bobfrankston/wallplater 1.0.6 → 1.0.7

package/README.md

@@ -14,6 +14,11 @@ separate, individually colourable objects) or per-part STLs.
 The manifold engine has no system dependency beyond Node and is the path
 forward; `-scad` is kept for parity/verification.
 
+If the `-scad` engine can't find OpenSCAD (neither the `openscad` config path nor
+`openscad` on `PATH`), it offers to install it for you — `winget` on Windows,
+`brew --cask` on macOS, `apt-get` on Linux — then re-checks. Decline (or a
+non-interactive stdin) exits with a hint to install manually or drop `-scad`.
+
 ## Build / install
 
 TypeScript compiled to co-located `.js` / `.d.ts` / `.map` (no `src`/`dist`
@@ -49,6 +54,13 @@ without manual assignment — provided the project has ≥2 filaments. The label
 objects sit flush in the plate's front-face pockets (printed front-face-down), so
 they look hidden in the viewport until coloured.
 
+The 3MF also embeds a **preview thumbnail** (`Metadata/thumbnail.png`, wired via
+the OPC thumbnail relationship) so Windows Explorer and slicers show an image of
+the plate. It's a pure-JS orthographic render of the front face in the configured
+`plateColor` / `accentColor` — no extra dependency, no STL/mesh rendering by the
+shell. (Without it, the file previews blank: the shell never renders the geometry
+itself, it only displays this embedded PNG.)
+
 ## Config
 
 Each specific config is **deep-merged over `defaults.json`** (in this
@@ -87,6 +99,9 @@ suffix) is treated as millimetres. Angles (e.g. `cskAngle`) are plain numbers.
 
 - `gangs[].type`: `"decora"` | `"duplex"` | `"blank"` | `"button"`.
 - `gangs[].screws`: `false` to omit that gang's screw holes (default true).
+- `gangs[].filler`: on a **blank** gang, marks it as backed by a filler/insert
+  plate, so its cover screws sit on the Decora line (wider spacing) instead of
+  the box-ear line.
 - `gangs[].legend`: single label centred above the gang's opening (positioned
   clear of the screw holes; `legendY` / `legendSize`).
 - `gangs[].breaker`: per-gang breaker/circuit label, lower-right of the opening
@@ -163,6 +178,27 @@ See `../decora_wallplate_spec.md` for the dimensional reference and print notes
 (print front-face-down; PETG/ASA recommended for heat near devices; keep plate
 and labels the same material family — see the chat note on ABS+PLA).
 
+### Appearance, output & engine
+
+Top-level keys (all have defaults in `defaults.json`):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `output` | `"3mf"` | `"3mf"` (multi-object + thumbnail), `"stl"` (one binary STL per part), or `"scad"` (write the `.scad` only, no render — implies the scad engine). |
+| `engine` | `"manifold"` | `"manifold"` (direct) or `"scad"` (OpenSCAD). `-scad` on the CLI forces scad. |
+| `plateColor` | `"#35589f"` | Plate (filament 1) colour — used for the embedded preview and the scad-engine preview. |
+| `accentColor` | `"#101010"` | Label (filament 2) colour, same uses. |
+| `printReady` | `true` | Flip the model front-face-down (rotate 180° about X) for printing. The preview camera follows the flip, so labels stay upright either way. |
+| `fontFile` | Arial Bold | Path to a `.ttf`/`.otf` for the **manifold** engine's text. |
+| `font` | Liberation Sans Bold | OpenSCAD fontconfig name for the **scad** engine's text. |
+| `openscad` | Program Files path | OpenSCAD executable; only used by the scad engine (auto-install offered if missing). |
+| `bevel` | `1.2mm` | Front-edge chamfer width. |
+| `labelDepth` | `0.6mm` | Recess depth of the label pockets / height of the label solids. |
+
+Plate geometry, opening sizes, screw spacing, etc. live under the `dims` object
+(see `defaults.json` for the full list, all unit-suffixed lengths). Override any
+single dim by deep-merge, e.g. `"dims": { "depth": "5mm" }`.
+
 ## Files
 
 - `index.ts` — CLI entry / engine dispatch / arg validation

package/index.js

@@ -15,9 +15,21 @@
 import { writeFileSync, unlinkSync } from "fs";
 import { basename, dirname, join } from "path";
 import { loadConfig } from "./config.js";
-import { generateScad, runOpenscad, readStl } from "./scad.js";
+import { generateScad, runOpenscad, readStl, ensureOpenscad } from "./scad.js";
 import { buildMeshes } from "./geometry.js";
 import { build3mf, writeBinaryStl } from "./threemf.js";
+// Preview-PNG view: both engines flip the model front-face-down when printReady
+// (rotate 180 about X -> front normal -Z, world-up -Y), so aim the thumbnail
+// camera at the readable front either way.
+function thumbView(cfg) {
+    const f = cfg.printReady;
+    return {
+        front: [0, 0, f ? -1 : 1],
+        up: [0, f ? -1 : 1, 0],
+        plateColor: cfg.plateColor,
+        accentColor: cfg.accentColor,
+    };
+}
 // Bambu object-list name: "<config> <part>"; the accent text object reads "labels".
 function partName(cfgName, label) {
     return `${cfgName} ${label === "legend" ? "labels" : label}`;
@@ -42,20 +54,21 @@ function runScadEngine(cfg, dir) {
     console.log("wrote", basename(scadPath));
     if (cfg.output === "scad")
         return;
+    const exe = ensureOpenscad(cfg.openscad); // verify/install OpenSCAD before any export
     const parts = partList(cfg);
     if (cfg.output === "stl") {
         for (const p of parts)
-            runOpenscad(cfg.openscad, scadPath, join(dir, `${cfg.name}_${p.label}.stl`), p.mode);
+            runOpenscad(exe, scadPath, join(dir, `${cfg.name}_${p.label}.stl`), p.mode);
     }
     else {
         const tmp = [];
         const objects = parts.map((p) => {
             const stl = join(dir, `_${cfg.name}_${p.label}.stl`);
-            runOpenscad(cfg.openscad, scadPath, stl, p.mode);
+            runOpenscad(exe, scadPath, stl, p.mode);
             tmp.push(stl);
             return { name: partName(cfg.name, p.label), mesh: readStl(stl), extruder: partExtruder(p.label) };
         });
-        writeFileSync(join(dir, `${cfg.name}.3mf`), build3mf(objects));
+        writeFileSync(join(dir, `${cfg.name}.3mf`), build3mf(objects, thumbView(cfg)));
         for (const t of tmp)
             unlinkSync(t);
         console.log("  wrote", `${cfg.name}.3mf`, `(${objects.length} objects: ${objects.map((o) => o.name).join(", ")})`);
@@ -75,7 +88,7 @@ async function runManifoldEngine(cfg, dir) {
     }
     else {
         const objects = meshes.map((m) => ({ name: partName(cfg.name, m.label), mesh: m.mesh, extruder: partExtruder(m.label) }));
-        writeFileSync(join(dir, `${cfg.name}.3mf`), build3mf(objects));
+        writeFileSync(join(dir, `${cfg.name}.3mf`), build3mf(objects, thumbView(cfg)));
         console.log("  wrote", `${cfg.name}.3mf`, `(${objects.length} objects: ${objects.map((o) => o.name).join(", ")})`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/wallplater",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "type": "module",
   "description": "JSON-driven wall-plate generator (Decora / duplex / blank). Direct-to-3MF via manifold-3d, with an optional OpenSCAD engine.",
   "main": "index.js",

package/scad.d.ts

@@ -1,6 +1,7 @@
 import { type Resolved } from "./config.js";
 import type { Mesh } from "./threemf.js";
 export declare function generateScad(cfg: Resolved): string;
+export declare function ensureOpenscad(exe: string): string;
 export declare function runOpenscad(exe: string, scadPath: string, outPath: string, mode: string): void;
 export declare function readStl(path: string): Mesh;
 //# sourceMappingURL=scad.d.ts.map

package/scad.js

@@ -4,8 +4,8 @@
  * one STL per colour part, and reads STLs back into the common Mesh shape.
  * Note: rocker/header labels are manifold-engine only and are not emitted here.
  */
-import { readFileSync } from "fs";
-import { execFileSync } from "child_process";
+import { readFileSync, existsSync, readSync } from "fs";
+import { execFileSync, spawnSync } from "child_process";
 import { basename } from "path";
 import { gangType } from "./config.js";
 function num(n) {
@@ -163,6 +163,68 @@ if (MODE == "preview") {
 else if (MODE == "legend")    oriented() legend_solids(LABEL_DEPTH);
 else if (MODE == "breaker")   oriented() breaker_solid(LABEL_DEPTH);
 `;
+// ----- OpenSCAD discovery + optional install -----
+// Return a runnable OpenSCAD command: the configured path if it exists, else a
+// bare "openscad(.exe)" if that's on PATH, else null.
+function findOpenscad(exe) {
+    if (exe && existsSync(exe))
+        return exe;
+    const probe = process.platform === "win32" ? "openscad.exe" : "openscad";
+    const r = spawnSync(probe, ["--version"], { stdio: "ignore" });
+    if (!r.error && r.status === 0)
+        return probe;
+    return null;
+}
+// Synchronous y/N prompt (CLI is otherwise synchronous). Non-TTY/EOF -> no.
+function promptYesNo(q) {
+    process.stdout.write(q);
+    const buf = Buffer.alloc(64);
+    try {
+        const n = readSync(0, buf, 0, buf.length, null);
+        const ans = buf.toString("utf8", 0, n).trim().toLowerCase();
+        return ans === "y" || ans === "yes";
+    }
+    catch {
+        return false; // stdin not readable (piped/CI) -> decline
+    }
+}
+// Platform install command for OpenSCAD: [exe, args].
+function installCmd() {
+    switch (process.platform) {
+        case "win32": return ["winget", ["install", "--id", "OpenSCAD.OpenSCAD", "-e",
+                "--accept-package-agreements", "--accept-source-agreements"]];
+        case "darwin": return ["brew", ["install", "--cask", "openscad"]];
+        default: return ["sudo", ["apt-get", "install", "-y", "openscad"]];
+    }
+}
+// Ensure OpenSCAD is available; offer to install it if not. Returns the command
+// to invoke, or exits the process if it can't be found/installed.
+export function ensureOpenscad(exe) {
+    const found = findOpenscad(exe);
+    if (found)
+        return found;
+    const [cmd, args] = installCmd();
+    const shown = `${cmd} ${args.join(" ")}`;
+    console.error(`OpenSCAD not found (looked for "${exe}" and "openscad" on PATH).`);
+    if (!promptYesNo(`Install it now with:\n    ${shown}\n? [y/N] `)) {
+        console.error("The -scad engine needs OpenSCAD. Install it, or drop -scad to use the default manifold engine.");
+        process.exit(1);
+    }
+    try {
+        execFileSync(cmd, args, { stdio: "inherit" });
+    }
+    catch {
+        console.error("Install failed. Install OpenSCAD manually: https://openscad.org/downloads.html");
+        process.exit(1);
+    }
+    const after = findOpenscad(exe);
+    if (!after) {
+        console.error('OpenSCAD installed but not yet found — open a new terminal (so PATH refreshes), or set "openscad" in your config to the full exe path.');
+        process.exit(1);
+    }
+    console.log("OpenSCAD installed.");
+    return after;
+}
 export function runOpenscad(exe, scadPath, outPath, mode) {
     const fmt = outPath.endsWith(".3mf") ? "3mf" : outPath.endsWith(".png") ? "png" : "binstl";
     execFileSync(exe, [`-D`, `MODE="${mode}"`, "--export-format", fmt, "-o", outPath, scadPath], { stdio: ["ignore", "ignore", "inherit"] });

package/threemf.d.ts

@@ -7,6 +7,14 @@ export interface Object3mf {
     mesh: Mesh;
     extruder?: number;
 }
-export declare function build3mf(objects: Object3mf[]): Buffer;
+export interface ViewOpts {
+    front?: number[];
+    up?: number[];
+    plateColor?: string;
+    accentColor?: string;
+    size?: number;
+}
+export declare function build3mf(objects: Object3mf[], view?: ViewOpts): Buffer;
+export declare function renderThumbnail(objects: Object3mf[], opts?: ViewOpts): Buffer;
 export declare function writeBinaryStl(mesh: Mesh): Buffer;
 //# sourceMappingURL=threemf.d.ts.map

package/threemf.js

@@ -5,12 +5,12 @@
  *     individually colourable objects), packed into the OPC zip by hand.
  *   - writeBinaryStl(): a single binary STL (used for the manifold STL path).
  */
-import { deflateRawSync } from "zlib";
+import { deflateRawSync, deflateSync } from "zlib";
 function xmlEscape(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 // ---------- multi-object 3MF (core spec, no slicer settings) ----------
-export function build3mf(objects) {
+export function build3mf(objects, view = {}) {
     // separate, named top-level objects (each individually selectable/colourable
     // in Bambu), all at the same transform so the labels stay seated in the
     // plate's pockets.
@@ -43,15 +43,21 @@ ${objects.map((o, i) => `  <object id="${i + 1}">
   </object>`).join("\n")}
 </config>
 `;
+    // Package thumbnail (PNG). Windows Explorer / slicers display this embedded
+    // image as the file's preview; they do NOT render the mesh themselves. It is
+    // wired up via the OPC thumbnail relationship below + the png content type.
+    const thumb = renderThumbnail(objects, view);
     const ct = `<?xml version="1.0" encoding="UTF-8"?>
 <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
  <Default Extension="model" ContentType="application/vnd.ms-package.3dmanufacturing-3dmodel+xml"/>
+ <Default Extension="png" ContentType="image/png"/>
 </Types>
 `;
     const rels = `<?xml version="1.0" encoding="UTF-8"?>
 <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
  <Relationship Target="/3D/3dmodel.model" Id="rel0" Type="http://schemas.microsoft.com/3dmanufacturing/2013/01/3dmodel"/>
+ <Relationship Target="/Metadata/thumbnail.png" Id="rel-thumb" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail"/>
 </Relationships>
 `;
     return zip([
@@ -59,8 +65,137 @@ ${objects.map((o, i) => `  <object id="${i + 1}">
         { name: "_rels/.rels", data: Buffer.from(rels) },
         { name: "3D/3dmodel.model", data: Buffer.from(model) },
         { name: "Metadata/model_settings.config", data: Buffer.from(settings) },
+        { name: "Metadata/thumbnail.png", data: thumb },
     ]);
 }
+// ---------- preview thumbnail (orthographic, pure-JS, no deps) ----------
+function hexRgb(s, fallback) {
+    const m = /^#?([0-9a-fA-F]{6})$/.exec(s ?? "");
+    if (!m)
+        return fallback;
+    const n = parseInt(m[1], 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+function vcross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function vdot(a, b) { return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]; }
+function vnorm(a) { const l = Math.hypot(a[0], a[1], a[2]) || 1; return [a[0] / l, a[1] / l, a[2] / l]; }
+// Render a top-down (front-facing) orthographic preview of all objects to a PNG.
+// Plate-extruder parts take plateColor, accent parts accentColor; a fixed light
+// gives the flat face a little form. Background is transparent.
+export function renderThumbnail(objects, opts = {}) {
+    const S = opts.size ?? 320;
+    const front = vnorm(opts.front ?? [0, 0, 1]);
+    const up = vnorm(opts.up ?? [0, 1, 0]);
+    const right = vnorm(vcross(up, front)); // right,up,front right-handed -> non-mirrored
+    const camUp = up;
+    const plateC = hexRgb(opts.plateColor, [120, 140, 200]);
+    const accentC = hexRgb(opts.accentColor, [20, 20, 24]);
+    // light from upper-left-front in screen space, expressed in world coords
+    const light = vnorm([
+        -0.4 * right[0] + 0.5 * camUp[0] + 0.9 * front[0],
+        -0.4 * right[1] + 0.5 * camUp[1] + 0.9 * front[1],
+        -0.4 * right[2] + 0.5 * camUp[2] + 0.9 * front[2],
+    ]);
+    const AMBIENT = 0.45;
+    const tris = [];
+    let uMin = Infinity, uMax = -Infinity, vMin = Infinity, vMax = -Infinity;
+    for (const o of objects) {
+        const col = (o.extruder ?? 1) === 1 ? plateC : accentC;
+        const pv = o.mesh.verts.map((p) => [vdot(p, right), vdot(p, camUp), vdot(p, front)]);
+        for (const p of pv) {
+            if (p[0] < uMin)
+                uMin = p[0];
+            if (p[0] > uMax)
+                uMax = p[0];
+            if (p[1] < vMin)
+                vMin = p[1];
+            if (p[1] > vMax)
+                vMax = p[1];
+        }
+        for (const t of o.mesh.tris) {
+            const a = o.mesh.verts[t[0]], b = o.mesh.verts[t[1]], c = o.mesh.verts[t[2]];
+            const n = vnorm(vcross([b[0] - a[0], b[1] - a[1], b[2] - a[2]], [c[0] - a[0], c[1] - a[1], c[2] - a[2]]));
+            if (vdot(n, front) <= 0)
+                continue; // cull faces pointing away from viewer
+            const inten = AMBIENT + (1 - AMBIENT) * Math.max(0, vdot(n, light));
+            const shade = [
+                Math.min(255, col[0] * inten), Math.min(255, col[1] * inten), Math.min(255, col[2] * inten),
+            ];
+            const A = pv[t[0]], B = pv[t[1]], C = pv[t[2]];
+            tris.push({ x: [A[0], B[0], C[0]], y: [A[1], B[1], C[1]], z: [A[2], B[2], C[2]], col: shade });
+        }
+    }
+    const pad = Math.round(S * 0.08);
+    const span = Math.max(uMax - uMin, vMax - vMin, 1e-6);
+    const scale = (S - 2 * pad) / span;
+    const ox = pad + (S - 2 * pad - (uMax - uMin) * scale) / 2;
+    const oy = pad + (S - 2 * pad - (vMax - vMin) * scale) / 2;
+    const sx = (u) => ox + (u - uMin) * scale;
+    const sy = (v) => S - (oy + (v - vMin) * scale); // flip: image row 0 is top
+    const rgba = Buffer.alloc(S * S * 4); // transparent background
+    const zbuf = new Float32Array(S * S).fill(-Infinity);
+    for (const tr of tris) {
+        const px = [sx(tr.x[0]), sx(tr.x[1]), sx(tr.x[2])];
+        const py = [sy(tr.y[0]), sy(tr.y[1]), sy(tr.y[2])];
+        const area = (px[1] - px[0]) * (py[2] - py[0]) - (px[2] - px[0]) * (py[1] - py[0]);
+        if (Math.abs(area) < 1e-9)
+            continue;
+        const minX = Math.max(0, Math.floor(Math.min(px[0], px[1], px[2])));
+        const maxX = Math.min(S - 1, Math.ceil(Math.max(px[0], px[1], px[2])));
+        const minY = Math.max(0, Math.floor(Math.min(py[0], py[1], py[2])));
+        const maxY = Math.min(S - 1, Math.ceil(Math.max(py[0], py[1], py[2])));
+        for (let yy = minY; yy <= maxY; yy++) {
+            for (let xx = minX; xx <= maxX; xx++) {
+                const cx = xx + 0.5, cy = yy + 0.5;
+                const w0 = ((px[1] - cx) * (py[2] - cy) - (px[2] - cx) * (py[1] - cy)) / area;
+                const w1 = ((px[2] - cx) * (py[0] - cy) - (px[0] - cx) * (py[2] - cy)) / area;
+                const w2 = 1 - w0 - w1;
+                if (w0 < 0 || w1 < 0 || w2 < 0)
+                    continue;
+                const z = w0 * tr.z[0] + w1 * tr.z[1] + w2 * tr.z[2];
+                const idx = yy * S + xx;
+                if (z <= zbuf[idx])
+                    continue;
+                zbuf[idx] = z;
+                const o4 = idx * 4;
+                rgba[o4] = tr.col[0];
+                rgba[o4 + 1] = tr.col[1];
+                rgba[o4 + 2] = tr.col[2];
+                rgba[o4 + 3] = 255;
+            }
+        }
+    }
+    return encodePng(S, S, rgba);
+}
+// minimal 8-bit RGBA PNG (single IDAT, no filtering)
+function encodePng(width, height, rgba) {
+    const chunk = (type, data) => {
+        const t = Buffer.from(type, "latin1");
+        const len = Buffer.alloc(4);
+        len.writeUInt32BE(data.length, 0);
+        const crc = Buffer.alloc(4);
+        crc.writeUInt32BE(crc32(Buffer.concat([t, data])), 0);
+        return Buffer.concat([len, t, data, crc]);
+    };
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8;
+    ihdr[9] = 6;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0; // 8-bit, RGBA
+    const row = width * 4;
+    const raw = Buffer.alloc(height * (1 + row));
+    for (let y = 0; y < height; y++) {
+        raw[y * (1 + row)] = 0; // filter: none
+        rgba.copy(raw, y * (1 + row) + 1, y * row, (y + 1) * row);
+    }
+    const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    return Buffer.concat([sig, chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw)), chunk("IEND", Buffer.alloc(0))]);
+}
 // ---------- binary STL (single object) ----------
 export function writeBinaryStl(mesh) {
     const buf = Buffer.alloc(84 + mesh.tris.length * 50);