@chestnutlabs/gcode-model-renderer 0.7.0 → 0.8.1

package/README.md

@@ -0,0 +1,61 @@
+# @chestnutlabs/gcode-model-renderer
+
+Three.js **presentation** renderer for source models — draws an `.stl` or `.3mf` mesh as a clean,
+studio-lit thumbnail. It answers *"what object is this?"*, and is deliberately **separate** from the
+toolpath renderer, which answers *"how does this print/cut run?"* (design: DD-018).
+
+> **Peer dependency:** `three` (supported range `^0.178.0`) — install it alongside this package.
+
+![Two presentation thumbnails: a neutral gray STL part (materials: unavailable) beside a red/amber/green three-object 3MF (materials: known)](https://raw.githubusercontent.com/ChestnutLabs/gcode-preview/dev/docs/media/model-render-stl-3mf.png)
+
+Use it for file-browser thumbnails, library cards, and "what's in this file" previews — the picture a
+slicer shows of a part, not the toolpath. For inspecting the actual moves (layers, travel, seams,
+color modes, live progress), use [`@chestnutlabs/gcode-renderer-three`](../gcode-renderer-three)
+instead.
+
+- **STL and 3MF** — a bare STL is a single object with no declared material; a 3MF brings its own
+  multi-object structure, per-object transforms, and per-object / per-triangle material colors,
+  including files that use the 3MF **Production Extension** (`p:path` external parts).
+- **Production multicolor** — real Bambu Studio / OrcaSlicer files paint per-region color with a
+  proprietary `paint_color` facet attribute and keep the palette in `project_settings.config`, not in
+  standard 3MF materials. The renderer decodes that facet-paint format (clean-room, see
+  [RR-005](../../docs/research/RR-005-3mf-paint-color-facet-format.md)) and reads the `filament_colour`
+  palette itself, so a designer's multicolor model renders in its true colors without slicing.
+- **Capability-honest color** — when the source declares colors — standard 3MF `basematerials`, or
+  `paint_color` + a filament palette — the render uses them and reports `materials: 'known'`
+  (`'approximated'` when a handful of multi-color facets are flattened). When it declares none — a
+  plain STL, or a paint format with no palette present — it draws a neutral default and reports
+  `materials: 'unavailable'`. It never invents a source color.
+- **Fixed presentation pose** — framed at a 3/4 angle on the shared render "stage" from
+  `@chestnutlabs/gcode-renderer-three`, under a neutral studio light rig, on a transparent (default)
+  or solid background you can composite onto a card.
+- **Headless still** — `renderModelStill` mirrors the toolpath side's `renderStill`: hand it bytes,
+  get back a canvas plus a stable `cacheKey` and the `materials` confidence for that render. Runs in
+  any Chromium-class WebGL2 context (an `OffscreenCanvas` in a Worker, or headless Chromium).
+- **Three-free public types** — `ModelScene` / `ModelObject` / `MeshGeometry` are plain typed arrays,
+  so the package's surface never leaks `three`; the renderer builds three meshes internally.
+
+```ts
+import { renderModelStill } from '@chestnutlabs/gcode-model-renderer';
+
+// In a Worker with an OffscreenCanvas, or headless Chromium:
+const { canvas, objectCount, materials, cacheKey } = await renderModelStill(
+  { kind: '3mf', bytes },                        // or { kind: 'stl', bytes }
+  { canvas: new OffscreenCanvas(512, 512), background: 'transparent' }
+);
+// materials === 'known'  → the render used colors the file declared
+// materials === 'unavailable' → the file carried none; a neutral default was used (never faked)
+const blob = await canvas.convertToBlob();
+```
+
+Already hold a corrected or richer filament palette (e.g. re-rendering a sliced file)? Pass
+`filamentPalette` (hex per 0-based slot) to `renderModelStill` / `parse3mf` to override the one read
+from `project_settings.config`. Optional — the renderer reads the file's own palette without it.
+
+Want to build your own scene or drive the renderer interactively? `parseStl` / `parse3mf` return a
+three-free `ModelScene`, and `ModelRenderer` renders one onto a canvas you own.
+
+Determinism: same input + same environment ⇒ identical output. Cross-GPU/driver pixel identity is not
+promised — cache by the returned `cacheKey`.
+
+Part of [Chestnut Labs G-code Preview](../../README.md) · MIT

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { renderModelStill } from './render-model-still.js';
 export type { ModelSource, RenderModelStillOptions, RenderModelStillResult } from './render-model-still.js';
 export { parseStl } from './stl.js';
 export { parse3mf } from './three-mf.js';
+export type { Parse3mfOptions } from './three-mf.js';
 export { computeCacheKey, defaultEnvId } from './cache-key.js';
 export { DEFAULT_LIMITS, resolveLimits, ModelParseError } from './limits.js';
 export type { ModelLimits, ResolvedLimits } from './limits.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAC5G,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAC5G,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/render-model-still.d.ts

@@ -33,6 +33,12 @@ export interface RenderModelStillOptions {
     view?: PresentationView;
     createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
     limits?: ModelLimits;
+    /**
+     * Override the 3MF source-model filament palette (hex `#RRGGBB` per 0-based slot) used to colour
+     * `paint_color` facets, instead of the file's own `project_settings.config`. Niche: for consumers
+     * re-rendering a file with a corrected/richer palette. Ignored for STL and pre-built scenes.
+     */
+    filamentPalette?: readonly (string | undefined)[];
     /** Override the environment id folded into the cache key (default: the `three` revision). */
     envId?: string;
 }

package/dist/render-model-still.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-model-still.d.ts","sourceRoot":"","sources":["../src/render-model-still.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7F,OAAO,EAAiB,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,yEAAyE;AACzE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAChD,UAAU,CAAC;AAEf,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,qCAAqC;IACrC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,SAAS,EAAE,UAAU,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAoBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAiCjC"}
+{"version":3,"file":"render-model-still.d.ts","sourceRoot":"","sources":["../src/render-model-still.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7F,OAAO,EAAiB,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,yEAAyE;AACzE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAChD,UAAU,CAAC;AAEf,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,qCAAqC;IACrC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAClD,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,SAAS,EAAE,UAAU,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAqBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAiCjC"}

package/dist/render-model-still.js

@@ -5,14 +5,14 @@ import { computeCacheKey } from './cache-key.js';
 function isModelScene(s) {
     return s.objects !== undefined && s.kind === undefined;
 }
-async function toScene(source, limits) {
+async function toScene(source, limits, filamentPalette) {
     if (isModelScene(source)) {
         // No raw bytes for a pre-built scene: key off a stable structural summary instead.
         const summary = JSON.stringify({ n: source.objects.length, b: source.bounds, c: source.capabilities });
         return { scene: source, sourceBytes: new TextEncoder().encode(summary) };
     }
     const bytes = source.bytes instanceof Uint8Array ? source.bytes : new Uint8Array(source.bytes);
-    const scene = source.kind === '3mf' ? await parse3mf(bytes, limits) : parseStl(bytes, limits);
+    const scene = source.kind === '3mf' ? await parse3mf(bytes, limits, { filamentPalette }) : parseStl(bytes, limits);
     return { scene, sourceBytes: bytes };
 }
 /**
@@ -26,7 +26,7 @@ export async function renderModelStill(source, options) {
     const height = options.height ?? canvas.height;
     const background = options.background ?? 'transparent';
     const view = options.view ?? 'iso';
-    const { scene, sourceBytes } = await toScene(source, options.limits);
+    const { scene, sourceBytes } = await toScene(source, options.limits, options.filamentPalette);
     const renderer = new ModelRenderer({
         canvas,
         background,
@@ -37,7 +37,7 @@ export async function renderModelStill(source, options) {
         renderer.resize(width, height);
         renderer.setScene(scene);
         renderer.render();
-        const optionsJson = JSON.stringify({ width, height, background, view });
+        const optionsJson = JSON.stringify({ width, height, background, view, palette: options.filamentPalette });
         const cacheKey = computeCacheKey(sourceBytes, optionsJson, options.envId);
         return {
             canvas,

package/dist/three-mf.d.ts

@@ -1,4 +1,13 @@
 import { type ModelScene } from './scene-model.js';
 import { type ModelLimits } from './limits.js';
-export declare function parse3mf(source: Uint8Array | ArrayBuffer, limits?: ModelLimits): Promise<ModelScene>;
+export interface Parse3mfOptions {
+    /**
+     * Override the source-model filament palette (hex `#RRGGBB` per 0-based slot) used to colour
+     * `paint_color` facets, instead of reading it from `project_settings.config`. For consumers that
+     * already hold a corrected/richer palette (e.g. re-rendering a sliced `.gcode.3mf`). Ignored when
+     * empty; the file's own palette is still read.
+     */
+    filamentPalette?: readonly (string | undefined)[];
+}
+export declare function parse3mf(source: Uint8Array | ArrayBuffer, limits?: ModelLimits, opts?: Parse3mfOptions): Promise<ModelScene>;
 //# sourceMappingURL=three-mf.d.ts.map

package/dist/three-mf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"three-mf.d.ts","sourceRoot":"","sources":["../src/three-mf.ts"],"names":[],"mappings":"AAoBA,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAkC,KAAK,WAAW,EAAuB,MAAM,aAAa,CAAC;AA8PpG,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAkH1G"}
+{"version":3,"file":"three-mf.d.ts","sourceRoot":"","sources":["../src/three-mf.ts"],"names":[],"mappings":"AAqBA,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAkC,KAAK,WAAW,EAAuB,MAAM,aAAa,CAAC;AA4VpG,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CACnD;AAKD,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,UAAU,GAAG,WAAW,EAChC,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,UAAU,CAAC,CAwJrB"}

package/dist/three-mf.js

@@ -12,7 +12,7 @@
  * `<components><component>` (with `p:path`), and `<build><item>` transforms. Textures and non-color
  * material properties are ignored (disclosed via capability honesty), never fetched (no network).
  */
-import { readDirectory, extractEntry, DEFAULT_CONTAINER_LIMITS } from '@chestnutlabs/gcode-containers';
+import { readDirectory, extractEntry, filamentColoursFromSettings, DEFAULT_CONTAINER_LIMITS } from '@chestnutlabs/gcode-containers';
 import { IDENTITY_MAT4 } from './scene-model.js';
 import { ModelParseError, resolveLimits } from './limits.js';
 /** millimeter is the 3MF default; convert others to mm. */
@@ -56,6 +56,75 @@ function srgbHexToLinear(hex) {
     const b = to(4);
     return Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b) ? null : [r, g, b];
 }
+/**
+ * Decode a Bambu/Orca `paint_color` facet-paint attribute (clean-room from the observed format —
+ * see RR-005, NOT from Orca/PrusaSlicer GPL source). The value is a **little-endian** stream of 4-bit
+ * nibble tokens forming a recursive triangle-split tree:
+ *
+ * - `token & 0b11` = split-sides: `0` ⇒ a **leaf**, otherwise the triangle is split into
+ *   `split_sides + 1` children (2/3/4) that follow, decoded depth-first (`token >> 2` is the split
+ *   side — irrelevant to a presentation render).
+ * - a leaf's state is `token >> 2`, with `3` escaping into the following nibble (`3 + next`).
+ *
+ * **State 0 = the object's default extruder (unpainted); state s ≥ 1 = filament index s − 1.**
+ * Returns the dominant leaf state plus whether the facet was subdivided (so the caller can flatten it
+ * to one colour and disclose `approximated`), or `null` if the value is malformed/truncated.
+ */
+function decodePaintState(hex) {
+    const clean = hex.trim();
+    if (clean.length === 0)
+        return null;
+    const nibbles = [];
+    for (let i = clean.length - 1; i >= 0; i--) {
+        const n = parseInt(clean[i], 16);
+        if (Number.isNaN(n))
+            return null;
+        nibbles.push(n);
+    }
+    let pos = 0;
+    const states = [];
+    const next = () => {
+        if (pos >= nibbles.length)
+            throw new ModelParseError('E_MODEL_PARSE', 'paint_color underflow');
+        return nibbles[pos++];
+    };
+    const node = (depth) => {
+        if (depth > 16)
+            throw new ModelParseError('E_MODEL_PARSE', 'paint_color too deep');
+        const t = next();
+        const ss = t & 0b11;
+        if (ss === 0) {
+            const s2 = t >> 2;
+            states.push(s2 === 3 ? 3 + next() : s2);
+        }
+        else {
+            for (let i = 0; i <= ss; i++)
+                node(depth + 1);
+        }
+    };
+    try {
+        node(0);
+    }
+    catch {
+        return null;
+    }
+    if (states.length === 0)
+        return null;
+    // Dominant leaf state — subdivided facets are a tiny fraction of any real model, so flattening them
+    // to their most-common state (and reporting `approximated`) is a faithful presentation trade-off.
+    const counts = new Map();
+    let best = states[0];
+    let bestN = 0;
+    for (const s of states) {
+        const c = (counts.get(s) ?? 0) + 1;
+        counts.set(s, c);
+        if (c > bestN) {
+            bestN = c;
+            best = s;
+        }
+    }
+    return { state: best, subdivided: states.length > 1 };
+}
 function parseTransform(s) {
     if (s === undefined)
         return null;
@@ -125,7 +194,15 @@ function parseModelPart(xml, lim) {
             else {
                 const a = attrs(raw);
                 curObjId = a.id ?? null;
-                curObj = { vertices: [], tris: [], triColorIdx: [], triPid: [], components: [], name: a.name };
+                curObj = {
+                    vertices: [],
+                    tris: [],
+                    triColorIdx: [],
+                    triPid: [],
+                    triPaint: [],
+                    components: [],
+                    name: a.name
+                };
                 if (a.pid !== undefined)
                     curObj.objPid = a.pid;
                 if (a.pindex !== undefined)
@@ -160,6 +237,7 @@ function parseModelPart(xml, lim) {
             }
             const pid = a.pid ?? curObj.objPid ?? null;
             curObj.triPid.push(pid);
+            curObj.triPaint.push(a.paint_color ?? null);
             if (a.p1 !== undefined) {
                 const p1 = Number(a.p1);
                 const p2 = a.p2 !== undefined ? Number(a.p2) : p1;
@@ -195,7 +273,26 @@ function bakeMesh(obj, part, chain, id, st, lim) {
     const positions = new Float32Array(triCount * 9);
     let colors = null;
     let objHasColor = false;
+    // A mesh painted with Bambu/Orca `paint_color` (only meaningful when we have a filament palette).
+    const objHasPaint = st.paintPalette.length > 0 && obj.triPaint.some((p) => p !== null);
     for (let ti = 0; ti < triCount; ti++) {
+        // Paint path: one filament colour for the whole triangle. Painted facets decode to a state; the
+        // unpainted facets of a painted mesh take the object's default-extruder colour (never left blank).
+        let paintCol;
+        if (objHasPaint) {
+            let idx = st.defaultExtruderIdx;
+            const paint = obj.triPaint[ti];
+            if (paint !== null) {
+                const dec = decodePaintState(paint);
+                if (dec !== null) {
+                    idx = dec.state === 0 ? st.defaultExtruderIdx : dec.state - 1;
+                    if (dec.subdivided)
+                        st.anyApprox = true;
+                }
+            }
+            paintCol = st.paintPalette[idx] ?? st.paintPalette[st.defaultExtruderIdx];
+        }
+        // Standard 3MF material path (basematerials / colorgroup + pid) — fallback when there's no paint.
         const pid = obj.triPid[ti];
         const palette = pid !== null ? part.palettes.get(pid) : undefined;
         const cidx = obj.triColorIdx[ti];
@@ -218,16 +315,14 @@ function bakeMesh(obj, part, chain, id, st, lim) {
                 st.max[1] = y;
             if (z > st.max[2])
                 st.max[2] = z;
-            if (palette !== undefined && cidx !== null) {
-                const col = palette[cidx[k]] ?? palette[0];
-                if (col !== undefined) {
-                    if (colors === null)
-                        colors = new Float32Array(triCount * 9);
-                    colors[o] = col[0];
-                    colors[o + 1] = col[1];
-                    colors[o + 2] = col[2];
-                    objHasColor = true;
-                }
+            const col = paintCol ?? (palette !== undefined && cidx !== null ? (palette[cidx[k]] ?? palette[0]) : undefined);
+            if (col !== undefined) {
+                if (colors === null)
+                    colors = new Float32Array(triCount * 9);
+                colors[o] = col[0];
+                colors[o + 1] = col[1];
+                colors[o + 2] = col[2];
+                objHasColor = true;
             }
         }
     }
@@ -239,7 +334,8 @@ function bakeMesh(obj, part, chain, id, st, lim) {
         built.name = obj.name;
     st.built.push(built);
 }
-export async function parse3mf(source, limits) {
+const hexPaletteToLinear = (hexes) => hexes.map((hex) => (hex !== undefined ? (srgbHexToLinear(hex) ?? [0.8, 0.8, 0.82]) : [0.8, 0.8, 0.82]));
+export async function parse3mf(source, limits, opts) {
     const lim = resolveLimits(limits);
     const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
     if (bytes.byteLength === 0)
@@ -297,10 +393,50 @@ export async function parse3mf(source, limits) {
             throw e;
         throw new ModelParseError('E_MODEL_PARSE', `3MF unzip failed: ${e.message}`);
     }
+    // Source-model filament palette for Bambu/Orca `paint_color`: it lives in `project_settings.config`
+    // (`filament_colour`), NOT the model XML, so the render is self-contained and needs no slicer output.
+    let paintPalette = [];
+    const override = opts?.filamentPalette;
+    if (override !== undefined && override.length > 0) {
+        // Consumer-supplied palette wins over the file's own (e.g. a corrected slicer palette).
+        paintPalette = hexPaletteToLinear(override);
+    }
+    else {
+        const settingsEntry = entryByName('metadata/project_settings.config');
+        if (settingsEntry !== undefined) {
+            try {
+                const json = new TextDecoder().decode(await extractEntry(bytes, settingsEntry, climits.maxMetadataBytes));
+                const settings = JSON.parse(json);
+                paintPalette = hexPaletteToLinear(filamentColoursFromSettings(settings));
+            }
+            catch {
+                // Malformed/oversized settings → no palette; paint stays capability-honest `unavailable`.
+                paintPalette = [];
+            }
+        }
+    }
+    // Default extruder (1-based) for a painted mesh's unpainted facets; from `model_settings.config`, else 1.
+    let defaultExtruderIdx = 0;
+    const modelSettingsEntry = entryByName('metadata/model_settings.config');
+    if (modelSettingsEntry !== undefined) {
+        try {
+            const xml = new TextDecoder().decode(await extractEntry(bytes, modelSettingsEntry, climits.maxMetadataBytes));
+            const m = /key="extruder"\s+value="(\d+)"/i.exec(xml);
+            const n = m !== null ? parseInt(m[1], 10) : NaN;
+            if (Number.isFinite(n) && n >= 1)
+                defaultExtruderIdx = n - 1;
+        }
+        catch {
+            defaultExtruderIdx = 0;
+        }
+    }
     const st = {
         built: [],
         anyColor: false,
         anyTransform: false,
+        anyApprox: false,
+        paintPalette,
+        defaultExtruderIdx,
         min: [Infinity, Infinity, Infinity],
         max: [-Infinity, -Infinity, -Infinity],
         totalTris: 0
@@ -343,7 +479,8 @@ export async function parse3mf(source, limits) {
         objects: st.built,
         bounds,
         capabilities: {
-            materials: st.anyColor ? 'known' : 'unavailable',
+            // `approximated` when any colour came from flattening a subdivided `paint_color` facet.
+            materials: st.anyApprox ? 'approximated' : st.anyColor ? 'known' : 'unavailable',
             transforms: st.anyTransform ? 'known' : 'unavailable',
             multiObject: st.built.length > 1 ? 'known' : 'unavailable'
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chestnutlabs/gcode-model-renderer",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Three.js presentation renderer for source models (STL/3MF) — clean thumbnails/cards, distinct from toolpath inspection (DD-018).",
   "keywords": [
     "3d-printing",
@@ -51,9 +51,9 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@chestnutlabs/gcode-containers": "0.7.0",
-    "@chestnutlabs/gcode-renderer-three": "0.7.0",
-    "@chestnutlabs/toolpath-core": "0.7.0"
+    "@chestnutlabs/gcode-containers": "0.8.1",
+    "@chestnutlabs/gcode-renderer-three": "0.8.1",
+    "@chestnutlabs/toolpath-core": "0.8.1"
   },
   "devDependencies": {
     "@types/three": "0.178.0"