three-slicer 0.1.4 → 0.1.6

package/README.md

@@ -4,6 +4,8 @@ Browser/WASM 3D-printing slicer package derived from [OrcaSlicer](https://github
 
 The package is published as a single npm package, `three-slicer`, with subpath exports for the engine, viewer, components, worker, and extracted OrcaSlicer data.
 
+![A sliced Benchy in the viewer's Preview tab — organic tree supports, per-feature toolpath colors, dual layer-range slider, filament and print-time estimates](https://raw.githubusercontent.com/kimgh06/Web_Three_Slicer/main/web/viewer/public/usage.png)
+
 ## Links
 
 - Package: [npmjs.com/package/three-slicer](https://www.npmjs.com/package/three-slicer)
@@ -19,6 +21,7 @@ The package is published as a single npm package, `three-slicer`, with subpath e
 - React `<SettingsPanel/>` generated from extracted OrcaSlicer metadata.
 - Vendor printer, print-process and filament preset catalogs, with one material assignable per extruder.
 - Support painting and material painting, plus per-tool filament and purge statistics.
+- 3MF **project** import in the viewer: a slicer-written `.3mf` (OrcaSlicer/BambuStudio save, MakerWorld download) restores its plate layout, project settings, and painted facets — not just the meshes.
 - Extracted data files for custom UIs: config schema, UI tree, toggle rules, invalidation map, and the printer/process/filament catalogs.
 - Automatic multithreaded WASM selection on cross-origin-isolated browser pages.
 
@@ -107,7 +110,7 @@ export default function App() {
 }
 ```
 
-The viewer handles model loading, drag and drop, transform controls, multi-plate layout, worker slicing, GPU toolpath preview, and G-code export. It supports STL, OBJ, 3MF (including the production extension used by Orca/Bambu/Prusa), AMF, and PLY out of the box; other formats such as STEP can be added with `registerLoader()`. Viewer and component styles are bundled into their Shadow DOM roots, so host app CSS does not need to import package CSS.
+The viewer handles model loading, drag and drop, transform controls, multi-plate layout, worker slicing, GPU toolpath preview, and G-code export. It supports STL, OBJ, 3MF (including the production extension used by Orca/Bambu/Prusa), AMF, and PLY out of the box; other formats such as STEP can be added with `registerLoader()`. A `.3mf` written by a slicer is treated as a project, not just geometry: its plate layout, project settings, and support/material painting are restored on import (where a facet carries both paint kinds, material paint wins and the dropped support paint is reported). Viewer and component styles are bundled into their Shadow DOM roots, so host app CSS does not need to import package CSS.
 
 ## Quick Start: Settings Panel
 

package/components/README.md

@@ -4,10 +4,10 @@ Reusable React components for the browser slicer. Props-driven — no global sta
 
 ## `<SettingsPanel/>`
 
-An OrcaSlicer-style settings form generated from `@three-slicer/data` (schema + UI tree + toggle rules): tab/page/group navigation, mode filter (simple/advanced/expert), search across 923 options, dirty markers with per-option reset, and enable/disable rules evaluation.
+An OrcaSlicer-style settings form generated from `three-slicer/data` (schema + UI tree + toggle rules): tab/page/group navigation, mode filter (simple/advanced/expert), search across 923 options, dirty markers with per-option reset, and enable/disable rules evaluation.
 
 ```bash
-npm i three-slicer/components react
+npm i three-slicer     # react is a peer dependency — npm installs it for you
 ```
 
 ```jsx

package/data/README.md

@@ -1,6 +1,6 @@
-# @three-slicer/data
+# three-slicer/data
 
-OrcaSlicer configuration metadata extracted from the original C++ sources, as plain JSON. Used by `three-slicer` (defaults, settings mapping) and `three-slicer/components` (settings UI), and usable standalone for building slicer UIs.
+OrcaSlicer configuration metadata extracted from the original C++ sources, shipped inside the `three-slicer` package as its `/data` subpath. Used by `three-slicer` (defaults, settings mapping) and `three-slicer/components` (settings UI), and usable standalone for building slicer UIs.
 
 | File | Contents |
 |---|---|

package/engine/README.md

@@ -2,7 +2,7 @@
 
 Browser/WASM 3D-slicing kernel reverse-engineered from [OrcaSlicer](https://github.com/OrcaSlicer/OrcaSlicer). Slices binary STL to G-code entirely client-side (or in Node) — no server, no native binaries.
 
-**No three.js dependency.** This is a headless SDK; the only dependency is `@three-slicer/data` (config metadata JSON). For a ready-made React viewer see `three-slicer/viewer`.
+**No three.js dependency.** This is a headless SDK with zero runtime dependencies; the config metadata it reads ships inside the same package (`three-slicer/data`). For a ready-made React viewer see `three-slicer/viewer`.
 
 Ported from the original C++ sources: Clipper polygon ops, Arachne variable-width walls, real fill patterns (gyroid TPMS / honeycomb / 3D-honeycomb / crosshatch / concentric), tree supports, pressure equalizer, arc fitting (G2/G3), scarf seams, ironing, multi-material with prime tower. Kernel changes are gated by a 120+ invariant test suite and golden byte-identical G-code checks.
 
@@ -38,7 +38,7 @@ Off-main-thread (browser): `new Worker(engineWorkerURL(), { type: 'module' })`
 Two levels — use whichever fits:
 
 1. **Kernel params (this package's native contract)** — a flat JSON object of ~90 keys (`layer_height`, `wall_loops`, `infill_density` 0–1, `sparse_infill_pattern`, `enable_support`, `wall_generator: 'classic' | 'arachne'`, …). See `src/settings.js` for the full shape.
-2. **OrcaSlicer settings map** — a sparse `{schemaKey: value}` map using original OrcaSlicer option keys (923 defined in `@three-slicer/data`); unset keys fall back to schema defaults:
+2. **OrcaSlicer settings map** — a sparse `{schemaKey: value}` map using original OrcaSlicer option keys (923 defined in `three-slicer/data`); unset keys fall back to schema defaults:
 
 ```js
 import { deriveKernelParams } from 'three-slicer/settings'

package/engine/src/settings.js

@@ -136,9 +136,128 @@ export function printerSettings(profileName) {
 /** The vendor's recommended process preset for a printer, or '' when the profile names none. */
 export function printerDefaultPreset(profileName) { return printerEntry(profileName)?.[3] ?? '' }
 
+// ---- Imported project settings (a slicer-written 3mf's Metadata/project_settings.config) --------------------
+// Upstream serializes every option as a STRING (or an array of them, one per extruder) — a bool is "0"/"1" and a
+//  float is "0.2". This settings map holds real JS types, and the difference is not cosmetic: `bool()` below reads
+//  a value with `!!v`, and `!!"0"` is TRUE — importing raw would turn every disabled option on. So each value is
+//  coerced by its schema type, and anything the schema does not know (inherits_group, *_settings_id, version, the
+//  whole preset-bookkeeping half of that file) is dropped rather than carried into a map keyed by schema keys.
+// The `inherits` / `different_settings_to_system` machinery upstream applies on top of this (Preset.cpp:2577) is
+//  deliberately NOT reproduced: it exists to reconcile a stored preset against a LOCAL vendor preset database of a
+//  possibly different version. project_settings.config is already flattened, so taking its values as written is
+//  both simpler and closer to what the project author actually sliced.
+const FALSE_STRINGS = new Set(['0', 'false', 'no', 'off', ''])
+
+function coerceScalar(type, value) {
+  if (typeof value !== 'string') return value
+  switch (type) {
+    case 'coBool': case 'coBools':
+      return !FALSE_STRINGS.has(value.trim().toLowerCase())
+    case 'coFloat': case 'coFloats': case 'coInt': case 'coInts':
+      return asNumber(value)
+    case 'coPercent': case 'coPercents':
+      // A percent option's value is the bare number (the schema default of sparse_infill_density is 20, not "20%")
+      //  and upstream serializes it that way — but the '%' does show up in hand-edited configs, so strip it.
+      return asNumber(value.trim().replace(/%$/, ''))
+    case 'coFloatOrPercent': case 'coFloatsOrPercents':
+      // "50%" must stay a string — the percent IS the value, and Number('50%') is NaN anyway.
+      return value.trim().endsWith('%') ? value : asNumber(value)
+    case 'coPoint': case 'coPoints':
+      return parsePoint(value) ?? value
+    case 'coPointsGroups':
+      return parsePointGroup(value) ?? value
+    default:
+      return value   // strings and enums — the kernel and the panel both read these as written
+  }
+}
+
+// Points are the other shape trap, and a quiet one: upstream writes a point as the STRING "XxY", while every
+//  consumer here indexes it as a [x, y] pair — so `printable_area[1][0]` on a raw import is the CHARACTER '2' of
+//  "256x0", and the bed comes out 2mm wide (measured on a real MakerWorld project: 2 x NaN).
+// Two separators exist in the wild: ConfigOptionPoint::serialize writes 'x', while some Orca options
+//  (best_object_pos) write "X,Y". A points GROUP is one string holding a comma-separated LIST of "XxY" points,
+//  so there the comma cannot also separate a point's own coordinates — hence two parsers rather than one regex.
+function parsePoint(text) {
+  const split = String(text).split('x')
+  const pair = split.length === 2 ? split : String(text).split(',')
+  if (pair.length !== 2) return null
+  const x = Number(pair[0]), y = Number(pair[1])
+  return Number.isFinite(x) && Number.isFinite(y) ? [x, y] : null
+}
+function parsePointGroup(text) {
+  const points = String(text).split(',').map(entry => {
+    const [a, b] = entry.split('x')
+    const x = Number(a), y = Number(b)
+    return Number.isFinite(x) && Number.isFinite(y) ? [x, y] : null
+  })
+  return points.length && points.every(Boolean) ? points : null
+}
+// Number('') is 0 and Number('  ') is 0, neither of which means "the option was set to zero" — an unparsable
+//  value is handed back untouched so the schema default keeps applying instead of a fabricated 0.
+function asNumber(value) {
+  if (value.trim() === '') return value
+  const n = Number(value)
+  return Number.isFinite(n) ? n : value
+}
+
+/**
+ * A 3mf project's raw `project_settings.config` object -> a settings map this package's own API accepts.
+ * Keys the config schema does not define are dropped. Returns `{settings, applied, skipped}`.
+ */
+export function normalizeProjectSettings(raw) {
+  const settings = {}
+  let applied = 0
+  const skipped = []
+  for (const [key, value] of Object.entries(raw || {})) {
+    const type = schema[key]?.type
+    if (!type) { skipped.push(key); continue }
+    settings[key] = Array.isArray(value) ? value.map(entry => coerceScalar(type, entry)) : coerceScalar(type, value)
+    applied++
+  }
+  return { settings, applied, skipped }
+}
+
+// The exact inverse, for WRITING a project_settings.config: every value back to the string shape upstream
+//  serializes (bool -> "1"/"0", point -> "XxY", a points group -> "X1xY1,X2xY2"), because that is what every other
+//  slicer's reader — and normalizeProjectSettings above — expects to coerce FROM. Writing the JS types raw would
+//  hand OrcaSlicer a bool it reads with its own string parser and this package a round-trip that only works here.
+//  Keys the schema does not define are dropped for the same reason normalize drops them: they could not be typed.
+const pointToText = (point) => (Array.isArray(point) ? `${point[0]}x${point[1]}` : String(point))
+
+function serializeScalar(type, value) {
+  if (value == null) return ''
+  switch (type) {
+    case 'coBool': case 'coBools':
+      return value ? '1' : '0'
+    case 'coPoint': case 'coPoints':
+      return pointToText(value)
+    case 'coPointsGroups':
+      return Array.isArray(value) ? value.map(pointToText).join(',') : String(value)
+    default:
+      return String(value)   // numbers, percents, strings, enums — String() is upstream's own spelling for all of them
+  }
+}
+
+/** A settings map (real JS types) -> the all-strings object a 3mf's `project_settings.config` stores. */
+export function serializeProjectSettings(settings) {
+  const out = {}
+  for (const [key, value] of Object.entries(settings || {})) {
+    const type = schema[key]?.type
+    if (!type) continue
+    // A coPoint's value IS an array ([x, y]) — the generic array path would serialize its two numbers separately.
+    out[key] = (type !== 'coPoint' && Array.isArray(value))
+      ? value.map(entry => serializeScalar(type, entry))
+      : serializeScalar(type, value)
+  }
+  return out
+}
+
 
 // Right-panel settings values -> kernel parameters (derived from schema keys)
-export function deriveKernelParams(settings) {
+//  opts.plate: which plate's entry to take from per-plate array options (wipe_tower_x/y — upstream coFloats,
+//  one entry per plate). Defaults to 0, so every existing caller reads exactly what it always did.
+export function deriveKernelParams(settings, opts) {
+  const plate = opts?.plate ?? 0
   const S = k => settingScalar(settings, k)
   const num = (k, d) => { const v = Number(S(k)); return Number.isFinite(v) ? v : d }
   const bool = (k, d) => { const v = settingRaw(settings, k); return typeof v === 'boolean' ? v : (Array.isArray(v) ? !!v[0] : (v == null ? d : !!v)) }
@@ -202,7 +321,9 @@ export function deriveKernelParams(settings) {
   //  A hole (a material that overrides nothing) is filled with the value tool 0 resolved to, because the kernel
   //  reads the array positionally and cannot tell "absent" from "0".
   // Prime tower keys, omitted when unset so the kernel/viewer defaults stay in charge (same rule as supportTools).
-  //  wipe_tower_x/y are coFloats upstream — one entry per plate — so the scalar reduction takes the first set one.
+  //  wipe_tower_x/y are coFloats upstream — one entry per plate — indexed by opts.plate. A hole (null entry) means
+  //  nobody chose a position for THAT plate, so the automatic placement stands there; a scalar applies to every
+  //  plate (the pre-array form, kept readable so old saved settings keep meaning what they meant).
   const towerSettings = {}
   {
     const width = num('prime_tower_width', 0)
@@ -211,7 +332,9 @@ export function deriveKernelParams(settings) {
     //  a coordinate off the front of a 200mm bed. Taking it as "the user chose a position" put the tower outside
     //  the plate and disabled the automatic placement entirely — measured as a tower at z=-127.5 on a 200mm bed.
     //  Absent from the map means nobody chose one, and the placement beside the model stands.
-    const chosen = (key) => { const v = settings?.[key]; const n = Number(Array.isArray(v) ? v[0] : v)
+    const chosen = (key) => { const raw = settings?.[key]
+      const v = Array.isArray(raw) ? raw[plate] : raw
+      const n = Number(v)
       return (v != null && v !== '' && Number.isFinite(n)) ? n : null }
     const towerX = chosen('wipe_tower_x'), towerY = chosen('wipe_tower_y')
     if (towerX != null) towerSettings.prime_tower_x = towerX

package/engine/src/slicer.worker.js

@@ -109,6 +109,12 @@ const paintedReply = (Module, message, paintedState) => {
 self.onmessage = async (e) => {
   const d = e.data
   try {
+    // Asking for the painting must not be what LOADS the kernel. Every other command needs it, but if this worker
+    //  has never loaded it then selector_prepare has never run either, so there is no painting to report — and
+    //  making a save wait on a 4MB WASM load before the first slice is seconds of nothing, for an empty answer.
+    if (d.cmd === 'exportPaint' && !modPromise) {
+      self.postMessage({ type: 'paintExport', supported: false, facets: [], hex: '' }); return
+    }
     if (!modPromise) modPromise = loadCore()
     const Module = await modPromise
     // Warmup: only load the kernel (+ spawn the mt pthread pool) ahead of time — removes the perceived load on the first slice
@@ -148,6 +154,29 @@ self.onmessage = async (e) => {
       else Module.selector_erase(d.facet, d.hx, d.hy, d.hz, d.cx, d.cy, d.cz, d.radius)
       self.postMessage(paintedReply(Module, d, null)); return
     }
+    // importPaint: load painting out of a 3mf. `facets` is an Int32Array of facet indices in the CURRENT selector's
+    //  numbering and `hex` the newline-joined per-facet split-tree strings the 3mf carried, in the same order.
+    //  It REPLACES every mark (the kernel's deserialize resets first), so it belongs immediately after a 'prepare'
+    //  and nowhere else — an import in the middle of a session would silently discard what the user had painted.
+    //  A kernel built before this binding existed simply has no selector_import_paint; the reply says applied:0
+    //  rather than throwing, because losing a 3mf's paint must not also lose its geometry.
+    if (d.cmd === 'importPaint') {
+      const applied = Module.selector_import_paint ? Module.selector_import_paint(d.facets, d.hex ?? '') : 0
+      const reply = paintedReply(Module, d, null)
+      reply.applied = applied
+      self.postMessage(reply); return
+    }
+    // exportPaint: the reverse of importPaint — every marked facet's split tree as {facets, hex} in the CURRENT
+    //  selector's numbering, the same parallel-array pairing importPaint takes (hex is one newline-joined blob).
+    //  The caller (3mf save) rebases the facet indices back onto per-object numbering; this worker cannot, because
+    //  which objects were merged in what order is the viewer's knowledge. A kernel built before the binding existed
+    //  reports supported:false rather than throwing — the save then falls back to the paint it imported.
+    if (d.cmd === 'exportPaint') {
+      const exported = Module.selector_export_paint ? Module.selector_export_paint() : null
+      self.postMessage({ type: 'paintExport', supported: !!Module.selector_export_paint,
+                         facets: exported?.facets ?? [], hex: exported?.hex ?? '' })
+      return
+    }
     // clear wipes every state at once, so each requested count is 0 by construction — no need to ask the kernel back.
     if (d.cmd === 'clear')   {
       Module.selector_clear()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-slicer",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Browser/WASM 3D-printing slicer reverse-engineered from OrcaSlicer: slicing engine (Arachne walls, tree/grid supports, multi-material), React viewer with GPU toolpath preview, and schema-driven settings UI.",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/types/settings.d.ts

@@ -16,7 +16,26 @@ export function settingScalar(settings: SlicerSettings | null | undefined, key:
  * ponytail: 53 returned keys, so Record instead of listing each — kernel params are passed straight to slice(),
  * not an API consumers read field by field. Expand it when field access is actually needed.
  */
-export function deriveKernelParams(settings: SlicerSettings | null | undefined): Record<string, unknown>
+export function deriveKernelParams(settings: SlicerSettings | null | undefined, opts?: { plate?: number }): Record<string, unknown>
+
+/**
+ * A 3mf project's raw `Metadata/project_settings.config` -> a settings map this API accepts.
+ * Upstream writes every option as a string ("0"/"1" for a bool, "0.2" for a float, one entry per extruder for a
+ * vector); each value is coerced by its config-schema type, and keys the schema does not define are dropped into
+ * `skipped` rather than carried into the map. `applied` is how many keys survived.
+ */
+export function normalizeProjectSettings(raw: Record<string, unknown> | null | undefined): {
+  settings: SlicerSettings
+  applied: number
+  skipped: string[]
+}
+
+/**
+ * The inverse, for WRITING a 3mf's `Metadata/project_settings.config`: every value back to the string shape
+ * upstream serializes (a bool as "1"/"0", a point as "XxY", a points group as "X1xY1,X2xY2"), so another slicer
+ * reads what it expects. Keys the config schema does not define are dropped.
+ */
+export function serializeProjectSettings(settings: SlicerSettings | null | undefined): Record<string, string | string[]>
 
 // ---- Lazily loaded presets --------------------------------------------------
 // Both facades hide the column layout of the artifact they wrap; the promise is created once and reused.

package/viewer/README.md

@@ -2,14 +2,15 @@
 
 3D slicer viewer as a React component: three.js viewport (orbit/transform gizmos), model import (STL/OBJ/3MF/AMF/PLY + pluggable formats such as STEP, multi-object, drag & drop), Web Worker slicing via `three-slicer`, support and material painting, per-extruder filament presets, multi-plate, and a GPU-instanced volumetric toolpath preview ported from OrcaSlicer's libvgcode (millions of segments in a single draw path, per-feature colors, layer range slider, G-code export).
 
+![The Prepare tab — drag-and-drop viewport with the printer, filament and process cards in the right sidebar](../../slice-sidebar.png)
+
 ```bash
-npm i three-slicer/viewer react react-dom three@^0.160.0
+npm i three-slicer     # react, react-dom and three are peer dependencies — npm installs them for you
 ```
 
 ```jsx
 import { useState } from 'react'
 import Viewport from 'three-slicer/viewer'
-import 'three-slicer/viewer/styles.css'
 
 function App() {
   const [settings, setSettings] = useState({})   // OrcaSlicer schema keys; sparse — defaults fill the rest
@@ -17,8 +18,12 @@ function App() {
 }
 ```
 
+Styles are injected into the component's Shadow DOM root — nothing to import, and host CSS cannot collide.
+
 Slice parameters are derived from `settings` via `three-slicer`'s schema mapping — pair it with `three-slicer/components`' `<SettingsPanel/>` sharing the same state for a full slicer UI.
 
+A `.3mf` written by a slicer (OrcaSlicer/BambuStudio save, MakerWorld download) imports as a **project**: plate layout, project settings, and support/material painting are restored, not just the meshes. Where a facet carries both paint kinds, material paint wins and the dropped support paint is reported.
+
 Props: `settings`, `setSettings`, and three optional React-node slots rendered in the right sidebar —
 `processPanel` (the process card), `motionPanel` (folded into the printer card) and `filamentPanel`
 (folded into the filament card, next to the material picker).