feat: per-region laser-AF offset (focus-map constant-z + laser AF)

[Alpaca233]

Summary

Lets each well/region be focused at its own offset from the single global laser-AF reference plane when laser autofocus (Reflection AF) and a constant-z focus map are used together — instead of every well being driven to that one shared reference plane.

Workflow: set the laser-AF reference once, define one focus point per well (the existing focus-map constant + Fit by Region case), and at each well record z. At capture, the system stores that region's laser-AF displacement (measure_displacement(), µm from the reference). During acquisition, laser AF at each FOV in a well drives to its stored offset (move_to_target(offset)) instead of the previously hardcoded move_to_target(0). This pins each well to its capture-time relationship with the reference plane, so laser AF maintains per-well focus against drift across a time-lapse.

Gated behind an explicit "Per-region laser AF offset" checkbox that is only active when Reflection AF is on and the focus map is constant + Fit by Region. The focus map's absolute z stays as the coarse pre-position; the existing per-channel z-offset composes additively (both unchanged).

What changed

• control/core/multi_point_worker.py — perform_autofocus targets region_laser_af_offsets.get(region_id, 0.0) instead of 0; new attribute unpacked from params.
• control/core/multi_point_controller.py — region_laser_af_offsets field + set_region_laser_af_offsets(); threaded through build_params; cleared per-run after build_params so stale offsets can't leak into a later acquisition from entry points that don't push them (fluidics / control server).
• control/core/multi_point_utils.py — AcquisitionParameters.region_laser_af_offsets: Dict[str, float] (defaults {} → current behavior).
• control/widgets.py (FocusMapWidget) — captures the offset on Add/Update-Z; the new checkbox + enable gating (Reflection AF + constant + Fit-by-Region); clears offsets when the laser-AF reference changes or the focus-point set changes; CSV export/import gains a back-compatible Offset_um column. Both multipoint widgets wire and push it at acquisition start (gated three ways); the third (fluidics) widget has no focus map and is untouched.
• control/gui_hcs.py — passes the laser-AF controller into FocusMapWidget (tolerates None when laser AF is unsupported).
• Docs — design spec + implementation plan under docs/superpowers/.

Backward compatibility

Empty region_laser_af_offsets (the default, and whenever the mode is off) reproduces the exact pre-feature behavior: every FOV targets displacement 0. move_to_target, the focus-map z-baking, and the per-channel z-offset logic are unchanged.

Testing

• New unit tests in tests/control/test_per_region_laser_af_offset.py (28): backend plumbing/apply, capture edge cases (no controller / no reference / NaN / out-of-range / disabled), reference-change invalidation, the constant-mode enable gating, and CSV round-trip + back-compat.
• Full suite: 1433 passed, 8 skipped, 1 xfailed; black --check clean.

Not yet done

• Interactive --simulation GUI smoke test is still pending (no display in the build env): live checkbox enable/disable, on-stage offset capture, reference-reset clearing, and CSV round-trip through the actual dialogs. The automated tests exercise the method logic via stubs but not the live Qt signal connections / acquisition-gate blocks.

Out of scope (noted)

MultiPointController.focus_map has the same pre-existing cross-entry-point staleness that the offsets had; only the new region_laser_af_offsets is reset per run here.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds support for per-region (well-level) laser reflection autofocus target offsets when using a constant-z focus map with “Fit by Region”, so each region can be maintained at its capture-time displacement relative to the global laser-AF reference plane.

Changes:

• Thread region_laser_af_offsets: Dict[str, float] through MultiPointController → AcquisitionParameters → MultiPointWorker, and use it as the laser-AF target in perform_autofocus.
• Extend FocusMapWidget to capture/clear/sync per-region offsets, gate the UI with a new checkbox, and persist offsets via an Offset_um CSV column (back-compatible read).
• Add unit tests covering backend apply path, capture edge cases, gating, invalidation, and CSV round-trip.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
software/control/core/multi_point_utils.py	Adds AcquisitionParameters.region_laser_af_offsets with default {}.
software/control/core/multi_point_controller.py	Stores/sets offsets, passes them into build_params, and clears controller state post-build to avoid stale reuse.
software/control/core/multi_point_worker.py	Uses per-region target offset in reflection AF path (move_to_target(target_um)).
software/control/widgets.py	Captures offsets in FocusMapWidget, adds UI gating + CSV persistence, and pushes offsets at acquisition start from both multipoint widgets.
software/control/gui_hcs.py	Passes the laser-AF controller into FocusMapWidget (supports None).
software/tests/control/test_per_region_laser_af_offset.py	New test suite for per-region offset behavior.
software/tests/control/test_MultiPointWorker_offsets.py	Updates AF stub to include region_laser_af_offsets for perform_autofocus.
software/docs/superpowers/specs/2026-06-18-per-region-laser-af-offset-design.md	Design spec documenting behavior and rationale.
software/docs/superpowers/plans/2026-06-18-per-region-laser-af-offset.md	Implementation plan and verification steps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.