Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,11 @@ skills (`atomic-commits`, `ai-review-before-commit`, `pre-commit-gate`,
recorded in `NAME.slice-warnings.json` (`3d slice-warnings record`, or `3d slice`) and
resolved or accepted with a reason. The full model → slice → G-code → start order is
`docs/workflows/print-pipeline.md`.
- A G-code never lacks its thumbnails (the Orca CLI writes none): every code path that runs a
slicer calls `slicing.thumbnails.finalize_*` on its output before the G-code is hashed or moved,
`3d printer upload|start` call `fix_in_place`, `print-preflight --fix` repairs. A new slicing
entry point without it fails `tests/test_thumbnail_guard.py`; layers in
`docs/commands/gcode-thumbnails.md`.

## Verification before "done"

Expand Down
3 changes: 2 additions & 1 deletion docs/architecture/lib-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ Target package: `lib/geometry/`, with subpackages only when a real boundary appe
### Slicing / Print Workflow

- `lib/slicing/printing.py`
- `lib/slicing/thumbnails.py` — the layers that keep a sliced G-code from missing its thumbnails: slicer settings that ask for 48x48/96x96/300x300 (`spec_for`, Prusa flags), `finalize_*` after every slice (G-code blocks, `.3mf` plate pictures), `fix_in_place` for `printer upload|start`; `tests/test_thumbnail_guard.py` fails a slicing module that skips it.
- `lib/slicing/orca_cli.py` — the one place for Snapmaker Orca / OrcaSlicer CLI knowledge: binary discovery, the slicing copy (no `<plate>` block), headless `slice_project` under the heavy lock, failure classification and the `KNOWN_QUIRKS` catalogue behind `docs/printers/u1-orca-cli.md` (#431).
- `lib/prep/` — `3d prep` (#431): `pipeline.py` (ordered, cached steps; `cache.py`), `steps.py` (adapters), `cli.py` (flags + spec file), and one library per step: `meshfix.py` (diagnose/repair + backend interface for the public meshfix library), `orient.py`, `overhang.py`, `adapt.py` (cavity fill, 45 degree wedges), `voxel.py` (scan-converted occupancy), `fit.py` (item-table fit envelope), `stability.py`, `regions.py` (landmark boxes -> colour parts/mixes), `layers.py` (adaptive layer-height plan), `project3mf.py` (Orca project 3MF + manifest), `gcode_gates.py` / `gcode_view.py`, and the proof pack (`raster.py`, `panels.py`, `report.py`, `proof.py`). Results follow `contracts.StepResult`.
- `prep_cli.py` — entry script `3d prep` runs through `cli.pyrun` with the prep dependencies (`uv sync --extra prep`).
Expand Down Expand Up @@ -285,7 +286,7 @@ Every current root Python module is listed here so future additions are intentio
- `gcode_scan.py` — one streaming pass over a sliced G-code, layer by layer: per-layer Z / height / extrusion runs (type, tool, XY) handed to consumers, plus M600 pauses, tool changes, grams per tool and feature type and footer settings; the whole file is never held; numpy only.
- `stripe_contrast.py` — perceptual layer-stripe contrast of a stack of single-colour layers at their real heights: eye-blurred profile vs its period mean, worst CIEDE2000 per layer (the `stripe contrast` check of `3d gcode-mix-gate`).
- `gcode_mix_gate.py` — the multi-colour gates of `3d gcode-mix-gate`: colour volumes attributed from the part STLs (pure / mixed per layer on the layer's own outer-wall evidence / accent / thin), pause, heads and prime tower, pocket void, layer heights, footer settings, and the `--mix-teeth` / `--cavity-teeth` controls that must FAIL (a gate that cannot fail is vacuous); numpy/scipy/trimesh.
- `gcode_thumbnails.py` — printer-screen thumbnail blocks in G-code: stdlib-only check against the profile's `thumbnails` spec, Orca-format block writer, z-buffered toolpath preview render (numpy); backs `3d gcode-thumbnails`.
- `gcode_thumbnails.py` — printer-screen thumbnail blocks in G-code: stdlib-only check against the profile's `thumbnails` spec (48x48/96x96/300x300 PNG when it names none), Orca-format block writer, z-buffered toolpath preview render (numpy); backs `3d gcode-thumbnails`.
- `frame_check.py` — render framing checks.
- `ha_deploy.py` — `3d ha deploy`: manifest/snippet/compose/vendor checks for `integrations/homeassistant/`, plan from a host probe, backup → submodule checkout → symlinks/copies → check_config → reloads → service recreate → post-checks with rollback, HA-repo deploy PR.
- `ha_vision.py` — `3d ha vision`: generates the Home Assistant side of camera vision (vision sensors, alert frame grabber, go2rtc stream, camera proxy service, dashboard camera cards, ghost switch) for every fleet printer with a camera, from `fleet/printers.yaml`; checks the committed files for drift and missing entities.
Expand Down
29 changes: 24 additions & 5 deletions docs/commands/gcode-thumbnails.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,21 @@ A printer screen (Snapmaker U1, any Klipper/Moonraker host, Creality K1 stock fi
## Usage

```
3d gcode-thumbnails check <file.gcode>... [--json]
3d gcode-thumbnails add <file.gcode>... [--image PNG] [--size WxH/FMT]... [--out FILE] [--replace] [--preview PNG] [--json]
3d gcode-thumbnails check <file.gcode|file.3mf>... [--json]
3d gcode-thumbnails add <file.gcode>... [--image PNG] [--size WxH/FMT]... [--out FILE] [--replace] [--preview PNG] [--3mf X.3mf [--plate N]] [--json]
3d gcode-thumbnails add <file.3mf>... [--image PNG] [--json]
```

You rarely need to run this yourself: every path that produces or sends a G-code adds the thumbnails on its own (see [Layers](#layers-a-thumbnail-cannot-be-missed)).

| Subcommand / option | What |
|---|---|
| `check` | PASS/FAIL per file. PASS = every size of the profile's `; thumbnails =` is present as a valid block in the first MiB (what Moonraker reads). No spec in the file: PASS when at least one thumbnail is present. Exit 1 on any FAIL. |
| `check` | PASS/FAIL per file. PASS = every size of the profile's `; thumbnails =` is present as a valid block in the first MiB (what Moonraker reads). No spec in the file: 48x48, 96x96 and 300x300 PNG are required. A `.3mf`: every plate has `Metadata/plate_N.png` and `plate_N_small.png`. Exit 1 on any FAIL. |
| `add` | Insert the missing sizes. The file is rewritten atomically with its mode and mtime kept (a staleness check "G-code older than its project" must not be fooled). A file that already passes is left byte-identical. |
| `--image PNG` | Use this picture (e.g. a plate render; transparent margins trimmed) instead of drawing one from the G-code. Needs Pillow. |
| `--size WxH[/FMT]` | Sizes for a G-code without a `; thumbnails =` spec (repeatable). 1..4096 px per side, otherwise exit 2 (also applies to the profile's own spec). |
| `--size WxH[/FMT]` | Sizes added on top of the required ones (repeatable). 1..4096 px per side, otherwise exit 2 (also applies to the profile's own spec). |
| `--3mf X.3mf [--plate N]` | Also add the missing `Metadata/plate_N.png` (512 px) and `plate_N_small.png` (128 px) to this project, drawn from the same render (written atomically, the project's mtime kept so it does not look newer than the G-code). Plate 1 also gets the package thumbnail relationship. |
| `add X.3mf` | A `.gcode.3mf` / sliced project: the missing plate pictures, drawn from each embedded `Metadata/plate_N.gcode` (or from `--image`). |
| `--out FILE` | Write the result to `FILE`, leave the input untouched (one input only). |
| `--preview PNG` | Also save the full-size G-code render. |
| `--replace` | Redraw every size, dropping the thumbnail blocks already in the head (e.g. after a better `--image`). |
Expand All @@ -27,6 +32,20 @@ A printer screen (Snapmaker U1, any Klipper/Moonraker host, Creality K1 stock fi
3d gcode-thumbnails add other.gcode --size 300x300/PNG --size 32x32/PNG
```

## Layers: a thumbnail cannot be missing

The Orca CLI writes no thumbnails, so nothing may depend on somebody remembering `add`. Five independent layers; each one alone gets a bare G-code to all required sizes, and none changes a G-code that already has them (it stays byte-identical; a block that is there is never duplicated or redrawn). The code is `lib/slicing/thumbnails.py`.

| Layer | Where | What it does |
|---|---|---|
| (a) ask the slicer | `slice_project` / `slice_stl_with_profiles` (`3d prep`, calibration), `3d slice` of a `.3mf`, `3d retarget --gcode`, PrusaSlicer via `--thumbnails 48x48,96x96,300x300` | The slicer's `thumbnails` setting also asks for 48x48, 96x96 and 300x300 PNG on top of what the preset names (the preset's own sizes and string/list shape are kept; a copy is slicing-ready, the user's file is never rewritten). A slicer that writes thumbnails (Orca GUI, PrusaSlicer, Bambu Studio) does; for every other one the config block names the sizes the checks require. |
| (b) draw after the slice | `3d slice`, `3d prep`, `3d retarget --gcode`, `3d calibrate gen` (all kinds), `3d gcode-resume` (its output copies the head of a G-code that may have had none) | Before the G-code is hashed, moved or recorded, the missing sizes are drawn from the toolpaths and inserted. A `.gcode.3mf` / `sliced.3mf` gets its missing plate pictures from the same render. A G-code that extrudes nothing visible (console macros) gets a neutral grey tile. A failure is a failed slice (`3d slice` exits 1, `3d prep` reports `thumbnails`) and names the repair command. `--dry-run` keeps no G-code and renders nothing. |
| (c) before upload / start | `3d printer upload`, `3d printer start` | The missing sizes are added to FILE **in place** (atomic, mode and mtime kept, a current slice-warnings record follows the new SHA-256) before the snapshot is hashed; the old and new SHA-256 are printed. The remote name is content-addressed, so the fixed bytes have a name of their own: a `start` after such a fix finds no stored copy and asks you to upload again. |
| (d) preflight | `3d print-preflight` | FAIL on a missing size, naming the exact command (`3d gcode-thumbnails add 'FILE'`). `--fix` runs it before the checks (the one option that writes). |
| (e) the gate | `tests/test_thumbnail_guard.py` (part of `dev run test` and the pre-commit fast gate) | Fails when a module of `lib/` runs a slicer (`--slice`, `--outputdir`, `-g --output`) without calling a layer-(b) function, unless it is listed as exempt with a reason (`slice-check` discards its G-code; the mix tester only reads a probe project back). |

Not covered by (b): the U1 calibration plate generator (`calibration_plates/u1_underlay.py`, [#724](https://github.com/alex-mextner/3d-cli/issues/724): the module is over the repo's lint file-length gate and cannot be committed until it is split; its G-code gets thumbnails from layers (c) and (d)), and a G-code that some other program writes straight to disk, outside `lib/`. Layers (c) and (d) catch it before it reaches a printer. A `3d mix tester` project is sliced in the Orca GUI, which writes its own thumbnails.

## Format written

Exactly Orca's own block (GCode/Thumbnails.hpp), right after `; HEADER_BLOCK_END` and its blank line (after existing thumbnail blocks, if any; at the file start when there is no header) — always before the first move:
Expand All @@ -52,4 +71,4 @@ Without `--image`, every visible extrusion move (walls, surfaces, bridges, brim,

## Printer preflights

`lib/gcode_thumbnails.py` is importable: `check(path) -> ThumbCheck(ok, required, present, missing, reason)` (stdlib only, raises `InputNotFound` for a missing file) and `ensure(path, image=None, sizes=None, out=None) -> ThumbCheck` (numpy).
`lib/gcode_thumbnails.py` is importable: `check(path) -> ThumbCheck(ok, required, present, missing, reason)` (stdlib only, raises `InputNotFound` for a missing file) and `ensure(path, image=None, sizes=None, out=None) -> ThumbCheck` (numpy). `lib/slicing/thumbnails.py` has the layer entry points: `finalize_slice(gcode, three_mf=None)` / `finalize_gcode` / `finalize_workdir` (b), `fix_in_place` (c), `spec_for` / `with_project_spec` / `with_machine_spec` (a).
6 changes: 4 additions & 2 deletions docs/commands/print-preflight.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,14 @@ input is missing is SKIP and its line says what to pass — it never passes sile
```
3d print-preflight FILE.gcode [--printer NAME] [--axis-limits X0:X1,Y0:Y1|NAME] [--source-3mf FILE.3mf]
[--visible [OBJ:]SPEC]... [--bridge-max MM] [--printops-api URL] [--offline]
[--printops-snapshot FILE] [--accept preset_match|mix_calibration|spool_in_sync --reason TEXT] [--json] [--secs S] [--no-bed-move]
[--printops-snapshot FILE] [--accept preset_match|mix_calibration|spool_in_sync --reason TEXT] [--json] [--secs S] [--no-bed-move] [--fix]
```

`--fix` adds the thumbnails the G-code lacks, in place (header only; mtime kept, a current slice-warnings record follows the new SHA-256), then runs the checks. It is the only option that writes.

| Check | When | FAIL means |
|---|---|---|
| `thumbnails` | always | The G-code lacks preview images its `; thumbnails =` spec asks for (fix: `3d gcode-thumbnails add FILE`). |
| `thumbnails` | always | The G-code lacks preview images its `; thumbnails =` spec asks for (48x48, 96x96 and 300x300 PNG when it names none). The line names the exact fix, `3d gcode-thumbnails add 'FILE'`; `--fix` runs it. [Layers](gcode-thumbnails.md#layers-a-thumbnail-cannot-be-missing) add thumbnails earlier, so this FAIL means the G-code came from outside them. |
| `printer` | `--printer` | The printer is printing, paused, busy, or its state cannot be read. |
| `bed` | `--printer` with `watch.bed.enabled` (SKIP otherwise) | The camera sees objects on the bed or the build plate missing against the empty-bed reference; WARN when it cannot tell (no reference at this Z, plate out of view, camera down). See [Bed state](printer.md#bed-state). On an idle printer with `watch.bed.auto_view` (the U1: its camera sees 15 % of the plate at the Z 200 rest) the bed is moved in Z only to where the whole plate is in view, judged there and put back, and the line names the Z used; never while printing/paused, never homing; `--no-bed-move` judges at the current Z. |
| `slot Tn` | `--printer` on a printer with per-head data (Snapmaker U1) | Tool *n* is used by the G-code but head T*n+1* is empty, or its colour/material differs from `; filament_colour` / `; filament_type`. |
Expand Down
4 changes: 2 additions & 2 deletions docs/commands/printer.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@ Epic: [#90](https://github.com/alex-mextner/3d-cli/issues/90).
|---|---|
| `list` | Every fleet and configured printer: owner, access, model, address, heads (an unusable head with its reason), and where the device settings came from when a user/project file overrides the fleet. |
| `status NAME` | State, current file and progress, temperatures, and (U1) what each head holds. |
| `upload NAME FILE` | Store the file on the printer and verify its size there. Never starts a print. |
| `start NAME FILE --yes` | Start a file that was uploaded before. Runs [`3d print-preflight`](print-preflight.md) first. |
| `upload NAME FILE` | Store the file on the printer and verify its size there. Never starts a print. A FILE without its preview thumbnails gets them first, in place (old and new SHA-256 printed; see [`3d gcode-thumbnails`](gcode-thumbnails.md#layers-a-thumbnail-cannot-be-missing)). |
| `start NAME FILE --yes` | Start a file that was uploaded before. Runs [`3d print-preflight`](print-preflight.md) first. Adds missing thumbnails to FILE in place like `upload`; the fixed bytes have another content-addressed name, so upload again. |
| `cancel NAME --yes` | Cancel the running or paused job. |
| `evidence NAME --out DIR` | After EVERY print (done, cancelled, failed): save the Moonraker history job and the klippy.log lines around its pauses and errors as `DIR/<date>-<outcome>.md` + `.json`, with the layer of each stop when `--gcode` is given; GET only. See [printer-evidence.md](printer-evidence.md). |
| `guard NAME --job-id ID --yes` | Authorize one automatic native PAUSE of this exact live Moonraker job on confirmed camera failure; [policy and readiness](printer-vision.md#one-job-automatic-pause). |
Expand Down
2 changes: 1 addition & 1 deletion docs/printers/u1-orca-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ Each row: what you see, why, what to do, where it was observed.
| `arrange-moves-objects` | objects overlap, slice fails with -101 | without `--arrange 0` the CLI arranges the plate itself | pass `--arrange 0` | babushkin-dom `gen/verify_slices.py` (P1S roofs, error -101) |
| `inherits-one-level` | settings of grandparent presets are lost | `--load-settings` resolves one `inherits` level | flatten the chain (`SystemPresets.flat`) | babushkin-dom `gen/build_orca_3mf.py` |
| `application-tag-newer` | the CLI refuses a project we wrote: `result.json` `return_code` -24, "Unsupported 3MF version" | an `Application` tag newer than the CLI's build number is rejected (even `Snapmaker_Orca-2.4.0`, the tag the CLI wrote itself; reproduced by `test_real_cli_refuses_its_own_unstamped_project`) | stamp the build number (`01.10.01.50`) | babushkin-dom `gen/build_orca_3mf.py` `orca_version()` |
| `no-thumbnails` | sliced G-code has no preview image | `export_gcode` gets a null thumbnail callback | `3d gcode-thumbnails add FILE` | babushkin-dom `gen/verify_slices.py` |
| `no-thumbnails` | sliced G-code has no preview image | `export_gcode` gets a null thumbnail callback | nothing: `slicing.orca_cli` asks for 48x48/96x96/300x300 and draws what is missing after every slice (by hand: `3d gcode-thumbnails add FILE`) | babushkin-dom `gen/verify_slices.py` |
| `host-noise-warnings` | a clean slice lists warnings (version banner, OpenGL / GLFW / Wayland) | headless thumbnail renderer and banner logged as warnings / errors | ignore; `SliceOutcome.warnings` omits them (`slice_warnings.HOST_NOISE`) | `lib/slicing/slice_warnings.py` |

## Related
Expand Down
4 changes: 2 additions & 2 deletions docs/workflows/print-pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ it keeps the orientation, supports and tuned settings and fails loudly when the
Every slice records the slicer's own warnings next to the G-code, bound to its SHA-256:
`3d slice` does it itself; a project script that runs the slicer CLI keeps its stdout+stderr,
`result.json` and (with `--export-3mf`) the sliced 3MF, and after the last edit of the G-code
(`3d gcode-thumbnails add` moves a current record along) calls
(`3d gcode-thumbnails add` moves a current record along; `3d prep`, `3d slice` and `3d retarget` add the thumbnails themselves) calls
[`3d slice-warnings record`](../commands/slice-warnings.md):

```bash
Expand All @@ -57,7 +57,7 @@ All of these run inside `3d print-preflight FILE.gcode`; each is also a command
| 4 | head sequence | [`3d slice-check PLATE.3mf --gcode FILE.gcode --check head-sequence`](../commands/slice-check.md) | an object printed on the wrong head on some layer (mixed-filament patterns); needs the project 3MF |
| 4a | mix face | [`3d mix check PLATE.3mf`](../commands/mix.md) (the same check, on the project 3MF next to the G-code) | a part in a mixed filament whose top outweighs half its walls; by the project 3MF (FAIL), else by the G-code alone for objects printed by several heads (WARN) |
| 4b | mix layers | [`3d mix gcode FILE.gcode --project PLATE.3mf`](../commands/mix.md) (the same check) | the additional colour printed on consecutive layers, a colour band or a mixed layer thicker than 0.12 mm, measured on the real per-layer heads and Z; works without the project for objects that alternate one head per layer |
| 5 | thumbnails | [`3d gcode-thumbnails check FILE.gcode`](../commands/gcode-thumbnails.md) | missing printer-screen previews |
| 5 | thumbnails | [`3d gcode-thumbnails check FILE.gcode`](../commands/gcode-thumbnails.md) | missing printer-screen previews (added automatically by every slicing wrapper, `upload`/`start` and `print-preflight --fix`) |
| 6 | visible faces | [`3d visible-faces --gcode FILE.gcode --visible 'WALL*:y<104.8'`](../commands/visible-faces.md) | support or sagging islands on a visible side, in the real toolpaths |

## 4. `print-preflight`, then `printer start`
Expand Down
Loading
Loading