feat: init

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

@@ -0,0 +1,86 @@
+==============
+Acquiring Data
+==============
+
+This provides detailed descriptions of **navigate**'s acquisition modes and saving capabilities. For a how-to on acquiring data, please see :ref:`Acquiring an Image <beginner>`.
+
+----------------
+
+Standard Acquisition Modes
+==========================
+
+**navigate** features standard acquisition modes including Continuous/Live, Single Frame, and Z-Stack, which can be saved to TIFF, OME-TIFF, HDF5, N5, and OME-Zarr data formats. Saving is toggled under the GUI's :ref:`timepoint settings <ui_timepoint_settings>`.
+
+These modes (and other custom modes) can be selected in the program's :ref:`acquisition bar <ui_acquisition_bar>` dropdown list. Each acquisition mode is implemented as a :ref:`feature list <user_guide_features>` and can be used in sequence with other features that can, for example, :ref:`make smart decisions <intermediate>`.
+
+----------------
+
+.. _user_guide_continuous:
+
+Continuous Scan
+---------------
+
+This creates a live view of what is on the camera. It is not possible to save data in this mode, only to preview what is in focus. This mode is helpful for alignment, parameter tuning, and scrolling around the sample with the stage.
+
+It is implemented as a :ref:`feature list <user_guide_features>`, shown in its :ref:`textual form <text_representation_features>` below.
+
+.. code-block:: python
+
+    [
+      (
+        {"name": PrepareNextChannel},
+        {
+            "name": LoopByCount,
+            "args": ("channels",),
+        },
+      )
+    ]
+
+The sequence begins with the `PrepareNextChannel` feature and loops over `experiment.MicroscopeState.selected_channels`. As such, continuous mode will display a live preview of all :ref:`selected color channels <ui_channel_settings>` in sequence, then return the first color channel and start again.
+
+----------------
+
+Single Acquisition
+------------------
+
+This takes a single image of each :ref:`selected channel <ui_channel_settings>` and optionally saves them to a file. Its feature list is identical to that of "Continuous Scan".
+
+----------------
+
+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".
+
+Z-Stack acquisition is implemented as the feature list below.
+
+.. code-block:: python
+
+    [
+        (
+            {"name": ZStackAcquisition},
+            {"name": StackPause},
+            {
+                "name": LoopByCount,
+                "args": ("experiment.MicroscopeState.timepoints",),
+            },
+        )
+    ]
+
+Note that in the z-stack the color channel looping is abstracted into ``ZStackAcquisition``, but we will take one set of z-stacks at each :ref:`timepoint <ui_timepoint_settings>`. It is also worth noting that ``ZStackAcquisition`` handles moving through :ref:`multiple positions <ui_multiposition>`. ``ZStackAcquisition`` will loop over ``Z`` or ``C`` first, as decided by "Per Stack" or "Per Z", and then will loop over positions.
+
+----------------
+
+Customized
+----------
+
+The customized acquisition mode can be used to run any feature list of the user's choosing. Data acquisition with **navigate** is almost infinitely reconfigurable with either the :ref:`feature container <user_guide_features>`, if a desired acquisition can be performed using a reconfiguration of existing features and saving formats, or the :ref:`plugin architecture <plugin>`, if new features or saving formats are required. We strongly recommend the reader check through the :ref:`available features <currently_implemented_features>` and see if they can be combined into an acquisition feature list before writing a new acquisition feature.
+
+----------------
+
+Analysis Pipeline
+=================
+
+Images are stored from the camera onto a circular buffer of size ``databuffer_size``. By default, this buffer is 100 frames in length.
+
+Image processing and saving operations (see the :ref:`feature container <features>` data operations) are performed on frames in this buffer. These operations must take less time than it takes to add a new frame to the buffer, or the buffer will eventually overflow. This is, in part, why saving to an SSD (as opposed to HDD) is critical.

docs/source/02_user_guide/05_acquiring_data/02_feature_container/features.rst

@@ -0,0 +1,148 @@
+.. _user_guide_features:
+
+==========================================
+Reconfigurable Acquisitions Using Features
+==========================================
+
+What are features?
+------------------
+
+**navigate** allows users to reconfigure acquisition routines within the GUI by chaining so-called "features" together in sequence. A feature is the name given to a single acquisition unit such as ``Snap``, which snaps an image, or ``MoveToNextPositionInMultiPositionTable``, which moves the stage to the next imaging position indicated in the :guilabel:`Multiposition Table`. Some acquisition units, such as ``Autofocus`` or ``ZStackAcquisition`` have a bit more going on under the hood, but can be used in the same way.
+
+-----------
+
+Customizing Feature Functionality in the GUI
+--------------------------------------------
+
+Features can be optionally customized within the GUI. For example instead of reprogramming a feature and loading it again, we can swap Python functions in and out of features. This can be helpful, e.g., when you are prototyping a function to automatically detect an object within an image and want to try a few different options.
+
+-----------
+
+Creating a Custom Feature List in the GUI
+-----------------------------------------
+
+Once you have loaded your feature list, the next step is to use it in combination with other features to create an intelligent acquisition workflow. To do this, you will need to create a new feature list that combines your custom feature with other
+features:
+
+#. Select :menuselection:`Features --> Add Customized Feature List`. This will open a new dialog box that allows you to create a new feature list.
+
+#. Provide the feature list with a :guilabel:`Feature List Name` of your choice, and type the feature list content (which must be a list object). The feature list content could be the whole feature list or just a simple feature name. In this example, the feature list name is ``Feature Example 2``, and the content is a simple feature name:
+
+   .. code-block::
+
+       [{"name": PrepareNextChannel}]
+
+   Once you select `Preview`, the feature list will be displayed in the  :guilabel:`Preview` window. If you are satisfied with the feature list, select `OK` to save it.
+
+   .. image:: images/step_3.png
+
+
+#. You can edit the list of features directly by modifying the text, or through a popup menu that is available by right clicking the feature tile. The popup menu allows you to add a new feature, delete a feature, or edit a feature. In this example, click :guilabel:`Insert After`, and a new feature ``PrepareNextChannel`` will be inserted by default.
+
+   .. image:: images/step_4.png
+
+   .. image:: images/step_5.png
+
+#. To change the identity of the inserted feature, you can select a different feature form the drop-down menu. For example, the feature can be changed from    ``PrepareNextChannel`` to ``LoopByCount``. The parameters of the feature can be changed automatically in the popup window.
+
+   .. image:: images/step_6.png
+
+#. If you click the preview button, a graphical representation of the feature list will be displayed.
+
+   .. image:: images/step_7.png
+
+6. If you want a loop structure, type a pair of parentheses around the features, then click :guilabel:`Preview`. Given this design, you can loop through  arbitrary features in a user-selected format.
+
+   .. image:: images/step_8.png
+      :alt: How to create a custom feature list.
+
+#. After editing the feature list, click :guilabel:`Add`. The new feature list will show up under the :guilabel:`Features` menu.
+
+-----------
+
+Editing Feature Lists on the Fly
+--------------------------------
+
+#. Select the feature list you want to run, choose "Customized" acquisition mode, and then click :guilabel:`Acquire`. A :guilabel:`Feature List Configuration` popup window will show up. In this popup window, you can see the structure of the selected feature list.
+
+   .. image:: images/step_16.png
+
+   .. image:: images/step_17.png
+
+   .. image:: images/step_18.png
+
+#. Click one feature in the preview window, a :guilabel:`Feature Parameters` window will show up. Then set the desired parameters (e.g., :guilabel:`planes`    in this screenshot). Close the :guilabel:`Feature Parameters` window.
+
+   .. image:: images/step_19.png
+
+#. Click :guilabel:`Confirm`. The feature list will start to run.
+
+
+   .. image:: images/step_20.png
+
+-----------
+
+Deleting Feature Lists
+----------------------
+
+#. Select the feature list you want to delete in the :guilabel:`Features` menu.
+#. Then, go back to the :guilabel:`Features` menu and select :guilabel:`Delete Selected Feature` The feature list will be removed from the menu and the software.
+
+   .. image:: images/step_9.png
+
+-----------
+
+.. _text_representation_features:
+
+Text Representation of Feature Lists
+-------------------------------------
+
+At the bottom of each of the :guilabel:`Feature List Configuration` frames above, there is a text box with a textual representation of the feature list. As an alternative to point-and-click editing, a user can update feature lists by editing this textual representation and then pressing :guilabel:`Preview`.
+
+The square brackets ``[]`` create a sequence of events to run in the feature container. The ``{}`` braces contain features. The parentheses ``()`` indicate a loop.
+
+As an example, let's look at the feature list that describes the :ref:`Continuous Scan <user_guide_continuous>` mode:
+
+.. code-block:: python
+
+    [
+      (
+        {"name": PrepareNextChannel},
+        {
+            "name": LoopByCount,
+            "args": ("experiment.MicroscopeState.selected_channels",),
+        },
+      )
+    ]
+
+Here, we have a sequence defined by ``[]`` containing one element, a loop, indicated by the closed parentheses. There are two features within this loop. One feature has the name :doc:`PrepareNextChannel <../../../05_reference/_autosummary/navigate.model.features.common_features.PrepareNextChannel>` and the other :doc:`LoopByCount <../../../05_reference/_autosummary/navigate.model.features.common_features.LoopByCount>`. The parentheses indicate we will keep looping through both of these features until stopping criteria is met. In this case, the looping will stop when ``LoopByCount`` returns ``False`` due to running out of  ``selected_channels`` to loop through. That is, it will end once all :ref:`selected channel <ui_channel_settings>` have been imaged.
+
+.. _loading_custom_functions:
+
+Loading Custom Functions
+------------------------
+You can load custom Python-based functions into the software, which will then be used to provide image-based feedback to the microscope. This allows you to easily adapt what the microscope responds to, thus tailoring the acquisition to your needs.
+
+#. You can load customized functions in the software by selecting the menu :menuselection:`Features --> Advanced Setting`.
+
+   .. image:: images/step_10.png
+
+#. In the :guilabel:`Advanced Setting` popup window, choose the feature name with which you want to use the dynamic customized functions as feature parameters.
+
+   .. image:: images/step_11.png
+
+
+   .. image:: images/step_12.png
+
+#. Click :guilabel:`Add`, A new line will appear and allow you to edit the parameter options. Type the function name which is defined in your python file.
+
+   .. image:: images/step_13.png
+
+#. Then click :guilabel:`Load` to choose your Python file.
+
+   .. image:: images/step_14.png
+
+#. When you run a feature list containing the feature you just set, the new function name will appear and you can choose the one you just added.
+
+   .. image:: images/step_15.png
+

docs/source/02_user_guide/05_acquiring_data/03_example_features/example_feature_lists.rst

@@ -0,0 +1,54 @@
+=====================
+Example Feature Lists
+=====================
+
+Fairly complex imaging sequences can be created by chaining together multiple features. Here are a few examples of feature lists that can be used to create custom acquisition protocols.
+
+Multi-Position Imaging with Automated Autofocus
+------------------------------------------------
+
+Large volumes are often acquired in a tiling format, where the sample is imaged at multiple positions. In some cases, if the sample is not perfectly transparent, the focus may need to be adjusted at each position. This can be done automatically using the autofocus feature. #. You can load customized functions in the software by selecting the menu
+
+Here, we begin by moving to the first position of the multi-position table, then move to the first z-position, measure the autofocus, set the F_Start position, move to the last z-position, measure the autofocus, set the F_End position, and image the full z-stack prior to moving to the next position in the multi-position table.
+
+.. code-block:: python
+
+    [
+        {"name": PrepareNextChannel,},
+        (
+            {"name": MoveToNextPositionInMultiPositionTable,"args": (None,None,None,),},
+            {"name": CalculateFocusRange,},
+            {"name": ZStackAcquisition,"args": (True,True,"z-stack",),},
+            {"name": WaitToContinue,},
+            {"name": LoopByCount,"args": ("positions",),},
+        ),
+    ]
+
+Time-Lapse Imaging with Automated Autofocus
+--------------------------------------------
+
+Time-lapse imaging is a common technique used to monitor changes in samples over time. If you do not have a hardware solution for maintaining the focus of the specimen, a common technique for maintaining the focus of a microscope is to intermittently measure the focus using the image as a metric.
+
+.. code-block:: python
+
+    [
+        (
+            {"name": PrepareNextChannel, },
+            (
+                {"name": Snap, "args": (True,),},
+                {"name": LoopByCount, "args": (10,),},
+            ),
+            {"name": LoopByCount, "args": (2,),},),
+            {"name": PrepareNextChannel, },
+            {"name": WaitToContinue, },
+            (
+                {"name": Autofocus, "args": ("stage","z",),},
+                (
+                    {"name": Snap, "args": (True,),},
+                    {"name": LoopByCount, "args": (5,),},
+                ),
+                {"name": StackPause, "args": ("experiment.MicroscopeState.timepoints",),},
+                {"name": LoopByCount, "args": (10,),},
+            ),
+        ),
+    ]

docs/source/02_user_guide/05_acquiring_data/04_current_features/current_features.rst

@@ -0,0 +1,19 @@
+.. _currently_implemented_features:
+
+Currently Implemented Features
+==============================
+
+Below is a comprehensive list of all the available features that can be utilized to create smart imaging workflows in navigate. These features are designed to streamline and enhance various aspects of imaging experiments. For guidance on creating your own custom features, please refer to the Development section of the documentation.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../../../05_reference/_autosummary/navigate.model.features.adaptive_optics
+   ../../../05_reference/_autosummary/navigate.model.features.auto_tile_scan
+   ../../../05_reference/_autosummary/navigate.model.features.autofocus
+   ../../../05_reference/_autosummary/navigate.model.features.common_features
+   ../../../05_reference/_autosummary/navigate.model.features.image_writer
+   ../../../05_reference/_autosummary/navigate.model.features.remove_empty_tiles
+   ../../../05_reference/_autosummary/navigate.model.features.restful_features
+   ../../../05_reference/_autosummary/navigate.model.features.volume_search
+

docs/source/02_user_guide/05_acquiring_data/acquiring_home.rst

@@ -0,0 +1,11 @@
+==============
+Acquiring Data
+==============
+
+.. toctree::
+   :maxdepth: 2
+
+   01_acquiring_guide/01_acquiring_guide
+   02_feature_container/features
+   03_example_features/example_feature_lists
+   04_current_features/current_features