Merge pull request #1211 from annie-xd-wang/fix-z-stack-setting

set up z-stack start and end positions according to primary z axis

Author: annie-xd-wang

docs/source/01_getting_started/06_acquiring_data.rst

@@ -175,6 +175,8 @@ Acquiring a Z-Stack
        :align: center
        :alt: Adjusting the stage position in **navigate**.
 
+* If the microscope has more than one stage that can move in the Z direction, choose the stage that should perform the stack from :guilabel:`Z-Stack Device` before setting the start and end positions. This selected device is the primary Z-stack stage: :guilabel:`Start`, :guilabel:`End`, and :guilabel:`Step Size` are applied to this stage. Other stack-capable stages can be moved with fixed offsets from the primary Z-stack stage when their offset settings are enabled.
+
 * Under the :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (μm)` press :guilabel:`Set Start Pos/Foc`.
 
     .. image:: ../images/press-start-pos.png

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

@@ -76,7 +76,10 @@ This section defines Z-stack geometry and sequencing.
 1. :guilabel:`Start` / :guilabel:`End` are relative stack bounds.
 2. :guilabel:`Set Start Pos/Foc` and :guilabel:`Set End Pos/Foc` read current stage values.
 3. :guilabel:`Step Size` sets spacing in microns; :guilabel:`# slices` updates automatically.
-4. :guilabel:`Laser Cycling Settings` selects Per Stack or Per Z channel ordering.
+4. :guilabel:`Z-Stack Device` selects the primary Z-stack stage. When multiple stages can move along the Z direction, this is the stage that steps through the planes of the stack.
+5. :guilabel:`Focus Device` selects the focus stage that is ramped with the primary Z-stack stage when the start and end focus values differ.
+6. Additional stack-device offset controls, when present, move secondary stack stages at fixed offsets from the primary Z-stack stage.
+7. :guilabel:`Laser Cycling Settings` selects Per Stack or Per Z channel ordering.
 
 .. _ui_timepoint_settings:
 

docs/source/02_user_guide/05_acquiring_data/01_acquiring_guide/01_acquiring_guide.rst

@@ -52,6 +52,8 @@ Z-Stack Acquisition
 
 This takes an image stack over the range and at the step size defined by the :ref:`stack acquisition settings <ui_stack_settings>` and optionally saves the stack to a file. The color channels will appear as in "Continuous Scan" and "Single Acquisition" if :guilabel:`Laser Cycling Settings` is set to "Per Z" in the stack acquisition settings. A single z-stack will be taken for each color channel, one channel at a time, if :guilabel:`Laser Cycling Settings` is set to "Per Stack".
 
+If the microscope exposes multiple stages that can move along the Z direction, :guilabel:`Z-Stack Device` in the stack acquisition settings selects the primary Z-stack stage. This primary stage is the one that receives the Z-stack start, end, and step-size moves. The selected :guilabel:`Focus Device` can be ramped with it to maintain focus, and any secondary stack stages with enabled offsets follow the primary Z-stack position plus their configured offsets.
+
 Z-Stack acquisition is implemented as the feature list below.
 
 .. code-block:: python

src/navigate/controller/sub_controllers/channels_tab.py

@@ -298,13 +298,16 @@ def populate_experiment_values(self) -> None:
         # after initialization
         self.in_initialization = False
         self.channel_setting_controller.in_initialization = False
+        # get primary z and f axis
+        primary_z_axis = self.microscope_state_dict.get("primary_z_axis", "z")
+        primary_f_axis = self.microscope_state_dict.get("primary_f_axis", "f")
         # update z and f position
         self.z_origin = self.parent_controller.configuration["experiment"][
             "StageParameters"
-        ]["z"]
+        ][primary_z_axis]
         self.focus_origin = self.parent_controller.configuration["experiment"][
             "StageParameters"
-        ]["f"]
+        ][primary_f_axis]
         self.update_z_steps()
 
         self.show_verbose_info("Channels tab has been set new values")
@@ -516,9 +519,13 @@ def update_z_steps(self, *_: tuple[str]) -> None:
         )
         self.stack_acq_vals["number_z_steps"].set(number_z_steps)
 
+        # get the primary z-stack and focus axis
+        primary_z_stage = self.stack_acq_vals["z_device"].get()
+        primary_z_axis = primary_z_stage.split(" - ")[1]
+
         # Shift the start/stop positions by the relative position
         flip_flags = self.parent_controller.configuration_controller.stage_flip_flags
-        if flip_flags["z"]:
+        if flip_flags[primary_z_axis]:
             self.microscope_state_dict["abs_z_start"] = self.z_origin + end_position
             self.microscope_state_dict["abs_z_end"] = self.z_origin + start_position
             # self.stack_acq_vals["abs_z_start"].set(self.z_origin + end_position)
@@ -533,7 +540,7 @@ def update_z_steps(self, *_: tuple[str]) -> None:
         self.microscope_state_dict["start_position"] = start_position
         self.microscope_state_dict["end_position"] = end_position
         self.microscope_state_dict["step_size"] = step_size * (
-            -1 if flip_flags["z"] else 1
+            -1 if flip_flags[primary_z_axis] else 1
         )
         self.microscope_state_dict["number_z_steps"] = number_z_steps
         self.stack_acq_vals["bottom"].set(self.microscope_state_dict["abs_z_start"])
@@ -568,17 +575,21 @@ def update_start_position(self, *_: tuple[str]) -> None:
         _ : tuple[str]
             Values is a tuple of strings. e.g., ('PY_VAR0', '', 'write')
         """
-
+        # get the primary z-stack and focus axis
+        primary_z_stage = self.stack_acq_vals["z_device"].get()
+        primary_z_axis = primary_z_stage.split(" - ")[1]
+        primary_f_stage = self.stack_acq_vals["f_device"].get()
+        primary_f_axis = primary_f_stage.split(" - ")[1]
         # We have a new origin
         self.z_origin = self.parent_controller.configuration["experiment"][
             "StageParameters"
-        ]["z"]
+        ][primary_z_axis]
         self.focus_origin = self.parent_controller.configuration["experiment"][
             "StageParameters"
-        ]["f"]
+        ][primary_f_axis]
 
         flip_flags = self.parent_controller.configuration_controller.stage_flip_flags
-        if flip_flags["z"]:
+        if flip_flags[primary_z_axis]:
             self.stack_acq_vals["end_position"].set(0)
             self.stack_acq_vals["end_focus"].set(0)
         else:
@@ -597,13 +608,18 @@ def update_end_position(self, *_: tuple[str]) -> None:
             Values is a tuple of strings. e.g., ('PY_VAR0', '', 'write')
 
         """
+        # get the primary z-stack and focus axis
+        primary_z_stage = self.stack_acq_vals["z_device"].get()
+        primary_z_axis = primary_z_stage.split(" - ")[1]
+        primary_f_stage = self.stack_acq_vals["f_device"].get()
+        primary_f_axis = primary_f_stage.split(" - ")[1]
         # Grab current values
         z_end = self.parent_controller.configuration["experiment"]["StageParameters"][
-            "z"
+            primary_z_axis
         ]
         focus_end = self.parent_controller.configuration["experiment"][
             "StageParameters"
-        ]["f"]
+        ][primary_f_axis]
 
         z_start = self.z_origin
         focus_start = self.focus_origin
@@ -623,7 +639,7 @@ def update_end_position(self, *_: tuple[str]) -> None:
         end_pos = z_end - self.z_origin
         start_focus = focus_start - self.focus_origin
         end_focus = focus_end - self.focus_origin
-        if flip_flags["z"]:
+        if flip_flags[primary_z_axis]:
             start_pos, end_pos = end_pos, start_pos
             start_focus, end_focus = end_focus, start_focus
         self.stack_acq_vals["start_position"].set(start_pos)

src/navigate/model/features/common_features.py

@@ -1280,8 +1280,8 @@ def pre_signal_func(self) -> None:
 
         # restore z, f
         pos_dict = self.model.get_stage_position()
-        self.restore_z = pos_dict["z_pos"]
-        self.restore_f = pos_dict["f_pos"]
+        self.restore_z = pos_dict[f"{self.primary_z_axis}_pos"]
+        self.restore_f = pos_dict[f"{self.primary_f_axis}_pos"]
         self.pre_position = {
             axis: float(pos_dict[f"{axis}_pos"]) for axis in self.stage_axes
         }

test/model/devices/stages/test_asi.py

@@ -146,6 +146,9 @@ def setup_class(
         }
         self.stage_configuration = stage_configuration
         self.stage_configuration["stage"]["hardware"]["type"] = "ASI"
+        self.stage_configuration.setdefault("zoom", {}).setdefault(
+            "pixel_size", {"5X": 1.3}
+        )
         self.asi_serial_device = asi_serial_device
         self.random_single_axis_test = random_single_axis_test
         self.random_multiple_axes_test = random_multiple_axes_test

test/model/features/test_common_features.py

@@ -68,6 +68,47 @@ def test_multiposition_theta_move_pauses_data_thread(dummy_model_to_test_feature
     assert record_names.index("move_stage") < record_names.index("resume_data_thread")
 
 
+def test_z_stack_preserves_primary_axis_restore_and_pre_position(
+    dummy_model_to_test_features,
+):
+    model = dummy_model_to_test_features
+    model.virtual_microscopes = {}
+    microscope_state = model.configuration["experiment"]["MicroscopeState"]
+    stage_parameters = model.configuration["experiment"]["StageParameters"]
+    previous_primary_z_axis = microscope_state.get("primary_z_axis")
+    previous_primary_f_axis = microscope_state.get("primary_f_axis")
+    previous_stage_parameters = dict(stage_parameters)
+
+    try:
+        microscope_state["is_multiposition"] = False
+        microscope_state["primary_z_axis"] = "theta"
+        microscope_state["primary_f_axis"] = "x"
+        stage_parameters.update({"x": 11, "y": 22, "z": 33, "theta": 44, "f": 55})
+
+        feature = ZStackAcquisition(model)
+        feature.pre_signal_func()
+
+        assert feature.restore_z == 44
+        assert feature.restore_f == 11
+        assert feature.pre_position == {
+            "x": 11.0,
+            "y": 22.0,
+            "z": 33.0,
+            "theta": 44.0,
+            "f": 55.0,
+        }
+    finally:
+        if previous_primary_z_axis is None:
+            microscope_state.pop("primary_z_axis", None)
+        else:
+            microscope_state["primary_z_axis"] = previous_primary_z_axis
+        if previous_primary_f_axis is None:
+            microscope_state.pop("primary_f_axis", None)
+        else:
+            microscope_state["primary_f_axis"] = previous_primary_f_axis
+        stage_parameters.update(previous_stage_parameters)
+
+
 class TestZStack:
     @pytest.fixture(autouse=True)
     def _prepare_test(self, dummy_model_to_test_features):