three-slicer 0.2.1 → 0.2.3

package/viewer/README.md

@@ -38,9 +38,10 @@ Slice parameters are derived from `settings` via `three-slicer`'s schema mapping
 
 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).
+Props: `settings`, `setSettings`, and three optional sidebar slots — `processPanel` (the process card) and
+`motionPanel` (folded into the printer card) take a React node; `filamentPanel` (folded into the filament card,
+next to the material picker) takes a **function** `(settings, setSettings) => ReactNode`, because the filament
+card binds each extruder's per-extruder values.
 
 Subpath exports for custom UIs (framework-free, no React):
 - `three-slicer/viewer/toolpath` — GPU toolpath renderer (`buildSegmentData`, `makeToolpath`, view-type colorers)
@@ -63,25 +64,88 @@ Every panel can be switched off, and the values the component owns can be seeded
 - **`panels`** — `{name: false}` hides one. Everything is visible by default, so a host only ever opts out and a
   panel added in a later version does not vanish for hosts that listed the ones they wanted. `sidebar: false` drops
   the whole right column; the rest are `topBar`, `gizmoRail`, `objectToolbar`, `paintPanel`, `statsCard`, `plateBar`,
-  `emptyHint`, `status`, `printerCard`, `filamentCard`, `resinCard`, `objectList`, `previewControls`, `processCard`,
-  `sliceBar`. Which of `filamentCard`/`resinCard` renders follows the printer profile's technology: a profile whose
+  `emptyHint`, `status`, `printerCard`, `filamentCard`, `resinCard`, `towerCard`, `objectList`, `previewControls`,
+  `processCard`, `sliceBar`, `moveBar`, `bedWarn` (the off-bed warning strip). Which of `filamentCard`/`resinCard` renders follows the printer profile's technology: a profile whose
   `printer_technology` says SLA swaps the filament card (and the prime tower, and the painting brushes) for the
   resin card, and slicing routes to the kernel's `slice_sla` — PrusaSlicer's ported support/pad chain — with an
   `.sl1` export instead of G-code (portrait masks, like every SL1-family machine). The preview lifts the model by
   `stats.lift_layers` (pad + elevation), and a request the port does not cover (hollowing, organic trees)
   surfaces as a typed error instead of a wrong print.
+  An `.sl1` can also be OPENED (file picker or drag & drop). This viewer's own exports carry a SCENE sidecar
+  (`Metadata/threeslicer_scene.bin`: the model STL plus the support and pad meshes the preview was showing, ~3%
+  of the archive), so reopening one shows the exported surface ITSELF — no reconstruction, nothing approximated,
+  and the whole import lands in ~0.3s. A foreign SL1 has no such record, and there its SHAPE is reconstructed
+  from the masks —
+  every layer streamed through surface nets in workers (six producers turning masks into occupancy slices, one
+  sequential consumer sweeping them). It runs in TWO passes: a quarter-resolution one lands a real shaded mesh
+  in well under a second, then the full one replaces it (measured 0.7s and 4.2s on a 1095-layer archive), at the archive's own layer height in z and ~0.12mm
+  in xy, with the anti-aliased mask grays interpolated for sub-voxel edges and both the surface and its normals
+  relaxed (the layer ripple a mask grid leaves behind is largely a shading artefact) — and shown as a solid mesh on the
+  selected plate, with the layer slider section-cutting it like any sliced result. While the reconstruction
+  runs a translucent stack of sampled masks stands in, until the coarse pass replaces it.
+  Colours: a mask records what cures, not which pixels were model, support or pad — so this viewer's own
+  exports carry a role sidecar (`Metadata/threeslicer_roles.bin`, the support/pad segments per layer; every
+  other consumer ignores the unknown member) and reconstruct in the sliced preview's three colours. A foreign
+  SL1 has no such record and reconstructs in one colour. Opening one applies what the archive states —
+  `printer_technology` first of all, then the exposure family, the layer height and the pixel grid read off a
+  mask header — so a file opened in a fresh FFF session switches the whole route to SLA instead of stranding
+  resin masks on a filament bed. The one number it cannot supply is the display's PHYSICAL size: millimetres
+  appear nowhere in an SL1, so the preview is scaled by the printer set in the viewer and the import notice says
+  so. Export hands an imported archive back byte-identical rather than re-rasterizing empty geometry.
 - **`gcode`** — G-code text drawn on the selected plate instead of a slice result. `parseGcode` recovers roles from
   `;TYPE:` (OrcaSlicer/PrusaSlicer/Cura), from `;_EXTRUSION_ROLE:` tags and from this kernel's own feature comments;
   bead width comes from `;WIDTH:` or, absent that, from E. What the file never states cannot be recovered: an
   unmarked run reads as wall, and there is no print-time estimate (that needs the machine's acceleration limits).
+- **`sl1`** — the SLA half of that contract: an `.sl1` archive (`File`, raw bytes, or `{name, data}`) rendered as a
+  raster preview on the selected plate, again without starting the kernel. It routes into the same import the
+  picker and a drop use, so it behaves identically — including the two things `gcode` does not do: it writes the
+  archive's own job description into your `settings` (`printer_technology` among them, per the paragraph above),
+  and it reconstructs a surface from the masks in the background. Set both and the G-code wins; one plate holds one
+  artifact. It re-injects on the value's IDENTITY, so hold the File in state rather than rebuilding it each render.
+- **The move scrub** (`panels.moveBar`) — the horizontal counterpart of the layer slider, under the canvas in
+  Preview: the vertical one picks WHICH layers are shown, this one walks inside the top one. It is upstream's
+  sequential view (`GCodeViewer`'s `update_sequential_view_current`) in this viewer's terms. On an FFF result it
+  cuts that layer at a move — extrusions and travels together, in the order the printer performs them, which the
+  two draw lists do not store and `moveCursor` recovers — and marks where the nozzle is: a solid cone at the
+  current position and a translucent one where the layer ends. Both are fixed SCREEN size and drawn over
+  everything, because a marker that scales with the scene is a speck zoomed out and a marker that respects depth
+  is buried in the bead it is pointing at. Position changes reach the host as the `moveScrub` event.
+  FFF only, and deliberately: mSLA cures a whole layer in one exposure, so a resin layer has no intra-layer
+  order to walk — the same conclusion upstream reaches, PrusaSlicer's SLA preview having a layer slider and no
+  horizontal one.
+- **`files`** — content imported once on mount, through the same extension dispatch as a drop: models and 3mf
+  projects, `.sl1` archives, and preset files. Mount-only on purpose — a host that rebuilds the array each render
+  must not re-import its models; runtime loading stays with the picker and drop.
+- **`sliceRequest`** — the host's Slice button: a token whose identity change requests one slice of the current
+  plate. The mount value is inert, so hold a counter in state and bump it. Ignored under the same conditions
+  the built-in slice bar is not pressable (empty scene, an injected `gcode`/`sl1` plate); a change during a
+  running slice cancels and re-slices, so the last request wins.
 - **`defaultExtruderColors`**, **`defaultAutoSlice`** — initial values for state the component owns. Unlike the
   in-app toggle, `defaultAutoSlice` also performs the *first* slice, which is what makes a panel-less embed able to
   slice at all.
 - **`onEvent`** — one channel for every change: `canvasMode`, `objects`, `selectedPlate`, `plateCount`,
-  `extruderColors`, `autoSlice`, `slicing`, `progress`, `viewType`, `paintMode`, `layerCount`, `layerRange`,
-  `error`, `notice`. Initial values are not announced — the host passed them. `progress` fires several times a
-  second while slicing.
-- **`onSliced`** — `{plate, stats, gcode}` when a slice is cached. Switching plate tabs does not re-fire it.
+  `extruderColors`, `autoSlice`, `slicing`, `progress`, `sliceRate`, `viewType`, `paintMode`, `layerCount`,
+  `layerRange`, `moveScrub`, `error`, `notice`. Initial values are not announced — the host passed them.
+  `progress` and `sliceRate` fire several times a second while slicing.
+- **`onSliced`** — `{plate, stats, gcode, throughput}` when a slice is cached. Switching plate tabs does not
+  re-fire it. `throughput` sits beside `stats` rather than inside it, because that is where the engine puts it:
+  it is measured around the call, not reported by the kernel.
+
+`sliceRate` is live throughput — layers finished per second over a 250ms window, `0` between slices, and shown in
+the slice bar as well. When it appears depends on the technology, because the two publish per-layer news at
+opposite ends of the run:
+
+- **SLA** reports it throughout: its progress counter is linear in layers. (Its layer *stream* is not usable for
+  this — `slice_sla` builds the whole scene and then drains the sink, measured as 1095 layer messages inside a
+  22ms burst at the end of a 2.8s run, which would time the drain rather than the slicing.)
+- **FFF** reports it once the emission pass starts streaming layers. PASS1 publishes per-mille of itself rather
+  than a layer count (the total only arrives when it ends), and surfaces and support publish nothing per layer,
+  so there is nothing to measure before that and nothing is invented. Measured on a 38MB model: a 4.0s slice,
+  2.8s of it PASS1, the rate shown for the final 0.6s. On a support-heavy model emission is a much larger share.
+
+The whole-slice figure is `throughput` on `onSliced`, and it is present on both technologies — wall milliseconds,
+the kernel's own share, layers/second, and ms per million segments. It reads lower than the live figure whenever
+the live one covers only part of the run.
 
 ## Keyboard and mouse
 
@@ -209,8 +273,8 @@ download.
 ### Taking the saves
 
 The save buttons are inside the component, so `onExport` is the only way to send a file somewhere other than the
-browser's download folder. It sees the 3mf project, the STL and each plate's G-code. Return truthy to say you
-handled it:
+browser's download folder. It sees every save: the 3mf project, the STL, each plate's G-code, an SLA plate's
+`.sl1` archive, and preset files. Return truthy to say you handled it:
 
 ```jsx
 <Viewport onExport={(file, filename) => { uploadToServer(file, filename); return true }} />
@@ -223,11 +287,23 @@ Return nothing and the download happens as well, which is useful for logging wha
 The component owns its scene, and the props are the whole interface — there is no ref, no imperative handle, and no
 `models` prop. Worth knowing before you design around it:
 
-- **Models enter through the UI only** — the file dialog or drag and drop. A host cannot hand a mesh in, and cannot
-  remove or transform one. What it *can* do is watch: the `objects` event reports `{id, name, extruder, visible}`
-  for every object as the set changes.
-- **Slicing is triggered from the UI or by `defaultAutoSlice`**, which unlike the in-app toggle also performs the
-  first slice — that is what makes a panel-less embed able to slice at all. The result arrives on `onSliced`.
+- **Models enter through the UI, or once at mount through `files`** — after mount, runtime loading stays with the
+  file dialog and drag and drop. A host cannot remove or transform an object, or hand a mesh in mid-session. What
+  it *can* do is watch: the `objects` event reports `{id, name, extruder, visible}` for every object as the set
+  changes.
+- **Slicing is triggered from the UI, by `defaultAutoSlice`, or by bumping `sliceRequest`** — a token prop whose
+  identity change requests one slice of the current plate (the mount value is inert), which is what a host with
+  the built-in chrome hidden wires its own Slice button to. The result arrives on `onSliced`.
+- **The prime tower stand-in appears only when the plate actually changes tools** — objects assigned to more
+  than one extruder, or material paint reaching extruder 2 or higher. Loading a second filament is not enough:
+  with everything on T1 the slice emits no tool change and builds no tower, so drawing the box would promise one.
+- **A settings change discards every slice result.** Everything a slice puts on screen — the toolpaths, the stats
+  card, the layer slider, the G-code export — describes the settings it ran with, and none of it says so. So when
+  a value in `settings` changes, the results are dropped and the viewer returns to Prepare; with `autoSlice` on
+  the re-slice then fills the empty preview. Two exceptions, neither of which claims to be a slice of these
+  settings: a plate injected through `gcode` / `sl1`, and an opened `.sl1` archive (that import applies the
+  archive's own settings, so invalidating on it would erase what the file was opened to show). Comparison is by
+  value, so a host that rebuilds its settings object every render does not lose its preview to it.
 - **`gcode` is one-way**: pass G-code text and it is drawn on the selected plate instead of a slice result, and
   auto re-slice leaves that plate alone while it is set.
 - Everything else the component owns — camera, selection, plate count, paint state — is reported through `onEvent`