Add channel-aware defocus reference status (#1225)

* Add channel-aware defocus plan

* Implement channel-aware defocus calibration

* Add visible defocus reference status

Display the active defocus reference in the main Channel Settings table so users can see whether the zero-defocus plane is set and which channel/focus position established it.

Update the autofocus popup channel selector to use CH labels while preserving channel_n keys internally, and publish captured autofocus references to the main GUI.

Publish runtime zero-defocus reference updates from microscope channel preparation and clear the reference when manual focus moves invalidate it.

Tests cover autofocus channel label conversion, main-GUI defocus reference updates, and model reference publication/clearing.

* Fix autofocus test execute mock leakage

Scope the mocked parent_controller.execute with patch.object in the autofocus calibration test so the package-scoped dummy_controller restores its real execute method after the assertion.

This fixes the Windows CI order failure where camera view move_stage tests ran after the autofocus test and saw an empty command list because DummyController.execute had been replaced by a MagicMock.

Confirmed the failure locally with the autofocus/camera-view ordering reproducer before the fix, then verified the reproducer and the affected controller test files pass in the navigate conda environment.

* Prepare autofocus channel in feature init

Move target-channel preparation out of Autofocus.run() and into the signal init hook so standalone autofocus and live-mode injected autofocus share the same channel-selection behavior.

This addresses the PR review concern that live autofocus injection preserves target channel args but bypasses Autofocus.run(), which previously meant prepare_channel() was never called for the injected feature instance.

Tests now verify that run() only orchestrates standalone autofocus loading while pre_func_signal() prepares either the requested channel or the next selected channel fallback.

* Restore defocus reference after autofocus completion

Autofocus stage moves publish a transient defocus_reference=None event through the model, which can clear the main Channel Settings label during Regular and Populate Defocus runs.

Capture Reference already republished the saved reference after completion. Extend that restoration to other autofocus completions whenever an autofocus calibration reference exists, so the main GUI label does not remain at Not Set after Populate Defocus or Regular autofocus.

Adds regression coverage for Populate Defocus and Regular autofocus completion preserving the saved defocus reference event.

* add "Auto Defocus" option and warning info if selected channel is not activated

* fix tests

* fix(defocus): handle pre-existing values correctly

* update doc

* fix tests

* Update test_channels_tab.py

* docs: design PR 1225 GUI refresh

* docs: refresh defocus GUI screenshots

* docs: explain channel defocus calibration

* docs: complete PR 1225 GUI plan

---------

Co-authored-by: Annie Wang <annie.xd.wang@gmail.com>

Author: kevin-m-dean

.gitignore

@@ -299,4 +299,5 @@ test.xml
 /docs/source/05_reference/_autosummary
 /docs/source/05_reference/_autosummary
 codex.md
-uv.lock
+uv.lock
+.worktrees/

docs/capture_gui.py

@@ -227,8 +227,19 @@ def _build_controller_context() -> Dict[str, object]:
     root.withdraw()
     splash_screen = SplashScreen(root, _splash_image_path())
 
+    config_dir = SRC_DIR / "navigate" / "config"
     parser = create_parser()
-    args = parser.parse_args(["-sh"])
+    args = parser.parse_args(
+        [
+            "-sh",
+            "--config-file",
+            str(config_dir / "configuration.yaml"),
+            "--experiment-file",
+            str(config_dir / "experiment.yml"),
+            "--gui-config-file",
+            str(config_dir / "gui_configuration.yml"),
+        ]
+    )
 
     (
         configuration_path,
@@ -1590,10 +1601,22 @@ def _capture_popup_save_dialog_bdv_settings(
 def _capture_popup_autofocus(
     ctx: Dict[str, object], cli_args: argparse.Namespace
 ) -> str:
-    from navigate.view.popups.autofocus_setting_popup import AutofocusPopup
+    controller = ctx["controller"]
+    out_path, should_skip = _popup_capture_target(cli_args, "autofocus_settings")
+    if should_skip:
+        return out_path
+
+    _cleanup_controller_popup_attr(controller, "af_popup_controller")
+    controller.menu_controller.popup_autofocus_setting()
+    popup_controller = controller.af_popup_controller
+    popup_controller.widgets["calibration_action"].set("Auto Defocus")
+    popup = popup_controller.view.popup
 
-    popup_obj = AutofocusPopup(ctx["controller"].view)
-    return _capture_popup_obj(ctx, cli_args, popup_obj, "autofocus_settings")
+    try:
+        _prepare_for_capture(popup, cli_args)
+        return _capture_widget(popup, out_path, pad=2)
+    finally:
+        _cleanup_controller_popup_attr(controller, "af_popup_controller")
 
 
 def _capture_popup_camera_map_settings(

docs/source/01_getting_started/06_acquiring_data.rst

@@ -54,7 +54,7 @@ Configure the Channel Settings
 
     * Specify the camera :guilabel:`Exp. Time (ms)`. A good default value is ``100`` or ``200`` ms.  
     * Specify the :guilabel:`Interval` to be ``1.0``. While this feature is not currently implemented, future releases will allow users to image different channels at different time intervals.  
-    * Specify the :guilabel:`Defocus` to be ``0``. This feature allows you to adjust for chromatic aberrations that result in focal shifts between each imaging channel.
+    * Set :guilabel:`Defocus` to ``0`` unless the channel has a measured chromatic focus offset. Defocus is a per-channel offset from the zero-defocus focus position, not an absolute focus coordinate. At acquisition start, **navigate** derives that zero-defocus position from the current focus and the active channel's defocus, then applies each channel's offset. The status below the table reports the current reference; see :ref:`Autofocus Settings <ui_autofocus>` to measure channel offsets automatically.
 
 ---------------------------------------
 

docs/source/02_user_guide/03_user_interface_walkthrough/03_acquisition_and_settings_notebooks.rst

@@ -60,7 +60,13 @@ Use this section to define active imaging channels and per-channel acquisition v
 3. :guilabel:`Filter`: detection filter.
 4. :guilabel:`Exp. Time (ms)`: camera exposure time.
 5. :guilabel:`Interval`: channel cadence relative to other channels.
-6. :guilabel:`Defocus`: channel-specific focus offset.
+6. :guilabel:`Defocus`: channel-specific offset from the zero-defocus focus position.
+
+At acquisition start, **navigate** derives the zero-defocus position from the
+current focus and the active channel's defocus. It then moves each channel to
+that reference position plus the channel's offset. :guilabel:`Defocus Reference`
+shows the reference channel and, when an acquisition reference is active, its
+focus position. Manual focus motion invalidates the active acquisition reference.
 
 .. _ui_stack_settings:
 

docs/source/02_user_guide/03_user_interface_walkthrough/06_popups_and_tools.rst

@@ -52,6 +52,26 @@ region of highest contrast (best focus). Spline-fit and test-significance
 buttons are already present in preparation for additional intelligent autofocus
 functionality in future updates.
 
+The :guilabel:`Channel` must be active in Channel Settings. Choose a
+:guilabel:`Calibration` action before pressing :guilabel:`Start Autofocus`:
+
+* :guilabel:`Regular` focuses the selected channel without calculating a channel
+  offset.
+* :guilabel:`Capture Reference` focuses the selected channel, makes it the
+  zero-defocus calibration channel, and retains its best-focus position for the
+  current calibration sequence.
+* :guilabel:`Populate Defocus` focuses the selected channel and writes the
+  difference from the previously captured reference into that channel's
+  :guilabel:`Defocus` value. Capture a reference first.
+* :guilabel:`Auto Defocus` uses the selected channel as the reference, focuses
+  every other active channel, and populates all active channel offsets in one
+  sequence. Stop any acquisition before starting it.
+
+The popup's :guilabel:`Reference` status reports the calibration reference.
+:guilabel:`Populate Defocus` requires the captured focus retained by the current
+popup session. The resulting per-channel :guilabel:`Defocus` values are stored
+with the experiment settings and are used during acquisition.
+
 .. _ui_waveform_parameters:
 
 Waveform Parameters