Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
49d3fae
feat(slicing): thumbnails are added after every slice, in the slicer …
alex-mextner Nov 4, 2026
9e543ad
feat(printer): upload and start add missing thumbnails; print-preflig…
alex-mextner Nov 4, 2026
5a639fc
feat(bed): `3d printer bed check`, `reference --best-view`, and a ver…
alex-mextner Nov 4, 2026
ff6088f
feat(printer): `3d printer watch NAME --job` aborts a print whose par…
alex-mextner Nov 4, 2026
bf0da29
feat(jobwatch): follow the plate on a printer without a camera calibr…
alex-mextner Nov 4, 2026
630ce51
feat(bed): the printer's light for camera frames: detection, session,…
alex-mextner Nov 4, 2026
9d42cd3
feat(bed): every camera frame of the bed check, reference capture and…
alex-mextner Nov 4, 2026
46fbccc
feat(preflight): the `bed` line runs the full bed check and FAILs onl…
alex-mextner Nov 4, 2026
620b9d6
feat(bed): lighting-normalised verdict — an empty bed in another ligh…
alex-mextner Nov 5, 2026
9bdeefb
feat(print-preflight): slot colour by CIEDE2000 ΔE, --fix rewrites th…
alex-mextner Nov 5, 2026
d657c9d
fix(printer): retry a start --force approval Telegram could not post,…
alex-mextner Nov 5, 2026
48ad3ca
feat(printer): start --fix-colour and `printer slot set|show` align f…
alex-mextner Nov 5, 2026
612148c
test(printer): e2e for a start --force approval that Telegram could n…
alex-mextner Nov 5, 2026
79f4c90
feat(bed): references per plate type and light state with an age, `be…
alex-mextner Nov 5, 2026
36f710b
feat(bed): `3d printer bed calibrate NAME` learns the plate's visible…
alex-mextner Nov 5, 2026
5ccdf51
feat(bed): `bed check --assume-empty "why"` — the owner's auditable w…
alex-mextner Nov 5, 2026
9c69300
refactor(vision): split the over-complex functions of vision_detect.p…
alex-mextner Nov 5, 2026
403be12
feat(printer): print-quality measures and judge — stringing, pattern …
alex-mextner Nov 5, 2026
b39c2d6
feat(printer): job watch runs the print-quality tier and writes the m…
alex-mextner Nov 5, 2026
f77bb3f
feat(vision): printer vision runs the print-quality tier (Refs #733)
alex-mextner Nov 5, 2026
ea27db3
fix(printer): the first-layer floor is on only for a calibrated camer…
alex-mextner Nov 5, 2026
d35e2cf
fix(printer): per-model quality defaults come from a data file, not a…
alex-mextner Nov 5, 2026
bac07c1
merge: origin/main into feat/gcode-thumbnails-everywhere (Refs #722)
alex-mextner Nov 5, 2026
dcb63fa
merge: feat/gcode-thumbnails-everywhere into feat/slot-colour-fix; on…
alex-mextner Nov 5, 2026
4f501dd
test(thumbnails): user-workflow docstrings for the three e2e stories …
alex-mextner Nov 5, 2026
d34af67
Merge branch 'feat/gcode-thumbnails-everywhere' into feat/slot-colour…
alex-mextner Nov 5, 2026
659302f
test(printer): user-workflow docstrings for two colour e2e stories (R…
alex-mextner Nov 5, 2026
c7ac1ff
merge: feat/slot-colour-fix (with thumbnails) into feat/bed-watch-too…
alex-mextner Nov 5, 2026
4d53168
Merge branch 'feat/slot-colour-fix' into feat/bed-watch-tool
alex-mextner Nov 5, 2026
8aec241
Merge branch 'feat/bed-watch-tool' into feat/print-quality-monitor
alex-mextner Nov 5, 2026
652af64
merge: origin/main (squashed #725) into feat/bed-watch-tool; tree unc…
alex-mextner Nov 5, 2026
b26a036
merge: feat/bed-watch-tool into feat/print-quality-monitor (Refs #733)
alex-mextner Nov 5, 2026
9f8d49a
merge: origin/main (squashed #727) into feat/print-quality-monitor; t…
alex-mextner Nov 5, 2026
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
2 changes: 2 additions & 0 deletions docs/architecture/lib-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,8 @@ Every current root Python module is listed here so future additions are intentio
- `bed_view.py` — the auto view of the printer bed (#303 follow-up): pure picker of the best inspection Z (share of the plate in the camera frame, reference at that Z, clearance floor, axis ceiling), the guarded Z-only move + judge + restore flow `bed_state.py status` runs (`watch.bed.auto_view`). Stdlib only; the pixels stay in `bed_state.py`.
- `bed_photo.py` — the table photo of a finished print (#579): plan a lift of the bed to a viewing Z (`--lift MM` or `auto` from the camera calibration, within `bed_view.move_limits`), `bed_view.guarded_z_move`, a fresh camera frame, restore in a `finally`; dry run by default. Backs `3d photo capture`; the camera/printer are injected so tests never touch a printer.
- `bed_part.py` — the pixel half of `3d printer watch NAME --job` (#723): the changed share of the plate region against the job's empty-plate baseline (homography-warped to the current Z with a camera calibration; without one the plate is FOLLOWED on the picture — a chained ECC affine transform saved with every healthy footprint, `--track`/`--save-track`, so the baseline survives the bed's drift), and how much of the part's learnt footprint is still changed / how much changed beyond it; `blind` (never "gone") when the plate is out of view, cannot be followed, or the baseline cannot stand. Stateless, read-only; decisions live in `printer_ops/jobwatch.py`.
- `print_quality.py` — the pixel half of the print-quality monitor (#733): in the plate region of a frame (640 px wide) `fleck_frac` (small bright NEUTRAL specks and strands — the top-hat of the minimum colour channel — i.e. stringing debris), `order` (energy-weighted structure-tensor coherence: how regular the bead pattern is) and `luma`; `blind` when the plate is out of view. Stateless, read-only; run by `printer_ops/jobwatch_quality.py` as a subprocess and imported by `vision_quality.py`. Decisions live in `printer_ops/quality.py`; calibration in `docs/research/print-quality-monitor.md`.
- `vision_quality.py` — the print-quality tier of `3d printer vision` (#733): `QualityTier` measures each frame (`print_quality.py`), judges it with `printer_ops/quality.py` against the print's own first layers and returns `Finding`s (`quality_<issue>_<level>`, warning/severe -> a WARNING event with the marked frame, notice -> info; never critical, never a pause); `--once` reports the absolute verdict of one frame; writes the per-print monitoring report when the print ends.
- `lib/geometry/mesh_metrics.py` — pinned-convention 3D shape metrics (Chamfer, F-score@tau, Hausdorff, normal consistency, volumetric IoU) between two meshes; backs `3d metrics geometry`.
- `perceptual_metrics.py` — perceptual/semantic image metrics (PSNR, LPIPS, CLIP-sim) with explicit senses and graceful degradation; backs `3d metrics perceptual`.
- `metrics.py` — compatibility wrapper re-exporting `registries.metrics`.
Expand Down
34 changes: 33 additions & 1 deletion docs/commands/printer-vision.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ from the device's `watch:` block in `printer-devices.yaml`).
```text
3d printer vision NAME [--interval S] [--once] [--save OUT.jpg] [--dry-run] [--min-severity LEVEL]
[--snapshot URL|PATH] [--no-keepalive] [--no-npu] [--evidence DIR] [--verbose]
[--no-verify] [--no-geometry] [--scene] [--no-detach] [--model | --no-model]
[--no-verify] [--no-geometry] [--scene] [--no-detach] [--no-quality] [--model | --no-model]
3d printer vision eval --pos PATH... --neg PATH... [--every N] [--warmup N] [--interval S]
[--lead-in N] [--printer NAME] [--no-verify] [--scene] [--no-detach] [--json]
[--model [--model-class CLASS]]
Expand Down Expand Up @@ -37,6 +37,11 @@ from the device's `watch:` block in `printer-devices.yaml`).
- `--no-detach` — skip the part-detached check (`vision_part_detached`, below); same as `detach: false` in the
device's `watch: vision:` block, which can also hold a mapping that tunes it. With `--once` the report adds
`detach_gap` (0..1, null = the check abstained) and `part_detached` (gap at or above the absolute threshold).
- `--no-quality` — skip the print-quality tier (below) and its per-print monitoring report; same as
`watch.quality: false`. With `--once` the report adds a `quality` block: the numbers
(`fleck_frac`, `order`), the ABSOLUTE verdict of that one frame (`level`, `issue`, `basis`) — a single
frame has no job baseline, so it is a hint to look at the frame — and `findings` lists
`quality_<issue>_<level>`. Without the print position (Z) it says `status: blind` and why.
- `--scene` — also run the bed-change detectors (`vision_foreign_object`, `vision_part_moved` — against a
3-12 min reference and, for slow drift, a 15-60 min one — and `vision_no_growth`). Off by default: they are still noisy (see
[printer-vision-tuning.md](../research/printer-vision-tuning.md)). Same as `scene: true` in the
Expand Down Expand Up @@ -95,6 +100,9 @@ from the device's `watch:` block in `printer-devices.yaml`).
| `vision_part_detached` | warning, then critical | the printed part looks lifted/peeled off the plate: bare build plate shows where the near wall of the part should be (details below); on by default with the camera calibration; never pauses |
| `vision_model_spaghetti` | warning | tier (b): the whole-frame model scores loose filament >= 0.5 on 3 model runs (30 s apart) in a row; a second opinion next to `vision_spaghetti`, never a pause |
| `vision_model_part_detached`, `vision_model_empty_bed` | warning | tier (b), **off by default** (no skill zero-shot): only with a fitted head (`fit-head`) or a `threshold` in `watch.vision.model`; `vision_model_empty_bed` is only judged once the print is at least `min_z` (10 mm) high |
| `quality_stringing_warning`, `quality_stringing_severe` | warning | the print-quality tier: white stringing debris on the plate, against the print's own first layers (below); a WARNING event with the marked frame, once per issue and level, **never a pause** |
| `quality_texture_*`, `quality_first_layer_*` | warning | the bead pattern got lost with no debris (stripes, roughness, under/over-extrusion) / an uneven first layer (absolute floor) |
| `quality_<issue>_notice` | info | the first sign of the same; only subscribers that asked for info |
| `vision_foreign_object`, `vision_part_moved` | warning | only with `--scene`: something new on the bed outside the parts / a part's silhouette changed |
| `vision_no_growth` | info | only with `--scene`: the newest layers of a part look empty (under- or no extrusion) |
| `printer_noodle_verdict` | warning | the U1's own NPU detector logs a defect label (table below) at or above 0.83 (once per episode, 5 min quiet ends it) |
Expand Down Expand Up @@ -336,6 +344,25 @@ an `auto_pause` event in `printer-agents/NAME/events.jsonl` and the journal.
printing and logs each verdict to klippy.log; vision tails that log over HTTP Range requests.
Moonraker does not expose the detector itself (`camera.detect_capture` → -32601).

## Print quality (stringing, pattern loss, first layer)

Tiers (a) and (b) look for FAILURES. None of them knows stringing: the Obico model scored p 0.0 / q 0.0 on all
12 frames of the 2026-11-05 sheet job whose layers 2-4 were covered in white thread debris, so nothing was
flagged until the owner saw the part. The quality tier (`lib/vision_quality.py`, `lib/print_quality.py`,
`printer_ops/quality.py`) measures each frame in the plate region at the print's Z (`fleck_frac`: white
specks and strands; `order`: regularity of the bead pattern) and judges it against the print's OWN first
layers: the first frame of the print is the empty-plate reference (a part stands once a frame differs from
it; past the first layers it always does), the first 4 readings with a part are the baseline. Levels notice
< warning < severe, 2 of the last 4 readings to report one, one WARNING event with the marked frame
(`tg --photo FRAME "<russian text>"` through the dispatcher) per issue and level — a second level inside the
dispatcher's cooldown folds into its `+N more` line — and **never a pause**. When the print ends
(or another starts) `<evidence>/<printer>-<stamp>-monitor-report/` gets `report.json`, `report.md` and
`worst-frame.jpg`; one stderr line says where. It needs the camera calibration or `watch.bed.roi` for the plate
region and the print context (Z) from Moonraker. Start the supervisor at the beginning of a job: a print adopted
mid-way has no first layers to learn from. Numbers, calibration and limits:
[print-quality-monitor.md](../research/print-quality-monitor.md). The job watch
([`printer watch --job`](printer.md#print-quality-monitor)) runs the same tier on its own frames.

## Three tiers

1. **(a) cheap checks, every frame.** The pipeline above: stale/dark camera, Obico boxes + CLIP
Expand Down Expand Up @@ -427,6 +454,11 @@ u1:
head: ~/.cache/3d-cli/vision/models/tier-b-head.json # default; from `fit-head`
```

`watch.quality` (a sibling of `vision:`, shared with `printer watch --job`) tunes the print-quality tier:
`quality: false` turns it off, `quality: {baseline_n: 4, warning_ratio: 2.0, warning_abs: 0.035, severe_ratio:
3.5, severe_abs: 0.06, warning_drop: 0.10, first_layer_order: 0.6, ...}` any `QualityConfig` field
(`printer_ops/quality.py`); a wrong key is an error naming the valid ones. The first-layer floor (`first_layer_order`, 0 = off) is on by default only for a Snapmaker U1, the camera it was calibrated on.

The block is per device, so every Moonraker printer in the fleet (U1, K1 SE, others) gets its own
camera `snapshot`, thresholds and `crop`; nothing in tier (b) is U1-specific.

Expand Down
38 changes: 37 additions & 1 deletion docs/commands/printer.md
Original file line number Diff line number Diff line change
Expand Up @@ -979,7 +979,7 @@ alerts an agent): this one *acts*, so it needs `--yes` — you authorise a pause
```
3d printer watch NAME --job --yes [--on-fail auto|pause|cancel] [--gcode FILE.gcode] [--out DIR]
[--interval S] [--checkpoints L1@25%,L1@50%,L1@100%,25%,50%,100%] [--dry-run | --tg-dry-run]
[--fixture SCENARIO.json] [--duration S] [--wait-start S]
[--fixture SCENARIO.json] [--duration S] [--wait-start S] [--no-quality]
```

Start it right after `3d printer start NAME FILE --yes` (or give `start` [`--watch`](#start---watch));
Expand All @@ -999,6 +999,8 @@ quarter, half and all of the first layer — the first-layer marks need `--gcode
- *Signals.* The same Moonraker events as the always-on watch (filament runout, heater loss, bed off,
exception, G-code error, homing lost), and the printer's own defect detection (`noodle` verdicts
with p >= 0.8, read from klippy.log).
- *Print quality* ([below](#print-quality-monitor)). Is the print GOOD, not just still there: stringing
debris, a lost bead pattern (stripes, roughness), an uneven first layer. Warnings only, never a stop.

**Actions on a critical finding**, in this order, each step runs even if an earlier one failed:

Expand All @@ -1012,6 +1014,40 @@ quarter, half and all of the first layer — the first-layer marks need `--gcode
A warning (part moved, nothing seen, a heater drift) is only a tg message with the frame; nothing is
touched and nobody is called.

<a id="print-quality-monitor"></a>
**The print-quality monitor** (#733; `lib/print_quality.py` measures, `printer_ops/quality.py` decides) runs
on the same frame as the part check, in the plate region at the print's own Z. Why it exists: on 2026-11-05 a
10 h sheet of small tags stringed from layer 2 on — white thread debris all over the part — while the part
check (it only asks "is the part where it was") and the spaghetti model (no stringing class: p 0.0 on all
12 frames) stayed silent.

| number | what it is |
|---|---|
| `fleck_frac` | share of the plate region covered by small bright **neutral** specks and strands (the top-hat of the minimum colour channel: high only where R, G and B are all high, i.e. white debris — not beige part, not golden specular grain) |
| `order` | structure-tensor coherence: 1 = every neighbourhood has one dominant bead direction, lower = debris, webs, broken or striped lines |

The judge compares them with the **job's own first layers**: the first 4 readings with the part on the plate
(bed_part says so) are the baseline, never judged against anything but a floor; a clean reading drifts it a
little (bounded at 1.3x debris / 0.04 order), a bad one never does. Issues: `stringing` (debris against the
baseline AND an absolute level), `texture` (the pattern got lost with no debris: stripes, roughness,
under-/over-extrusion), `first_layer` (an absolute floor on `order` while layer <= 3; ON by default only for the U1, whose camera it was calibrated on — `first_layer_order: 0.6` in `watch.quality` turns it on elsewhere, a K1 SE view of a part reads 0.5 normally). Levels: `notice`
(report only) < `warning` < `severe`; a level is reported when 2 of the last 4 readings reach it (3 of 4
for severe), it is latched and clears after 6 clean readings. A debris trend (ratio to the baseline gained
per 10 min) lifts a notice to a warning.

A quality finding is **never critical**: one `tg --photo FRAME "<russian text: what is seen, what to
change>"` per issue and level (the frame has the debris marked in red), nobody is rung, the job is not
touched. Part gone, spaghetti and the noodle verdict still act as above. `--no-quality`, or
`<printer>.watch.quality: false`, turns it off; `<printer>.watch.quality: {baseline_n: 4, warning_ratio: 2.0,
warning_abs: 0.035, ...}` tunes any `QualityConfig` field (a wrong key is an error naming the valid ones).

**The monitoring report.** When the watch ends — the job completed, a lost print stopped it, or `--duration`
ran out — `DIR/<date>-NAME-monitor-report/` holds `report.json` (readings, counts per severity and per issue,
the alerts that were sent, the baseline, the worst reading, the timeline), `report.md` (the same for a human)
and `worst-frame.jpg`. A job with nothing wrong still gets one ("0 warnings in 41 judged readings"): silence
then means *checked and fine*, not *never ran*. Calibration, limits and the numbers on the real frames:
[print-quality-monitor.md](../research/print-quality-monitor.md).

**`--on-fail`.** `auto` (default): CANCEL when the part is gone, or on a camera finding in the first
layers (layer <= 3); PAUSE for everything else (runout, heater, later spaghetti: resumable).
`pause` / `cancel`: always that. Defaults can also be set in `<printer>.watch.job` (`on_fail`,
Expand Down
Loading
Loading