feat: per-channel z-offset for laser autofocus

[hongquanli]

Summary

Adds a per-channel z-offset (µm) for use with laser reflection autofocus. When laser AF is the active AF method, each acquisition channel can carry a saved offset measured from the laser AF reference plane and have it applied automatically during multi-point acquisition. Optionally, the same offset can be applied on channel switches in live view (absolute positioning, robust to manual z jogs).

Motivation: different fluorescence channels need different best-focus positions due to chromatic aberration and sample-induced effects (refractive index, coverslip / mounting variations). The offset is treated as sample-dependent, not a pure optical constant — LaserAutofocusSettingWidget gains a "Reset all channel offsets" button for the new-sample workflow.

What's new

• Acquisition behavior (MultiPointWorker):
  • Delta-tracking helpers (_apply_channel_z_offset, _reset_channel_z_offset, _move_z_for_offset) that emit the minimum stage/piezo moves needed to reach each channel's offset relative to the AF reference.
  • Tail-correction in try/finally around the inner channel loop so the offset is always undone before move_z_for_stack / _last_time_point_z_pos / abort.
  • Belt-and-braces reset in handle_acquisition_abort.
  • Works for both stage path and piezo path (with range clamping + warning log).
  • Startup log summarising any non-zero offsets that won't be applied this run (laser AF off or checkbox off).
• UI:
  • LiveControlWidget gains a hidden-by-default "Show Z-offset controls" row: spinbox (±50 µm), "Capture current" (reads measure_displacement()), "Reset", and "Apply on channel switch" (absolute positioning).
  • Three acquisition widgets (FlexibleMultiPointWidget, WellplateMultiPointWidget, MultiPointWithFluidicsWidget) gain an "Apply per-channel z-offset" checkbox via a shared _ApplyChannelOffsetMixin.
  • LaserAutofocusSettingWidget gains a "Reset all channel offsets" button.
• Plumbing:
  • apply_channel_offset: bool = True on AcquisitionParameters; default keeps TCP/MCP callers backward-compatible.
  • New "ZOffset" setting key on ConfigRepository.update_channel_setting (with a location == "channel" dispatch branch).
  • New signal_reference_changed = Signal(bool) on LaserAutofocusController.
• Pre-existing bug fix (M1 in design review): repository.py:761-782's "create objective config from general" path was silently dropping z_offset_um when constructing a new AcquisitionChannel. The fix is one line; the regression test in test_repository.py would catch any reintroduction.

Skipped on purpose

NapariLiveWidget was not updated — it is gated off by USE_NAPARI_FOR_LIVE_VIEW = False and never instantiated. A follow-up cleanup PR should remove the dead widget (notes left in worktrees/docs/2026-05-23-napari-live-widget-dead-code-cleanup.md).

Test plan

• pytest software/tests/control/test_MultiPointWorker_offsets.py — 14 unit tests (delta tracking, stage + piezo paths, abort, z-stack invariant, _log_ignored_offsets)
• pytest software/tests/control/test_LiveControlWidget_offset.py — 6 unit tests (absolute positioning, gating, exception path)
• pytest software/tests/control/core/config/test_repository.py — added 3 tests (M1 regression + ZOffset round-trip + zero-value persistence)
• pytest software/tests/control/test_MultiPointController.py — added 2 tests (default apply_channel_offset + override)
• Full suite: 1310 passed, 6 failed (zero new failures — all 6 are pre-existing on master)
• black --config software/pyproject.toml --check software/ — clean
• Manual simulation smoke (display required): launch python3 main_hcs.py --simulation, walk through Show Z-offset toggle → Capture → Reset → run acquisition with two channels at distinct offsets → confirm stage moves match the design
• Hardware verification — capture offsets on a real microscope and confirm chromatic-shift correction works as expected

Design docs

• Design spec: software/docs/laser-af-channel-offset-design.md (committed)
• Implementation plan: software/docs/laser-af-channel-offset-plan.md (committed)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds support for per-acquisition-channel Z offsets (µm) relative to the laser reflection autofocus (laser AF) reference plane, applying them during multi-point acquisition (including z-stacks) and optionally during live-view channel switching, with config persistence and tests.

Changes:

• Adds delta-tracked per-channel Z-offset application/reset logic in MultiPointWorker, gated by laser AF + a new apply_channel_offset flag.
• Adds UI controls to view/edit/capture/reset per-channel offsets and to apply offsets on live channel switch; adds a “Reset all channel offsets” workflow.
• Extends config repository plumbing to persist z_offset_um via a new "ZOffset" setting key and fixes an existing objective-config creation path that dropped z_offset_um.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
software/control/core/multi_point_worker.py	Adds delta-tracking helpers, integrates per-channel offsets into acquisition loop, abort cleanup, and “ignored offsets” logging.
software/control/core/multi_point_utils.py	Adds apply_channel_offset to AcquisitionParameters (default True).
software/control/core/multi_point_controller.py	Plumbs apply_channel_offset from controller state into worker parameters.
software/control/core/config/repository.py	Adds "ZOffset" setting support and preserves z_offset_um when creating objective config from general config.
software/control/core/laser_auto_focus_controller.py	Adds signal_reference_changed and emits it on reference set/clear (partial coverage).
software/control/widgets.py	Adds live-view Z-offset controls, “apply on channel switch”, “reset all offsets”, and acquisition checkbox via mixin.
software/control/gui_hcs.py	Wires “reset all offsets” signal to refresh the live Z-offset spinbox.
software/control/models/acquisition_config.py	Updates z_offset_um field description/semantics.
software/tests/control/test_MultiPointWorker_offsets.py	New unit tests for worker offset helpers (stage + piezo + abort + logging).
software/tests/control/test_LiveControlWidget_offset.py	New unit tests for live absolute-positioning helper.
software/tests/control/test_MultiPointController.py	Tests apply_channel_offset default and override behavior.
software/tests/control/core/config/test_repository.py	Regression + persistence tests for "ZOffset" and create-from-general behavior.
software/docs/laser-af-channel-offset-design.md	Design spec for the feature.
software/docs/laser-af-channel-offset-plan.md	Implementation plan/checklist for the feature.

Comments suppressed due to low confidence (1)

software/control/core/laser_auto_focus_controller.py:32

• signal_reference_changed is only emitted in initialize_auto() (False) and set_reference() (True). However on_settings_changed() reloads cached laser AF configs on profile/objective change and can flip laser_af_properties.has_reference without emitting the signal, so widgets can end up with stale enabled/disabled state. Suggest emitting signal_reference_changed.emit(self.laser_af_properties.has_reference) after load_cached_configuration() (or in initialize_manual() when applying a config) so listeners stay in sync.

class LaserAutofocusController(QObject):
    image_to_display = Signal(np.ndarray)
    signal_displacement_um = Signal(float)
    signal_cross_correlation = Signal(float)
    signal_piezo_position_update = Signal()  # Signal to emit piezo position updates
    signal_reference_changed = Signal(bool)  # emitted with new has_reference state

    def __init__(
        self,
        microcontroller: Microcontroller,
        camera: AbstractCamera,

---

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

[Alpaca233]

[Claude Code] Fixed in e2d07bc. Confirmed Microscope had no public laser_autofocus_controller attribute — the widget's getattr fell back to None silently. Added a public property exposing _laser_af_controller, and pre-populated it in gui_hcs.py with the GUI's LaserAutofocusController so both code paths share the same instance.

[Alpaca233]

[Claude Code] Fixed in 7c4e4eb (and tracked by an updated test in the same commit). _reset_channel_z_offset now zeros _current_z_offset_um only after _move_z_for_offset returns successfully; on failure the tracker is retained so a follow-on reset attempt knows the outstanding amount. The test test_reset_handles_stage_failure_without_stranding_state was updated to assert the retain-on-failure semantics plus a retry-succeeds case.

[Alpaca233]

[Claude Code] Acknowledged — the plan doc has tool-specific references and machine-local paths. Leaving cleanup of that doc for the PR author since it's documentation of how this work was done, not part of the shipping behavior.

[Copilot]

Pull request overview

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

[Alpaca233]

[Claude Code] Fixed in 7ec3d8b — kept the 'treating as 0' fall-through (it correctly resets the stage to baseline when a prior channel applied an offset), but reworded the log to 'treating as 0 (will reset to the un-offset baseline if a prior channel already applied an offset)' so the message matches the actual behavior.

[Alpaca233]

[Claude Code] Fixed in 7ec3d8b — removed setChecked(initial_has_ref) so 'Apply in Live' is now opt-in regardless of laser AF reference state. setEnabled is still gated on has_reference, so the control is visible/clickable only when a reference exists, but never auto-fires a stage move on the next channel switch.