feat: init

docs/source/02_user_guide/04_microscope_setup/01_software_configuration/software_configuration.rst

@@ -0,0 +1,304 @@
+.. _configuration_file:
+
+======================
+Configuration Overview
+======================
+
+This section outlines the ``configuration.yaml``, ``experiment.yml``, ``rest_api_config.yml``, ``waveform_templates.yml``, and ``waveform_constants.yml`` files.
+
+-----------------
+
+Initial Configuration
+=====================
+
+In order for the **navigate** software to function, you will need to configure the specifications of the various hardware that you will be using in the ``configuration.yaml`` file.
+
+An example ``configuration.yaml`` file is provided in the ``navigate\config`` directory. However, to avoid conflicts between different microscopes after pulling new changes from GitHub, **navigate** by default loads a local version of the ``configuration.yaml`` file. This file is stored in the ``C:\Users\Username\AppData\Local\.navigate\config`` directory on Windows or ``~/.navigate`` on Mac/Linux.
+
+-----------------
+
+Configuration Wizard
+-------------------------
+
+To help you set up your configuration file, we have created a configuration wizard that will guide you through the process of creating your ``configuration.yaml`` file. To launch the configuration wizard, open your Terminal or Anaconda Prompt, activate your **navigate** Python environment and launch the software by typing: ``navigate -c``.
+
+   .. image:: images/configurator.PNG
+     :width: 400px
+     :align: center
+
+The configuration wizard provides a convenient way for configuring your hardware. For each microscope, which can be renamed or deleted by right-clicking on the microscope tab, you will be asked to specify the hardware that you are using. Each hardware type is listed as its own independent tab, and required parameters are shown on the left column, a field for the parameter is shown in the middle, and an example of the parameter is shown on the right.
+
+Additional microscope instances can be added by clicking the :guilabel:`Add A Microscope` button. Should one want to start from scratch, the :guilabel:`New Configuration` button will clear the current configuration. If you have a configuration that you would like to modify, you can load it by clicking the :guilabel:`Load Configuration` button. Once you have completed the configuration, you can save it by clicking the :guilabel:`Save` button. For **navigate** to use the configuration file by default, it should be saved as ``configuration.yaml`` in the following directory, depending upon your operating system:
+
+* Windows: ``C:\Users\Username\AppData\Local\.navigate\config``
+* Mac/Linux: ``~/.navigate``
+
+.. note::
+
+   The configuration wizard is actively being developed, and may not support every device type or configuration option. If you encounter any issues with the configuration wizard, please let us know by creating an issue on `GitHub <https://github.com/TheDeanLab/navigate/issues/new/choose>`_.
+
+-----------------
+
+Manual Configuration
+-------------------------
+
+If you prefer to manually configure your ``configuration.yaml`` file, we recommend launching the software in the synthetic hardware mode initially. Within your Terminal, or Anaconda Prompt, activate your **navigate** Python environment and launch the software in the synthetic hardware mode by typing: ``navigate -sh``.
+
+Upon launching the software in the synthetic hardware mode, **navigate** will create a copy of the ``navigate\config\configuration.yaml`` file in ``C:\Users\Username\AppData\Local\.navigate\config`` on Windows or ``~/.navigate`` on Mac/Linux.
+
+Thereafter, you should only modify the ``configuration.yaml`` file in your local ``.navigate\config`` directory.
+
+.. tip::
+
+    Once **navigate** is open in the synthetic hardware mode, you can open the ``configuration.yaml`` file by going to :menuselection:`File` menu and selecting :ref:`Open Configuration Files <ui_file_menu>`.
+
+It may help to open ``C:\Users\Username\AppData\Local\.navigate\config\configuration.yaml`` and follow along in this file when reading the next sections.
+
+See the :ref:`Setting up an Axially Swept Light-Sheet Microscope <setup_aslm>` case study for a general walkthrough of how to build your own configuration file and see :ref:`Implementations <implemented_microscopes>` for examples of configuration files.
+
+-----------------
+
+.. _multiple_microscopes:
+
+Microscope Configurations
+-------------------------
+
+The ``configuration.yaml`` file contains the microscope configurations that you will be using with the software. Each microscope is represented as a YAML dictionary.
+
+Switching between each microscope is readily performed in **navigate**, enabling you to switch between different configurations or imaging modes, each with their own unique or shared hardware:
+
+.. code-block:: yaml
+
+    microscopes:
+        microscope1:
+            ...
+            ...
+        microscope2:
+            ...
+            ...
+
+Here, ``microscope1`` and ``microscope2`` are names of two different microscopes using different combinations of the hardware. The names of the microscopes must not include spaces or special characters such as ``<``, ``\``, ``#``, ``%``, or ``?``.
+
+Microscope Inheritance
+-------------------------
+
+When setting up a ``configuration.yaml`` file with multiple microscopes, the file can grow quite large and repetitive, especially if the microscopes share many of the same hardware components. To avoid this, **navigate** allows for inheritance of hardware components from one microscope to another. In the following example, ``microscope2`` inherits all of the hardware components from ``microscope1`` except for the camera, since this is specified in the ``microscope2`` section.
+
+.. code-block:: yaml
+
+    microscopes:
+        microscope1:
+            camera:
+                hardware:
+                    type: HamamatsuOrca
+                    ...
+            ...
+        microscope2(microscope1):
+            camera:
+                hardware:
+                    type: HamamatsuFusion
+                    ...
+            ...
+
+-----------------
+
+Microscope Hardware Specification
+---------------------------------
+
+Each microscope is expected to have a ``daq``, ``camera``, ``remote_focus_device``, ``galvo``, ``filter_wheel``, ``stage``, ``zoom``, ``shutter``, ``mirror`` and ``lasers`` section of the YAML dictionary. As in the hardware section, unused devices can be specified as synthetic.
+
+Most of the information to set up these devices can be found in the :ref:`Supported Hardware <hardware_overview>` section of the documentation. Additional explanations of a few specific sections of the microscope configuration are below. Notably, the ``zoom`` section of the ``configuration.yaml`` specifies effective pixel size.
+
+.. _configure_stages:
+
+Stage Subsection
+^^^^^^^^^^^^^^^^
+
+The stage section of the microscope 1) puts the stage control from the ``hardware`` section into the microscope 2) sets boundaries for stage movement and 3) optionally specifies joystick-controlled axes.
+
+.. code-block:: yaml
+
+    microscopes:
+        microscope1:
+            stage:
+                hardware:
+                  -
+                    name: stage
+                    type: ASI
+                    serial_number: 123456789
+                    axes: [x, y, z, f] # Software
+                    axes_mapping: [M, Y, X, Z] # M Shear axis mapping
+
+                  -
+                    name: stage
+                    type: SyntheticStage
+                    serial_number: 987654321
+                    axes: [theta]
+
+            joystick_axes: [x, y, z]
+            x_max: 100000
+            x_min: -100000
+            y_max: 100000
+            y_min: -100000
+            z_max: 100000
+            z_min: -100000
+            f_max: 100000
+            f_min: -100000
+            theta_max: 360
+            theta_min: 0
+
+            x_offset: 0
+            y_offset: 0
+            z_offset: 0
+            theta_offset: 0
+            f_offset: 0
+
+            flip_x: False
+            flip_y: False
+            flip_z: False
+            flip_f: False
+
+First, we set the axes controlled by each piece of hardware and a mapping from the hardware's API axes to our software's axes. For example, the ASI ``M`` axis is mapped onto our software's ``X`` axis below.
+
+For ``stages``, **navigate** requires that stages are configured for each microscope in ``X``, ``Y``, ``Z``, ``F``, and ``Theta``. If no physical stage is present, then that axes should be defined as a ``SyntheticStage``, as shown above for ``Theta``.
+
+Below this, we specify that only ``X``, ``Y`` and ``Z`` axes may be controlled by a joystick and we set the stage bounds for each of the axes.
+
+Below this, we set the minimum and maximum values for each axis. This can be used to set boundaries that prevent the stage from crashing into the sides of a chamber.
+
+Below this, we set the offset for each stage axis. This is an offset relative to other microscopes (e.g. ``microscope2``) specified in ``configuration.yaml``. In this case, ``microscope1`` is the reference microscope. Additional microscopes may ask the stage to move to a different offset in order to observe the sample at the same position as ``microscope1``.
+
+Finally, we set the flip flags. These are important for getting :ref:`multiposition <ui_multiposition>` acquisitions to run properly. We set a convention in the software to expect that increasing value along an axis brings the sample further into our field of view. That is, increasing the x-axis position should bring the sample further to the right in the frame (in the case :ref:`Flip XY <ui_lut>` is toggled on) and increasing the y-axis position should bring the sample down. Increasing the z-position should bring the sample closer to the objective. If the stage behaves the opposite of any of these ways, it is prudent to set the flip flag. If set properly, the calculations for moving through multiple positions will be performed correctly. These only need to be configured once when setting up the microscope.
+
+-----------------
+
+.. _software_configuration_stages:
+
+Stage Axes Definition
+^^^^^^^^^^^^^^^^^^^^^
+
+Many times, the coordinate system of the stage hardware do not agree with the optical definition of each axes identity. For example, many stages define their vertical dimension as ``Z``, whereas optically, we often define this axis as ``X``. Thus, there is often a need to map the mechanical axes to the optical axes, and this is done with the ``axes_mapping`` dictionary entry in the stage hardware section. By default, stage axes are read in as ``X``, ``Y``, ``Z``, ``Theta``, ``F``, where ``Theta`` is rotation and ``F`` is focus, but this can be changed by changing axes mapping.
+
+.. code-block:: yaml
+
+    axes: [x, y, z, theta, f]
+    axes_mapping: [x, y, z, r, f]
+
+If, on a certain microscope, the ``Z`` stage axis corresponds to the optical Y-axis, and vice versa, you would then have to import the stages as following:
+
+.. code-block:: yaml
+
+    axes: [x, y, z, theta, f]
+    axes_mapping: [x, z, y, r, f]
+
+-----------------
+
+Joystick Axes Definition
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are using a joystick, it is possible to disable GUI control of the stage axes that the joystick can interact with. The axes that the joystick can interact with appear in the stage field as following:
+
+.. code-block:: yaml
+
+    joystick_axes: [x, y, z]
+
+.. Note::
+
+    These axes should agree with the optical axes. If, on the same microscope as mentioned in the :ref:`Stage Axes Definition <software_configuration_stages>` section, the joystick were to control the optical y-axis corresponding to the stage z axis, you would have to put ``Y`` in the joystick axes brackets as following:
+
+.. code-block:: yaml
+
+    joystick_axes: [y]
+
+-----------------
+
+Zoom Subsection
+^^^^^^^^^^^^^^^
+
+The ``zoom`` section of ``configuration.yaml`` specifies control over microscope zoom lenses, or devices that change the magnification of the imaging system. For example, we use the `Dynamixel Smart Actuator <https://www.dynamixel.com/>`_ to control the rotating zoom wheel on an Olympus MVXPLAPO 1x/0.25.
+
+.. code-block:: yaml
+
+    microscopes:
+        microscope1:
+            zoom:
+                hardware:
+                    name: zoom
+                    type: DynamixelZoom
+                    servo_id: 1
+                position:
+                    0.63x: 0
+                    1x: 627
+                    2x: 1711
+                    3x: 2301
+                    4x: 2710
+                    5x: 3079
+                    6x: 3383
+                pixel_size:
+                    0.63x: 9.7
+                    1x: 6.38
+                    2x: 3.14
+                    3x: 2.12
+                    4x: 1.609
+                    5x: 1.255
+                    6x: 1.044
+                stage_positions:
+                    BABB:
+                        f:
+                            0.63x: 0
+                            1x: 1
+                            2x: 2
+                            3x: 3
+                            4x: 4
+                            5x: 5
+                            6x: 6
+
+The ``positions`` specify the voltage of the actuator at different zoom positions. The ``pixel_size`` specifies the effective pixel size of the system at each zoom. The ``stage_positions`` account for focal shifts in between the different zoom values (the MVXPLAPO does not have a consistent focal plane). These may change depending on the immersion media. Here it is specified for a ``BABB`` (Benzyl Alcohol Benzyl Benzoate) immersion media.
+
+Regardless of whether or not your microscope uses a zoom device, you must have a ``zoom`` entry, indicating the effective pixel size of your system in micrometers. For example,
+
+.. code-block:: yaml
+
+    zoom:
+      hardware:
+        name: zoom
+        type: SyntheticZoom
+        servo_id: 1
+      position:
+        N/A: 0
+      pixel_size:
+        N/A: 0.168
+
+-----------------
+
+.. _experiment_file:
+
+Experiment File
+===============
+
+The ``experiment.yml`` file stores information about the current state of the program. This includes laser and camera parameters, saving options, z-stack settings and much more. This file does not need to be edited by the user. The program will update it automatically and save changes automatically on exit.
+
+-----------------
+
+.. _configure_waveforms_constants:
+
+Waveform Constants File
+=======================
+
+The ``waveform_constants.yml`` file stores the waveform parameters that can be edited by going to :menuselection:`Microscope Configuration --> Waveform Parameters`. This file does not need to be edited by the user. The program will update it automatically and save changes automatically on exit.
+
+-----------------
+
+.. _configure_waveform_templates:
+
+Waveform Templates File
+=======================
+
+The waveform templates file stores default behavior for the number of repeats for specific waveforms. This file only needs to be edited if the user wishes to introduce a new waveform behavior to the application.
+
+-----------------
+
+Rest API Configuration File
+===========================
+
+The REST API configuration file specifies where the REST API should look to get and post data. This is only needed if you are using a plugin that requires the REST API, such as our communication with `ilastik <https://www.ilastik.org>`_. More information on how to setup the REST API for communication with ilastik can be found :ref:`here <case_study_ilastik>`.

docs/source/02_user_guide/04_microscope_setup/02_multiple_cameras/multiple_cameras.rst

@@ -0,0 +1,57 @@
+====================
+Multiple Cameras
+====================
+
+**navigate** is crafted for extensibility to enable the virtualization of multiple microscopes using the same and/or
+different devices, including cameras.
+
+-------------------------------------
+
+Enabling Multi-Camera Operation
+#################################
+
+**navigate** gives users the flexibility to capture images with multiple cameras. Prior to launching **navigate**, it is important that both cameras are functioning with the computer, and that they share the same external trigger signal from the data acquisition card. See :ref:`camera_configuration` for more information.
+
+
+#. Select and click menu :menuselection:`Microscope Configuration --> Configure Microscope`.
+
+   .. image:: images/multi_cams_1.png
+
+   There will be a pop-up window displaying a list of all available microscopes with its hardware details.
+
+   .. image:: images/multi_cams_2.png
+     :width: 400px
+     :align: center
+
+   There are three settings options for each microscope.
+
+   .. image:: images/multi_cams_3.png
+     :width: 400px
+     :align: center
+
+#. Set `Primary Microscope` and `Additional Microscope`, then click `Confirm`.
+
+   .. image:: images/multi_cams_4.png
+     :width: 400px
+     :align: center
+
+#. Then set `Acquisition mode` and click `Acquiring` the same way as using one camera. There will be a pop-up window displaying images obtained from an additional camera.
+
+   .. image:: images/multi_cams_5.png
+
+----------------------------------------------
+
+Disabling Multi-Camera Operation
+################################
+
+Once you're finished acquiring images with multiple cameras, remember to reset to the single-camera mode.
+
+#. Select and click menu :menuselection:`Microscope Configuration --> Configure Microscope`.
+
+   .. image:: images/multi_cams_1.png
+
+#. Set `Primary Microscope` and set the "additional microscope" as `Not Use`. Then click `Confirm`.
+
+   .. image:: images/multi_cams_9.png
+     :width: 400px
+     :align: center

docs/source/02_user_guide/04_microscope_setup/03_snr/snr.rst

@@ -0,0 +1,28 @@
+==================================
+Signal-to-Noise Visualization Mode
+==================================
+
+The Signal-to-Noise Ratio (SNR) Visualization Mode is designed to help users assess the quality of their images by visualizing the signal-to-noise ratio in real-time. This mode is particularly useful for identifying areas of high and low signal quality, which is helpful when aligning a microscope or when working with low-light conditions.
+
+In the future, we will provide a method to acquire the offset and variance maps directly from within *navigate*. For now, users will need to provide these maps manually using commercial software provided by the camera manufacturer or by using custom scripts.
+
+-------------------------------
+
+Acquiring Offset and Variance Maps
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In general, it is a good idea to acquire the data used to derive the offset and variance maps at a similar exposure time as the one used for imaging. To calculate the offset and variance maps, users can follow these general steps:
+
+1. **Capture Dark Frames**: With the camera lens cap on, capture a series of dark frames (e.g., 1000 frames). These frames will be used to calculate the offset map.
+
+2. **Calculate the Offset Map**: Compute the minimum of the dark frames to create the offset map. This map represents the baseline signal level of the camera.
+
+3. **Calculate the Variance Map**: Compute the variance of the dark frames to create the variance map. This map represents the noise characteristics of the camera.
+
+4. **Save the Maps**: Save the offset and variance maps as tiff images in a folder titled `camera_maps` in navigate's home directory.
+
+    - For Windows-based users: ``C:\AppData\Local\.navigate\camera_maps\``.
+    - For Linux and MacOS users: ``/home/<username>/.navigate/camera_maps/``.
+    - The files should be named as ``<camera_serial_number>_off.tiff`` and ``<camera_serial_number>_var.tiff``, where ``<camera_serial_number>`` is the serial number of the camera being used. By providing the serial number, users can easily switch between different cameras without needing to reconfigure the settings each time.
+
+5. **Launch navigate**: Next time you launch **navigate**, it will automatically detect the presence of the offset and variance maps in the specified directory and provide the appropriate options to enable the SNR visualization mode.

docs/source/02_user_guide/04_microscope_setup/setup_microscope.rst

@@ -0,0 +1,12 @@
+.. _setup_microscope:
+
+=======================
+Setting Up A Microscope
+=======================
+
+.. toctree::
+   :maxdepth: 2
+
+   01_software_configuration/software_configuration
+   02_multiple_cameras/multiple_cameras
+   03_snr/snr