feat: acquisition method schema v2 — FOV patterns, per-well Z, tilted-plate pre-AF (GUI + API)

[hongquanli]

Summary

Acquisition-method schema v2: per-well FOV patterns, per-well Z control, and tilted-plate pre-autofocus positioning — with the GUI and the REST/method API both reading and writing the evolved schema. Realizes the "get YAML acquisition straight" goal from the core-service design docs.

Draft / stacked PR. Base is feat/squid-core-service (#578), not master — the diff shows only schema-v2's changes. Do not merge until #578 lands; GitHub will retarget this to master automatically when #578 merges and its branch is deleted. The first commit (port per-region laser-AF offset core hook from PR #562) is a forward-port of the #562 worker hook this builds on; it becomes a no-op on rebase once #562 or #578 carries it.

What's in it

FOV patterns (wellplate_scan.fov_pattern, per well):

• coverage — area tiling (scan_size_mm + overlap_percent, with shape clipping). Today's behavior; the flat scan_size_mm/overlap_percent shorthand still means coverage.
• centered_grid — an exact nx×ny montage centered on each well.
• grid_subset — a chosen set of tiles: [[row,col],…] from that grid, identical in every well, with deterministic row-major indexing (i = row*nx + col).
• random — n_fovs points sampled inside each well, reproducible-but-independent per well via sha256(seed:well) (never hash()).

Per-well Z — two distinct mechanisms (a real design point, kept separate on purpose):

• well_z_offsets_um (TYPE-1, AF target offset): shifts where laser AF settles per well, µm from the AF reference plane. Requires laser_af; range-checked at preflight. Consumed via the per-region AF-offset hook (worker anchors at the reference, then applies the offset open-loop).
• z_plan (TYPE-2, pre-AF stage positioning): for tilted plates, moves the stage to a fitted plane before AF so the laser spot lands within capture range. points: (3 [x,y,z]) bakes a known plane into the FOV coordinates; generate: true measures a 3-corner plane at run start (now works alongside reflection AF — the contrast-AF gate was loosened and the generated plane is baked into coordinates).

GUI + API both on v2:

• GUI wellplate saves emit wells: + fov_pattern: for Select-Wells mode (breaking: drops regions[].center_mm there — manual/coordinate modes keep it). The reader loads both old and new forms and cleanly rejects (with a warning that now propagates as a load failure) patterns it can't yet render.
• API/service-driven runs save a faithful v2 record too — the real fov_pattern is threaded to the acquisition-record writer, so a centered_grid/grid_subset/random method (and inline grid requests) round-trip as v2 instead of flattening to legacy regions.
• Method-registry summaries expose pattern; quickstart-api.md + core-service-api.md document all three fields.

Backward compatibility

• Old regions[].center_mm YAML still parses and loads (service and GUI reader) and still round-trips as regions on API legacy-method runs.
• Non-GUI acquisition entry points are unaffected unless a method opts into the new fields.
• Breaking change is scoped to what the GUI writes for Select-Wells saves (nothing YAML-related has shipped).

Testing

• 98 schema-v2 tests (loader, four patterns, well_z_offsets preflight + resolution, z_plan points/generate, GUI writer/reader, API v2 round-trip incl. grid, registry) pass together.
• Full suite green: 1636 passed, 0 real failures (run split to avoid an unrelated Qt-under-load hang in test_widgets.py, which passes 135/135 in isolation). black==25.12.0 + ruff F401/F841 clean on changed files.
• Built via 10 spec-driven tasks, each independently implemented and reviewed, plus a final whole-branch review. Three merge-blockers were found and fixed during review: a YAML-load abort that reported success (could start an acquisition with stale well selection), z_plan colinearity surfacing as a 500 after preflight passed, and the loosened gen-map gate leaving a job stuck in ACQUIRING on a bounds/measurement failure.

Reviewer notes

• Read order: acquisition_yaml_loader.py (schema + validation) → squid_service/service.py _configure_regions/_add_*_region (pattern dispatch), _resolve_well_z_offsets + preflight, _apply_z_plan_points → multi_point_controller.py (the one production-controller behavior change: the loosened elif self.gen_focus_map: gate + reflection-AF plane baking) → the writer threading (fov_pattern on AcquisitionParameters) → GUI widgets reader/writer.
• Deferred to follow-up (from the whole-branch review, none blocking): grid_subset/random geometry faults raised at start rather than preflight (and not recorded to fault history); baked z not stage-Z-range-checked (relies on stage clamp); a picker UI for the new patterns in the GUI (API/method support does not wait for it); minor message/DRY polish.

🤖 Generated with Claude Code

[hongquanli]

Review guide

Stacked / draft. Base is feat/squid-core-service (#578), so the diff above is only schema-v2. Don't merge until #578 lands (GitHub retargets this to master automatically then). First commit forward-ports the #562 worker hook and no-ops away on rebase once #562/#578 carries it. 19 commits, +1.5k, CI green on Linux.

How it was built: 10 spec-driven tasks, each independently implemented + reviewed, plus a final whole-branch review — which found and fixed 3 merge-blockers (a YAML-load abort that reported success and could start an acquisition with stale wells; z_plan colinearity surfacing as a 500 after preflight passed; the loosened gen-map gate leaving a job stuck ACQUIRING). Line-level correctness was reviewed exhaustively; spend your time on the judgment calls below.

Reading order (each layer builds on the previous):

1. control/acquisition_yaml_loader.py — the v2 schema + all validation (fov_pattern 4 types, well_z_offsets_um, z_plan). Sets the vocabulary.
2. squid_service/service.py — _configure_regions/_add_*_region (pattern dispatch), _resolve_well_z_offsets + preflight, _apply_z_plan_points.
3. control/core/multi_point_controller.py — the one production-controller behavior change: the loosened elif self.gen_focus_map: gate + the reflection-AF plane-baking branch. Also the fov_pattern/offset threading to the writer.
4. GUI control/widgets.py reader/writer + multi_point_controller._save_acquisition_yaml.

Where human judgment matters most:

• The two Z mechanisms are deliberately distinct — well_z_offsets_um (TYPE-1: shifts where laser AF settles, µm from the reference plane) vs z_plan (TYPE-2: moves the stage to a fitted plane before AF so a tilted plate lands in capture range). Confirm this split matches how you focus at the bench, and that the composition order (z_plan coarse-position → laser AF anchors at reference + offset) is right.
• Tilted-plate generate: true measures a 3-corner contrast-AF plane at run start even on a laser-AF run — worth a domain eye.
• Breaking change, scoped: GUI Select-Wells saves now emit wells:+fov_pattern: and drop regions[].center_mm there only (manual/coordinate modes unchanged; old files still load). Nothing YAML-related has shipped, so this was sanctioned.
• Determinism: random uses sha256(seed:well) (reproducible-but-independent per well), grid_subset forces row-major indexing.

Hardware validation (sim can't prove these): a real tilted-plate acquisition (z_plan) and a real per-well-offset acquisition (well_z_offsets_um) on an instrument — the laser-AF-in-capture-range and offset-anchoring behavior are exactly the untested seam.

Deferred to follow-up (none blocking): grid_subset/random geometry faults raised at start not preflight; baked z not stage-Z-range-checked (relies on stage clamp); a GUI picker for the new patterns (API/method support doesn't wait for it).

🤖 Generated with Claude Code