feat: init

docs/source/03_contributing/06_plugin/plugin_home.rst

@@ -0,0 +1,227 @@
+.. _plugin:
+
+====================
+Plugin Architecture
+====================
+
+**navigate** is designed with extensibility. Users can seamlessly integrate custom GUI plugins, device plugins, new feature plugins, and even define specific acquisition modes.
+
+-------------------------------------
+
+Introduction to Plugins
+########################
+
+The **navigate** **plugin system** gives users the flexibility to extend its functionality according to their specific needs. **navigate** will load plugins automatically and users can use their plugins with **navigate** seamlessly.
+
+-----------
+
+Installing a Plugin
+####################
+
+Once you've built a plugin or downloaded a **navigate** plugin, you can easily install it. Here, we have downloaded the `Navigate Confocal-Projection Plugin <https://github.com/TheDeanLab/navigate-confocal-projection>`_.
+
+#. You can install the **navigate-confocal-projection** plugin by selecting the menu :menuselection:`Plugins --> Install Plugin`.
+
+   .. image:: images/plugin_1.png
+      :width: 60%
+      :align: center
+
+#. Select the folder `ConfocalProjectionPlugin` and click :guilabel:`Select`.
+
+   .. image:: images/plugin_2.png
+      :width: 60%
+      :align: center
+
+#. You should receive a message indicating that the plugin has been installed successfully.
+
+   .. image:: images/plugin_3.png
+      :width: 60%
+      :align: center
+
+#. Restart **navigate** to use this installed plugin.
+
+-----------
+
+Uninstalling a Plugin
+#####################
+
+Uninstalling a plugin is very easy.
+
+#. Select :menuselection:`Plugins --> Uninstall Plugins`. This will open a popup window where you can see all of the currently installed plugins.
+
+   .. image:: images/plugin_4.png
+      :width: 60%
+      :align: center
+
+#. Select the plugin you want to uninstall.
+
+   .. image:: images/plugin_5.png
+      :width: 60%
+      :align: center
+
+#. Click :guilabel:`Uninstall`.
+
+   .. image:: images/plugin_6.png
+      :width: 60%
+      :align: center
+
+#. Restart **navigate** to fully remove the uninstalled plugin.
+
+-------------------------------------
+
+Designing a Plugin
+##########################
+
+Using a Plugin Template
+-------------------------------------
+
+A comprehensive **plugin template** is provided. Users could download the **plugin template** from `github <https://github.com/TheDeanLab/navigate-plugin-template>`_ and build plugins on it.
+
+Plugin Structure:
+
+.. code-block:: none
+
+    plugin_name/
+        ├── controller/
+        │   ├── plugin_name_controller.py
+        │   ├── ...
+        ├── model/
+        │   ├── devices/
+        │   │   └── plugin_device/
+        │   │       ├── device_startup_functions.py
+        │   │       ├── plugin_device.py
+        │   │       └── synthetic_plugin_device.py
+        │   └── features/
+        │           ├── plugin_feature.py
+        │           ├── ...
+        │
+        ├── view/
+        │   ├── plugin_name_frame.py
+        │   ├── ...
+        │
+        ├── feature_list.py
+        ├── plugin_acquisition_mode.py
+        └── plugin_config.yml
+
+.. note::
+
+    The template shows a plugin with GUI, device, feature, feature_list and acquisition mode. If your plugin only incorporates some of these components, you should remove unused folders and files.
+
+-------------------------------------
+
+Plugin Configuration
+--------------------
+
+There should always have a ``plugin_config.yml`` file under the plugin folder, which tells **navigate** the plugin name, the GUI as a Tab or Popup and custom acquisition mode name. A typical plugin config is:
+
+.. code-block:: none
+
+    name: Plugin Name
+    view: Popup # or Tab
+    acquisition_modes:
+      - name: Plugin Acquisition
+        file_name: plugin_acquisition_mode.py
+
+-------------------------------------
+
+Plugin GUI Elements
+--------------------
+
+**navigate** supports plugins with their own GUIs. A custom plugin GUI can be integrated as a tab or a popup. Users should specify a view option in ``plugin_config.yml``. If it is a popup, users can find the plugin under the :guilabel:`Plugins` menu in the **navigate** window. If it is a tab, it will appear next to the :ref:`Settings Notebooks <ui_settings_notebooks>`.
+
+When creating a new plugin with a GUI, ensure that the plugin name is consistent with the naming conventions for the associated Python files (``plugin_name_controller.py`` and ``plugin_name_frame.py``). Both Python filenames should be in lowercase.
+
+For example, if your plugin is named "My Plugin" (there is a space in between), the associated Python files should be named: ``my_plugin_frame.py`` and ``my_plugin_controller.py``.
+
+-------------------------------------
+
+Plugin Devices
+------------------
+
+The **navigate** plugin architecture allows you to integrate new hardware device. There can be more than one device inside a plugin. If they are different kinds of device, please put them into different folders. For each kind of device, there should be a ``device_startup_functions.py`` telling **navigate** how to start the device and indicating the reference name of the device to be used in ``configuration.yaml``.
+
+Device type name and reference name are given as following:
+
+.. code-block:: python
+
+    DEVICE_TYPE_NAME = "plugin_device"  # Same as in configuration.yaml, for example "stage", "filter_wheel", "remote_focus_device"...
+    DEVICE_REF_LIST = ["type", "serial_number"]
+
+A function to load the device connection should be given,
+
+.. code-block:: python
+
+    def load_device(hardware_configuration, is_synthetic=False):
+        # ...
+        return device_connection
+
+A function to start the device should be given,
+
+.. code-block:: python
+
+    def start_device(microscope_name, device_connection, configuration, is_synthetic=False):
+        # ...
+        return device_object
+
+The template for ``device_startup_functions.py`` can be found in the `plugin template <https://github.com/TheDeanLab/navigate-plugin-template/blob/main/plugins_template/model/devices/plugin_device/device_startup_functions.py>`_.
+
+-------------------------------------
+
+Plugin Features
+-------------------------
+
+**navigate** allows users to add new features. New feature objects and feature lists can each be a plugin or components of a plugin. Features and feature lists are automatically loaded into **navigate**.
+
+Please visit `here <https://thedeanlab.github.io/navigate/contributing/feature_container.html>`_ for details about how to build a new feature object and feature list.
+
+-------------------------------------
+
+Custom Acquisition Modes
+------------------------
+
+Navigate offers seamless support for custom acquisition modes, and registering a new mode is straightforward.
+
+1. Download the template for `plugin_acquisition_mode.py <https://github.com/TheDeanLab/navigate-plugin-template/blob/main/plugins_template/plugin_acquisition_mode.py>`_
+
+2. Update the ``feature_list``.
+
+.. code-block:: python
+
+    @AcquisitionMode
+    class PluginAcquisitionMode:
+        def __init__(self, name):
+            self.acquisition_mode = name
+
+            self.feature_list = [
+                # update here
+            ]
+
+3. Update the functions.
+
+Users should tell **navigate** what to do before and after acquisition using the following functions.
+
+.. code-block:: python
+
+    def prepare_acquisition_controller(self, controller):
+        # update here
+
+    def end_acquisition_controller(self, controller):
+        # update here
+
+    def prepare_acquisition_model(self, model):
+        # update here
+
+    def end_acquisition_model(self, model):
+        # update here
+
+4. Register the acquisition mode in ``plugin_config.yml``.
+
+.. code-block:: none
+
+    acquisition_modes:
+        - name: Custom Acquisition
+          file_name: plugin_acquisition_mode.py
+
+-----------
+
+For more plugin examples, please visit the plugins in the table of contents menu on the left.