feat: init

docs/source/02_user_guide/06_case_studies/06_human_in_the_loop/human_in_the_loop.rst

@@ -0,0 +1,86 @@
+.. _human_in_the_loop:
+
+====================================
+Human-in-the-Loop Multiscale Imaging
+====================================
+
+Human-in-the-Loop multiscale imaging in *navigate* allows users to manually select regions of interest at low magnification, and then automatically revisit and image those regions at higher magnification with an alternative microscope configuration. This workflow is ideal for targeted analysis of biologically relevant features that may not be automatically detected, and gives the user direct control over which areas are imaged in detail.
+
+This guide provides a step-by-step overview of how to set up and perform human-guided, multi-resolution imaging by creating a **NavigateMultipos** feature.
+
+----------------------------
+
+1. **Manually Mark Regions of Interest**
+
+   - In the desired magnification of the low-resolution imaging system, right-click in the display window to mark regions or cells of interest. A popup will appear with the option to  **Mark Position**.
+
+   .. image:: images/Picture1.png
+      :align: center
+
+   - These positions will be added to the multiposition table and used for targeted imaging.
+
+2. **Switch to the Target, High-Resolution Imaging Mode**
+
+   - Change the microscope to the target, high-resolution imaging system.
+   - Verify that the imaging parameters (e.g., zoom, illumination settings) are correct.
+
+3. **Select the NavigateMultipos Feature**
+
+    - From the **Features** menu, select **Customized**, and choose **NavigateMultipos**.
+
+   .. image:: images/Picture2.png
+      :align: center
+
+   - Change the acquisition mode to **Customized**, and select **Acquire** to open the **Feature List Configuration Window**.
+
+   .. image:: images/Picture3.png
+      :align: center
+
+   - If the feature is not available, you may need create your own version of the feature, which can be done by selecting the **Add New Feature** menu from the **Features** menu. This can be done by copying the following code into the **Feature Popup Window**. In this example, the microscope automatically switches back to the low-resolution imaging system upon completing the high-resolution imaging.
+
+    .. code-block:: python
+
+        [
+            {"name": PrepareNextChannel, },
+            [
+                {"name": MoveToNextPositionInMultiPositionTable, "args": (
+                    "Mesoscale","1x",None,),},
+                {"name": ZStackAcquisition, "args": (
+                    True,True,"test/test/test",False,),},
+                {"name": LoopByCount, "args": (
+                    "experiment.MicroscopeState.multiposition_count",),}
+            ],
+            {"name": ChangeResolution, "args": (
+                "Mesoscale","1x",),},
+        ]
+
+|
+
+4. **Press the MoveToNextPositionInMultiPositionTable button in the Feature List Configuration Window**:
+
+   - This will open the **Feature Parameters** window, which is where you configure the **MoveToNextPositionInMultiPositionTable** feature. It includes the following entries:
+
+        - **get_origin**: Set to ``True``. This instructs the system to acquire the Z-stack at the current stage location, instead of using a predefined global Z-stack setting.
+        - **saving_flag**: Set to ``True``. This instructs the system to save the acquired Z-stack.
+        - **saving_dir**: Set to the desired directory for saving the acquired Z-stacks.
+        - **force_multiposition**: Set to ``False``. If ``True``, this will force the system to acquire a Z-stack at each position, even if the position is not marked in the multiposition table.
+
+   .. image:: images/Picture4.png
+      :align: center
+
+
+   - Once you have configured the parameters, close the window to save the settings.
+
+5. **Click ZStackAcquisition**
+
+    - In the same Feature List Configuration Window window, click **ZStackAcquisition** to configure the Z-stack acquisition settings for each marked position.
+    - Once you have configured the parameters, close the window to save the settings.
+
+   .. image:: images/Picture5.png
+      :align: center
+
+6. **Start Human-in-the-Loop Imaging**
+
+   - Click **Confirm** to begin acquisition.
+   - The system will automatically move to each marked position and acquire a Z-stack at the selected high-resolution settings.
+

docs/source/02_user_guide/06_case_studies/07_smart_tiling/smart_tiling.rst

@@ -0,0 +1,70 @@
+.. _smart_tiling:
+
+================================
+Automatic Multiscale Tiling
+================================
+
+Smart Tiling in *navigate* enables automated, multi-resolution imaging across different magnification levels by selectively tiling only regions of interest. Tiling can take place at different magnifications within one microscope object, or between two separate microscope objects. This approach minimizes unnecessary data acquisition by avoiding the imaging of empty or biologically irrelevant space, significantly improving throughput and data efficiency.
+
+This guide provides a step-by-step overview of how to set up and use the **VolumeSearch** feature in *navigate*, which enables automated tiling across independent imaging modules.
+
+----------------------------
+
+1. **Configure Low-Resolution Imaging Parameters**
+
+   - Begin with the lower magnification imaging system (e.g., 1x in the macroscale module).
+   - Set the appropriate Z-scan range and step size to capture a low-resolution overview of the sample.
+
+        - The range should be sufficient to capture the entirety of the specimen, and the step size should be set according to the size of the volume that you wish to image at higher resolution.
+        - For example, if the step size is 50 microns for the low-resolution imaging system, then the Z-scan range for the high-resolution imaging system will become 50 microns.
+
+1. Select the **VolumeSearch** feature from the **Features** menu in *navigate*.
+
+3. **Confirm that the Feature is Selected**:
+
+   - Ensure that the **VolumeSearch** feature is selected in the features list menu.
+   - Change the acquisition mode to **Customized**, and select **Acquire**.
+   - This will open the **Feature List Configuration Window**.
+
+   .. image:: images/Picture1.png
+     :align: center
+
+4. **Press the VolumeSearch Button in the Feature List Configuration Window**:
+
+   - This will open the **Feature Parameters** window, which is where you configure the **VolumeSearch** feature. It includes the following entries:
+
+        - **target_resolution**: Set to higher-resolution imaging system that we will be switching to upon completion of the low-resolution imaging.
+        - **target_zoom**: Set to the zoom level for the system that you wish to use for high-resolution imaging.
+        - **flipx**: Allows you to flip the x-axes between the imaging systems (e.g., a positive movement for microscope 1 is a negative movement for microscope 2).
+        - **flipy**: Allows you to flip the y-axes between the imaging systems (e.g., a positive movement for microscope 1 is a negative movement for microscope 2).
+        - **overlap**: The desired overlap between adjacent images in the X and Y directions for the target imaging system.
+        - **debug**: Set to **False**. This is used for debugging purposes.
+
+    - Once you have configured the parameters, close the window to save the settings.
+
+   .. image:: images/Picture2.png
+      :width: 60%
+      :align: center
+
+5. **Press Confirm to Begin Imaging**:
+
+   - This will start the low-resolution imaging process.
+   - Once the low-resolution scan is complete, the software will automatically segment and define the boundaries of the sample using a basic Otsu threshold.
+   - These regions are then used to populate the multiposition table with target coordinates for tiling.
+
+6. **Switch to the Target Imaging Mode**
+
+   - Switch to the microscope that was specified according to the ``target_resolution`` (e.g., switch from macroscale to nanoscale).
+   - Set the system to the correct ``target_zoom`` and verify stage alignment and calibration.
+
+7. **Configure Acquisition Settings**
+
+   - Select the **Multiposition** option and enable **Z Stack** acquisition.
+   - Verify the camera settings, channel selections, and waveform configurations as appropriate for the resolution.
+   - If you wish to save the data, make sure tha the **Save Data** option is selected.
+
+8. **Start Smart Tiling Acquisition**
+
+   - Press **Confirm** to begin imaging.
+   - The system will automatically visit each position in the multiposition table and acquire image stacks at the desired resolution.
+

docs/source/02_user_guide/06_case_studies/08_smart_object_detection/smart_object_detection.rst

@@ -0,0 +1,193 @@
+.. _smart_object_detection:
+
+=========================
+Smart 3D Object Detection
+=========================
+
+Smart 3D Object Detection in *navigate* enables automated, feature-driven imaging across spatial scales. In this workflow, a specimen is first imaged volumetrically at a user-defined magnification using one microscope configuration—typically in a low-resolution, large field-of-view mode. A custom segmentation algorithm is then applied to the dataset to identify objects of interest in 3D. The positions of these detected features are automatically populated into the multiposition table. The system then switches to an alternatively configured microscope object—often operating at higher magnification and resolution—and revisits each detected location to acquire high-resolution image stacks. This streamlined process enables efficient, targeted imaging of biologically relevant features while minimizing unnecessary data acquisition.
+
+This guide provides a step-by-step overview of how to set up and utilize the **Volume Search 3D** feature in *navigate*, which is essential for achieving high-resolution imaging of specific features within a larger volume.
+
+---------------
+
+1. **Configure the Low-Resolution Imaging Parameters**:
+
+   - Set the Z-scan range and step size. This low-resolution overview is used to identify targets.
+   - Use a step size appropriate for the size of the features to be detected (e.g., glomeruli).
+
+2. **Load the Analysis Function**:
+
+   - Load the analysis function that will be used to detect the objects of interest. This function should be capable of processing the low-resolution images and identifying the features you want to target. Detailed directions on how to do this can be found in the :ref:`Loading Custom Functions <loading_custom_functions>` section of the documentation.
+
+    .. image:: images/Picture2.png
+       :width: 60%
+       :align: center
+
+   - For the following example, we developed our own segmentation method:
+
+    .. code-block:: python
+
+        from tifffile import imread, imwrite
+        from scipy import ndimage
+        import time
+        import dask.array as da
+        import skimage.filters as skfilters
+        import skimage.measure as skmeasure
+        import skimage.morphology as skmorph
+        import numpy as np
+
+
+        def threshold_block(block, threshold):
+            return np.where(block >= threshold, 1, 0)
+
+        def segment_data(image):
+
+            image =np.array(image)
+
+            # Set all values above the 99.99th percentile to 100
+            percentile = np.percentile(image[::4, ::4, ::4], 99.99)
+            image = np.where(image > percentile, 100, image)
+            print(f"Setting all values above {percentile} to 100.")
+
+            # Convert to Dask Array
+            dask_array = da.from_array(image.astype(np.float32), chunks=(256,256,256))
+
+            # High-Pass Filtering
+            FWHM = 10
+            sigma = FWHM/2.35
+            high_pass_filtered = dask_array.map_overlap(ndimage.gaussian_filter, sigma=sigma, order=0, mode="nearest", depth=40)
+
+            # Low-Pass Filtering
+            FWHM = 20
+            sigma = FWHM/2.35
+            low_pass_filtered = dask_array.map_overlap(ndimage.gaussian_filter, sigma=sigma, order=0, mode="nearest", depth=40)
+
+            # Difference Image
+            subtracted = da.map_blocks(np.subtract, high_pass_filtered, low_pass_filtered)
+
+            # Compute Operation
+            filtered = subtracted.compute()
+
+            # Multi-Level Otsu
+            n_classes = 3
+            thresholds = skfilters.threshold_multiotsu(filtered[::4, ::4, ::4], classes=n_classes)
+            print("Total number of thresholds available:", len(thresholds))
+
+            counter = 0
+            for threshold in thresholds:
+                print("Index:", counter, "Threshold:", threshold)
+                counter += 1
+
+            # Binarize the Data
+            binary = subtracted.map_blocks(threshold_block, thresholds[1])
+
+            # Distance Transform
+            distance = binary.map_overlap(ndimage.distance_transform_edt, depth=40)
+            distance_image = distance.compute()
+
+            # Threshold distance image according to threshold.
+            distance_thresh = np.where(distance_image >= 7, 1, 0)
+
+            # Create labels
+            labelled = skmeasure.label(distance_thresh)
+            uniq_labels = np.setdiff1d(np.unique(labelled), 0)
+            print('n_unique labels', len(uniq_labels))
+
+|
+
+3. **Select the VolumeSearch3D feature from the Features menu in navigate.**
+
+    .. image:: images/Picture1.png
+       :width: 60%
+       :align: center
+
+   - If the feature is not available, you may need create your own version of the feature, which can be done by selecting the **Add New Feature** menu from the **Features** menu. This can be done by copying the following code into the **Feature Popup Window**.
+
+    .. code-block:: python
+
+        [
+            {"name": ZStackAcquisition, "args": (
+                False,False,"z-stack",False,),},
+            {"name": WaitToContinue, },
+            {"name": VolumeSearch3D, "args": (
+                "Nanoscale","N/A",0,0.2,"-y","x",0.05,"segment_data",1.01,10,),},
+            {"name": WaitToContinue, },
+            {"name": ChangeResolution, "args": (
+                "Nanoscale","N/A",),},
+            {"name": SetCameraParameters, "args": (
+                "Nanoscale","Light-Sheet","Top-to-Bottom",20,),},
+            {"name": UpdateExperimentSetting, "args": ("({
+                'MicroscopeState.channels.channel_1.is_selected': True,
+                'MicroscopeState.channels.channel_3.is_selected': True},)",),},
+            {"name": ZStackAcquisition, "args": (
+                False,False,"z-stack",True,),},]
+
+    |
+
+4. **Confirm that the Feature is Selected**:
+
+   - Ensure that the **VolumeSearch3D** feature is selected in the features list menu.
+   - Change the acquisition mode to **Customized**, and select **Acquire**.
+
+    .. image:: images/Picture3.png
+       :width: 60%
+       :align: center
+
+   - This will open the **Feature List Configuration Window**.
+
+    .. image:: images/Picture4.png
+       :width: 100%
+       :align: center
+
+5. **Press the VolumeSearch3D Button in the Feature List Configuration Window**:
+
+   - This will open the **Feature Parameters** window, which is where you configure the **VolumeSearch3D** feature. It includes the following entries:
+
+        - **target_resolution**: Set to **Nanoscale**. This is the microscope object that we will be switching to upon completion of the low-resolution imaging.
+        - **target_zoom**: Set to **N/A**. This is the zoom level of the **Nanoscale** microscope object, here configured to **N/A** since it operates at a fixed zoom level.
+        - **position_id**: Set to **0**.
+        - **z_step_size**: Set to **0.2**. This is the step size for the **Nanoscale** module.
+        - **x_direction**: Set to **-y**. This is the direction of the stage movement in the X direction.
+        - **y_direction**: Set to **x**. This is the direction of the stage movement in the Y direction.
+        - **overlap**: Set to **0.05**. This is the overlap between adjacent images in the X and Y directions if tiling is necessary.
+        - **analysis_function**: Input the name of the segmentation function (e.g., segment_data) that will be used to detect objects.
+        - **current_pixel_size**: Set to **1.01**. This is the pixel size of the low-resolution imaging.
+        - **filter_pixel_number**: Set to **10**. This is the minimum number of pixels that must be present in a detected object for it to be considered valid.
+
+   - Once you have configured the parameters, close the window to save the settings.
+
+    .. image:: images/Picture6.png
+       :width: 60%
+       :align: center
+
+6. **Press the SetCameraParameters button in the Feature List Configuration Window**:
+
+    - If you need to adjust the camera settings between the two imaging modalities, you can do so here. This is typically done to ensure that the camera settings are appropriate for the resolution and magnification of the imaging mode. Here, we specify the target microscope, the sensor_mode (e.g., Light-Sheet or Normal). If imaging in the light-sheet mode, you will also need to specify the readout direction (Top-to-Bottom, or Bottom-to-Top, etc.), and the Rolling Shutter Width.
+
+    - Once the settings are configured, close the window to save the settings.
+
+    .. image:: images/Picture7.png
+       :width: 60%
+       :align: center
+
+7. **Press the UpdateExperimentSetting button in the Feature List Configuration Window**:
+
+    - If you need to change which channels are selected, you can do so here. In this example, the low-resolution imaging was performed for as single channel. Once the microscope switched to the nanoscale microscope object, we select two channels for imaging. This is done by specifying the channel names in the format of a dictionary, where the keys are the channel names and the values are booleans indicating whether the channel is selected (True) or not (False). For example, to select channels 1 and 3, you would use:
+
+    .. code-block:: python
+
+        {
+            'MicroscopeState.channels.channel_1.is_selected': True,
+            'MicroscopeState.channels.channel_3.is_selected': True
+        }
+
+
+|
+
+    .. image:: images/Picture8.png
+       :width: 60%
+       :align: center
+
+8. **Press Confirm to Begin Imaging**:
+
+   - Once all the parameters are set, press the **Confirm** button to start the imaging process. The system will first perform low-resolution imaging to identify the objects of interest, apply the segmentation algorithm, and then switch to the high-resolution imaging mode to acquire detailed images of the detected features.

docs/source/02_user_guide/06_case_studies/acquire_CT-ASLM-V1_and_CT-ASLM-V2.rst

@@ -0,0 +1,106 @@
+.. _cs_ctaslm:
+
+========================================
+Imaging on the CT-ASLM-V1 and CT-ASLM-V2
+========================================
+
+This is a case study in using the software to image with a `CT-ASLM-V1 and CT-ASLM-V2 microscopes <https://www.nature.com/articles/s41592-019-0615-4>`_.
+
+-----------------
+
+Setting up the chamber
+======================
+
+Make sure the chamber is clean and dry. If in doubt, fill the chamber with deionized water to see if there is any residue. To clean the chamber, rinse it with deionized water and ethanol, then gently clean the chamber with Q-tips. Repeat the process a few times and end the process with a rinse of 100% ethanol. Gently clean the objectives with lens paper and 100% ethanol. Finally, let the chamber air dry. To speed up the drying process, one can gently blow some air into the chamber. Once the chamber is completely dry, fill the chamber with imaging media.
+
+-----------------
+
+Sample loading and finding the samples
+======================================
+
+It's recommended to start the software before loading the sample on the stage.
+
+#. Mount the sample on custom cut glass slide with silicon or super glue.  
+#. Mount the glass slide onto the sample holder.  
+#. Mount the sample holder onto the stage with the sample facing the illumination and detection objective so the glass slide is 45 degrees with both objectives.  
+#. Decrease the numerical aperture of the illumination beam such that it covers the entire field of view. Typically this is achieved with a magnetic mounted slit aperture that can be readily adjusted.  
+#. Go to :guilabel:`Camera Settings`. Select :guilabel:`Normal` under :guilabel:`Sensor Mode`.  
+#. Go to the :menuselection:`Microscope Configuration --> Waveform Parameters`. A popup named :guilabel:`Waveform Parameter Settings` will appear.  
+#. Set the wavelength's :guilabel:`Amplitude` and :guilabel:`Offset` to ``0.0``.  
+#. Select the channel with a proper laser under the :guilabel:`Channels` tab and set the laser power to an appropriate value.  
+#. Select "Continuous Scan" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. This will launch a live acquisition mode.  
+#. Scroll around with the stage either via joystick or using the controls in the :guilabel:`Stage Control` tab until the sample comes into view.  
+#. Focus on the sample in the center of the beam. Zoom in by placing the mouse over the image and scrolling the mouse wheel. Slowly adjust the focus by scrolling the piezo controller to move the detection objective along the z axis. Lower the laser power if the image is saturated.
+
+-----------------
+
+.. _z_stack_stelzer:
+
+Imaging a Z-Stack with Stelzer mode
+===================================
+
+Stelzer mode is the normal non-ASLM light sheet mode, it gives more signal while offering around 1040 nm (CT-ASLM-V1) and 500 nm (CT-ASLM-V2) axial resolution.
+
+#. Go to the :menuselection:`Microscope Configuration --> Waveform Parameters`. A popup named :guilabel:`Waveform Parameter Settings` will appear.  
+#. Set the wavelength's :guilabel:`Amplitude` and :guilabel:`Offset` to ``0.0``.  
+#. Go to :guilabel:`Camera Settings`, select :guilabel:`Normal` under :guilabel:`Sensor Mode`.  
+#. Put a slit into the setup.  
+#. Select the channel with a proper laser under the :guilabel:`Channels` tab and set the laser power to an appropriate value.  
+#. Select "Continuous Scan" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. This will launch a live acquisition mode.  
+#. If needed, slowly adjust the slit opening until the image sharpness looks uniform across the whole field of view. Uncheck :guilabel:`Autoscale` in :guilabel:`Camera View` under LUT and adjust the :guilabel:`Min Counts` and :guilabel:`Max Counts` if needed.  
+#. Go to :guilabel:`Stage Control`, set the Z position in :guilabel:`Stage Positions` to be ``0``.  
+#. Find the region of interest by using the joystick or using the controls in the :guilabel:`Stage Control` tab.  
+#. Move along the Z axis with the joystick or the "Focus" in the :guilabel:`Stage Control` tab to one end of the region of interest. Under the :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (um)`, press :guilabel:`Set Start Pos/Foc`.  
+#. Go to :guilabel:`Stage Control`, change the Z position in :guilabel:`Stage Positions` to set the scan range. Be aware the range for z-piezo is 0 - 200. Going outside of the range will cause the stage to have issues.  
+#. Go back to :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (um)`, press :guilabel:`Set End Pos/Foc`.  
+#. Setup :guilabel:`Step Size` under the :guilabel:`Channels`, recommend 3.0 (CT-ASLM-V1) and 1.0 (CT-ASLM-V2).  
+#. Under the :guilabel:`Channels`, make sure :guilabel:`Enable` is unchecked under :guilabel:`Multi-Position Acquisition`.  
+#. Under the :guilabel:`Channels`, make sure :guilabel:`Save Data` is checked under :guilabel:`Timepoint Settings`.  
+#. Select "Z-Stack" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. A popup named :guilabel:`File Saving Dialog` will appear.  
+#. Fill out the fields and press :guilabel:`Acquire Data`.
+
+-----------------
+
+.. _z_stack_aslm:
+
+Imaging a Z-Stack with ASLM mode
+================================
+
+ASLM mode is the high-resolution light sheet mode, it gives less signal but offers around 950 nm (CT-ASLM-V1) and 480 nm (CT-ASLM-V2) isotropic resolution.
+
+#. Switch the slit out of the setup.  
+#. Go to :guilabel:`Camera Settings`, select "Light-Sheet" under :guilabel:`Sensor Mode`.  
+#. Select the channel with a proper laser under the :guilabel:`Channels` tab and set the laser power to an appropriate value.  
+#. Select "Continuous Scan" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. This will launch a live acquisition mode.  
+#. Go to the :menuselection:`Microscope Configuration --> Waveform Parameters`. A popup named :guilabel:`Waveform Parameter Settings` will appear.  
+#. Uncheck :guilabel:`Autoscale` in :guilabel:`Camera View` under LUT and adjust the :guilabel:`Min Counts` and :guilabel:`Max Counts` if needed.  
+#. Set the wavelength's :guilabel:`Amplitude` to ``0.0``.  
+#. Adjust the wavelength's :guilabel:`Offset` so the focus part of the image can be located perfectly in the center of the field of view.  
+#. Slowly adjust the wavelength's :guilabel:`Amplitude` so it will be uniform across the whole field of view.  
+#. Adjust the wavelength's :guilabel:`Offset` again slightly and make sure it is uniformly in focus across the whole field of view.  
+#. Go to :guilabel:`Stage Control`, set the Z position in :guilabel:`Stage Positions` to be ``0``.  
+#. Find the region of interest by using the joystick or using the controls in the :guilabel:`Stage Control` tab.  
+#. Move along the Z axis with the joystick or the “Focus” in the :guilabel:`Stage Control` tab to one end of the region of interest. Under the :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (um)`, press :guilabel:`Set Start Pos/Foc`.  
+#. Go to :guilabel:`Stage Control`, change the Z position in :guilabel:`Stage Positions` to set the scan range. Be aware the range for z-piezo is 0 - 200. Going outside of the range will cause the stage to have issues.  
+#. Go back to :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (um)`, press :guilabel:`Set End Pos/Foc`.  
+#. Setup :guilabel:`Step Size` under the :guilabel:`Channels`, recommend 0.46 (CT-ASLM-V1) and 0.2 (CT-ASLM-V2) for isotropic imaging.  
+#. Under the :guilabel:`Channels`, make sure :guilabel:`Enable` is unchecked under :guilabel:`Multi-Position Acquisition`.  
+#. Under the :guilabel:`Channels`, make sure :guilabel:`Save Data` is checked under :guilabel:`Timepoint Settings`.  
+#. Select "Z-Stack" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. A popup named :guilabel:`File Saving Dialog` will appear.  
+#. Fill out the fields and press :guilabel:`Acquire Data`.
+
+-----------------
+
+Tiling a sample larger than the field of view
+=============================================
+
+This assumes you have already found the samples and are ready to acquire data in either Stelzer mode or ASLM mode. (see :ref:`Imaging a Z-Stack with Stelzer mode <z_stack_stelzer>` and :ref:`Imaging a Z-Stack with ASLM mode <z_stack_aslm>`).
+
+#. Under :guilabel:`Channels` tab, press :guilabel:`Launch Tiling Wizard`. A popup named :guilabel:`Multi-Position Tiling Wizard` will appear.  
+#. Follow :ref:`Imaging a Z-Stack with Stelzer mode <z_stack_stelzer>` to set up the start and end positions in :guilabel:`Stack Acquisition Settings (um)`. At the same time, when pressing :guilabel:`Set Start Pos/Foc` to set up the start position, go to :guilabel:`Multi-Position Tiling Wizard` and press :guilabel:`Set Z Start`. When pressing :guilabel:`Set End Pos/Foc` to set up the end position, go to :guilabel:`Multi-Position Tiling Wizard` and press :guilabel:`Set Z End`.  
+#. Move the joystick or the “X Movement” in the :guilabel:`Stage Control` tab to the lower bound of the x-axis and press :guilabel:`Set X Start` in the :guilabel:`Multi-Position Tiling Wizard` popup. Navigate to the upper bound of the x-axis and press :guilabel:`Set X End` in the :guilabel:`Multi-Position Tiling Wizard` popup. Repeat for all axes except for z.  
+#. Press :guilabel:`Populate Multi-Position Table`. Navigate to the :guilabel:`Multiposition` tab and ensure the locations populated.  
+#. Under the :guilabel:`Channels`, make sure Enable is checked under :guilabel:`Multi-Position Acquisition`.  
+#. Under the :guilabel:`Channels`, make sure :guilabel:`Save Data` is checked under :guilabel:`Timepoint Settings`.  
+#. Select “Z-Stack” from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`.  
+#. Enter the sample parameters in the :guilabel:`File Saving Dialog` that pops up. Press :guilabel:`Acquire Data`.

docs/source/02_user_guide/06_case_studies/acquire_exASLM.rst

@@ -0,0 +1,51 @@
+==========================
+Imaging on an Upright ASLM
+==========================
+
+This case study outlines how to use **navigate** for imaging on an upright ASLM microscope. Here, the specimen is positioned with an Applied Scientific Instrumentation FTP-2000 stage, which permits imaging samples with large lateral extents. Moreover, the stage can be moved at a constant velocity during imaging, which allows for acquisition of data without delays introduced by stage communication protocols and settling times.
+
+To achieve this, **navigate** receives a `trigger signal <http://www.asiimaging.com/docs/scan_module>`_ from the stage controller to start image acquisition once the stage has reached the desired position and velocity. Thereafter, **navigate** acquires images at a constant rate until the stage has reached the end position. This mode of acquisition is termed "Constant Velocity Acquisition" and is implemented as a plugin in **navigate**. To download the plugin, please visit `navigate-constant-velocity-acquisition <https://github.com/TheDeanLab/navigate-constant-velocity-acquisition>`_.
+
+Since the stage moves at a 45 degree angle relative to the microscope detection axis, computational shearing of the data is necessary. For large data sets, this can become computationally challenging and unnecessarily results in greater data overhead owing to empty space introduced in the data. To avoid this, we also provide a guide on how to perform two axis stage scanning which removes the need for computational shearing. More information about this microscope and this method, which we refer to as mechanical shearing, can be found `here <https://pubmed.ncbi.nlm.nih.gov/38645073/>`_.
+
+.. _Constant Velocity Acquisition:
+
+Imaging a Z-Stack using Constant Velocity Acquisition Mode
+==========================================================
+
+#. Select `Continuous Scan` from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. This will launch a live acquisition mode.
+#. Using the :guilabel:`Stage Control`, go to a shallow Z-position in the sample. Under the :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (um)` press :guilabel:`Set Start Pos`.
+#. Go to a deep Z-position in the sample. Press :guilabel:`Set End Pos`.
+#. Make sure :guilabel:`Set Foc` is ``0`` for both the :guilabel:`Set Start Pos` and :guilabel:`End Pos`.
+#. Type the desired step size (units um) in the :guilabel:`Step Size` dialog box in :guilabel:`Stack Acquisition Settings (um)`. Note: The step size represents the optical step size. The velocity at which the stage moves during imaging accounts for the shear angle.
+#. Select the number of color channels needed imaging in the :guilabel:`Channel tab` under :guilabel:`Channel Settings`. Select the correct filter for each channel by using the dropdown menu after each channel under the :guilabel:`Filter`.
+#. Change the exposure time by changing number in the :guilabel:`Exp. Time (ms)` for each channel. For the ORCA Lightning camera using ASLM mode, the maximum exposure time is 100 ms.
+#. Set :guilabel:`Interval` to be ``1.0`` for each channel.
+#. Set :guilabel:`Defocus` to be ``0`` for each channel.
+#. Select "Constant Velocity Acquisition" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`.
+#. Enter the sample parameters in the :guilabel:`File Saving Dialog` that pops up. Make sure to save to SSD drive or change buffer size in configuration file to prevent any overwriting of images. Then Press :guilabel:`Acquire Data`. The stage will move from its current position to beyond the start position. The stage then ramps up to the desired stage velocity as the stage reaches the start position. Once the stage is at the start position, the stage will send an external trigger which is received by the DAQ to begin image acquisition. The number of frames required for each channel scan is precalculated from the stage velocity, scan distance, and single frame acquisition time. Acquisition will automatically stop when the desired number of frames are acquired which also corresponds to when the stage reaches its end position. For multichannel scans, the stage returns to the start position and the process repeats until all channels are acquired.
+#. To change frame buffer size, in the :guilabel:`CameraParameters` section in the :guilabel:`experiment.yaml` file in your local navigate directory in the :guilabel:`config` folder, change :guilabel:`databuffer_size` to desired number of frames. Make sure the size of the desired number of frames isn't above the available RAM in the computer.
+
+.. _z_stack_exaslm:
+
+Imaging a Z-Stack using two-axis scanning
+=========================================
+
+#. Select `Continuous Scan` from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. This will launch a live acquisition mode.
+#. Using the :guilabel:`Stage Control` tab, go to a shallow z-position in the sample. Under the :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (um)` press :guilabel:`Set Start Pos`.
+#. Using the :guilabel:`Stage Control` tab, Go to a deep z-position in the sample.
+#. Using the :guilabel:`Stage Control` tab, move the :guilabel:`Focus` button to match the z-axis scan distance. Make sure that the focus moves in the same direction as the z-scan.
+
+.. note::
+
+    One should pay attention to both the magnitude and the direction of the scan in both ``Z`` and ``F``. Scanning in ``F`` is accompanied with risk of crashing the stage into the objective. Importantly, the direction of travel varies depending upon the manufacturer.
+
+#. Move Press :guilabel:`Set End Pos`.
+#. Make sure :guilabel:`Set Foc` is the same range as :guilabel:`Set Start Pos` and :guilabel:`End Pos`.
+#. Type the desired step size (units um) in the :guilabel:`Step Size` dialog box in :guilabel:`Stack Acquisition Settings (um)`.
+#. Select the number of color channels needed imaging in the :guilabel:`Channel tab` under :guilabel:`Channel Settings`. Select the correct filter for each channel by using the dropdown menu after each channel under the :guilabel:`Filter`.
+#. Change the exposure time by changing number in the :guilabel:`Exp. Time (ms)` for each channel. For the ORCA Lightning camera using ASLM mode, the minimum frame rate is 75 ms and the maximum is 100 ms.
+#. Set :guilabel:`Interval` to be ``1.0`` for each channel.
+#. Set :guilabel:`Defocus` to be ``0`` for each channel.
+#. Select "Z-Stack" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`.
+#. Enter the sample parameters in the :guilabel:`File Saving Dialog` that pops up. Press :guilabel:`Acquire Data`. This will move the stage in the z-axis and the x-axis before imaging a plane during the z-stack. Move the stage at the same angle as the shearing angle removes the need for computational shearing which can be computationally cumbersome.

docs/source/02_user_guide/06_case_studies/acquire_mesospimbt.rst

@@ -0,0 +1,148 @@
+.. _acquire_mesospimbt:
+
+========================
+Imaging on a mesoSPIM BT
+========================
+
+This is a case study in using the software to image with a `mesoSPIM BT microscope <https://pubmed.ncbi.nlm.nih.gov/38538644/>`_. It is a Digitally Scanned, Axially Swept Light-Sheet Microscope that scans the beam laterally (``X``) with galvanometric mirrors to create a virtual sheet of light, and axially (``Y``) with an electronically tunable lens. The sample is moved in the detection direction (``Z``) to acquire a stack. Tiling in ``X``, ``Y``, and ``Z`` is provided by a motorized stage.
+
+-----------------
+
+Setting the beam parameters
+===========================
+
+Make sure the imaging chamber is empty or, if a sample is mounted, the sample is not in the beam path.
+
+#. Select "Continuous Scan" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. This will launch a live acquisition mode.
+#. Go to the :guilabel:`Channels` tab. Choose the wavelength you want to align. Set the laser's :guilabel:`Power` to ``100.0``. Change :guilabel:`Filter` to an "Empty" option.
+
+   .. image:: images/meso_beam_1.png
+
+#. Go to the :menuselection:`Microscope Configuration --> Waveform Parameters`. A popup named :guilabel:`Waveform Parameter Settings` will appear. Make sure the :guilabel:`Mode` matches "mesoSPIM BT" and the :guilabel:`Magnification` matches the magnification of the objective you are using.
+
+.. note::
+
+    The :guilabel:`Mode` is the name of the microscope as defined in the ``configuration.yaml`` file. Likewise, the :guilabel:`Magnification` is the magnification(s) for that microscope as defined in the ``configuration.yaml`` file.
+
+    The mesoSPIM BT largely operates at a fixed magnification. However, the original mesoSPIM used a variable magnification research grade macro zoom microscope.
+
+#. :guilabel:`Galvo 0` digitally sweeps the beam across the field of view in the ``X`` direction. To align the axially-swept light sheet parameters, set the :guilabel:`Galvo 0` :guilabel:`Amplitude` to ``0.0``.
+
+   .. image:: images/meso_beam_2.png
+
+#. The empty filter makes us susceptible to seeing particles scattering light in the chamber. This can affect the software's autoscaling routine. To ensure we are looking at the beam correctly, uncheck :guilabel:`Autoscale` and set the :guilabel:`Min Counts` and :guilabel:`Max Counts` so the beam is visible, but not saturating the display.
+
+#. Set the wavelength's :guilabel:`Amplitude` to ``0.0``. Set the wavelength's :guilabel:`Offset` so that the beam is focused in the center of the field of view.
+
+   .. image:: images/meso_beam_3.png
+
+   .. image:: images/meso_beam_4.png
+
+#. Set the :guilabel:`Galvo 0` :guilabel:`Offset` so that the beam is centered in the field of view. Click the :guilabel:`Camera View` to toggle the crosshair, which indicate the center of the field of view.
+
+   .. image:: images/meso_beam_5.png
+
+   .. image:: images/meso_beam_6.png
+
+#. Go to :guilabel:`Camera Settings` and ensure that :guilabel:`Light-Sheet` is selected under :guilabel:`Sensor Mode`. Slowly increase the wavelength's :guilabel:`Amplitude` until the beam becomes a straight line across the screen. If the beam does not become straighter, try changing the camera's :ref:`Readout Direction <ui_camera_modes>`.
+
+   .. image:: images/meso_beam_7.png
+
+   .. image:: images/meso_beam_8.png
+
+   Adjust the :guilabel:`F` (focus) value in the :guilabel:`Stage Control` panel until the beam is as thin/focused as possible.
+
+   .. image:: images/meso_beam_9.png
+
+#. Once the beam is straight, slowly change the wavelength's :guilabel:`Offset` until the beam has an even thickness across the field of view. This will also make the beam a bit thinner.
+
+   .. image:: images/meso_beam_10.png
+
+   .. image:: images/meso_beam_11.png
+
+.. warning::
+
+    Proper alignment of the ASLM scan is critical to the quality of the image. We recommend iterating the :guilabel:`Amplitude`, :guilabel:`Offset`, and :guilabel:`F` until the beam is uniformly as thin as possible throughout the entire field of view.
+
+#. Slowly increase :guilabel:`Galvo 0`'s :guilabel:`Amplitude` until the entire field of view is just covered by the digitally scanned beam. Over-scanning the beam will result in a loss of light, but also provide a more uniform illumination for tiling applications.
+
+   .. image:: images/meso_beam_12.png
+
+   .. image:: images/meso_beam_13.png
+
+   .. image:: images/meso_beam_14.png
+
+   .. image:: images/meso_beam_15.png
+
+#. Under :guilabel:`Waveform Parameter Settings`, press :guilabel:`Save Configuration`.
+#. Under the :guilabel:`Channels` tab, restore the filter to its non-empty position.
+
+-----------------
+
+Loading and finding the sample
+==============================
+
+#. Load the sample on the microscope.
+#. Select "Continuous Scan" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. This will launch a live acquisition mode.
+#. Scroll around with the stage either via joystick or using the controls in the :guilabel:`Stage Control` tab until the sample comes into view.
+
+   .. image:: images/find_sample.png
+
+#. Focus on the sample using the ``F`` axis. Optionally, use Autofocus by going to :menuselection:`Autofocus --> Autofocus Settings`. Press :guilabel:`Autofocus`. Ensure there is a clear peak in the resulting plot.
+
+   .. image:: images/autofocus_settings.png
+
+   If there is not a clear peak, the autofocusing routine did not work. Try increasing the laser power and/or bringing the sample more into focus manually. If it did work, the sample should now be in focus.
+
+   .. image:: images/autofocus_image.png
+
+   .. note::
+
+        Sometimes there isn't a clear peak, but there is a clear trend toward a peak. In this case, the autofocus is converging, but the true focus position is outside the range of your search. Run autofocus again to achieve convergence.
+
+        .. image:: images/autofocus_settings_partial.png
+
+-----------------
+
+.. _z_stack_mesospim:
+
+Imaging a z-stack
+=================
+
+#. Select "Continuous Scan" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`. This will launch a live acquisition mode.
+#. Using the :guilabel:`Stage Control`, go to a shallow Z-position in the sample. Under the :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (um)` press :guilabel:`Set Start Pos/Foc`.
+
+   .. image:: images/set_start_pos.png
+
+#. Go to a deep Z-position in the sample. Press :guilabel:`Set End Pos/Foc`.
+
+   .. image:: images/set_end_pos.png
+
+#. Select "Z-Stack" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`.
+#. Enter the sample parameters in the :guilabel:`File Saving Dialog` that pops up. Press :guilabel:`Acquire Data`.
+
+   .. image:: images/save_dialog.png
+
+-----------------
+
+.. _acquire_mesospimbt_tiling:
+
+Tiling a sample larger than the field of view
+=============================================
+
+This assumes you have already set the start and end positions in :guilabel:`Stack Acquisition Settings (um)` (see :ref:`Imaging a Z-Stack <i_want_to_z_stack>`).
+
+#. Under the :guilabel:`Channels` tab, press :guilabel:`Launch Tiling Wizard`.
+
+   .. image:: images/tiling_wizard.png
+
+#. Go to thickest part of the sample. Go to the lower bound of the ``X`` axis and press :guilabel:`Set X Start`. Go to the upper bound of the ``X`` axis and press :guilabel:`Set X End`. Repeat for all axes except for focus.
+#. Ensure the sample is in focus and press :guilabel:`Set F Start` and :guilabel:`Set F End` without changing the focus position.
+#. Press :guilabel:`Populate Multi-Position Table`. Navigate to the :guilabel:`Multiposition` tab and ensure the locations populated.
+
+   .. image:: images/multiposition_table.png
+
+#. Under the :guilabel:`Channels`, make sure :guilabel:`Enable` is checked under :guilabel:`Multi-Position Acquisition`.
+#. Under the :guilabel:`Channels`, make sure :guilabel:`Save Data` is checked under :guilabel:`Timepoint Settings`.
+#. Select "Z-Stack" from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`.
+#. Enter the sample parameters in the :guilabel:`File Saving Dialog` that pops up. Press :guilabel:`Acquire Data`.

docs/source/02_user_guide/06_case_studies/case_studies_home.rst

@@ -0,0 +1,40 @@
+Case Studies
+============
+
+Light sheet microscopy is a very versatile technique. Here we present some case studies that demonstrate how **navigate** can be used to configure and acquire data from different types of light sheet microscopes. We also provide information on how to use the REST-API to communicate with other software, such as ilastik, for image segmentation and analysis, and how to use the feature container to execute multiscale imaging and smart microscopy.
+
+------------------
+
+.. toctree::
+   :caption: Setting Up a Microscope
+   :maxdepth: 2
+
+   setup_voodoo
+
+------------------
+
+.. toctree::
+   :caption: Operating a Microscope
+   :maxdepth: 2
+
+   acquire_mesospimbt
+   acquire_CT-ASLM-V1_and_CT-ASLM-V2
+   acquire_exASLM
+
+------------------------
+
+.. toctree::
+   :caption: Using the REST-API
+   :maxdepth: 2
+
+   ilastik_segmentation
+
+------------------
+
+.. toctree::
+   :caption: Performing Smart Microscopy
+   :maxdepth: 2
+
+   06_human_in_the_loop/human_in_the_loop
+   07_smart_tiling/smart_tiling
+   08_smart_object_detection/smart_object_detection

docs/source/02_user_guide/06_case_studies/ilastik_segmentation.rst

@@ -0,0 +1,134 @@
+.. _case_study_ilastik:
+
+=============================
+Analyzing Images via REST-API
+=============================
+
+**navigate** has the ability to communicate with other image analysis software through REST-API interfaces. In general, the REST-API is used to communicate with software that has different or conflicting dependencies with the **navigate** codebase. Data is transferred via HTTP requests and responses, which is faster and more efficient than locally saving the data and then loading it into another piece of software, but slower than direct access of the data in memory.
+
+Here is an example using `ilastik <https://www.nature.com/articles/s41592-019-0582-9>`_ to segment images and mark positions for higher resolution in a multiscale microscope. ilastik is a powerful image analysis software that enables users to train a support vector machine learning classifier to segment images using a combination of intensity, texture, and shape features. More information about ilastik can be found `here <https://www.ilastik.org/>`_.
+
+Install navigate-ilastik server
+###########################################
+
+Install ilastik first and then follow the steps below:
+
+.. code-block::
+
+    conda activate your-ilastik-environment
+    python -m pip install --upgrade pip
+    mkdir ~/Git/
+    cd ~/Git/
+    git clone https://github.com/TheDeanLab/navigate-ilastik-server
+    cd navigate-ilastik-server
+    pip install -e .
+
+Visit `navigate-ilastik-server <https://github.com/TheDeanLab/navigate-ilastik-server>`_ for more information.
+
+Run navigate-ilastik-server
+#####################################
+
+In the conda environment command window, go to the folder "navigate-ilastik-server", run the command:
+
+.. code-block::
+
+    flask --app navigate_server run
+
+If ilastik server runs on a different machine, run the command:
+
+.. code-block::
+
+    flask --app navigate_server run --host 0.0.0.0
+
+If want to specify a specific port, add parameter ``--port port-number``.
+
+Set REST-API configuration
+######################################
+
+Specify url address of the ilastik server in the configuration file (.navigate/config/rest_api_config.yml). If the ilastik server runs on the same machine as navigate, set the configuration as follow:
+
+.. code-block::
+
+    ilastik:
+    url: 'http://127.0.0.1:5000/ilastik'
+
+If the ilastik server runs on a different machine, set the configuration as follow:
+
+.. code-block::
+
+    ilastik:
+    url: 'http://remote-url:5000/ilastik'
+
+.. note::
+
+    As shown here, the default port is 5000. If another port is used, provide it here.
+
+Load and set ilastik project
+############################
+
+#. Select and click menu :menuselection:`Features --> ilastik Settings`.
+
+    .. image:: images/ilastik_1.png
+     :width: 400px
+     :align: center
+
+#. Load one ilastik segmentation project file from the pop-up window.
+
+    .. image:: images/ilastik_2.png
+     :width: 400px
+     :align: center
+
+    .. image:: images/ilastik_3.png
+     :width: 400px
+     :align: center
+
+#. Select target labels and the way to use the segmentation (display or mark positions), then click :guilabel:`Confirm`.
+
+    .. image:: images/ilastik_5.png
+     :width: 400px
+     :align: center
+
+Use ilastik feature
+#######################
+
+#. Choose :guilabel:`Customize` acquisition mode, and select the menu :menuselection:`Features --> ilastik Segmentation`.
+
+    .. image:: images/ilastik_6.png
+     :width: 400px
+     :align: center
+
+#. Click :guilabel:`Acquire` to run acquisition. If you choose to show segmentation only, click :guilabel:`Confirm` in the popup window directly.
+
+    .. image:: images/ilastik_7.png
+     :width: 400px
+     :align: center
+
+    .. image:: images/ilastik_9.png
+     :width: 400px
+     :align: center
+
+If you choose to :guilabel:`Mark Position`, please click :guilabel:`ilastik` in the pop-up window and set the target microscope name and zoom value.
+
+    .. image:: images/ilastik_10.png
+     :width: 400px
+     :align: center
+
+    .. image:: images/ilastik_8.png
+     :width: 400px
+     :align: center
+
+The positions will be populated to the multi-position table.
+
+    .. image:: images/ilastik_11.png
+     :width: 400px
+     :align: center
+
+The positions look like the following if saved in a CSV file.
+
+    .. image:: images/ilastik_12.png
+     :width: 400px
+     :align: center
+
+    .. image:: images/ilastik_13.png
+     :width: 400px
+     :align: center

docs/source/02_user_guide/06_case_studies/setup_voodoo.rst

@@ -0,0 +1,97 @@
+.. _setup_aslm:
+
+==================================================
+Setting up an Axially Swept Light-Sheet Microscope
+==================================================
+
+This case study describes Axially Swept Light-Sheet Microscope that scans the beam in both the laser propagation (``Y``) and detection (``Z``) directions synchronously with a piezo mounted objective. Tiling in ``X``, ``Y``, and ``Z`` is provided by a motorized stage.
+
+Important points
+================
+The key to properly setting up the navigate software is to sequentially enable select devices, and troubleshoot each one independently. By carefully and methodically adding devices, and checking that they are functional, one can be confident that the entire system is working as intended. In this example, we will be using a Hamamatsu Flash 4.0 camera. However, you may also use another Hamamatsu sCMOS model, or a Photometrics camera, as long as the drivers are installed and the camera is recognized by the computer. The microscope will operate in a sample scanning format for volumetric image acquisition.
+
+-------------
+
+First steps
+============
+
+#. Launch the software in synthetic hardware mode. This requires that the conda environment has been established, and that the software has been installed. Once the conda environment has been activated, the software can be launched by typing ``navigate -sh`` in the terminal.
+
+#. Once the software has been launched, the GUI will appear. Open the folder containing the configuration files by selecting to the menu :menuselection:`File --> Open Configuration Files`. This will open the ``.navigate`` folder in the file explorer, which is where local configuration files are stored.
+
+#. Open the ``configuration.yaml`` file in your preferred integrated development environment (e.g., PyCharm, VSCode, etc.).
+
+#. For every device in the ``hardware`` and ``microscopes`` sections of the ``configuration.yaml`` file, you will need to change the type to ``synthetic``. For convenience, we provide a ``synthetic_configuration.yaml`` file in ``navigate/src/navigate/config`` that can be used to replace the ``configuration.yaml`` file that already has synthetic for each device. You will need to replace the ``configuration.yaml`` file that is located in the ``.navigate`` folder with the ``synthetic_configuration.yaml`` file.
+
+#. Restart the software, but this time launch it in a standard operating mode by typing **navigate** in the terminal. This confirms that the base configuration file is functional. If any problems are encountered, please submit a ticket on `GitHub <https://github.com/TheDeanLab/navigate>`_ under the "Issues" tab.
+
+-------------
+
+Sequentially adding devices
+===========================
+
+Data Acquisition Card
+---------------------
+
+#. We will now begin sequentially adding non-synthetic devices to the configuration file. The first device to add is the NI data acquisition card. Of course, the data acquisition card's drivers must be `installed <https://www.ni.com/en/support/downloads/drivers/download.ni-daq-mx.html>`_ and functioning. To confirm that it is functioning, it is best to use the `NI MAX` software and evaluate the card's functionality with an oscilloscope.
+
+#. In the ``hardware`` and ``microscopes`` sections of the ``configuration.yaml`` file, change the ``type`` to ``NI``. You will also need to hard-wire the ``master_trigger_out_line`` to the ``trigger_source``. The identity of these pins can be found in the NI MAX software by right-clicking on the device and selecting :guilabel:`Device Pinouts`. You will also need to make sure that the identity of the pinouts is correct in the ``configuration.yaml`` file. Most commonly, NI cards default to a device name such as "Dev1". You can change this name in NI MAX, or leave it as is, but whatever you do it has to match the name in the ``configuration.yaml`` file (e.g., ``PXI6259/port0/line1`` if the name of the device is "PXI6259" and the pinout is "port0/line1").
+
+#. Open the **navigate** software in the standard operating mode, select the "Continuous Scan" mode, and press :guilabel:`Acquire`. If the software is operating as expected, it should display a synthetically generated image of noise. If it does not, double-check the configuration file and make sure that the ``master_trigger_out_line`` is connected to the ``trigger_source``.
+
+----------
+
+Camera
+------
+
+#. Next, we will add the camera. The camera must be connected to the computer via a USB or the dedicated frame-grabber cable. The camera drivers must also be installed. The camera drivers can be found on the `DCAM-API Website <https://dcam-api.com>`_.
+
+#. Update the camera type to ``HamamatsuOrca`` and input the correct serial number, which can be found on the camera label or through the DCAMConfigurator or HCImage. You will also need to connect the ``camera_trigger_out_line`` on the data acquisition card to the BNC port labeled "Ext. Trig." on the back of the camera.
+
+#. Restart the software and begin an acquisition in the "Continuous Scan" mode. The camera should now be delivering frames to the software.
+
+----------
+
+Filter Wheel
+------------
+
+#. Set up the Filter Wheel. First, identify the comport via the device manager on Windows. Change the ``filter_wheel`` type to ``SutterFilterWheel`` or equivalent in the ``hardware`` and ``microscopes`` sections of the configuration file, and provide the necessary information for that filter wheel device (e.g., ``baudrate``). At this point, you can also name each filter if desired under the ``available_filters`` section.
+
+#. Restart the software and select multiple channels in the :guilabel:`Channel Settings` tab, each with different filters. Run the software in "Continuous Scan" mode again and ensure that the filter wheel is changing filters between each acquisition.
+
+----------
+
+Lasers
+------
+
+#. Set up the lasers. Ideally, the lasers will operate in a mixed modulation mode, which requires that the NI card provides both analog and digital signals to each laser. This allows blanking of the laser, as well as control of its intensity. Open the control software for the lasers, and configure them in a mixed modulation mode. Next, connect the analog output of the NI card to the analog input of the laser. Finally, connect the digital output of the NI card to the digital input of the laser. A common port for the analog and digital outputs are ``PXI6733/ao0`` and ``PXI6733/port0/line2``, respectively.
+
+#. Configure the lasers in the ``hardware`` and ``microscopes`` sections of the configuration to type ``NI``. Here, you can specify the wavelength of each laser, as well as the minimum and maximum volts to deliver to the laser in both the analog (``power``) and digital (``onoff``) sections.
+
+----------
+
+Remote focusing unit
+--------------------
+
+#. Configure the Voice Coil. Most voice coils only require an analog signal to control, which can be delivered via the type ``NI`` in the ``hardware`` and ``microscopes``. However, some voice coils must be configured to accept an analog signal upon each power cycle (e.g., ``EquipmentSolutions``). In this case, you will also need to specify the COM port.
+
+----------
+
+Galvos
+------
+
+#. Set up the galvos. Galvos can be used for a wide variety of tasks, including shadow reduction, digitally scanned light-sheet formation, and also for stepping the beam in z during the acquisition of a z-stack. If the galvo will be used for a z-stack, it should be configured in the ``stage`` section. All other galvos are placed in ``galvo`` section. For a sample-scanning ASLM, we use a resonant galvo to perform shadow reduction.
+
+----------
+
+Stages
+------
+
+#. Install and configure the Stages. You will need to specify stages for the ``X``, ``Y``, ``Z``, ``Theta``, and ``F`` axes. If you do not need one of these stages, it should remain specified as a ``SyntheticStage``. It is also important to make sure that you map the stage coordinates to the software coordinates. For example, with the Sutter MP285, the vertical movement of the stage is its z axis. However, for light-sheet microscopes that are laid out horizontally, this axis is the x axis. Thus, we must map the hardware z-axis to the software x-axis. This is done with the ``axes`` and ``axes_mapping`` entries, which for the example provided, would be as follows:
+
+   .. code-block:: yaml
+
+        axes: [x] # software axes
+        axes_mapping: [z] # hardware axes
+
+   Importantly, any stage you designate as ``Z`` will be used for acquisition of a z-stack.