feat: init
This commit is contained in:
22
docs/Makefile
Normal file
22
docs/Makefile
Normal file
@@ -0,0 +1,22 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = source
|
||||
BUILDDIR = build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
|
||||
$(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
|
||||
$(O)
|
||||
97
docs/capture_gui.py
Normal file
97
docs/capture_gui.py
Normal file
@@ -0,0 +1,97 @@
|
||||
import tkinter as tk
|
||||
import os
|
||||
|
||||
from navigate.tools.gui import capture_region, tk_window_bbox
|
||||
from navigate.view.splash_screen import SplashScreen
|
||||
from navigate.controller.controller import Controller
|
||||
from navigate.tools.main_functions import create_parser, evaluate_parser_input_arguments
|
||||
|
||||
|
||||
def get_controller():
|
||||
root = tk.Tk()
|
||||
root.withdraw()
|
||||
|
||||
# Create splash screen
|
||||
current_directory = os.path.dirname(os.path.realpath(__file__))
|
||||
splash_screen = SplashScreen(
|
||||
root,
|
||||
os.path.join(
|
||||
current_directory,
|
||||
"..",
|
||||
"navigate",
|
||||
"view",
|
||||
"icon",
|
||||
"splash_screen_image.png",
|
||||
),
|
||||
)
|
||||
|
||||
# Parse arguments with -sh flag
|
||||
parser = create_parser()
|
||||
args = parser.parse_args(["-sh"])
|
||||
|
||||
# Get paths from arguments
|
||||
(
|
||||
configuration_path,
|
||||
experiment_path,
|
||||
waveform_constants_path,
|
||||
rest_api_path,
|
||||
waveform_templates_path,
|
||||
logging_path,
|
||||
configurator,
|
||||
gui_configuration_path,
|
||||
multi_positions_path,
|
||||
) = evaluate_parser_input_arguments(args)
|
||||
|
||||
# Create and return controller
|
||||
controller = Controller(
|
||||
root,
|
||||
splash_screen,
|
||||
configuration_path,
|
||||
experiment_path,
|
||||
waveform_constants_path,
|
||||
rest_api_path,
|
||||
waveform_templates_path,
|
||||
gui_configuration_path,
|
||||
multi_positions_path,
|
||||
args,
|
||||
)
|
||||
|
||||
return root, controller
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
root, controller = get_controller()
|
||||
current_directory = os.path.dirname(os.path.realpath(__file__))
|
||||
|
||||
# Main Window
|
||||
bbox = tk_window_bbox(controller.view)
|
||||
save_path = os.path.join(
|
||||
current_directory, f"{controller.view.__class__.__name__}.png"
|
||||
)
|
||||
capture_region(*bbox, out_path=save_path)
|
||||
root.update()
|
||||
|
||||
# Settings Tabs
|
||||
for tab in [
|
||||
controller.view.settings.camera_settings_tab,
|
||||
controller.view.settings.channels_tab,
|
||||
controller.view.settings.stage_control_tab,
|
||||
controller.view.settings.multiposition_tab,
|
||||
]:
|
||||
controller.view.settings.select(tab)
|
||||
root.update()
|
||||
bbox = tk_window_bbox(controller.view.settings)
|
||||
save_path = os.path.join(current_directory, f"{tab.__class__.__name__}.png")
|
||||
capture_region(*bbox, out_path=save_path)
|
||||
|
||||
# Camera Tabs
|
||||
for tab in [
|
||||
controller.view.camera_waveform.camera_tab,
|
||||
# controller.view.camera_waveform.waveform_tab,
|
||||
controller.view.camera_waveform.mip_tab,
|
||||
]:
|
||||
controller.view.camera_waveform.select(tab)
|
||||
root.update()
|
||||
bbox = tk_window_bbox(controller.view.camera_waveform)
|
||||
save_path = os.path.join(current_directory, f"{tab.__class__.__name__}.png")
|
||||
capture_region(*bbox, out_path=save_path)
|
||||
50
docs/make.bat
Normal file
50
docs/make.bat
Normal file
@@ -0,0 +1,50 @@
|
||||
@ECHO OFF
|
||||
|
||||
REM Save the current directory and change to the script's directory
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
REM Set the SPHINXBUILD variable if it is not already set
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
|
||||
REM Define the source and build directories
|
||||
set SOURCEDIR=source
|
||||
set BUILDDIR=build
|
||||
|
||||
REM Check if sphinx-build is available
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.https://www.sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
REM If no argument is provided, show help
|
||||
if "%1" == "" goto help
|
||||
|
||||
REM Handle the linkcheck target
|
||||
if "%1" == "linkcheck" (
|
||||
%SPHINXBUILD% -b linkcheck %SOURCEDIR% %BUILDDIR%/linkcheck %SPHINXOPTS% %O%
|
||||
goto end
|
||||
)
|
||||
|
||||
REM Run the specified target
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
|
||||
REM Return to the original directory
|
||||
popd
|
||||
@@ -0,0 +1,60 @@
|
||||
.. _Quick_Start_Guide:
|
||||
|
||||
=================================
|
||||
Quick Start Guide
|
||||
=================================
|
||||
|
||||
This quick start guide covers how to install **navigate**, launch it in synthetic hardware mode to confirm it is working, and save an image to disk.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
1. *Install Miniconda.* Download and install Miniconda from the `official website <https://docs.conda.io/en/latest/miniconda.html>`_.
|
||||
|
||||
2. *Create and Activate a Conda Environment.* Launch a Miniconda Prompt (or a Terminal on MacOS) and enter the following.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(base) conda create -n navigate python=3.9.7
|
||||
(base) conda activate navigate
|
||||
|
||||
3. *Install* **navigate**.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(navigate) pip install navigate-micro
|
||||
|
||||
4. *Launch* **navigate** *in synthetic hardware mode.* This will allow you to test its functionality without actual hardware.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(navigate) navigate -sh
|
||||
|
||||
Saving a Z-Stack to Disk
|
||||
------------------------
|
||||
|
||||
To save an image to disk, follow these steps:
|
||||
|
||||
* Launch **navigate** in synthetic hardware mode as described above.
|
||||
* Next to the :guilabel:`Acquire` button on the upper left, make sure that the acquisition mode in the dropdown is set to "Continuous Scan".
|
||||
* Press :guilabel:`Acquire` (:kbd:`ctrl + enter`) and confirm that a synthetic noise image is displayed in the :guilabel:`Camera View` window.
|
||||
|
||||
.. Note::
|
||||
At least one channel must be selected (checkbox marked) in the :guilabel:`Channel Settings` window, and all of the parameters (e.g., :guilabel:`Power`) in that row must be populated.
|
||||
|
||||
* Select the :guilabel:`Channels` tab. In the :guilabel:`Stack Acquisition Settings` window in this tab, press the :guilabel:`Set Start Pos/Foc` button. This specifies the starting ``Z`` and ``F`` (e.g., Focus) positions for the stack acquisition.
|
||||
* Select the :guilabel:`Stage Control` tab (:kbd:`ctrl + 3`), move the ``Z`` stage to the desired position (e.g., ``100`` μm), go back to the :guilabel:`Channels` tab (:kbd:`ctrl + 1`), and press the :guilabel:`Set End Pos/Foc` button. This specifies the ending ``Z`` and ``F`` positions for the stack acquisition.
|
||||
* In the :guilabel:`Stack Acquisition Settings` frame, you can now adjust the step size, which determines the number of slices in a z-stack.
|
||||
* In the :guilabel:`Timepoint Settings` window, select :guilabel:`Save Data` by marking the checkbox. If the number of timepoints is set to ``1``, only a single stack will be acquired.
|
||||
* Next to the :guilabel:`Acquire` button on the upper left, change the acquisition mode in the dropdown to "Z-Stack", and press :guilabel:`Acquire` (:kbd:`ctrl + enter`).
|
||||
* A :guilabel:`File Saving Dialog` popup window will appear.
|
||||
* With the exception of :guilabel:`Notes`, all fields must be populated. Any spaces in the fields will be replaced with an underscore.
|
||||
* :guilabel:`Notes` is saved with the metadata, and can be useful for describing the experiment.
|
||||
* :guilabel:`Solvent` is useful for tissue clearing experiments.
|
||||
* :guilabel:`File Type` can be set to :guilabel:`.TIFF`, :guilabel:`OME-TIFF`, :guilabel:`H5`, or :guilabel:`N5`. The latter two options are pyramidal file formats that are best used for large datasets and are immediately compatible with `BigDataViewer <https://imagej.net/plugins/bdv/>`_ and `BigStitcher <https://imagej.net/plugins/bigstitcher/index>`_.
|
||||
* Press :guilabel:`Acquire` to begin the acquisition.
|
||||
* Once complete, the data can be opened using standard image processing software such as `Fiji <https://imagej.net/software/fiji/>`_.
|
||||
|
||||
.. image:: images/save_dialog.png
|
||||
:align: center
|
||||
:alt: File Saving Dialog
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
@@ -0,0 +1,149 @@
|
||||
=====================
|
||||
Software Installation
|
||||
=====================
|
||||
|
||||
.. _software_installation:
|
||||
|
||||
Computer Specifications
|
||||
=======================
|
||||
|
||||
Below are the recommended specifications for **navigate**.
|
||||
|
||||
Operating System Compatibility
|
||||
------------------------------
|
||||
|
||||
.. important::
|
||||
**navigate** is developed for use on Windows-based systems. This is due to the compatibility of device drivers for various microscope hardware components, such as cameras, stages, and data acquisition cards, which are predominantly designed for the Windows environment. The software is only partially tested on MacOS and Linux systems. Users considering the use of **navigate** software on Linux should proceed with caution and be prepared for potential compatibility issues. For optimal performance and compatibility, it is strongly recommended to run **navigate** on a Windows machine.
|
||||
|
||||
.. _computer_considerations:
|
||||
|
||||
Computer Considerations
|
||||
-----------------------
|
||||
|
||||
**navigate** will run on a mid-range laptop with at least 8 GB of RAM and a processor with two cores. Most of its operations are undemanding. Saving data at a reasonable rate, however, will require an SSD. The hardware configuration for an example microscope control machine is shown below.
|
||||
|
||||
.. important::
|
||||
Scientific cameras are capable of rapidly generating large amounts of high-resolution data. As such, the read/write speed of the data storage device is critical for smooth operation of the software. For example, for a standard Hamamatsu camera with a 2048 x 2048 sensor, operating at 16-bit depth and 20 frames per second, the data save rate is approximately ~167 MB/s. While such capabilities are well within the capabilities of modern SSDs, they are beyond the capabilities of most HDDs. Therefore, it is recommended to use a fast SSD for data saving operations.
|
||||
|
||||
.. collapse:: Example Computer Configuration
|
||||
|
||||
- *Base Platform*
|
||||
- **Product Name**: `Colfax SX6300 Workstation <https://www.colfax-intl.com/workstations/sx6300>`_
|
||||
- **Colfax Part #**: CX-116263
|
||||
|
||||
- *Primary and Secondary CPU*
|
||||
- **CPU Model**: Intel Xeon Silver 4215R
|
||||
- **Configuration**: 8 Cores / 16 Threads
|
||||
- **Frequency**: 3.2 GHz
|
||||
- **Cache**: 11 MB
|
||||
- **TDP**: 130W
|
||||
- **Memory Support**: 2400 MHz
|
||||
|
||||
- *Memory*
|
||||
- **Type**: Registered ECC DDR4
|
||||
- **Speed**: 3200 MHz
|
||||
- **Configuration**: 16 GB per socket, 8 sockets per CPU
|
||||
- **Total RAM**: >64 GB (recommended)
|
||||
|
||||
- *Operating System Drive*:
|
||||
- **Type**: M.2 NVMe SSD
|
||||
- **Model**: Micron 7450 Max
|
||||
- **Capacity**: 800 GB
|
||||
- **Endurance**: 3 DWPD
|
||||
|
||||
- *Primary Data Drive*:
|
||||
- **Type**: NVMe SSD
|
||||
- **Model**: Samsung PM9A3
|
||||
- **Capacity**: 7.68 TB
|
||||
- **Interface**: U.2 Gen4
|
||||
|
||||
- *Secondary Data Drive*:
|
||||
- **Type**: SATA HDD
|
||||
- **Model**: Seagate Exos X20
|
||||
- **Capacity**: 20 TB
|
||||
- **Speed**: 7200 RPM
|
||||
- **Cache**: 256 MB
|
||||
- **Interface**: SATA 6.0 Gb/s
|
||||
|
||||
- *Video Card*
|
||||
- **Model**: PNY nVidia T1000
|
||||
- **Memory**: 4 GB
|
||||
- **Interface**: PCI Express
|
||||
|
||||
- *Network Interface*
|
||||
- **Model**: Intel X710-T2L RJ45 Copper
|
||||
- **Type**: Dual Port 10GbE
|
||||
- **Interface**: PCI-E x 8
|
||||
|
||||
.. note::
|
||||
The specifications listed are based on an example system configuration and can be adjusted based on specific needs and availability.
|
||||
|
||||
---------------------
|
||||
|
||||
Quick install
|
||||
=============
|
||||
|
||||
**Setup your Python Environment**
|
||||
|
||||
Head over to the `miniconda website <https://docs.conda.io/en/latest/miniconda.html>`_ and install the appropriate version based on your operating system.
|
||||
|
||||
.. tip::
|
||||
It is also handy to have the `conda cheatsheet <https://docs.conda.io/projects/conda/en/4.6.0/_downloads/52a95608c49671267e40c689e0bc00ca/conda-cheatsheet.pdf>`_ open when first using miniconda to get accustomed to the commands available.
|
||||
|
||||
* Windows: Use the Windows taskbar search to find ``Anaconda Prompt (Miniconda3)``. Given how frequently you will use this, we recommend pinning it to your taskbar. * Linux/Mac: Open a Terminal.
|
||||
|
||||
**Create a Python environment called navigate that uses Python version 3.9.7**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(base) MyComputer ~ $ conda create -n navigate python=3.9.7
|
||||
|
||||
**Activate the navigate environment**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(base) MyComputer ~ $ conda activate navigate
|
||||
|
||||
The active environment is shown in parentheses on the far-left. Originally, we were in the miniconda ``(base)`` environment. After activating the navigate environment, it should now show ``(navigate)``.
|
||||
|
||||
**Install navigate via pip**
|
||||
|
||||
To install the latest stable release of **navigate**, run the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(navigate) MyComputer ~ $ pip install navigate-micro
|
||||
|
||||
To install the bleeding edge version of **navigate**, run the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(navigate) MyComputer ~ $ pip install git+https://github.com/TheDeanLab/navigate.git
|
||||
|
||||
**Run navigate software**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(navigate) MyComputer ~ $ navigate
|
||||
|
||||
.. note::
|
||||
If you are running the software on a computer that is not connected to microscope hardware, you can add the flag ``-sh`` (``--synthetic-hardware``) to launch the program:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
navigate -sh
|
||||
|
||||
Launching **navigate**
|
||||
======================
|
||||
|
||||
Open an ``Anaconda Prompt (Miniconda3)`` and enter the following.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(base) conda activate navigate
|
||||
(navigate) navigate
|
||||
|
||||
.. tip::
|
||||
If you are running Windows, you can create a desktop shortcut to **navigate** by right-clicking the Desktop, navigating to New and then Shortcut and entering ``%windir%\system32\cmd.exe "/c" C:\path\to\miniconda\Scripts\activate.bat navigate && navigate`` into the location text box.
|
||||
|
||||
This provides a convenient executable shortcut to launch the software, which is advantageous for users who are not comfortable with the command line.
|
||||
19
docs/source/01_getting_started/03_i_want_to/03_i_want_to.rst
Normal file
19
docs/source/01_getting_started/03_i_want_to/03_i_want_to.rst
Normal file
@@ -0,0 +1,19 @@
|
||||
============
|
||||
I Want To...
|
||||
============
|
||||
|
||||
This section contains how-to documents organized into three levels of difficulty: beginner, intermediate, and advanced.
|
||||
|
||||
- The beginner how-to is intended for users who have little to no experience with computer programming and simply wish to acquire an image.
|
||||
- The intermediate how-to is intended for users who want to learn how to use the graphical user interface to create their own smart acquisition workflows.
|
||||
- The advanced how-to is intended for users who have experience with computer programming and wish to extend the functionality of **navigate** by adding new devices or writing their own acquisition features.
|
||||
|
||||
Through this tiered approach, we hope to provide a gentle introduction to the software while also reaching the maximum number of users.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
beginner
|
||||
intermediate
|
||||
advanced
|
||||
add_new_device
|
||||
101
docs/source/01_getting_started/03_i_want_to/add_new_device.rst
Normal file
101
docs/source/01_getting_started/03_i_want_to/add_new_device.rst
Normal file
@@ -0,0 +1,101 @@
|
||||
======================================
|
||||
Add a New Hardware Device (Advanced)
|
||||
======================================
|
||||
|
||||
**navigate** includes several standard hardware device types. These include:
|
||||
|
||||
- Cameras
|
||||
- Data Acquisition Cards
|
||||
- Filter Wheels
|
||||
- Galvo Scanners
|
||||
- Lasers
|
||||
- Deformable Mirrors
|
||||
- Remote Focusing Systems
|
||||
- Shutters
|
||||
- Stages
|
||||
- Zoom Devices
|
||||
|
||||
To add a new piece of hardware to one of these device types requires knowledge about the software's device abstraction layer. Here’s a detailed guide to help you integrate a new ``CustomStage`` device into **navigate**. The same principles work for other device types.
|
||||
|
||||
.. note::
|
||||
A strong knowledge of Python and object-oriented programming is required to integrate new hardware devices into **navigate**.
|
||||
|
||||
----------------
|
||||
|
||||
What is the Device Abstraction Layer?
|
||||
-------------------------------------
|
||||
|
||||
To ensure compatibility and extendability, **navigate** utilizes a device abstraction layer, which allows the same commands to be used across different hardware devices. For example, all stages in **navigate** are programmed to include the `stop()` command, which can be used to stop the stage's movement. When someone hits the :guilabel:`Stop Stage` button on the GUI, this action is relayed from the ``Controller`` to the ``Model`` and ultimately the ``CustomStage``, which communicates with the hardware in a device-specific format to stop the stage's movement.
|
||||
|
||||
--------------
|
||||
|
||||
Device Integration Approaches
|
||||
-----------------------------
|
||||
|
||||
There are two primary approaches to integrating new hardware into **navigate**:
|
||||
|
||||
- **Plugin**: If you want to continue to work with an up-to-date version of **navigate**, consider integrating your new hardware device as a plugin. This allows you to pull updates from the main repository without losing your custom hardware integration. It also allows you to integrate non-standard device types. Learn more about the plugin architecture :ref:`here <plugin>`, and how to write a custom plugin :ref:`here <advanced>`.
|
||||
- **Fork**: Alternatively, you can fork the **navigate** repository on GitHub and modify it directly. This is useful for custom, in-house developments. In select circumstances, you can contribute your changes back to the main repository through a pull request. Please contact the **navigate** development team for guidance on this approach.
|
||||
|
||||
--------------
|
||||
|
||||
Device Class Creation
|
||||
---------------------
|
||||
- New hardware devices must have a corresponding device class in navigate. To ensure consistency and reduce redundancy, each device must inherit the appropriate abstract base class. For instance, a ``CustomStage`` device would inherit from ``StageBase``.
|
||||
- Classes should follow CamelCase naming conventions and reflect the device they control (e.g., ``NewportStage`` for a stage from the manufacturer Newport).
|
||||
- Place the new device class within the appropriate device directory, `src/navigate/model/devices/`.
|
||||
- Place related API or hardware documentation within the appropriate manufacturer directory, typically under `src/navigate/model/devices/APIs/`.
|
||||
|
||||
--------------
|
||||
|
||||
Establish Device Communication
|
||||
------------------------------
|
||||
|
||||
- Each device requires a unique method to initialize a connection, which may involve APIs, serial communication, or other protocols. This method should be separate from the device class and is typically located at the beginning of the device file.
|
||||
- For example, a function named `build_custom_stage_connection()` would handle the connection setup for ``CustomStage`` class.
|
||||
- By separating the connection setup from the device class, you can easily interact with the hardware device outside of the larger **navigate** ecosystem, which can be useful for debugging and testing (e.g., within a Jupyter notebook).
|
||||
|
||||
--------------
|
||||
|
||||
Device Class Constructor
|
||||
------------------------
|
||||
|
||||
- The constructor for the device class (`__init__`) should accept parameters for the `microscope_name`, `device_connection`, `configuration_file`, and an optional `device_ID` (useful when multiple instances of the same device are used).
|
||||
- The constructor should load and enforce device settings from the `configuration_file`. For a new stage, this could be defining the axes mapping between **navigate** and the device, `{x:'X', y:'Y', z:'Z'}`.
|
||||
- Ensure the device class uses the connection established by your `build_custom_stage_connection` method.
|
||||
|
||||
--------------
|
||||
|
||||
Device Class Methods
|
||||
--------------------
|
||||
|
||||
- Implement any necessary device-specific methods within your device class.
|
||||
- Essential methods are inherited from the base class (e.g., ``StageBase`` for the ``CustomStage``), but you can override them or add new methods as needed for specialized functionality.
|
||||
|
||||
--------------
|
||||
|
||||
Startup and Configuration
|
||||
-------------------------
|
||||
|
||||
- Utilize or modify methods within `src/navigate/model/device_startup_functions` to configure and start your device upon system initialization.
|
||||
- These functions should handle configuration parsing and the device communication setup.
|
||||
- Implement a retry mechanism, such as `auto_redial`, to handle communication issues robustly, attempting multiple times before failing.
|
||||
|
||||
--------------
|
||||
|
||||
Integration with Microscope Object Configurations
|
||||
-------------------------------------------------
|
||||
|
||||
- Each microscope configuration in **navigate** that uses the new device should receive a reference to the established communication object.
|
||||
- This setup is defined in the *configuration.yaml* and handled within the `device_startup_functions`, ensuring each configuration has access to the necessary hardware.
|
||||
|
||||
--------------
|
||||
|
||||
Testing and Validation
|
||||
----------------------
|
||||
- Thoroughly test the new hardware integration to ensure it functions correctly within navigate, across all intended use cases and configurations.
|
||||
- The naming convention for test files is: `test_` + module name.
|
||||
- Device test files are located in `test\model\devices\`
|
||||
- Device testing utilizes the `pytest` package.
|
||||
|
||||
By following these steps, you can effectively integrate new hardware into the **navigate** platform, enhancing its functionality and ensuring it meets specific experimental needs.
|
||||
445
docs/source/01_getting_started/03_i_want_to/advanced.rst
Normal file
445
docs/source/01_getting_started/03_i_want_to/advanced.rst
Normal file
@@ -0,0 +1,445 @@
|
||||
.. _advanced:
|
||||
|
||||
=======================================
|
||||
Write a Custom Device Plugin (Advanced)
|
||||
=======================================
|
||||
|
||||
**navigate**'s :ref:`plugin system <plugin>` enables users to easily incorporate new devices and integrate new features and acquisition modes. In this guide, we will add a new device type, titled ``CustomDevice``, and a dedicated GUI window to control it. This hypothetical ``CustomDevice`` is capable of moving a certain distance, rotating a specified number of degrees, and applying a force to halt its movement.
|
||||
|
||||
**navigate** plugins are implemented using a Model-View-Controller architecture. The model contains the device-specific code, the view contains the GUI code, and the controller contains the code that communicates between the model and the view.
|
||||
|
||||
-----------------
|
||||
|
||||
Initial Steps
|
||||
-------------
|
||||
|
||||
To ease the addition of a new plugin, we have created a template plugin that can be used as a starting point.
|
||||
|
||||
* Go to `navigate-plugin-template <https://github.com/TheDeanLab/navigate-plugin-template>`_.
|
||||
* In the upper right, click "Use this template" and then "Create a new repository".
|
||||
* In this repository, rename the ``plugin_device`` folder to ``custom_device``.
|
||||
* Rename the file ``plugin_device.py`` to ``custom_device.py``.
|
||||
|
||||
-----------------
|
||||
|
||||
Model Code
|
||||
----------
|
||||
|
||||
Create a new custom device using the following code.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class CustomDevice:
|
||||
""" A Custom Device Class """
|
||||
def __init__(self, device_connection, *args):
|
||||
""" Initialize the Custom Device
|
||||
|
||||
Parameters
|
||||
----------
|
||||
device_connection : object
|
||||
The device connection object
|
||||
args : list
|
||||
The arguments for the device
|
||||
"""
|
||||
self.device_connection = device_connection
|
||||
|
||||
def move(self, step_size=1.0):
|
||||
""" Move the Custom Device
|
||||
|
||||
Parameters
|
||||
----------
|
||||
step_size : float
|
||||
The step size of the movement. Default is 1.0 micron.
|
||||
"""
|
||||
print("*** Custom Device is moving by", step_size)
|
||||
|
||||
def stop(self):
|
||||
""" Stop the Custom Device """
|
||||
print("*** Stopping the Custom Device!")
|
||||
|
||||
def turn(self, angle=0.1):
|
||||
""" Turn the Custom Device
|
||||
|
||||
Parameters
|
||||
----------
|
||||
angle : float
|
||||
The angle of the rotation. Default is 0.1 degree.
|
||||
"""
|
||||
print("*** Custom Device is turning by", angle)
|
||||
|
||||
@property
|
||||
def commands(self):
|
||||
""" Return the commands for the Custom Device
|
||||
|
||||
Returns
|
||||
-------
|
||||
dict
|
||||
The commands for the Custom Device
|
||||
"""
|
||||
return {
|
||||
"move_custom_device": lambda *args: self.move(args[0]),
|
||||
"stop_custom_device": lambda *args: self.stop(),
|
||||
"rotate_custom_device": lambda *args: self.rotate(args[0]),
|
||||
}
|
||||
|
||||
All devices should be accompanied by synthetic versions, which enables the software to run without the hardware connected. Thus, in a manner that is similar to the ``CustomDevice`` class, we edit the code in ``synthetic_device.py``, albeit without any calls to the device itself.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class SyntheticCustomDevice:
|
||||
""" A Synthetic Device Class """
|
||||
def __init__(self, device_connection, *args):
|
||||
""" Initialize the Synthetic Device
|
||||
|
||||
Parameters
|
||||
----------
|
||||
device_connection : object
|
||||
The device connection object
|
||||
args : list
|
||||
The arguments for the device
|
||||
"""
|
||||
pass
|
||||
|
||||
def move(self, step_size=1.0):
|
||||
""" Move the Synthetic Device
|
||||
|
||||
Parameters
|
||||
----------
|
||||
step_size : float
|
||||
The step size of the movement. Default is 1.0 micron.
|
||||
"""
|
||||
print("*** Synthetic Device receive command: move", step_size)
|
||||
|
||||
def stop(self):
|
||||
""" Stop the Synthetic Device """
|
||||
print("*** Synthetic Device receive command: stop")
|
||||
|
||||
def rotate(self, angle=0.1):
|
||||
""" Turn the Synthetic Device
|
||||
|
||||
Parameters
|
||||
----------
|
||||
angle : float
|
||||
The angle of the rotation. Default is 0.1 degree.
|
||||
"""
|
||||
print("*** Synthetic Device receive command: turn", angle)
|
||||
|
||||
@property
|
||||
def commands(self):
|
||||
""" Return the commands for the Synthetic Device.
|
||||
|
||||
Returns
|
||||
-------
|
||||
dict
|
||||
The commands for the Synthetic Device
|
||||
"""
|
||||
return {
|
||||
"move_custom_device": lambda *args: self.move(args[0]),
|
||||
"stop_custom_device": lambda *args: self.stop(),
|
||||
"rotate_custom_device": lambda *args: self.rotate(args[0]),
|
||||
}
|
||||
|
||||
Edit ``device_startup_functions.py`` to tell **navigate** how to connect to and start the ``CustomDevice``. This is the portion of the code that actually makes a connection to the hardware. ``load_device()`` should return an object that can control the hardware.
|
||||
|
||||
**navigate** establishes communication with each device independently, and passes the instance of that device to class that controls it (e.g., in this case, the `CustomDevice` class). This allows **navigate** to be initialized with multiple microscope :ref:`configurations <multiple_microscopes>`, some of which may share devices.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Standard library imports
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
# Third party imports
|
||||
|
||||
# Local application imports
|
||||
from navigate.tools.common_functions import load_module_from_file
|
||||
from navigate.model.device_startup_functions import (
|
||||
auto_redial,
|
||||
device_not_found,
|
||||
DummyDeviceConnection,
|
||||
)
|
||||
|
||||
DEVICE_TYPE_NAME = "custom_device"
|
||||
DEVICE_REF_LIST = ["type"]
|
||||
|
||||
def load_device(configuration, is_synthetic=False):
|
||||
""" Load the Custom Device
|
||||
|
||||
Parameters
|
||||
----------
|
||||
configuration : dict
|
||||
The configuration for the Custom Device
|
||||
is_synthetic : bool
|
||||
Whether the device is synthetic or not. Default is False.
|
||||
|
||||
Returns
|
||||
-------
|
||||
object
|
||||
The Custom Device object
|
||||
"""
|
||||
return DummyDeviceConnection()
|
||||
|
||||
def start_device(microscope_name, device_connection, configuration, is_synthetic=False):
|
||||
""" Start the Custom Device
|
||||
|
||||
Parameters
|
||||
----------
|
||||
microscope_name : str
|
||||
The name of the microscope
|
||||
device_connection : object
|
||||
The device connection object
|
||||
configuration : dict
|
||||
The configuration for the Custom Device
|
||||
is_synthetic : bool
|
||||
Whether the device is synthetic or not. Default is False.
|
||||
|
||||
Returns
|
||||
-------
|
||||
object
|
||||
The Custom Device object
|
||||
"""
|
||||
if is_synthetic:
|
||||
device_type = "synthetic"
|
||||
else:
|
||||
device_type = configuration["configuration"]["microscopes"][microscope_name][
|
||||
"custom_device"
|
||||
]["hardware"]["type"]
|
||||
|
||||
if device_type == "CustomDevice":
|
||||
custom_device = load_module_from_file(
|
||||
"custom_device",
|
||||
os.path.join(Path(__file__).resolve().parent, "custom_device.py"),
|
||||
)
|
||||
return custom_device.CustomDevice(
|
||||
microscope_name, device_connection, configuration
|
||||
)
|
||||
elif device_type == "synthetic":
|
||||
synthetic_device = load_module_from_file(
|
||||
"custom_synthetic_device",
|
||||
os.path.join(Path(__file__).resolve().parent, "synthetic_device.py"),
|
||||
)
|
||||
return synthetic_device.SyntheticDevice(
|
||||
microscope_name, device_connection, configuration
|
||||
)
|
||||
else:
|
||||
device_not_found(microscope_name, device_type)
|
||||
|
||||
-----------------
|
||||
|
||||
View Code
|
||||
---------
|
||||
To add a GUI control window, go to the ``view`` folder, rename ``plugin_name_frame.py`` to ``custom_device_frame.py``, and edit the code as follows.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Standard library imports
|
||||
import tkinter as tk
|
||||
from tkinter import ttk
|
||||
|
||||
# Third party imports
|
||||
|
||||
# Local application imports
|
||||
from navigate.view.custom_widgets.LabelInputWidgetFactory import LabelInput
|
||||
|
||||
class CustomDeviceFrame(ttk.Frame):
|
||||
""" The Custom Device Frame """
|
||||
def __init__(self, root, *args, **kwargs):
|
||||
""" Initialize the Custom Device Frame
|
||||
|
||||
Parameters
|
||||
----------
|
||||
root : object
|
||||
The root Tk object
|
||||
args : list
|
||||
The arguments for the Custom Device Frame
|
||||
kwargs : dict
|
||||
The keyword arguments for the Custom Device Frame
|
||||
"""
|
||||
ttk.Frame.__init__(self, root, *args, **kwargs)
|
||||
|
||||
# Formatting
|
||||
tk.Grid.columnconfigure(self, "all", weight=1)
|
||||
tk.Grid.rowconfigure(self, "all", weight=1)
|
||||
|
||||
# Dictionary for widgets and buttons
|
||||
#: dict: Dictionary of the widgets in the frame
|
||||
self.inputs = {}
|
||||
|
||||
self.inputs["step_size"] = LabelInput(
|
||||
parent=self,
|
||||
label="Step Size",
|
||||
label_args={"padding": (0, 0, 10, 0)},
|
||||
input_class=ttk.Entry,
|
||||
input_var=tk.DoubleVar(),
|
||||
)
|
||||
self.inputs["step_size"].grid(row=0, column=0, sticky="N", padx=6)
|
||||
self.inputs["step_size"].label.grid(sticky="N")
|
||||
self.inputs["angle"] = LabelInput(
|
||||
parent=self,
|
||||
label="Angle",
|
||||
label_args={"padding": (0, 5, 25, 0)},
|
||||
input_class=ttk.Entry,
|
||||
input_var=tk.DoubleVar(),
|
||||
)
|
||||
self.inputs["angle"].grid(row=1, column=0, sticky="N", padx=6)
|
||||
self.inputs["angle"].label.grid(sticky="N")
|
||||
|
||||
self.buttons = {}
|
||||
self.buttons["move"] = ttk.Button(self, text="MOVE")
|
||||
self.buttons["rotate"] = ttk.Button(self, text="ROTATE")
|
||||
self.buttons["stop"] = ttk.Button(self, text="STOP")
|
||||
self.buttons["move"].grid(row=0, column=1, sticky="N", padx=6)
|
||||
self.buttons["rotate"].grid(row=1, column=1, sticky="N", padx=6)
|
||||
self.buttons["stop"].grid(row=2, column=1, sticky="N", padx=6)
|
||||
|
||||
# Getters
|
||||
def get_variables(self):
|
||||
variables = {}
|
||||
for key, widget in self.inputs.items():
|
||||
variables[key] = widget.get_variable()
|
||||
return variables
|
||||
|
||||
def get_widgets(self):
|
||||
return self.inputs
|
||||
|
||||
.. tip::
|
||||
|
||||
**navigate** comes equipped with a large number of validated widgets, which prevent users from entering invalid values that can crash the program or result in undesirable outcomes. It is highly recommended that you use these, which include the following:
|
||||
|
||||
* The ``LabelInput`` widget conveniently combines a label and an input widget into a single object. It is used to create the ``step_size`` and ``angle`` widgets in the code above.
|
||||
* The ``LabelInput`` widget can accept multiple types of ``input_class`` objects, which can include standard tkinter widgets (e.g., spinbox, entry, etc.) or custom widgets. In this example, we use the ``ttk.Entry`` widget.
|
||||
* Other examples of validated widgets include a ``ValidatedSpinbox``, ``ValidatedEntry``, ``ValidatedCombobox``, and ``ValidatedMixin``.
|
||||
* Please see the :any:`navigate.view.custom_widgets` module for more details.
|
||||
|
||||
-----------------
|
||||
|
||||
Controller Code
|
||||
----------------
|
||||
Now, let's build a controller. Open the ``controller`` folder, rename ``plugin_name_controller.py`` to ``custom_device_controller.py``, and edit the code as follows.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Standard library imports
|
||||
import tkinter as tk
|
||||
|
||||
# Third party imports
|
||||
|
||||
# Local application imports
|
||||
from navigate.controller.sub_controllers.gui_controller import GUIController
|
||||
|
||||
class CustomDeviceController(GUIController):
|
||||
""" The Custom Device Controller """
|
||||
def __init__(self, view, parent_controller=None):
|
||||
""" Initialize the Custom Device Controller
|
||||
|
||||
Parameters
|
||||
----------
|
||||
view : object
|
||||
The Custom Device View object
|
||||
parent_controller : object
|
||||
The parent (e.g., main) controller object
|
||||
"""
|
||||
super().__init__(view, parent_controller)
|
||||
|
||||
# Get the variables and buttons from the view
|
||||
self.variables = self.view.get_variables()
|
||||
self.buttons = self.view.buttons
|
||||
|
||||
# Set the trace commands for the variables associated with the widgets in the View.
|
||||
self.buttons["move"].configure(command=self.move_device)
|
||||
self.buttons["rotate"].configure(command=self.rotate_device)
|
||||
self.buttons["stop"].configure(command=self.stop_device)
|
||||
|
||||
def move_device(self, *args):
|
||||
""" Listen to the move button and move the Custom Device upon clicking.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
args : list
|
||||
The arguments for the move_device function. Should be included as the tkinter event
|
||||
is passed to this function.
|
||||
"""
|
||||
self.parent_controller.execute(
|
||||
"move_custom_device", self.variables["step_size"].get()
|
||||
)
|
||||
|
||||
def rotate_device(self, *args):
|
||||
""" Listen to the rotate button and rotate the Custom Device upon clicking.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
args : list
|
||||
The arguments for the rotate_device function. Should be included as the tkinter event
|
||||
is passed to this function.
|
||||
"""
|
||||
self.parent_controller.execute(
|
||||
"rotate_custom_device", self.variables["angle"].get()
|
||||
)
|
||||
|
||||
def stop_device(self, *args):
|
||||
""" Listen to the stop button and stop the Custom Device upon clicking.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
args : list
|
||||
The arguments for the stop_device function. Should be included as the tkinter event
|
||||
is passed to this function.
|
||||
"""
|
||||
self.parent_controller.execute("stop_custom_device")
|
||||
|
||||
In each case above, the sub-controller for the ``custom-device`` establishes what actions should take place once a button in the view is clicked. In this case, the methods ``move_device``, ``rotate_device``, and ``stop_device``. This triggers a sequence of events:
|
||||
|
||||
* The sub-controller passes the command to the parent controller, which is the main controller for the software.
|
||||
* The parent controller passes the command to the model, which is operating in its own sub-process, using an event queue. This eliminates the need for the controller to know anything about the model and prevents race conditions.
|
||||
* The model then executes command, and any updates to the controller from the model are relayed using another event queue.
|
||||
|
||||
-----------------
|
||||
|
||||
Plugin Configuration
|
||||
--------------------
|
||||
Next, update the ``plugin_config.yml`` file as follows:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
name: Custom Device
|
||||
view: Popup
|
||||
|
||||
Remove the folder ``./model/features``, the file ``feature_list.py``, and the file ``plugin_acquisition_mode.py``. The plugin folder structure is as follows.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
custom_device/
|
||||
├── controller/
|
||||
│ └── custom_device_controller.py
|
||||
|
|
||||
├── model/
|
||||
| └── devices/
|
||||
│ └── custom_device/
|
||||
│ ├── device_startup_functions.py
|
||||
│ ├── custom_device.py
|
||||
│ └── synthetic_device.py
|
||||
├── view/
|
||||
| └── custom_device_frame.py
|
||||
│
|
||||
└── plugin_config.yml
|
||||
|
||||
Install the plugin using one of two methods:
|
||||
* Install a plugin by putting the whole plugin folder directly into ``navigate/plugins/``. In this example, put ``custom_device`` folder and all its contents into ``navigate/plugins``.
|
||||
* Alternatively, install this plugin through the menu :menuselection:`Plugins --> Install Plugin` by selecting the plugin folder.
|
||||
|
||||
The plugin is ready to use. For this plugin, you can now specify a CustomDevice in the ``configuration.yaml`` as follows.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_1:
|
||||
daq:
|
||||
hardware:
|
||||
name: daq
|
||||
type: NI
|
||||
...
|
||||
custom_device:
|
||||
hardware:
|
||||
type: CustomDevice
|
||||
|
||||
The ``custom_device`` will be loaded when **navigate** is launched, and it can be controlled through the GUI.
|
||||
207
docs/source/01_getting_started/03_i_want_to/beginner.rst
Normal file
207
docs/source/01_getting_started/03_i_want_to/beginner.rst
Normal file
@@ -0,0 +1,207 @@
|
||||
.. _beginner:
|
||||
|
||||
===========================
|
||||
Acquire an Image (Beginner)
|
||||
===========================
|
||||
|
||||
This guide will describe how to acquire a single image and a z-stack using the **navigate** software package.
|
||||
|
||||
Launching the Software Package
|
||||
==============================
|
||||
|
||||
Open Anaconda Prompt
|
||||
--------------------
|
||||
|
||||
To start, you need to open the Anaconda Prompt. Follow these steps:
|
||||
1. On Windows, click on the Start menu.
|
||||
2. Type ``Anaconda Prompt`` into the search bar.
|
||||
3. Click on the Anaconda Prompt application to open it.
|
||||
|
||||
.. note:: Ensure that Anaconda and **navigate** are already installed on your system. If not, please refer to our :ref:`Quick_Start_Guide` for more information.
|
||||
|
||||
Activate Conda Environment
|
||||
--------------------------
|
||||
|
||||
Once the Anaconda Prompt is open, activate the desired conda environment. By default, the command prompt will open the base environment (as shown in parentheses). To activate **navigate** environment, type the following command into the Anaconda command window and press :kbd:`Enter`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(base) conda activate navigate
|
||||
|
||||
Launch the Software Package
|
||||
---------------------------
|
||||
|
||||
After activating the environment, **navigate** should now be shown in parentheses. After you have already :ref:`configured <setup_microscope>` **navigate**, you can launch it by typing the following command into the Anaconda command window:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(navigate) navigate
|
||||
|
||||
The **navigate** software package will launch and the main window will appear.
|
||||
|
||||
.. image:: images/beginner/open-navigate.png
|
||||
:alt: Opening **navigate**.
|
||||
|
||||
Configure the Channel Settings
|
||||
==============================
|
||||
|
||||
* Select the :guilabel:`Channels` tab, which is located on the upper left of the main window.
|
||||
* Under the :guilabel:`Channel Settings` section, select the number of channels needed for imaging. For each channel selected, you will need to configure the acquisition settings:
|
||||
|
||||
.. image:: images/beginner/channel-selector.png
|
||||
:alt: Channel settings in the **navigate** software package.
|
||||
|
||||
* Select the appropriate :guilabel:`Laser` from the dropdown menu.
|
||||
* Select the appropriate :guilabel:`Power` for the laser.
|
||||
* Select the appropriate emission :guilabel:`Filter` from the dropdown menu.
|
||||
|
||||
.. image:: images/beginner/channel-selector-filter.png
|
||||
:alt: Changing the emission filter in **navigate**.
|
||||
|
||||
* Specify the camera :guilabel:`Exp. Time (ms)`. A good default value is ``100`` or ``200`` ms.
|
||||
* Specify the :guilabel:`Interval` to be ``1.0``. While this feature is not currently implemented, future releases will allow users to image different channels at different time intervals.
|
||||
* Specify the :guilabel:`Defocus` to be ``0``. This feature allows you to adjust for chromatic aberrations that result in focal shifts between each imaging channel.
|
||||
|
||||
Configure the Camera Settings
|
||||
=============================
|
||||
|
||||
* Select the :guilabel:`Camera Settings` tab.
|
||||
* For standard imaging applications, select :guilabel:`Normal` in the :guilabel:`Sensor Modes` dropdown menu within the :guilabel:`Camera Modes` section.
|
||||
* If you are using the rolling shutter, select :guilabel:`Light-Sheet` and specify its :guilabel:`Readout Direction` and :guilabel:`Number of Pixels`.
|
||||
|
||||
.. note:: For more information on how to configure the rolling shutter for ASLM operation, please refer to :ref:`ASLM <setup_aslm>`.
|
||||
|
||||
.. image:: images/beginner/sensor-mode.png
|
||||
:alt: Changing the camera sensor mode in **navigate**.
|
||||
|
||||
* Choose the size of your camera's field of view.
|
||||
* Specify the :guilabel:`Region of Interest Settings` by entering the appropriate :guilabel:`Number of Pixels` for both the :guilabel:`Width` and :guilabel:`Height` values. Alternatively, one can select from one of several default values in the :guilabel:`Default FOVs` section.
|
||||
|
||||
.. note:: The :guilabel:`FOV Dimensions (microns)` is automatically calculated based on the :guilabel:`Number of Pixels` and the `pixel_size` as specified in the `zoom` section of your ``configuration.yaml`` file.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
zoom:
|
||||
pixel_size:
|
||||
20x: 0.325 # magnification, and pixel size in microns
|
||||
|
||||
.. image:: images/beginner/ROI-definition.png
|
||||
:alt: Changing the camera region of interest in **navigate**.
|
||||
|
||||
.. note:: If multiple channels are selected, each channel will be acquired with the same camera :guilabel:`Sensor Mode`, :guilabel:`Readout Direction`, and :guilabel:`Region of Interest Settings`.
|
||||
|
||||
Acquire in a Continuous Scan Mode
|
||||
=================================
|
||||
|
||||
* Select "Continuous Scan" in the dropdown next to the :guilabel:`Acquire` button in the :ref:`acquisition bar <ui_acquisition_bar>`.
|
||||
|
||||
.. image:: images/beginner/continuous-scan-dropdown.png
|
||||
:alt: Selecting the continuous scan mode in **navigate**.
|
||||
|
||||
* Press :guilabel:`Acquire`. This will launch a live acquisition mode.
|
||||
|
||||
.. note:: If multiple channels are selected, each channel will be imaged sequentially. The order of imaging is determined by the order of the channels in the :guilabel:`Channel Settings` section of the :guilabel:`Channels` tab, and will proceed from the top to the bottom of this channel list.
|
||||
|
||||
.. image:: images/beginner/continuous-scan-acquire.png
|
||||
:alt: Launching the continuous scan mode in **navigate**.
|
||||
|
||||
* Move the stage to identify the location of the sample.
|
||||
* Select the :guilabel:`Stage Control` tab, and use the graphical user interface to move the stage. This includes buttons for moving the stage in ``X``, ``Y``, ``Z``, ``F``, and ``Theta`` directions.
|
||||
* The step size for each axis can be adjusted with the spinbox next to each button.
|
||||
* For stages loaded in a synthetic mode, buttons will be disabled.
|
||||
* Absolute positions can be entered in the text boxes next to each button.
|
||||
* Check :ref:`configuration settings <configuration_file>` for more information.
|
||||
* Alternatively, if available, use the manufacturer-provided joystick to position the sample.
|
||||
|
||||
.. note:: The axes for a light-sheet microscope vary in the literature. Here, we define the ``Y`` axis as the direction of the light-sheet propagation, the ``Z`` axis as the direction of the detection objective, and the ``X`` axis as the direction perpendicular to the light-sheet and detection objective axes. The ``F`` axis typically controls the position of the detection objective along the detection axis. The ``Theta`` axis typically controls the rotation of the sample.
|
||||
|
||||
.. warning:: One should always be careful when moving the stage. If the stage is moved too quickly, the sample and/or microscope may be damaged. We strongly recommend that you implement stage limits in your configuration file. Please refer to the :ref:`configuration settings <configuration_file>` for more information.
|
||||
|
||||
.. image:: images/beginner/stage-movement-panel.png
|
||||
:alt: Moving the stage in **navigate**.
|
||||
|
||||
* Press the :guilabel:`Stop` button in the acquisition bar to stop acquisition.
|
||||
|
||||
.. image:: images/beginner/stop-acquisition.png
|
||||
:alt: Stopping the continuous scan mode in **navigate**.
|
||||
|
||||
Acquiring a Single Image
|
||||
=========================
|
||||
|
||||
* Check the :guilabel:`Save Data` box in the :guilabel:`Timepoint Settings` section under the :guilabel:`Channels` tab to save the acquired images. Check this box before acquiring data.
|
||||
|
||||
.. image:: images/beginner/save-data.png
|
||||
:alt: Saving data in **navigate**.
|
||||
|
||||
* Select :guilabel:`Single Acquisition` from the dropdown next to the :guilabel:`Acquire` button.
|
||||
|
||||
.. image:: images/beginner/single-acquisition-dropdown.png
|
||||
:alt: Selecting the single acquisition mode in **navigate**.
|
||||
|
||||
* Press :guilabel:`Acquire` to open the :guilabel:`File Saving Dialog` interface. Enter the sample parameters, notes, location to save file, and filetype in the :guilabel:`File Saving Dialog` that pops up.
|
||||
|
||||
.. image:: images/beginner/save-dialog-box.png
|
||||
:alt: Saving data in **navigate**.
|
||||
|
||||
* Press :guilabel:`Acquire Data` to initiate acquisition. Acquisition will automatically stop once the image is acquired.
|
||||
|
||||
.. note:: Each acquisition will be saved in a separate folder (e.g., ``Cell01``, ``Cell02``, ...) within the directory specified in the :guilabel:`File Saving Dialog` interface. Data will not be overwritten between acquisitions.
|
||||
|
||||
.. image:: images/beginner/save-dialog-box-acquire.png
|
||||
:alt: Saving data in **navigate**.
|
||||
|
||||
.. _i_want_to_z_stack:
|
||||
|
||||
Acquiring a Z-Stack
|
||||
===================
|
||||
|
||||
* Using the :guilabel:`Stage Control`, go to the desired z-position in the sample. Make sure that the sample is in focus. To use the autofocus feature, please refer to the :ref:`Autofocus Settings <ui_autofocus>`.
|
||||
|
||||
.. image:: images/beginner/stage-control-start-pos-zstack.png
|
||||
:alt: Adjusting the stage position in **navigate**.
|
||||
|
||||
* Under the :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (μm)` press :guilabel:`Set Start Pos`.
|
||||
|
||||
.. image:: images/beginner/press-start-pos.png
|
||||
:alt: Adjusting the stage position in **navigate**.
|
||||
|
||||
* Using the :guilabel:`Stage Control`, go to a different z-position within the sample. Again, make sure that the sample is in focus.
|
||||
|
||||
.. image:: images/beginner/stage-control-end-pos-zstack.png
|
||||
:alt: Adjusting the stage position in **navigate**.
|
||||
|
||||
* Under the :guilabel:`Channels` tab, in :guilabel:`Stack Acquisition Settings (μm)` press :guilabel:`Set End Pos`.
|
||||
|
||||
.. image:: images/beginner/press-end-pos.png
|
||||
:alt: Adjusting the stage position in **navigate**.
|
||||
|
||||
.. note:: If there is a shift in ``F`` between the start and stop positions, the ``F`` axis will be ramped synchronously with ``Z`` to maintain focus. Check :ref:`configuration settings <configuration_file>` for more information to determine if focus is enabled in hardware. Refer to :ref:`Imaging on a mesoSPIM BT <acquire_mesospimbt>` section for an example of how to acquire a z-stack with a focus ramp.
|
||||
|
||||
* Type the desired step size in microns in the :guilabel:`Step Size` dialog box in :guilabel:`Stack Acquisition Settings (μm)`.
|
||||
|
||||
.. note:: The minimum step size, and increment between steps, are graphical user interface defaults that are specified in the ``configuration.yaml`` file. More information can :ref:`configuration settings <configuration_file>`.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
gui:
|
||||
stack_acquisition:
|
||||
step_size:
|
||||
min: 0.100
|
||||
max: 1000
|
||||
step: 0.1
|
||||
|
||||
.. image:: images/beginner/define-step-size.png
|
||||
|
||||
* If using multiple channels for imaging, select either :guilabel:`Per Z` or :guilabel:`Per Stack` under :guilabel:`Laser Cycling Settings` in the :guilabel:`Stack Acquisition Settings (μm)` section under the :guilabel:`Channels` tab.
|
||||
|
||||
* :guilabel:`Per Z` acquires all channels before moving the stage to a new position.
|
||||
* :guilabel:`Per Stack` acquires all images in a stack acquisition for a single channel before moving the stage back to the start position and restarting acquisition for the subsequent channel until all channels are imaged.
|
||||
|
||||
.. image:: images/beginner/laser-cycling-settings.png
|
||||
|
||||
* Select :guilabel:`Z-Stack` from the dropdown next to the :guilabel:`Acquire` button. Press :guilabel:`Acquire`.
|
||||
|
||||
.. image:: images/beginner/z-stack-acquisition.png
|
||||
|
||||
* Enter the sample parameters, notes, location to save file, and filetype in the :guilabel:`File Saving Dialog` that pops up.
|
||||
* Press :guilabel:`Acquire Data` to initiate acquisition. Acquisition will automatically stop once the image series is acquired.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 3.3 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 361 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 357 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 349 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 347 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 335 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.8 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.9 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 353 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.8 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.1 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.8 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 328 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 326 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 336 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 336 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 327 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 249 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 324 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 340 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 342 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.0 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 292 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 294 KiB |
92
docs/source/01_getting_started/03_i_want_to/intermediate.rst
Normal file
92
docs/source/01_getting_started/03_i_want_to/intermediate.rst
Normal file
@@ -0,0 +1,92 @@
|
||||
.. _intermediate:
|
||||
|
||||
================================================
|
||||
Write A Smart Acquisition Routine (Intermediate)
|
||||
================================================
|
||||
|
||||
**navigate**'s :ref:`feature container <user_guide_features>` enables us to write acquisition routines on the fly by chaining existing :ref:`features <user_guide_features>` into lists. Please see :ref:`Currently Implemented Features <currently_implemented_features>` for a complete list of features. Users can build additional features within :ref:`plugins <plugin>`.
|
||||
|
||||
In this guide, we will use existing features to write a routine that scans through an imaging chamber and takes z-stacks only where it finds the sample.
|
||||
|
||||
Suppose there are two positions listed in the :ref:`multiposition table <ui_multiposition>`, one containing tissue and one empty, as shown below.
|
||||
|
||||
.. image:: images/intermediate/multiposition_tissue.png
|
||||
|
||||
.. image:: images/intermediate/multiposition_empty.png
|
||||
|
||||
We will build a feature that scans both positions, but only takes a z-stack at the one containing tissue. To access the GUI feature list editor, navigate to :menuselection:`Features --> Add Customized Feature List`. A window titled "Add New Feature List" will pop up. Enter ``TestFeature`` in the text box at the top of the popup. Enter
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
[{"name": PrepareNextChannel}]
|
||||
|
||||
in the text box at the bottom of this popup and press :guilabel:`Preview`. The window should appear as below.
|
||||
|
||||
.. image:: images/feature_gui_1.png
|
||||
|
||||
The square brackets ``[]`` create a sequence of events to run in the feature container. The ``{}`` braces contain features. In this case, we have a single feature, ``PrepareNextChannel``, which will set up the next color channel for acquisition. The complete sequence (as it stands) will take an image in the first :ref:`selected color channel <ui_channel_settings>`.
|
||||
|
||||
We can build much of the rest of our desired acquisition in the GUI. Right-click on the ``PrepareNextChannel`` tile to reveal the editing menu.
|
||||
|
||||
.. image:: images/feature_gui_2.png
|
||||
|
||||
Select :guilabel:`Insert After`. A second copy of ``PrepareNextChannel`` will appear in the feature list.
|
||||
|
||||
.. image:: images/feature_gui_3.png
|
||||
|
||||
Left-click on this second tile to reveal a popup that allows us to select which feature we want to use in this tile.
|
||||
|
||||
.. image:: images/feature_gui_4.png
|
||||
|
||||
Select ``MoveToNextPositionInMultiPositionTable`` and then close the popup. Your feature list editing window should now appear as below.
|
||||
|
||||
.. image:: images/feature_gui_5.png
|
||||
|
||||
Our feature now takes one image of the first selected color channel at each position in the multiposition table.
|
||||
|
||||
Now, right-click ``MoveToNextPositionInMultiPositionTable`` and press :guilabel:`Insert After`. Click the new tile and change it to ``DetectTissueInStackAndReturn``. There are three options associated with this feature.
|
||||
|
||||
.. image:: images/feature_gui_6.png
|
||||
|
||||
* :guilabel:`planes` indicates how many planes of the z-stack this feature should check for tissue.
|
||||
* :guilabel:`percentage` indicates what percent of the total image must contain tissue for this feature to return ``true`` that tissue was detected. 1 indicates that the entire image contains tissue, 0.5 indicates that half of the image contains tissue, and so on.
|
||||
* :guilabel:`detect_func` is one of the tissue detection functions in :doc:`remove_empty_tiles <../../../05_reference/_autosummary/navigate.model.features.remove_empty_tiles>`. If this is set to ``None``, it defaults to ``detect_tissue()``, which states that tissue is present if signal is above the Otsu threshold of the stack of images acquired.
|
||||
|
||||
In this example, if any plane meets the desired threshold, the feature will return ``true`` and it will be acquired. If no plane meets the desired threshold, the feature will return ``false``.
|
||||
|
||||
Now, right-click ``DetectTissueInStackAndReturn`` and press :guilabel:`Insert After`. Click the new tile and change it to ``LoopByCount``.
|
||||
|
||||
.. image:: images/feature_gui_7.png
|
||||
|
||||
We want to iterate over all of the positions in the multi-position table, so we will set ``steps`` to ``experiment.MicroscopeState.multiposition_count``.
|
||||
|
||||
Notice that the acquisition protocol does not appear to loop, but rather still moves in a sequence. This is because all of the tiles are still in the sequence brackets ``[]``. We can now enclose the section of the protocol we want to loop in parentheses ``()`` and press :guilabel:`Preview` to see the update.
|
||||
|
||||
.. image:: images/feature_gui_8.png
|
||||
|
||||
Now, we set up one color channel to image (``PrepareNextChannel``), and then within this channel visit every position in the multiposition table, and detect if there is tissue. However, we do not yet make any decisions of what to do if tissue is found. To do this, we will convert ``DetectTissueInStackAndReturn`` into a decision node.
|
||||
|
||||
To do this, we add ``true`` and ``false`` options within the feature braces:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{"name": DetectTissueInStackAndReturn,
|
||||
"args": (1, 0.5, None),
|
||||
"true": [{"name": ZStackAcquisition,"args": (False,False,"z-stack",),}],
|
||||
"false": "continue",}
|
||||
|
||||
Our ``true`` argument tells the software what to do if tissue is detected. In this case, we take a z-stack at the positions where tissue is found. The ``false`` argument tells the software how to proceed if no tissue is found. In this case, the ``continue`` option tells the software to keep moving through the loop to the next position in the multi-position table. Press :guilabel:`Preview` to see the update.
|
||||
|
||||
.. image:: images/feature_gui_9.png
|
||||
|
||||
``DetectTissueInStackAndReturn`` now has a red border, indicating it is a decision node. Click on it to access the decision node GUI.
|
||||
|
||||
.. image:: images/feature_gui_10.png
|
||||
|
||||
This contains the same settings for ``DetectTissueInStackAndReturn`` we saw before, but now also features GUI editing windows for the results of ``true`` and ``false`` decisions arising from this node.
|
||||
|
||||
Close the node window and press :guilabel:`Add` in the "Add New Feature List" window. This feature is now available under :menuselection:`Features --> TestFeature` and can be run in "Customized" :ref:`acquisition mode <ui_acquisition_bar>`.
|
||||
|
||||
Select "Customized" acquisition mode, select :menuselection:`Features --> TestFeature`, and press :guilabel:`Acquire`. For the positions shown at the start of this guide, the software will go to the first position in the multi-position table, decide there is tissue present, and take a z-stack. It will then go to the second position in the multi-position table, find there is no tissue, and decide not to take a z-stack. It will then exit the loop as no more positions are available in the multi-position table.
|
||||
|
||||
Now you can use this feature or build another smart acquisition routine suited to your microscope's needs.
|
||||
288
docs/source/02_user_guide/01_supported_hardware/camera.rst
Normal file
288
docs/source/02_user_guide/01_supported_hardware/camera.rst
Normal file
@@ -0,0 +1,288 @@
|
||||
.. _camera_configuration:
|
||||
|
||||
=======
|
||||
Cameras
|
||||
=======
|
||||
|
||||
The software supports camera-based acquisition. It can run both normal and rolling
|
||||
shutter modes of contemporary scientific CMOS cameras.
|
||||
|
||||
-------------------
|
||||
|
||||
Daheng
|
||||
------
|
||||
|
||||
MER2-1220-32U3C
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
More information on the Daheng MER2-1220-32U3C camera can be found
|
||||
`here <https://en.daheng-imaging.com/show-106-1997-1.html>`_.
|
||||
|
||||
.. warning::
|
||||
|
||||
This camera class has not been internally tested by our team. Users are advised to exercise caution when using it.
|
||||
|
||||
.. note::
|
||||
|
||||
This camera requires Daheng Imaging's proprietary Python SDK and must be installed manually. Download the SDK `here <https://www.daheng-imaging.com/>`_. Locate 'gxipy' under: Development/Samples/Python/gxipy and then install it using pip. Also, this camera class uses the Line0 trigger input by default for external triggering.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
camera:
|
||||
hardware:
|
||||
type: daheng.Daheng
|
||||
serial_number: "123456"
|
||||
defect_correct_mode: 2.0
|
||||
delay: 1.0 #ms
|
||||
settle_down: 0.1 #ms
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
|
||||
|
|
||||
|
||||
|
||||
Hamamatsu
|
||||
---------
|
||||
|
||||
.. note::
|
||||
|
||||
**navigate** has been tested with the following versions of the Hamamatsu's
|
||||
drivers:
|
||||
|
||||
- DCAM API: 20.7.641, 21.7.4321, 22.9.6509, 22.11.4321, 23.12.6736
|
||||
- Camera Firmware: 2.21B, 2.53.A, 3.20.A, 4.30.B,
|
||||
- Active Silicon CoaXpress: 1.10, 1.13, 1.21.
|
||||
|
||||
|
||||
-----------------
|
||||
|
||||
ORCA-Flash4.0 V3
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- :ref:`Install Directions <dcam>`.
|
||||
- `ORCA-Flash 4.0 v3 Manual <https://www.hamamatsu
|
||||
.com/us/en/product/cameras/cmos-cameras/C13440-20CU.html>`_.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
camera:
|
||||
hardware:
|
||||
type: HamamatsuOrca
|
||||
serial_number: 111
|
||||
camera_connection:
|
||||
defect_correct_mode: 2.0
|
||||
delay: 1.0 #ms
|
||||
settle_down: 0.1 #ms
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
|
||||
ORCA-Fusion
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- :ref:`Install Directions <dcam>`.
|
||||
- `ORCA-Fusion Manual <https://www.hamamatsu
|
||||
.com/jp/en/product/cameras/cmos-cameras/C15440-20UP.html>`_.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
camera:
|
||||
hardware:
|
||||
type: HamamatsuOrcaFusion
|
||||
serial_number: 111
|
||||
camera_connection:
|
||||
defect_correct_mode: 2.0
|
||||
delay: 1.0 #ms
|
||||
settle_down: 0.1 #ms
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
|
||||
ORCA-Lightning
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- :ref:`Install Directions <dcam>`.
|
||||
- `ORCA-Lightning Manual <https://camera.hamamatsu.com/content/dam/hamamatsu-photonics/sites/static/sys/en/manual/C14120-20P_IM_En.pdf>`_.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
camera:
|
||||
hardware:
|
||||
type: HamamatsuOrcaLightning
|
||||
serial_number: 111
|
||||
camera_connection:
|
||||
defect_correct_mode: 2.0
|
||||
delay: 1.0 #ms
|
||||
settle_down: 0.1 #ms
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
|
||||
ORCA-Fire
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
- :ref:`Install Directions <dcam>`.
|
||||
- `ORCA-Fire Manual <https://www.hamamatsu.com/us/en/product/cameras/cmos-cameras/C16240-20UP.html>`_.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
camera:
|
||||
hardware:
|
||||
type: HamamatsuOrcaFire
|
||||
serial_number: 111
|
||||
camera_connection:
|
||||
defect_correct_mode: 2.0
|
||||
delay: 1.0 #ms
|
||||
settle_down: 0.1 #ms
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
Photometrics
|
||||
------------
|
||||
|
||||
- :ref:`Install Directions <pvcam>`.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
**navigate** has been tested with the following versions of the Photometric's drivers:
|
||||
- PVCAM: 3.9.13
|
||||
|
||||
-----------------
|
||||
|
||||
Iris 15
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
camera:
|
||||
hardware:
|
||||
type: Photometrics
|
||||
serial_number: 111
|
||||
camera_connection: PMPCIECam00
|
||||
defect_correct_mode: 2.0
|
||||
delay: 1.0 #ms
|
||||
settle_down: 0.1 #ms
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
|
|
||||
|
||||
-----------------
|
||||
|
||||
Ximea
|
||||
--------------------------------
|
||||
|
||||
|
||||
MU196MR-ON
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
camera:
|
||||
hardware:
|
||||
type: ximea.MU196XR
|
||||
serial_number: 111
|
||||
defect_correct_mode: 2.0
|
||||
delay: 1.0 #ms
|
||||
settle_down: 0.1 #ms
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
gain: 1
|
||||
pixel_size_in_microns: 1.4
|
||||
readout_port: 0
|
||||
readout_speed: 1.0
|
||||
settle_down: 0.0
|
||||
speed_table_index: 0
|
||||
supported_readout_directions: ['Top-to-Bottom']
|
||||
supported_sensor_modes: ['Normal']
|
||||
supported_trigger_sources: ['External']
|
||||
trigger_active: 1.0
|
||||
trigger_mode: 1.0
|
||||
trigger_polarity: 2.0
|
||||
trigger_source: 2.0
|
||||
x_pixels: 5112
|
||||
x_pixels_min: 192
|
||||
x_pixels_step: 24
|
||||
y_pixels: 3840
|
||||
y_pixels_min: 2
|
||||
y_pixels_step: 2
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
.. _synthetic_camera:
|
||||
|
||||
Synthetic Camera
|
||||
----------------
|
||||
|
||||
The synthetic camera simulates noise images from an sCMOS camera. If no camera is present,
|
||||
the synthetic camera class must be used.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
camera:
|
||||
hardware:
|
||||
type: synthetic
|
||||
serial_number: 111
|
||||
camera_connection:
|
||||
defect_correct_mode: 2.0
|
||||
delay: 1.0 #ms
|
||||
settle_down: 0.1 #ms
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
|
||||
|
|
||||
221
docs/source/02_user_guide/01_supported_hardware/daq.rst
Normal file
221
docs/source/02_user_guide/01_supported_hardware/daq.rst
Normal file
@@ -0,0 +1,221 @@
|
||||
======================
|
||||
Data Acquisition Cards
|
||||
======================
|
||||
|
||||
Data acquisition cards deliver and receive analog and digital signals.
|
||||
To acquire an image, the software calculates all of the analog and digital waveforms and
|
||||
queues these waveforms on the data acquisition card. Upon receipt of a trigger (either from the software itself,
|
||||
or an external piece of hardware), all
|
||||
of the analog and digital signals are delivered in parallel. This provides
|
||||
deterministic behavior on a per-frame basis, which is necessary for proper acquisition of light-sheet data.
|
||||
It does not however provide us with deterministic behavior between image
|
||||
frames, and some jitter in timing is anticipated.
|
||||
|
||||
------------------
|
||||
|
||||
.. _hardware_ni:
|
||||
|
||||
National Instruments
|
||||
--------------------
|
||||
In principle, most NI-based data acquisition cards should work with the software, so long
|
||||
as there are a sufficient number of analog and digital ports, and the sampling rate (typically 100 kHz)
|
||||
is high enough per port.
|
||||
|
||||
Prior to installing the card within
|
||||
the computer, first install the `NI-DAQmx drivers <https://www.ni.com/en/support/downloads/drivers/download.ni-daq-mx.html>`_.
|
||||
Once installed, connect the PCIe or PXIe-based device to the computer. A functioning
|
||||
system should be recognized by the operating system, and visible in the Windows Device
|
||||
Manager as a **NI Data Acquisition Device**.
|
||||
|
||||
.. note::
|
||||
|
||||
**navigate** has been tested with the following versions of the NI-DAQmx drivers:
|
||||
|
||||
- 22.5.0
|
||||
- 22.8.0
|
||||
- 23.3.0
|
||||
- 23.8.0
|
||||
|
||||
|
||||
.. tip::
|
||||
|
||||
**The most important aspect is to wire up the breakout box properly.**
|
||||
|
||||
To find the device pin outs for your NI-based data acquisition card, open NI
|
||||
MAX, find the card under devices, right-click and select "device pinouts".
|
||||
|
||||
Important: Should you use the SCB-68A breakout box, do not look at the pinout on
|
||||
the back of the cover. This is misleading. You must look at the device pinouts in
|
||||
NI MAX.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
For NI-based cards, ``port0/line1`` is the equivalent of ``P0.1``.
|
||||
There are multiple pins for each PFIO, including source, out, gate, etc. You must
|
||||
use the out terminal.
|
||||
|
||||
|
||||
- Identify the device name in NI MAX, and change it if you would like. Common names are
|
||||
``Dev1``, ``Dev2``, etc. This name must correspond with the pinouts provided in the
|
||||
configuration file.
|
||||
|
||||
- Connect the ``master_trigger_out_line`` to the ``trigger_source`` with a direct wire,
|
||||
commonly ``PXI6259/port0/line1`` and ``/PXI6259/PFI0``. In this example, the default name
|
||||
for the device (e.g., ``Dev1``) has been changed to ``PXI6259``.
|
||||
|
||||
- Connect the ``camera_trigger_out_line`` to the ``Ext. Trigger`` on the camera using
|
||||
the ``CTR0Out`` pin.
|
||||
|
||||
- These values must precisely match those in the configuration file. An example is provided below:
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
daq:
|
||||
hardware:
|
||||
type: NI
|
||||
sample_rate: 10000
|
||||
master_trigger_out_line: PXI6259/port0/line1
|
||||
camera_trigger_out_line: /PXI6259/ctr0
|
||||
trigger_source: /PXI6259/PFIO
|
||||
laser_port_switcher: PXI6733/port0/line0
|
||||
laser_switch_state: False
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
|
||||
**navigate** has been tested with the following NI-based cards:
|
||||
|
||||
PCIe/PXIe-6738
|
||||
"""""""""""""""
|
||||
|
||||
The PCIe-6738 can only create one software-timed analog task for every four channels.
|
||||
As such, the lasers much be attached to analog output ports outside of the banks (shown as solid lines in the device pinout) used
|
||||
by the galvo/remote focus units. For example, if you use ao0, ao2, and ao6 for the
|
||||
remote focus, galvo, and galvo stage, the lasers should be connected to ao8, ao9, and
|
||||
ao10. In such a configuration, they will not compete with the other analog output
|
||||
ports. Since only one task will be created created on the ao8, ao9, ao10 bank at a time
|
||||
(only one laser is on at a time), only one laser can be on at a time. If we wanted to
|
||||
turn lasers on simultaneously, we could distribute the lasers across independent banks
|
||||
(e.g. ao8, ao14, ao19).
|
||||
|
||||
.. collapse:: Device Pinout
|
||||
|
||||
.. image:: images/6738_pinout.png
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
|
||||
PCIe/PXIe-6259
|
||||
"""""""""""""""
|
||||
|
||||
The PXI-6259 can create one software-timed analog task per channel. As such, the
|
||||
galvo/remote focus/lasers can be attached to any of the analog output ports. The 6259 has
|
||||
two connectors, and it is important to make sure that the analog and digital ports that you
|
||||
are using are connected to the correct connector. For example, if you are using ``ao0``, this is
|
||||
located on ``connector 0``.
|
||||
|
||||
.. collapse:: Device Pinout
|
||||
|
||||
.. image:: images/6259_pinout.png
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
|
||||
PCIe/PXIe-6723
|
||||
"""""""""""""""
|
||||
|
||||
The PXI-6723 can also create one software-timed analog task per channel. As such, the analog
|
||||
outputs can be wired up as is most convenient.
|
||||
|
||||
.. collapse:: Device Pinout
|
||||
|
||||
.. image:: images/6723_pinout.png
|
||||
|
||||
------------------
|
||||
|
||||
Applied Scientific Instrumentation
|
||||
----------------------------------
|
||||
|
||||
Tiger Controller
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. warning::
|
||||
|
||||
USE OF THE TIGER CONTROLLER AS A DATA ACQUISITION CARD IS STILL IN DEVELOPMENT.
|
||||
|
||||
|
||||
The ASI `Tiger Controller <https://www.asiimaging.com/controllers/tiger-controller/>`_ is
|
||||
a multi-purpose controller for ASI stages, filter wheels, and dichroic sliders.
|
||||
It can also control lasers, shutters, remote focusing devices, and galvanometers. More info
|
||||
for these devices can be found on their respective documention pages.
|
||||
|
||||
Remote focus device, galvanometer, and analog laser control is done by the `TGGALVO <https://asiimaging.com/docs/tggalvo>`_ control card.
|
||||
Shutter and digital laser control is done by the `TGPLC <https://asiimaging.com/docs/tiger_programmable_logic_card>`_ control card.
|
||||
TGPLC output 1 delivers the camera trigger signal (equivalent to camera_trigger_out_line for the NI Card).
|
||||
|
||||
We communicate with Tiger Controllers via a serial port. It is recommended that you
|
||||
first establish communication with the device using `ASI provided software <https://asiimaging.com/docs/products/tiger>`_.
|
||||
If not, simply install the `USB driver <https://www.asiimaging.com/support/downloads/usb-support-on-ms-2000-wk-controllers/>`_
|
||||
to communicate with the Tiger Controller
|
||||
|
||||
.. note::
|
||||
|
||||
**navigate** has been tested with the following versions of the ASI's Tiger
|
||||
Controller software:
|
||||
|
||||
- Tiger Controller 2.2.0.
|
||||
|
||||
.. note::
|
||||
Some users have reported intermittent connection issues at random intervals when
|
||||
used with Coherent OBIS lasers. These issues, and how to address them, are discussed
|
||||
in the :ref:`communication challenges <obis_tiger_connection>` section.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
daq:
|
||||
hardware:
|
||||
type: ASI
|
||||
port: COM4
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
Synthetic Data Acquisition Card
|
||||
-------------------------------
|
||||
If no data acquisition card is present, one must configure the software to use a synthetic
|
||||
data acquisition card.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
daq:
|
||||
hardware:
|
||||
type: NI
|
||||
sample_rate: 10000
|
||||
master_trigger_out_line: PXI6259/port0/line1
|
||||
camera_trigger_out_line: /PXI6259/ctr0
|
||||
trigger_source: /PXI6259/PFIO
|
||||
laser_port_switcher: PXI6733/port0/line0
|
||||
laser_switch_state: False
|
||||
|
||||
|
|
||||
19
docs/source/02_user_guide/01_supported_hardware/dcam_api.rst
Normal file
19
docs/source/02_user_guide/01_supported_hardware/dcam_api.rst
Normal file
@@ -0,0 +1,19 @@
|
||||
.. _dcam:
|
||||
|
||||
=================
|
||||
Hamamatsu Drivers
|
||||
=================
|
||||
|
||||
* Insert the USB that came with the camera into the computer and install HCImageLive. Alternatively,
|
||||
download DCAM-API. The software can be found `here <https://dcam-api.com>`_.
|
||||
* When prompted with the DCAM-API Setup
|
||||
|
||||
* If you are going to use the Frame Grabber, install the Active Silicon Firebird drivers.
|
||||
* Select ... next to the tools button, and install DCAM tools onto the computer.
|
||||
|
||||
* Shutdown the computer and install the Hamamatsu frame grabber into an appropriate
|
||||
PCIe-x16 slot on the motherboard.
|
||||
* Turn on the computer and the camera, and confirm that it is functioning properly in
|
||||
HCImageLive or Excap (one of the DCAM tools installed).
|
||||
* Connect the `camera_trigger_out_line` to the External Trigger of the Hamamatsu
|
||||
Camera. Commonly, this is done with a counter port, e.g., ``/PXI6259/ctr0``
|
||||
@@ -0,0 +1,59 @@
|
||||
|
||||
==================
|
||||
Deformable Mirrors
|
||||
==================
|
||||
|
||||
Deformable mirrors enable correction for aberrations in the image that arise from
|
||||
sample or system-specific distortions in the optical wavefront.
|
||||
|
||||
------------
|
||||
|
||||
Imagine Optic
|
||||
-------------
|
||||
|
||||
Mirao 52E
|
||||
~~~~~~~~~
|
||||
|
||||
We currently have support for a
|
||||
`Mirao 52E <https://www.imagine-optic.com/products/deformable-mirror-mirao-52e/>`_.
|
||||
The ``flat_path`` provides a path to a system correction ``.wcs`` file, an Imagine
|
||||
Optic proprietary file that stores actuator voltages and corresponding Zernike
|
||||
coefficients.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
mirror:
|
||||
hardware:
|
||||
type: ImagineOpticsMirror
|
||||
flat_path: D:\WaveKitX64\MirrorFiles\BeadsCoverslip_20231212.wcs
|
||||
n_modes: 32
|
||||
|
||||
|
||||
|
|
||||
|
||||
-------------
|
||||
|
||||
Synthetic Mirror
|
||||
----------------
|
||||
It is not necessary to have a deformable mirror to run the software. If no deformable
|
||||
mirror is present, but one wants to evaluate the deformable mirror correction features,
|
||||
one must configure the software to use a synthetic deformable mirror.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
mirror:
|
||||
hardware:
|
||||
type: SyntheticMirror
|
||||
flat_path: D:\WaveKitX64\MirrorFiles\BeadsCoverslip_20231212.wcs
|
||||
n_modes: 32
|
||||
|
||||
|
||||
|
|
||||
67
docs/source/02_user_guide/01_supported_hardware/dichroic.rst
Normal file
67
docs/source/02_user_guide/01_supported_hardware/dichroic.rst
Normal file
@@ -0,0 +1,67 @@
|
||||
================
|
||||
Dichroic Turrets
|
||||
================
|
||||
|
||||
Dichroics can be used to reflect the excitation light towards the camera, while
|
||||
permitting the emission light that is captured by the objective to be transmitted
|
||||
to the camera. Alternatively, they can be placed in the detection path to separate
|
||||
different emission wavelengths and to direct it to the appropriate camera.
|
||||
|
||||
Currently, **navigate** incorporates a dichroic turret as a filter wheel, which enables
|
||||
you to add as many different dichroic turrets as you would like.
|
||||
|
||||
.. note::
|
||||
|
||||
The `name` parameter under `hardware` is optional. If not provided, the name of the
|
||||
device will be default to Filter 0, Filter 1, ... Filter N in the GUI. However, if
|
||||
is is provided, then the GUI will automatically use the name provided as a label.
|
||||
|
||||
ASI
|
||||
---
|
||||
|
||||
C60-CUBE-SLDR
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The `C60-CUBE-SLDR <https://www.asiimaging.com/products/modular-infinity-microscope-mim/modular-infinity-microscope-mim/cubes/>`_
|
||||
is a motorized dichroic slider that can be controlled by the ASI Tiger Controller.
|
||||
The example below shows the configuration file with one dichroic turret, and one
|
||||
filter wheel. The same communication instance is used for both the stage and filter
|
||||
wheel. It holds a maximum of 4 dichroics.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
-
|
||||
filter_wheel:
|
||||
hardware:
|
||||
type: ASI
|
||||
name: Filter Wheel 1
|
||||
wheel_number: 1
|
||||
port: COM1
|
||||
baudrate: 115200
|
||||
filter_wheel_delay: 0.03
|
||||
available_filters:
|
||||
Empty-Alignment: 0
|
||||
GFP: 1
|
||||
RFP: 2
|
||||
Far-Red: 3
|
||||
-
|
||||
filter_wheel:
|
||||
hardware:
|
||||
type: ASICubeSlider
|
||||
name: Dichroic Turret 1
|
||||
wheel_number: 2
|
||||
port: COM1
|
||||
baudrate: 115200
|
||||
filter_wheel_delay: 0.25
|
||||
available_filters:
|
||||
510LP: 0
|
||||
560LP: 1
|
||||
600LP: 2
|
||||
660LP: 3
|
||||
|
||||
|
|
||||
218
docs/source/02_user_guide/01_supported_hardware/filter_wheel.rst
Normal file
218
docs/source/02_user_guide/01_supported_hardware/filter_wheel.rst
Normal file
@@ -0,0 +1,218 @@
|
||||
=============
|
||||
Filter Wheels
|
||||
=============
|
||||
|
||||
Filter wheels can be used in both illumination and detection paths. The user
|
||||
is expected to change the names of available filters to match what is in the
|
||||
filter wheel or turret. If more than one filter wheel is present, the user
|
||||
should add additional filter_wheel instances in the ``configuration.yaml``
|
||||
file as follows:
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
-
|
||||
filter_wheel:
|
||||
hardware:
|
||||
name: Lower Filter Wheel
|
||||
type: SutterFilterWheel
|
||||
wheel_number: 1
|
||||
port: COM1
|
||||
baudrate: 9600
|
||||
filter_wheel_delay: 0.03
|
||||
available_filters:
|
||||
Empty-Alignment: 0
|
||||
GFP: 1
|
||||
RFP: 2
|
||||
Far-Red: 3
|
||||
-
|
||||
filter_wheel:
|
||||
hardware:
|
||||
name: Upper Filter Wheel
|
||||
type: SutterFilterWheel
|
||||
wheel_number: 2
|
||||
port: COM1
|
||||
baudrate: 9600
|
||||
filter_wheel_delay: 0.03
|
||||
available_filters:
|
||||
CFP: 0
|
||||
YFP: 1
|
||||
RFP: 2
|
||||
Far-Red: 3
|
||||
|
||||
|
|
||||
|
||||
.. note::
|
||||
|
||||
The `name` parameter under `hardware` is optional. If not provided, the name of the
|
||||
device will be default to Filter 0, Filter 1, ... Filter N in the GUI. However, if
|
||||
is is provided, then the GUI will automatically use the name provided as a label.
|
||||
|
||||
-----------
|
||||
|
||||
ASI
|
||||
---
|
||||
|
||||
FW-1000
|
||||
~~~~~~~
|
||||
|
||||
The ASI `filter wheel <https://www.asiimaging
|
||||
.com/illumination-control/fw-1000-high-speed-filter-wheel/>`_ is controlled by the
|
||||
ASI Tiger Controller. Thus, you should provide the same ``comport`` entry as you did
|
||||
for the stage. A single communication instance is used for both the stage and filter wheel.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
-
|
||||
filter_wheel:
|
||||
hardware:
|
||||
type: ASI
|
||||
wheel_number: 1
|
||||
port: COM1
|
||||
baudrate: 115200
|
||||
filter_wheel_delay: 0.03
|
||||
available_filters:
|
||||
Empty-Alignment: 0
|
||||
GFP: 1
|
||||
RFP: 2
|
||||
Far-Red: 3
|
||||
|
||||
|
|
||||
|
||||
--------------
|
||||
|
||||
Sutter Instruments
|
||||
------------------
|
||||
|
||||
Lambda 10-3 & 10-B
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We typically communicate with Sutter Lambda 10-3 controllers via serial port. It is
|
||||
recommended that you first establish communication with the device using manufacturer
|
||||
provided software. Alternatively, one can use MicroManager. For some filter wheel types,
|
||||
the filter_wheel_delay is calculated according to the size of the move and model of the
|
||||
filter wheel. For other filter wheel types, the filter_wheel_delay is a fixed value, which is specified as
|
||||
the ``filter_wheel_delay`` entry in the configuration file. The number of filter wheels
|
||||
connected to the controller is specified as ``wheel_number`` in the configuration file.
|
||||
Currently, both wheels are moved to the same position, but future implementations will
|
||||
enable control of both filter wheels independently.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
-
|
||||
filter_wheel:
|
||||
hardware:
|
||||
type: SutterFilterWheel
|
||||
wheel_number: 1
|
||||
port: COM1
|
||||
baudrate: 9600
|
||||
filter_wheel_delay: 0.03
|
||||
available_filters:
|
||||
Empty-Alignment: 0
|
||||
GFP: 1
|
||||
RFP: 2
|
||||
Far-Red: 3
|
||||
|
||||
|
|
||||
|
||||
-------------
|
||||
|
||||
LUDL Electronic Products
|
||||
------------------------
|
||||
|
||||
MAC6000
|
||||
~~~~~~~
|
||||
|
||||
.. note::
|
||||
Currently, the software only supports a single filter wheel for the MAC6000
|
||||
device. Should additional filter wheels be necessary, please reach out to the
|
||||
**navigate** team by placing a feature request on GitHub.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
-
|
||||
filter_wheel:
|
||||
hardware:
|
||||
type: LUDLFilterWheel
|
||||
wheel_number: 1
|
||||
port: COM1
|
||||
baudrate: 9600
|
||||
filter_wheel_delay: 0.03
|
||||
available_filters:
|
||||
Empty-Alignment: 0
|
||||
GFP: 1
|
||||
RFP: 2
|
||||
Far-Red: 3
|
||||
|
||||
|
|
||||
|
||||
-------------
|
||||
|
||||
National Instruments
|
||||
--------------------
|
||||
|
||||
Some manufacturers provide filter wheels that are controlled by analog or digital signals. Here, each digital signal corresponds to a filter position. The user must specify the number of filters in the filter wheel and the digital signal that corresponds to each filter position.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
filter_wheel:
|
||||
hardware:
|
||||
type: NI
|
||||
wheel_number: 1
|
||||
filter_wheel_delay: 0.050
|
||||
available_filters:
|
||||
473nm: Dev2/port0/line1
|
||||
561nm: Dev2/port0/line3
|
||||
638nm: Dev2/port0/line5
|
||||
Empty: Dev2/port0/line7
|
||||
|
||||
|
|
||||
|
||||
-------------
|
||||
|
||||
Synthetic Filter Wheel
|
||||
----------------------
|
||||
If no filter wheel is present, one must configure the software to use a synthetic
|
||||
filter wheel.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
filter_wheel:
|
||||
hardware:
|
||||
type: synthetic
|
||||
wheel_number: 1
|
||||
port: COM1
|
||||
baudrate: 9600
|
||||
filter_wheel_delay: 0.03
|
||||
available_filters:
|
||||
Empty-Alignment: 0
|
||||
GFP: 1
|
||||
RFP: 2
|
||||
Far-Red: 3
|
||||
|
||||
|
|
||||
118
docs/source/02_user_guide/01_supported_hardware/galvo.rst
Normal file
118
docs/source/02_user_guide/01_supported_hardware/galvo.rst
Normal file
@@ -0,0 +1,118 @@
|
||||
=============
|
||||
Galvanometers
|
||||
=============
|
||||
|
||||
Galvo mirrors are used for fast scanning, shadow reduction, and occasionally as stages
|
||||
(see :ref:`Analog-Controlled Galvo/Piezo <galvo_stage>`).
|
||||
|
||||
------------
|
||||
|
||||
National Instruments
|
||||
--------------------
|
||||
|
||||
Multiple types of galvanometers have been used, including Cambridge Technologies/Novanta, Thorlabs, and ScannerMAX. Each of these devices are externally controlled via analog signals delivered from an NI-based data acquisition card.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
galvo:
|
||||
-
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6259/ao1
|
||||
min: -1.0
|
||||
max: 1.0
|
||||
waveform: sawtooth
|
||||
phase: 0
|
||||
-
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6259/ao1
|
||||
min: -1.0
|
||||
max: 1.0
|
||||
waveform: square
|
||||
phase: 0
|
||||
|
||||
|
|
||||
|
||||
------------
|
||||
|
||||
Applied Scientific Instrumentation
|
||||
----------------------------------
|
||||
|
||||
In principle, this hardware type can support any analog-controlled galvanometer,
|
||||
including those from Cambridge Technologies/Novanta, Thorlabs, and ScannerMAX.
|
||||
Each of these devices are externally controlled via analog signals delivered from the ASI Tiger Controller (`TG-1000 <https://asiimaging.com/docs/products/tiger>`_).
|
||||
|
||||
Galvanometers can take two types of analog waveforms: sawtooth and sine.
|
||||
The sawtooth waveform is a periodic analog waveform. There are three duty cycle values
|
||||
accepted, 0, 50, and 100. If the duty cycle is 0, the waveform is a falling sawtooth
|
||||
waveform. If the duty cycle is 50, then it is a triangle wave. If the duty cycle is 100,
|
||||
the waveform is a rising sawtooth waveform. The duty cycle will be rounded to the nearest acceptable value.
|
||||
|
||||
The ASI Tiger Controller has a few limitations for the analog signals.
|
||||
The period value will be rounded to the nearest whole number of milliseconds,
|
||||
and for the triangle wave, the period will be rounded to the nearest even number.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
galvo:
|
||||
-
|
||||
hardware:
|
||||
type: ASI
|
||||
axis: A
|
||||
min: 0
|
||||
max: 1.0
|
||||
waveform: sine
|
||||
phase: 0
|
||||
-
|
||||
hardware:
|
||||
type: ASI
|
||||
axis: B
|
||||
min: -5.0
|
||||
max: 5.0
|
||||
waveform: sawtooth
|
||||
phase: 1.57
|
||||
|
||||
|
|
||||
|
||||
-----------------
|
||||
|
||||
Synthetic Galvo
|
||||
---------------
|
||||
If no galvo is present, one must configure the software to use a synthetic
|
||||
galvo.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
galvo:
|
||||
-
|
||||
hardware:
|
||||
type: synthetic
|
||||
channel: PXI6259/ao1
|
||||
min: -1.0
|
||||
max: 1.0
|
||||
waveform: sawtooth
|
||||
phase: 0
|
||||
-
|
||||
hardware:
|
||||
type: synthetic
|
||||
channel: PXI6259/ao1
|
||||
min: -1.0
|
||||
max: 1.0
|
||||
waveform: square
|
||||
phase: 0
|
||||
|
||||
|
|
||||
@@ -0,0 +1,26 @@
|
||||
====================
|
||||
Supported Hardware
|
||||
====================
|
||||
|
||||
.. _hardware_overview:
|
||||
|
||||
**navigate** provides access to a growing list of hardware devices. Information on how to configure each of these devices, including supported firmware, is provided here.
|
||||
|
||||
Additional devices are available by installing the **navigate-mmcore-plugin**. To learn more, please visit the **navigate-mmcore-plugin**
|
||||
`documentation <https://thedeanlab.github.io/navigate-mmcore-plugin/>`_.
|
||||
|
||||
.. toctree::
|
||||
:caption: Devices
|
||||
:maxdepth: 4
|
||||
|
||||
daq.rst
|
||||
camera.rst
|
||||
remote_focus.rst
|
||||
stage.rst
|
||||
filter_wheel.rst
|
||||
dichroic.rst
|
||||
galvo.rst
|
||||
laser.rst
|
||||
shutter.rst
|
||||
zoom.rst
|
||||
deformable_mirror.rst
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
151
docs/source/02_user_guide/01_supported_hardware/laser.rst
Normal file
151
docs/source/02_user_guide/01_supported_hardware/laser.rst
Normal file
@@ -0,0 +1,151 @@
|
||||
======
|
||||
Lasers
|
||||
======
|
||||
We currently support laser control via voltage signals. In the near-future, we will consider implementing laser control via serial communication for power control, but digital modulation will still be controlled via voltage signals. The ``onoff`` entry is for digital modulation. The ``power`` entry is for analog modulation.
|
||||
|
||||
---------------------
|
||||
|
||||
Applied Scientific Instrumentation
|
||||
----------------------------------
|
||||
|
||||
The Tiger Controller (`TG-1000 <https://asiimaging.com/docs/products/tiger>`_) from ASI can also be used to perform analog, digital, and mixed modulation of lasers.
|
||||
Digital modulation is controlled with a `TGPLC <https://asiimaging.com/docs/tiger_programmable_logic_card>`_
|
||||
or `TGGALVO <https://asiimaging.com/docs/tggalvo>`_ control cards, while analog modulation is controlled with a TGGALVO control card.
|
||||
TGPLC output 1 is reserved for the camera trigger.
|
||||
|
||||
--------------------------------
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
lasers:
|
||||
-
|
||||
wavelength: 488
|
||||
onoff:
|
||||
hardware:
|
||||
type: ASI
|
||||
axis: 2
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
power:
|
||||
hardware:
|
||||
type: ASI
|
||||
axis: A
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
-
|
||||
wavelength: 561
|
||||
onoff:
|
||||
hardware:
|
||||
type: ASI
|
||||
axis: 3
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
power:
|
||||
hardware:
|
||||
type: ASI
|
||||
axis: B
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
|
||||
|
||||
-------------------
|
||||
|
||||
|
||||
National Instruments
|
||||
--------------------
|
||||
|
||||
Most lasers are controlled externally via mixed analog and digital modulation. Thus, a NI data acquisition card may be used to control the laser. In general, an analog output can be used to control both the digital and analog modulation of the laser, whereas a digital output can only be used to control the digital modulation of the laser.
|
||||
|
||||
.. note::
|
||||
Omicron LightHUB Ultra laser launches include both Coherent- and LuxX lasers, which vary according to wavelength. LuxX lasers should be operated in an ACC operating mode with the analog modulation option enabled. The Coherent Obis lasers should be set in the mixed modulation mode.
|
||||
|
||||
.. note::
|
||||
Coherent Obis lasers should be set in the mixed modulation mode. It is not uncommon for the slew rate from the data acquisition card to be insufficient to drive the modulation of the laser if the laser is set to an analog modulation mode.
|
||||
|
||||
.. note::
|
||||
Users have reported intermittent connection issues at random intervals arising from USB-based communication instance with Coherent Obis controllers. Specifically, these errors were observed as a conflict over COM port assignments between the Coherent OBIS laser and the ASI Tiger controller. These issues are discussed in depth in the :ref:`communication challenges <obis_tiger_connection>` section.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
lasers:
|
||||
-
|
||||
wavelength: 488
|
||||
onoff:
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6733/port0/line2
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
power:
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6733/ao0
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
-
|
||||
wavelength: 561
|
||||
onoff:
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6733/port0/line3
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
power:
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6733/ao1
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
|
|
||||
|
||||
-------------------
|
||||
|
||||
Synthetic Lasers
|
||||
--------------------------------
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
lasers:
|
||||
-
|
||||
wavelength: 488
|
||||
onoff:
|
||||
hardware:
|
||||
type: synthetic
|
||||
channel: PXI6733/port0/line2
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
power:
|
||||
hardware:
|
||||
type: synthetic
|
||||
channel: PXI6733/ao0
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
-
|
||||
wavelength: 561
|
||||
onoff:
|
||||
hardware:
|
||||
type: synthetic
|
||||
channel: PXI6733/port0/line3
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
power:
|
||||
hardware:
|
||||
type: synthetic
|
||||
channel: PXI6733/ao1
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
|
|
||||
22
docs/source/02_user_guide/01_supported_hardware/pvcam.rst
Normal file
22
docs/source/02_user_guide/01_supported_hardware/pvcam.rst
Normal file
@@ -0,0 +1,22 @@
|
||||
.. _pvcam:
|
||||
|
||||
====================
|
||||
Photometrics Drivers
|
||||
====================
|
||||
|
||||
* Download the `PVCAM software <https://www.teledynevisionsolutions.com/company/about-teledyne-vision-solutions/teledyne-photometrics/>`_ from Photometrics. The PVCAM SDK is also available form this location. You will likely have to register and agree to Photometrics terms.
|
||||
* Perform the Full Installation of the PVCAM software.
|
||||
* Should a "Base Device" still show up as unknown in the Windows Device Manager, you may need to install the `Broadcom PCI/PCIe Software Development Kit <https://www.broadcom.com/products/pcie-switches-retimers/software-dev-kits>`_
|
||||
* Upon successful installation, one should be able to acquire images with the manufacturer-provided PVCamTest software.
|
||||
|
||||
.. Note::
|
||||
|
||||
A static version of the Photometrics API is provided with this software. It is located in in srcs/model/devices/APIs/photo_metrics/PyVCAM-master. To install this API, go to this folder in the command line and from within your **navigate** environment, run ``python setup.py install``.
|
||||
|
||||
.. Note::
|
||||
|
||||
The most up-to-date version of PVCAM can be found on `GitHub <https://github.com/Photometrics/PyVCAM>`_.
|
||||
|
||||
|
||||
|
||||
|
||||
168
docs/source/02_user_guide/01_supported_hardware/remote_focus.rst
Normal file
168
docs/source/02_user_guide/01_supported_hardware/remote_focus.rst
Normal file
@@ -0,0 +1,168 @@
|
||||
=======================
|
||||
Remote Focusing Devices
|
||||
=======================
|
||||
|
||||
Voice coils, also known as linear actuators, play a crucial role in implementing
|
||||
aberration-free remote focusing in **navigate**. These electromagnetic actuators are
|
||||
used to control the axial position of the light-sheet and the sample relative to the
|
||||
microscope objective lens. By precisely adjusting the axial position, the focal plane
|
||||
can be shifted without moving the objective lens, thus enabling remote focusing.
|
||||
|
||||
Focus tunable lenses serve as an alternative to voice coils owing to their simple
|
||||
operation and high bandwidth. Tunable lenses axially scan
|
||||
a beam by introducing defocus into the optical train. Nonetheless, they do not provide the
|
||||
higher-order correction provided by voice coils in an aberration-free remote focusing system.
|
||||
|
||||
--------------
|
||||
|
||||
Equipment Solutions
|
||||
-------------------
|
||||
|
||||
LFA-2010
|
||||
~~~~~~~~
|
||||
|
||||
Configuration of the device can be variable. Many voice coils we have received require
|
||||
establishing serial communication with the device to explicitly place it in an analog
|
||||
control mode. In this case, the comport must be specified properly in the configuration
|
||||
file.
|
||||
|
||||
More recently, Equipment Solutions has begun delivering devices that
|
||||
automatically initialize in an analog control mode, and thus no longer need the
|
||||
serial communication to be established. For these devices, we recommend using the analog
|
||||
control mode described in the next section.
|
||||
|
||||
The `LFA-2010 Linear Focus Actuator <https://www.equipsolutions.com/products/linear-focus-actuators/lfa-2010-linear-focus-actuator/>`_
|
||||
is controlled with a `SCA814 Linear Servo Controller <https://www.equipsolutions.com/products/linear-servo-controllers/sca814-linear-servo-controller/>`_,
|
||||
which accepts a +/- 2.5 Volt analog signal. The minimum and maximum voltages can be set
|
||||
in the configuration file to prevent the device from receiving a voltage outside of its
|
||||
operating range.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
remote_focus_device:
|
||||
hardware:
|
||||
type: EquipmentSolutions
|
||||
channel: PXI6269/ao3
|
||||
min: -5.0
|
||||
max: 5.0
|
||||
port: COM2
|
||||
baudrate: 9600
|
||||
|
||||
|
|
||||
|
||||
-------------
|
||||
|
||||
National Instruments
|
||||
--------------------
|
||||
|
||||
In principle, this hardware type can support any analog-controlled voice coil or tunable lens. The `BLINK <https://www.thorlabs.com/thorproduct.cfm?partnumber=BLINK>`_ and the `Optotune Focus Tunable Lens <https://www.optotune.com/tunable-lenses>`_ are controlled with an analog signal from the DAQ.
|
||||
|
||||
-----------------
|
||||
|
||||
Thorlabs BLINK
|
||||
~~~~~~~~~~~~~~
|
||||
The BLINK is a voice coil that is
|
||||
pneumatically actuated voice coil. It is recommended that you specify the min and max
|
||||
voltages that are compatible with your device to prevent the device from receiving a
|
||||
voltage outside of its operating range.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
remote_focus_device:
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6269/ao3
|
||||
min: -5.0
|
||||
max: 5.0
|
||||
port: COM2
|
||||
baudrate: 9600
|
||||
|
||||
|
|
||||
|
||||
-----------------
|
||||
|
||||
Optotune Focus Tunable Lens
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
remote_focus_device:
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6269/ao3
|
||||
min: -5.0
|
||||
max: 5.0
|
||||
port: COM2
|
||||
baudrate: 9600
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
Applied Scientific Instrumentation
|
||||
----------------------------------
|
||||
|
||||
In principle, this hardware type can support any analog-controlled voice coil or tunable lens.
|
||||
The `BLINK <https://www.thorlabs.com/thorproduct.cfm?partnumber=BLINK>`_ and the `Optotune Focus Tunable Lens <https://www.optotune.com/tunable-lenses>`_
|
||||
can be controlled with an analog signal from the ASI Tiger Controller (`TG-1000 <https://asiimaging.com/docs/products/tiger>`_).
|
||||
|
||||
The ASI Tiger Controller has a few limitations for the analog signals.
|
||||
The remote focus waveform is a periodic ramp waveform with a delay period between each ramp.
|
||||
The ramp lasts for the exposure time, falls very quickly and rests until the next exposure time.
|
||||
Fall time is not configurable so there is no 'gentle' fall with this hardware.
|
||||
|
||||
The ramp waveform must last a whole number of milliseconds. If exposure time is not a whole number,
|
||||
the ramp time will be rounded to the nearest whole number.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
remote_focus_device:
|
||||
hardware:
|
||||
type: ASI
|
||||
axis: A
|
||||
min: 0
|
||||
max: 5
|
||||
port: COM4
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
Synthetic Remote Focus Device
|
||||
-----------------------------
|
||||
If no remote focus device is present, one must configure the software to use a synthetic
|
||||
remote focus device.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
remote_focus_device:
|
||||
hardware:
|
||||
type: synthetic
|
||||
channel: PXI6269/ao3
|
||||
min: -5.0
|
||||
max: 5.0
|
||||
port: COM2
|
||||
baudrate: 9600
|
||||
|
||||
|
|
||||
98
docs/source/02_user_guide/01_supported_hardware/shutter.rst
Normal file
98
docs/source/02_user_guide/01_supported_hardware/shutter.rst
Normal file
@@ -0,0 +1,98 @@
|
||||
========
|
||||
Shutters
|
||||
========
|
||||
|
||||
When only controlled with analog modulation, many laser sources do not
|
||||
reduce their emitted intensity to 0 watts. In such cases, residual illumination subjects
|
||||
the specimen to unnecessary irradiation between image acquisitions. Shutters overcome
|
||||
this by completely blocking the laser, albeit on a much slower timescale than direct
|
||||
modulation of the laser. With **navigate**, shutters automatically open at the start
|
||||
of acquisition and close upon finish.
|
||||
|
||||
Most shutters are controlled via a digital voltage. When the voltage is high (e.g., >
|
||||
2.5 V), the shutter is open, and when the voltage is low (e.g., < 2.5 V), the shutter
|
||||
is closed.
|
||||
|
||||
------------
|
||||
|
||||
|
||||
Applied Scientific Instrumentation
|
||||
----------------------------------
|
||||
|
||||
The `TGPLC <https://asiimaging.com/docs/tiger_programmable_logic_card>`_ control card for the
|
||||
Tiger Controller (`TG-1000 <https://asiimaging.com/docs/products/tiger>`_) from ASI can be used to trigger shutter operation.
|
||||
TGPLC output 1 is reserved for the camera trigger.
|
||||
|
||||
-----------------
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
shutter:
|
||||
hardware:
|
||||
type: ASI
|
||||
axis: 2
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
port: COM4
|
||||
|
||||
|
|
||||
|
||||
-----------------
|
||||
|
||||
National Instruments
|
||||
--------------------
|
||||
|
||||
We can control these shutters using a digital output from a National Instruments (NI) data acquisition card.
|
||||
|
||||
.. Note::
|
||||
|
||||
If the shutter opens and closes immediately upon starting an acquisition, try a
|
||||
different port for the digital I/O on the NI data acquisition card. Some NI devices
|
||||
(e.g.PCIe-6738) have port/sample size limitations. If the port/sample size is
|
||||
exceeded, the shutter will not open. For example, on our `NI PCIe-6738 <https://www
|
||||
.ni.com/docs/en-US/bundle/pcie-6738-specs/page/specs.html>`_ using port 0 for the
|
||||
shutter causes this issue, but switching the shutter to any port 1 channel fixed it.
|
||||
In comparison, for the `NI PCIe-6259 <https://www.ni
|
||||
.com/docs/en-US/bundle/pci-pcie-pxi-pxie-usb-6259-specs/page/specs.html>`_,
|
||||
using port 0 had no averse effects.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
shutter:
|
||||
hardware:
|
||||
type: NI
|
||||
channel: PXI6249/port0/line0
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
Synthetic Shutter
|
||||
-----------------
|
||||
If no shutter is present, one must configure the software to use a synthetic
|
||||
shutter.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
shutter:
|
||||
hardware:
|
||||
type: synthetic
|
||||
channel: PXI6249/port0/line0
|
||||
min: 0.0
|
||||
max: 5.0
|
||||
|
||||
------------------
|
||||
689
docs/source/02_user_guide/01_supported_hardware/stage.rst
Normal file
689
docs/source/02_user_guide/01_supported_hardware/stage.rst
Normal file
@@ -0,0 +1,689 @@
|
||||
======
|
||||
Stages
|
||||
======
|
||||
|
||||
Our software empowers users with a flexible solution for configuring multiple stages, catering to diverse microscope modalities. Each stage can be customized to suit the specific requirements of a particular modality or shared across various modalities. Our unique approach allows seamless integration of stages from different manufacturers, enabling users to mix and match components for a truly versatile and optimized setup tailored to their research needs.
|
||||
|
||||
.. Note::
|
||||
The software provides configure specific hardware axes to software axes. This is specified in the configuration file. For example, if specified as follows, the software x, y, z, and f axes can be mapped to the hardware axes M, Y, X, and Z, respectively.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
axes: [x, y, z, f]
|
||||
axes_mapping: [M, Y, X, Z]
|
||||
|
||||
------------------
|
||||
|
||||
Applied Scientific Instrumentation
|
||||
----------------------------------
|
||||
|
||||
Tiger Controller
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
The ASI `Tiger Controller <https://www.asiimaging.com/controllers/tiger-controller/>`_. is
|
||||
a multi-purpose controller for ASI stages, filter wheels, dichroic sliders,
|
||||
and more. We communicate with Tiger Controllers via a serial port. It is recommended that you
|
||||
first establish communication with the device using `ASI provided software <https://asiimaging.com/docs/products/tiger>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
**navigate** has been tested with the following versions of the ASI's Tiger
|
||||
Controller software:
|
||||
|
||||
- Tiger Controller 2.2.0.
|
||||
|
||||
.. note::
|
||||
Some users have reported intermittent connection issues at random intervals when
|
||||
used with Coherent OBIS lasers. These issues, and how to address them, are discussed
|
||||
in the :ref:`communication challenges <obis_tiger_connection>` section.
|
||||
|
||||
.. warning::
|
||||
If you are using the FTP-2000 stage, do not change the F stage axis. This
|
||||
will differentially drive the two vertical posts, causing them to torque and
|
||||
potentially damage one another.
|
||||
|
||||
.. tip::
|
||||
ASI stage's include a configuration option, ``feedback_alignment``, which
|
||||
corresponds to the `Tiger Controller AA Command <https://asiimaging.com/docs/commands/aalign>`_.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: ASI
|
||||
serial_number: 001
|
||||
axes: [x, y, z, theta, f]
|
||||
axes_mapping: [A, B, C, D, E]
|
||||
feedback_alignment: [90, 90, 90, 5, 90]
|
||||
volts_per_micron: 0.0
|
||||
min: 0.0
|
||||
max: 1.0
|
||||
controllername:
|
||||
stages:
|
||||
refmode:
|
||||
port: COM12
|
||||
baudrate: 115200
|
||||
timeout: 0.25
|
||||
joystick_axes: [x, y, z]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
-----------------
|
||||
|
||||
MFC2000
|
||||
~~~~~~~
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: MFC2000
|
||||
serial_number: 001
|
||||
axes: [x, y, z, theta, f]
|
||||
axes_mapping: [A, B, C, D, E]
|
||||
feedback_alignment: [90, 90, 90, 5, 90]
|
||||
volts_per_micron: 0.0
|
||||
min: 0.0
|
||||
max: 1.0
|
||||
controllername:
|
||||
stages:
|
||||
refmode:
|
||||
port: COM12
|
||||
baudrate: 9600
|
||||
timeout: 0.25
|
||||
joystick_axes: [x, y, z]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
|
||||
-----------------
|
||||
|
||||
MS2000
|
||||
~~~~~~~
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: MS2000
|
||||
serial_number: 001
|
||||
axes: [x, y, z, theta, f]
|
||||
axes_mapping: [A, B, C, D, E]
|
||||
feedback_alignment: [90, 90, 90, 5, 90]
|
||||
volts_per_micron: 0.0
|
||||
min: 0.0
|
||||
max: 1.0
|
||||
controllername:
|
||||
stages:
|
||||
refmode:
|
||||
port: COM12
|
||||
baudrate: 9600
|
||||
timeout: 0.25
|
||||
joystick_axes: [x, y, z]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
Sutter Instruments
|
||||
------------------
|
||||
|
||||
MP-285
|
||||
~~~~~~
|
||||
|
||||
The `Sutter MP-285 <https://www.sutter.com/MICROMANIPULATION/mp285.html>`_ communicates
|
||||
via serial port and is quite particular. We have done our best to ensure the
|
||||
communication is stable, but occasionally the stage will send or receive an extra
|
||||
character, throwing off communication. In this case, the MP-285's screen will be
|
||||
covered in 0s, 1s or look garbled. If this happens, simply turn off the software,
|
||||
power cycle the stage, and press the "MOVE" button on the MP-285 controller once. When
|
||||
the software is restarted, it should work.
|
||||
|
||||
.. tip::
|
||||
|
||||
Sometimes the Coherent Connection software messes with the MP-285 serial
|
||||
communication if it is connected to the lasers.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: MP285
|
||||
serial_number: 001
|
||||
axes: [x, y, z]
|
||||
axes_mapping: [x, y, z]
|
||||
feedback_alignment:
|
||||
volts_per_micron: 0.0
|
||||
min: 0.0
|
||||
max: 25000
|
||||
controllername:
|
||||
stages:
|
||||
refmode:
|
||||
port: COM1
|
||||
baudrate: 9600
|
||||
timeout: 0.25
|
||||
joystick_axes: [x, y, z]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
|
||||
-----------------
|
||||
|
||||
Physik Instrumente
|
||||
------------------
|
||||
|
||||
These stages are controlled by `PI <https://www.pi-usa.us/en/>`_'s own
|
||||
`Python code <https://pypi.org/project/PIPython/>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
**navigate** has been tested with the following versions of the Physik
|
||||
Instrumente software and drivers:
|
||||
|
||||
- PIMikroMove: 2.36.1.0
|
||||
- PI_GCS2_DLL: 3.22.0.0
|
||||
|
||||
.. note::
|
||||
PI stages require a special ``hardware`` option in the configuration.yaml file, ``refmode``,
|
||||
which corresponds to how the PI stage chooses to self-reference. Options are:
|
||||
|
||||
* ``REF``
|
||||
* ``FRF``
|
||||
* ``MNL``
|
||||
* ``FNL``
|
||||
* ``MPL``
|
||||
* ``FPL``
|
||||
* ``" "`` - An empty string can be provided if no stage referencing mode is needed.
|
||||
|
||||
These are PI's GCS commands, and the correct reference mode for your stage should be found by
|
||||
launching PIMikroMove, which comes with your stage and can be downloaded
|
||||
`here <https://www.pi-usa.us/en/products/controllers-drivers-motion-control-software/motion-control-software>`_.
|
||||
Stage names (e.g. ``L-509.20DG10``) can also be found in PIMikroMove or on a label on the side of your stage.
|
||||
|
||||
-----------------
|
||||
|
||||
C-884
|
||||
~~~~~
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: PI
|
||||
serial_number: 119060508
|
||||
axes: [x, y, z, theta, f]
|
||||
axes_mapping: [1, 2, 3, 4, 5]
|
||||
feedback_alignment:
|
||||
volts_per_micron: 0.0
|
||||
min:
|
||||
max:
|
||||
controllername: C-884
|
||||
stages: L-509.20DG10 L-509.40DG10 L-509.20DG10 M-060.DG M-406.4PD NOSTAGE
|
||||
refmode: FRF FRF FRF FRF FRF FRF
|
||||
port:
|
||||
baudrate:
|
||||
timeout:
|
||||
joystick_axes: [x, y, z]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
|
||||
-----------------
|
||||
|
||||
E-709
|
||||
~~~~~
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: PI
|
||||
serial_number: 119060508
|
||||
axes: [x, y, z, theta, f]
|
||||
axes_mapping: [1, 2, 3, 4, 5]
|
||||
feedback_alignment:
|
||||
volts_per_micron: 0.0
|
||||
min:
|
||||
max:
|
||||
controllername: E-709
|
||||
stages: L-509.20DG10 L-509.40DG10 L-509.20DG10 M-060.DG M-406.4PD NOSTAGE
|
||||
refmode: FRF FRF FRF FRF FRF FRF
|
||||
port:
|
||||
baudrate:
|
||||
timeout:
|
||||
joystick_axes: [x, y, z]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
|
||||
------------------
|
||||
|
||||
Thorlabs
|
||||
--------
|
||||
|
||||
KIM001
|
||||
~~~~~~
|
||||
**navigate** supports the `KIM001 <https://www.thorlabs.com/thorproduct
|
||||
.cfm?partnumber=KIM001>`_ controller. However, this device shows significant
|
||||
hysteresis, and thus we do not recommend it for precise positioning tasks (e.g.,
|
||||
autofocusing). It serves as a cost-effective solution for manual, user-driven
|
||||
positioning.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: Thorlabs
|
||||
serial_number: 74000375
|
||||
axes: [f]
|
||||
axes_mapping: [1]
|
||||
feedback_alignment:
|
||||
volts_per_micron: 0.0
|
||||
min:
|
||||
max:
|
||||
controllername:
|
||||
stages:
|
||||
refmode:
|
||||
port:
|
||||
baudrate:
|
||||
timeout:
|
||||
joystick_axes: [f]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
|
||||
-----------------
|
||||
|
||||
KST101
|
||||
~~~~~~
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: KST101
|
||||
serial_number: 26001318
|
||||
axes: [f]
|
||||
axes_mapping: [1]
|
||||
feedback_alignment:
|
||||
device_units_per_mm: 20000000/9.957067
|
||||
volts_per_micron: 0.0
|
||||
min: 0
|
||||
max: 25
|
||||
controllername:
|
||||
stages:
|
||||
refmode:
|
||||
port:
|
||||
baudrate:
|
||||
timeout:
|
||||
joystick_axes: [f]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
|
||||
--------------
|
||||
|
||||
.. _galvo_stage:
|
||||
|
||||
National Instruments
|
||||
--------------------
|
||||
|
||||
We sometimes control position via a galvo or piezo with no software API.
|
||||
In this case, we treat a standard galvo mirror or piezo as a stage axis. We control the
|
||||
"stage" via voltages sent to the galvo or piezo. The ``volts_per_micron`` setting
|
||||
allows the user to pass an equation that converts position in microns ``X``, which is
|
||||
passed from the software stage controls, to a voltage. Note that we use
|
||||
``GalvoNIStage`` whether or not the device is a galvo or a piezo since the logic is
|
||||
identical. The voltage signal is delivered via the data acquisition card specified in the
|
||||
``axes_mapping`` entry.
|
||||
|
||||
.. note::
|
||||
|
||||
The parameters ``distance_threshold`` and ``settle_duration_ms`` are used to provide
|
||||
a settle time for large moves. if the move is larger than the ``distance_threshold``,
|
||||
then a wait duration of ``settle_duration_ms`` is used to allow the stage to settle
|
||||
before the image is acquired.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: GalvoNIStage
|
||||
serial_number: 001
|
||||
axes: [Z]
|
||||
axes_mapping: [PCI6738/ao6]
|
||||
volts_per_micron: 0.05*x
|
||||
min: 0.0
|
||||
max: 1.0
|
||||
distance_threshold: 5
|
||||
settle_duration_ms: 5
|
||||
controllername:
|
||||
stages:
|
||||
refmode:
|
||||
port:
|
||||
baudrate: 0
|
||||
joystick_axes: [f]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
|
||||
----------------
|
||||
|
||||
|
||||
Newport
|
||||
-------
|
||||
Newport offers motion control solutions for various applications in microscopy. Our software supports two Newport stage controllers that provide accurate positioning capabilities.
|
||||
|
||||
Conex Controller
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The Newport Conex Controller series offers compact, integrated motion control solutions that come pre-wired with dedicated controllers for quick, out-of-the-box operation. While the Conex series offers four `different controller types with various drive technologies <https://www.newport.com/c/controller-&-stage-kits>`_, we have used it to drive a `TRA6CC <https://www.newport.com/p/TRA6CC>`_ (Linear Actuator, DC Servo, 6 mm Travel, TRA6CC and CONEX-CC Controller) connected to a `M-SV-0.5 <https://www.newport.com/p/M-SV-0.5>`_ adjustable width slit that is positioned conjugate to the back pupil of the illumination objective. This setup allows precise and automated control of the illumination numerical aperture.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
name: slit
|
||||
type: conex.ConexStage
|
||||
serial_number: 126
|
||||
port: COM4
|
||||
axes: [S]
|
||||
axes_mapping: [S]
|
||||
s_min: -10000.0
|
||||
s_max: 10000.0
|
||||
s_offset: 0.0
|
||||
|
||||
|
|
||||
|
||||
--------------
|
||||
|
||||
ESP302 Motion Controller Controller
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Newport `ESP302 Motion Controller <https://www.newport.com/f/esp30x-3-axis-dc-and-stepper-motion-controller>`_ is a versatile, 1-, 2-, or 3-axis motion controller that provides precise positioning capabilities for a wide range of Newport stages.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
name: delay_stage
|
||||
type: newport.NewportStage
|
||||
serial_number: 127
|
||||
axes: [theta]
|
||||
axes_mapping: [1]
|
||||
port: "192.168.1.90"
|
||||
baudrate: 5001
|
||||
timeout: 5.0
|
||||
|
|
||||
|
||||
---------------
|
||||
|
||||
Synthetic Stage
|
||||
---------------
|
||||
If no stage is present for a particular axis, one must configure the software to use a synthetic
|
||||
stage. For example, not all microscopes have a theta axis.
|
||||
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
type: synthetic
|
||||
serial_number: 001
|
||||
axes: [x, y, z, theta, f]
|
||||
axes_mapping: [A, B, C, D, E]
|
||||
volts_per_micron: 0.0
|
||||
min: 0.0
|
||||
max: 1.0
|
||||
controllername:
|
||||
stages:
|
||||
refmode:
|
||||
port:
|
||||
baudrate: 0
|
||||
joystick_axes: [x, y, z]
|
||||
x_min: -10000.0
|
||||
x_max: 10000.0
|
||||
y_min: -10000.0
|
||||
y_max: 10000.0
|
||||
z_min: -10000.0
|
||||
z_max: 10000.0
|
||||
theta_min: 0.0
|
||||
theta_max: 360.0
|
||||
f_min: -10000.0
|
||||
f_max: 10000.0
|
||||
x_offset: 0.0
|
||||
y_offset: 0.0
|
||||
z_offset: 0.0
|
||||
theta_offset: 0.0
|
||||
f_offset: 0.0
|
||||
flip_x: False
|
||||
flip_y: False
|
||||
flip_z: False
|
||||
flip_f: False
|
||||
|
||||
|
|
||||
89
docs/source/02_user_guide/01_supported_hardware/zoom.rst
Normal file
89
docs/source/02_user_guide/01_supported_hardware/zoom.rst
Normal file
@@ -0,0 +1,89 @@
|
||||
.. _mechanical_zoom:
|
||||
|
||||
===============
|
||||
Mechanical Zoom
|
||||
===============
|
||||
|
||||
Zoom devices control the magnification of the microscope. If such control is not
|
||||
needed, the software expects a :ref:`Synthetic Zoom <synthetic_zoom>` to provide
|
||||
the fixed magnification and the effective pixel size of the microscope.
|
||||
|
||||
---------------
|
||||
|
||||
Dynamixel
|
||||
---------
|
||||
|
||||
MX-28R
|
||||
~~~~~~
|
||||
|
||||
This software supports the
|
||||
`Dynamixel Smart Actuator <https://www.dynamixel.com/>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``positions`` specify the voltage of the actuator at different zoom positions.
|
||||
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. The ``pixel_size`` specifies the effective pixel size of
|
||||
the system at each zoom.
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
zoom:
|
||||
hardware:
|
||||
type: DynamixelZoom
|
||||
servo_id: 1
|
||||
port: COM1
|
||||
baudrate: 9600
|
||||
position:
|
||||
1x: 200.0
|
||||
6.5x: 2000.0
|
||||
pixel_size:
|
||||
1x: 6.5
|
||||
6.5x: 1.0
|
||||
stage_positions:
|
||||
BABB:
|
||||
f:
|
||||
1X: 0
|
||||
6.5x: 2
|
||||
|
||||
|
||||
|
|
||||
|
||||
---------------
|
||||
|
||||
.. _synthetic_zoom:
|
||||
|
||||
Synthetic Zoom
|
||||
--------------
|
||||
|
||||
.. collapse:: Configuration File
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microscopes:
|
||||
microscope_name:
|
||||
zoom:
|
||||
hardware:
|
||||
type: synthetic
|
||||
servo_id: 1
|
||||
port: COM1
|
||||
baudrate: 9600
|
||||
position:
|
||||
1x: 200.0
|
||||
6.5x: 2000.0
|
||||
pixel_size:
|
||||
1x: 6.5
|
||||
6.5x: 1.0
|
||||
stage_positions:
|
||||
BABB:
|
||||
f:
|
||||
1X: 0
|
||||
6.5x: 2
|
||||
|
||||
|
|
||||
89
docs/source/02_user_guide/02_file_formats/file_formats.rst
Normal file
89
docs/source/02_user_guide/02_file_formats/file_formats.rst
Normal file
@@ -0,0 +1,89 @@
|
||||
======================
|
||||
Supported File Formats
|
||||
======================
|
||||
|
||||
The choice of file format for saving imaging data in microscopy is crucial because it affects write speed, data integrity, accessibility, and analysis efficiency. Formats like TIFF and its derivative OME-TIFF are widely used due to their ability to store metadata and support multiple imaging channels. However, modern formats such as Zarr, N5, and HDF5, including OME-Zarr, cater to the needs of large-scale, multi-dimensional datasets by enabling efficient data storage, access, and processing at cloud-compute scales.
|
||||
|
||||
To enable ambitious imaging projects, **navigate** comes pre-packaged with TIFF, OME-TIFF, OME-Zarr, and HDF5/N5 (`BigDataViewer <https://imagej.net/plugins/bdv/>`_) file saving formats. OME, or Open Microscopy Environment, is a standardized metadata model that ensures that imaging data can be accurately understood, shared, and analyzed across different software platforms and research groups.
|
||||
|
||||
.. Note::
|
||||
|
||||
The performance of saving to these data sources is limited by write speed to disk. To achieve maximal saving speed, we recommend saving all data to a local solid state drive. See :ref:`Hardware Considerations <computer_considerations>` for more information.
|
||||
|
||||
----------------
|
||||
|
||||
TIFF/OME-TIFF
|
||||
-------------
|
||||
|
||||
**navigate** uses the `tifffile <https://pypi.org/project/tifffile/>`_ package to write TIFF, BigTIFF, and OME-TIFF data to file. The **navigate** package creates a custom :doc:`OME-TIFF XML <../../05_reference/_autosummary/navigate.model.metadata_sources.ome_tiff_metadata.OMETIFFMetadata>` to store metadata.
|
||||
|
||||
----------------
|
||||
|
||||
BigDataViewer H5/N5
|
||||
-------------------
|
||||
|
||||
**navigate** uses `h5py <https://docs.h5py.org/en/stable/index.html>`_ (H5) and `zarr <https://zarr.readthedocs.io/en/stable/>`_ (N5) to store data in a BigDataViewer file format. This is a pyramidal format, necessitating the saving of both the original data and down sampled versions of this data. The additional data slows down the write speed. The N5 format can be faster than H5 because it allows for multithreaded writes.
|
||||
|
||||
OME-Zarr
|
||||
--------
|
||||
|
||||
OME-Zarr is a Zarr file format that adheres to strict metadata specifications, detailed at https://ngff.openmicroscopy.org/0.4/index.html. It allows for pyramidal data writing, storage of segmentation labels with the data set, and updating the pyramidal structure on the fly.
|
||||
|
||||
----------------
|
||||
|
||||
Image Writing Benchmarks
|
||||
------------------------
|
||||
|
||||
To evaluate the performance of saving imaging data in different formats, we conducted benchmarks on a Windows 10 system. We assessed the median disk write time for TIFF, OME-TIFF, H5, N5, and OME-Zarr formats across image resolutions of 512x512, 1024x1024, and 2048x2048 under two conditions: (A) capturing 1000 single-plane images and (B) acquiring a single z-stack composed of 1000 planes. All times are measured in milliseconds. Results are presented below. For z-stack imaging, TIFF and OME-TIFF formats achieved write speeds of up to approximately 300 Hz for a 2048x2048 camera resolution, surpassing the operational speeds of most contemporary sCMOS cameras. The Big-TIFF variant was used for both TIFF and OME-TIFF formats to accommodate the large file sizes.
|
||||
|
||||
Timelapse Imaging
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
1000 images acquired, with a single Z plane. Median write time reported in milliseconds.
|
||||
|
||||
.. table::
|
||||
:widths: auto
|
||||
:align: center
|
||||
|
||||
+-------------+---------+----------+-------+-------+---------+
|
||||
| | TIFF | OME-TIFF | H5 | N5 | OME-Zarr|
|
||||
+=============+=========+==========+=======+=======+=========+
|
||||
| 512x512 | 1.19 | 29.24 | 3.17 | 9.00 | 5.30 |
|
||||
+-------------+---------+----------+-------+-------+---------+
|
||||
| 1024x1024 | 1.84 | 36.69 | 18.59 | 14.55 | 8.81 |
|
||||
+-------------+---------+----------+-------+-------+---------+
|
||||
| 2048x2048 | 5.55 | 44.65 | 84.18 | 38.60 | 25.02 |
|
||||
+-------------+---------+----------+-------+-------+---------+
|
||||
|
||||
Z-Stack Imaging
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
1 image acquired, with 1000 Z planes. Median write speed time in milliseconds.
|
||||
|
||||
.. table::
|
||||
:widths: auto
|
||||
:align: center
|
||||
|
||||
+--------------+---------+----------+-------+-------+---------+
|
||||
| | TIFF | OME-TIFF | H5 | N5 | OME-Zarr|
|
||||
+==============+=========+==========+=======+=======+=========+
|
||||
| 512x512 | 0.28 | 0.25 | 7.30 | 5.10 | 3.29 |
|
||||
+--------------+---------+----------+-------+-------+---------+
|
||||
| 1024x1024 | 0.89 | 0.88 | 29.15 | 12.44 | 8.26 |
|
||||
+--------------+---------+----------+-------+-------+---------+
|
||||
| 2048x2048 | 4.12 | 3.30 | 135.74| 37.09 | 24.83 |
|
||||
+--------------+---------+----------+-------+-------+---------+
|
||||
|
||||
Additional Sources of Overhead
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The initial setup for writing H5/N5 files introduces significant overhead, and to a lesser extent for TIFF and OME-TIFF files, which elevates the average write time. However, the median write time remains consistently low and stable across most of the acquisition.
|
||||
|
||||
Computer Specifications for Benchmarks
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The computer specifications that the benchmarks were performed on are as follows.
|
||||
|
||||
- CPU: Intel(R) Xeon(R) Silver 4112 CPU @ 2.60GHz
|
||||
- Memory: 88 GB
|
||||
- Hard Drive: Micron 5200 ECO 7680gb SSD
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 511 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 573 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 7.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.0 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.7 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 429 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
@@ -0,0 +1,586 @@
|
||||
==========================
|
||||
User Interface Walkthrough
|
||||
==========================
|
||||
|
||||
**navigate**'s user interface is modular and designed to be reconfigurable to a user's preferences. At a high level, it is split into a menu bar, an acquisition bar, settings notebooks, and display notebooks.
|
||||
|
||||
.. image:: images/home_screen.png
|
||||
|
||||
-----------------
|
||||
|
||||
.. _ui_menu_bar:
|
||||
|
||||
Menu Bar
|
||||
========
|
||||
|
||||
The menu bar is an entry point for much of **navigate**.
|
||||
|
||||
.. _ui_file_menu:
|
||||
|
||||
File
|
||||
----
|
||||
|
||||
.. image:: images/menu_file.png
|
||||
|
||||
The :guilabel:`File` menu lets a user create, load, and save :ref:`experiment files <experiment_file>`, which store the states of the GUI and the hardware. The menu also provides an option to load and save :ref:`waveform constants files <configure_waveform_templates>` to store the waveform constants used for a given experiment. This is useful if a user wants to perform an experiment with the same parameters multiple times but close the software in between acquisitions. To facilitate reproducibility, `experiment.yml` and `waveform_constants.yml` files are always saved with the collected image data.
|
||||
|
||||
The :guilabel:`File` menu also provides access to toggle the :guilabel:`Save Data` flag, also found under :guilabel:`Timepoint Settings` in the :guilabel:`Channels Settings Notebook`, and to start an acquisition (which can also be done by pressing :guilabel:`Acquire` in the :ref:`ui_acquisition_bar`). Loading and unloading images only works if there is a :ref:`synthetic camera <synthetic_camera>`. In this case, the camera loads images to display in lieu of the simulated noise usually generated by the synthetic camera.
|
||||
|
||||
:guilabel:`Open Log Files` opens the folder containing the software's log files. This is helpful for debugging code and configuration problems.
|
||||
|
||||
:guilabel:`Open Configuration Files` opens the folder containing the software's :ref:`configuration file <configuration_file>`.
|
||||
|
||||
-----------------
|
||||
|
||||
.. _ui_microscope_configuration:
|
||||
|
||||
Microscope Configuration
|
||||
------------------------
|
||||
|
||||
.. image:: images/menu_microscope_configuration.png
|
||||
|
||||
The :guilabel:`Microscope Configuration` menu is split into two parts, above and below the horizontal divider.
|
||||
|
||||
Above the horizontal divider, it lists the names of all microscopes named in the ``microscopes`` section of the :ref:`configuration file <configuration_file>`. This allows users to readily switch between different microscopes, each with their own hardware configurations. Mousing over a microscope name reveals all zoom values available under the :ref:`Mechanical Zoom <mechanical_zoom>`. Selecting one of these zoom values changes the magnification of the microscope.
|
||||
|
||||
Below the horizontal divider is access to the :ref:`Waveform Parameters <ui_waveform_parameters>` settings panel and the :ref:`Configure Microscope <ui_configure_microscopes>` settings panel.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _stage_control_menu:
|
||||
|
||||
Stage Control Menu
|
||||
------------------
|
||||
|
||||
.. image:: images/menu_stage_control.png
|
||||
|
||||
The stage control menu is split by horizontal dividers into three parts.
|
||||
|
||||
The top part provides similar functionality to the :ref:`Stage Control Settings Notebook <stage_control_notebook>`. It allows movement of the stage along ``X``, ``Y``, ``Z``, ``focus`` and ``Theta``. The ``w``, ``s``, ``a`` and ``d`` keys are bound to movement in ``X`` and ``Y``, and these can be used to scroll around a sample.
|
||||
|
||||
The middle part provides similar functionality to the :ref:`Multiposition Settings Notebook <ui_multiposition>`. Here, a user can launch the :ref:`Tiling Wizard <ui_multiposition_tiling_wizard>`, load and export (save) positions stored in the :guilabel:`Multiposition Settings Notebook`, and add the current stage position to the multiposition table.
|
||||
|
||||
The bottom part of the menu is used to enable and disable the stage limits set in the configuration file (see the :ref:`stage subsection <configure_stages>`).
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_autofocus_menu:
|
||||
|
||||
Autofocus
|
||||
---------
|
||||
|
||||
.. image:: images/menu_autofocus.png
|
||||
|
||||
The autofocus menu has two options: :guilabel:`Perform Autofocus`, which autofocuses the sample using the current autofocus settings, and :guilabel:`Autofocus Settings`, which launches the :ref:`Autofocus Settings <ui_autofocus>` popup.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_features_menu:
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
.. image:: images/menu_features.png
|
||||
|
||||
This menu provides access to acquisition feature lists. An explanation of features, feature lists, and the use and operation of this menu is provided under :ref:`Reconfigurable Acquisitions Using Features <user_guide_features>`.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_plugins_menu:
|
||||
|
||||
Plugins
|
||||
-------
|
||||
|
||||
.. image:: images/menu_plugins.png
|
||||
|
||||
This menu provides an access point for :ref:`plugins <plugin>` that feature a popup GUI.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_window_menu:
|
||||
|
||||
Window
|
||||
------
|
||||
|
||||
.. image:: images/menu_window.png
|
||||
|
||||
This menu is split into two parts by a horizontal divider and provides some GUI controls.
|
||||
|
||||
The top part allows the user to switch between the main :ref:`Settings Notebooks <ui_settings_notebooks>`.
|
||||
|
||||
The bottom part provides an option to move the camera display to a popup window, and :guilabel:`Help` brings the user to the online documentation for **navigate**.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_acquisition_bar:
|
||||
|
||||
Acquisition Bar
|
||||
===============
|
||||
|
||||
Left-to-right, the acquisition bar provides:
|
||||
|
||||
* An :guilabel:`Acquire` button, which starts acquisition.
|
||||
* A drop-down menu providing a selection of acquisition modes.
|
||||
* A progress bar indicating how far the program has made it through an acquisition. The top bar indicates progress on the current z-stack, whereas the bottom indicates progress for the entire acquisition.
|
||||
* An approximate estimate of how much time is left in the acquisition.
|
||||
* An emergency :guilabel:`Stop Stage` button, which instantly halts all stage movement.
|
||||
* An :guilabel:`Exit Button`, which quits the software.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_settings_notebooks:
|
||||
|
||||
Settings Notebooks
|
||||
==================
|
||||
|
||||
The settings notebooks are a series of tabs that control microscope settings, including laser power, camera settings, stage positions, and many others.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_channels_notebook:
|
||||
|
||||
Channels
|
||||
--------
|
||||
|
||||
.. image:: images/settings_channels.png
|
||||
|
||||
The :guilabel:`Channels` Settings Notebook is a tab (optionally, a popup if right-clicked on) split into five sections: :guilabel:`Channel Settings`, :guilabel:`Stack Acquisition Settings (µm)`, :guilabel:`Timepoint Settings`, :guilabel:`Multi-Position Acquisition`, and :guilabel:`Quick Launch Buttons`.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_channel_settings:
|
||||
|
||||
Channel Settings
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
This is used to set up acquisition color channels. A channel is considered to be a combination of an illuminating laser wavelength and a detection filter. Each channel has its own power, exposure time, interval, and defocus. The checkbox on the left indicates if a channel should be used (is selected) during acquisition. An acquisition may loop through the channels in sequence.
|
||||
|
||||
* :guilabel:`Laser` is the name of the laser, taken from the :ref:`configuration file <configuration_file>`, and usually expressed in nanometers.
|
||||
* :guilabel:`Power` is the power of the laser between 0 and 100 percent.
|
||||
* :guilabel:`Filter` is the name of the filter selected in the detection path filter wheel. Filter names are stored in the configuration file.
|
||||
* :guilabel:`Exp. Time (ms)` is the exposure time of the camera in milliseconds.
|
||||
* :guilabel:`Interval` indicates how often this channel should be used in an acquisition. For example, in two-color imaging, CH1 may image a process twice as fast as what is labeled in CH2. Setting the CH2 interval to 2 allows a user to image the processes in both channels at a similar rate. This will be implemented in future releases of the software.
|
||||
* :guilabel:`Defocus` indicates the defocus between two channels in micrometers. The defocus values are always relative to the focus of the first channel imaged. This setting is useful for compensating for chromatic aberration.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_stack_settings:
|
||||
|
||||
Stack Acquisition Settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These are the settings used for a standard Z-Stack Acquisition.
|
||||
|
||||
:guilabel:`Pos` indicates z-positions. :guilabel:`Foc` indicates focus positions. The z-stack can optionally ramp through ``focus`` along with ``Z``.
|
||||
|
||||
:guilabel:`Start` and :guilabel:`End` are always expressed relative to the center of the z-stack. :guilabel:`Abs Z Start` and :guilabel:`Abs Z Stop` provide true stage positions at the start and end of the z-stack.
|
||||
|
||||
The buttons :guilabel:`Set Start Pos/Foc` and :guilabel:`Set End Pos/Foc` grab the current ``Z`` and ``focus`` positions from the stage and enter them into the corresponding start and end (stop) GUI boxes.
|
||||
|
||||
The :guilabel:`Step Size` is expressed in microns and can be modified by the user. Upon modification, :guilabel:`# slices` will automatically update.
|
||||
|
||||
:guilabel:`Laser Cycling Settings` provide the options "Per Stack" and "Per Z". In "Per Stack" mode, the software will move through all positions before changing to another color channel. In "Per Z" mode, the software will acquire all color channels selected before moving to the next position in the z-stack.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_timepoint_settings:
|
||||
|
||||
Timepoint Settings
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These are used for acquiring data over multiple timepoints and for toggling the option to save data.
|
||||
|
||||
* :guilabel:`Save Data` tells the software to save acquired data to disk when checked. If this is selected, a :ref:`saving popup window <ui_file_save_dialog>` will appear when :guilabel:`Acquire` is pressed, unless the user is in "Continuous Scan" mode, which is designed for live previews only.
|
||||
* :guilabel:`Timepoints` indicates how many time points this acquisition should acquire.
|
||||
* :guilabel:`Stack Acq Time` provides an estimate of how long a single z-stack will take to acquire.
|
||||
* :guilabel:`Stack Pause (s)` indicates how much waiting time the software should introduce in between acquisition steps (e.g. in between taking z-stacks).
|
||||
* :guilabel:`Time Interval (hh:mm:ss)` provides an estimate of how long each time point takes to acquire. This is (stack acquisition + stack pause) x number of channels to image.
|
||||
* :guilabel:`Experiment Duration (hh:mm:ss)` provides an estimate of how long the full acquisition will take.
|
||||
|
||||
.. Note::
|
||||
|
||||
The :guilabel:`Stack Acq Time` and :guilabel:`Experiment Duration (hh:mm:ss)` do not account for stage movement time. Thus, for stages with serial communication protocols, or stages with slow movement, these estimates will be an underestimate. Future releases will account for stage movement time to provide a more accurate estimate.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_multiposition_settings:
|
||||
|
||||
Multi-Position Acquisition
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This contains settings to set up acquisition over multiple positions in the sample, e.g. tiling.
|
||||
|
||||
* :guilabel:`Enable` indicates that the software should move through the positions listed in the :ref:`Multiposition Settings Notebook <ui_multiposition>` during the acquisition.
|
||||
* :guilabel:`Launch Tiling Wizard` launches the :ref:`Tiling Wizard <ui_multiposition_tiling_wizard>`.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_quick_launch_buttons:
|
||||
|
||||
Quick Launch Buttons
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This provides access to the :ref:`Waveform Parameters <ui_waveform_parameters>` and :ref:`Autofocus Settings <ui_autofocus>` popups.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_camera_settings:
|
||||
|
||||
Camera Settings
|
||||
---------------
|
||||
|
||||
.. image:: images/settings_camera.png
|
||||
|
||||
The :guilabel:`Camera Settings` Notebook is a tab (optionally, a popup) that controls the camera. It is split into three sections: :guilabel:`Camera Modes`, :guilabel:`Framerate Info`, and :guilabel:`Region of Interest Settings`.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_camera_modes:
|
||||
|
||||
Camera Modes
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The :guilabel:`Camera Modes` section is designed for switching between normal mode of operation, where the camera exposes all pixels semi-simultaneously, and light-sheet mode (a.k.a rolling shutter mode), where the camera exposes only a few pixels at a time, and progressively images from the top to the bottom of the camera chip or vice versa.
|
||||
|
||||
* :guilabel:`Sensor Mode` is used to switch between "Normal" and "Light-Sheet" modes.
|
||||
* :guilabel:`Readout Direction` indicates if the rolling shutter should move from the bottom to the top of the camera chip or vice versa.
|
||||
* :guilabel:`Number of Pixels` sets the rolling shutter width of the camera.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_framerate_info:
|
||||
|
||||
Framerate Info
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
This displays information concerning the speed of acquisition and optionally allows the user to average these values over multiple images.
|
||||
|
||||
* :guilabel:`Exposure Time (ms)` displays the set camera exposure time.
|
||||
* :guilabel:`Readout Time (ms)` displays how long it takes to read a frame from the camera. This includes exposure time.
|
||||
* :guilabel:`Framerate (Hz)` displays how long it takes to acquire an image. This is based on an internal "wait ticket" approach, where the software times how long it waits for a frame to come in after receiving the previous frame. This frequency includes not only camera readout time, but, e.g. how long the software had to wait for the stage to finish moving before taking the next image in a z-stack. It is the most accurate time estimate in the software.
|
||||
* :guilabel:`Images to Average` tells the camera to average frames. This will be implemented in future releases of the software.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_region_of_interest:
|
||||
|
||||
Region of Interest Settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These allow the user to set the size of the region of interest in pixels. The camera can also be told to bin pixels. The corresponding field of view is displayed by calculating the number of pixels multiplied by the camera's effective pixel size, which is set in the :ref:`Mechanical Zoom <mechanical_zoom>` section of the configuration file.
|
||||
|
||||
:guilabel:`Default FOVs` includes buttons to quickly change the FOV to preset values.
|
||||
|
||||
:guilabel:`ROI center` indicates about what point the pixels crop on the camera.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _stage_control_notebook:
|
||||
|
||||
Stage Control
|
||||
-------------
|
||||
|
||||
.. image:: images/settings_stage.png
|
||||
|
||||
The :guilabel:`Stage Control` Settings Notebook is a tab (optionally, a popup) that controls the stage positions. It is split into six parts: :guilabel:`Stage Positions`, :guilabel:`X Y Movement`, :guilabel:`Z Movement`, :guilabel:`Focus Movement`, :guilabel:`Theta Movement`, and includes an emergency :guilabel:`STOP` button, as well as a button to :guilabel:`Enable Joystick`/:guilabel:`Disable Joystick`.
|
||||
|
||||
.. Note::
|
||||
|
||||
* The joystick button will only appear if the ``configuration.yaml`` file specifies which axes are controlled by the joystick. For example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
stage:
|
||||
hardware:
|
||||
-
|
||||
name: stage
|
||||
type: PI
|
||||
axes: [x, y, z, theta, f]
|
||||
axes_mapping: [1, 2, 3, 4, 5]
|
||||
joystick_axes: [x, y, z]
|
||||
|
||||
* Any stage axes that are loaded as a `synthetic_stage` will have disabled buttons.
|
||||
|
||||
By default, the stage is expected to have ``X``, ``Y``, ``Z``, ``Focus`` and ``Theta`` (rotation) axes. If a stage does not have one of these axes, the user can choose to not use that control. See the :ref:`stage subsection <configure_stages>` for more information.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_stage_positions:
|
||||
|
||||
Stage Positions
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
The entry boxes report the current position of each stage axis. If a user changes a value in an entry box, the stage axis will move to that value (provided it is within the stage bounds if stage limits are enabled, see :any:`here <stage_control_menu>`).
|
||||
|
||||
.. Warning::
|
||||
|
||||
If the value in the entry box is changed, the stage will move to that value. Such actions may result in the stage crashing into the sample or the objective lens. As such, we highly recommend that you keep the stage limits enabled.
|
||||
|
||||
-------------------
|
||||
|
||||
XY Movement
|
||||
^^^^^^^^^^^
|
||||
|
||||
This includes the movement buttons for the ``X`` and ``Y`` axes. The left and right buttons control ``X``, while the up and down buttons control ``Y.`` The entry box in the middle of the buttons indicates the step size along these axes in microns. It can be changed by the user.
|
||||
|
||||
-------------------
|
||||
|
||||
Z Movement
|
||||
^^^^^^^^^^
|
||||
|
||||
This controls the movement of the ``Z`` stage. The entry box indicates the step size along this axis and it can be changed by the user.
|
||||
|
||||
-------------------
|
||||
|
||||
Focus Movement
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
This controls the movement of the ``Focus`` stage. The entry box indicates the step size along this axis and it can be changed by the user.
|
||||
|
||||
-------------------
|
||||
|
||||
Theta Movement
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
This controls the movement of the ``Theta`` stage (i.e., sample rotation). The entry box indicates the step size along this axis and it can be changed by the user.
|
||||
|
||||
-------------------
|
||||
|
||||
Buttons
|
||||
^^^^^^^
|
||||
|
||||
The :guilabel:`STOP` button halts all stage axes and updates the stage positions to wherever the stage stopped.
|
||||
|
||||
The :guilabel:`Enable Joystick` button disables control over the axes associated with the joystick (see the :ref:`stage subsection <configure_stages>`).
|
||||
|
||||
.. note::
|
||||
|
||||
It is not necessary to press this button to use a joystick. The joystick can be used along with the software controls. However, if a user is running the acquisition in "Continuous Scan" mode and uses the joystick without pressing :guilabel:`Enable Joystick`, the stage positions may not update unless :guilabel:`STOP` is also pressed. In "Continuous Scan" mode, if a user tries to move with the joystick and then the software stage controls without first pressing :guilabel:`STOP`, it is likely the stage will update to the software's position of choice and undo the joystick movement.
|
||||
|
||||
.. tip::
|
||||
|
||||
For a large monitor, it is often helpful to convert the :guilabel:`Stage Control Settings Notebook` to a popup. Right click on the tab and press :guilabel:`Popout Tab`.
|
||||
|
||||
.. image:: images/popout_right_click.png
|
||||
|
||||
|
|
||||
|
||||
Once this is done, it should be possible to move the stage controls next to the main **navigate** window.
|
||||
|
||||
.. image:: images/popout_stage.png
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_multiposition:
|
||||
|
||||
Multi-Position
|
||||
--------------
|
||||
|
||||
.. image:: images/settings_multiposition.png
|
||||
|
||||
The :guilabel:`Multiposition` Settings Notebook is a tab (optionally, a popup) that helps the user set up and visualize a multi-position acquisition for tiling a large sample. It is split into two parts: buttons and the multi-position table.
|
||||
|
||||
-------------------
|
||||
|
||||
Multi-Position Buttons
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* :guilabel:`Launch Tiling Wizard` launches the :ref:`Tiling Wizard <ui_multiposition_tiling_wizard>`
|
||||
* :guilabel:`Eliminate Empty Positions` is not implemented and does nothing.
|
||||
* :guilabel:`Save Positions To Disk` saves the multi-position table to a file.
|
||||
* :guilabel:`Load Positions From Disk` loads a multi-position file into the table.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_multiposition_table:
|
||||
|
||||
Multi-Position Table
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The multi-position table lists stage positions that are included in a multi-position acquisition.
|
||||
|
||||
* :kbd:`Double-clicking` on the integer to the left of a row moves the stage to that position.
|
||||
|
||||
* :kbd:`Double-clicking` on a table cell allows the user to edit the stage position in that cell.
|
||||
|
||||
* :kbd:`Right-clicking` on the integer to the left of a row yields a popup with four options:
|
||||
|
||||
.. image:: images/multiposition_right_click.png
|
||||
|
||||
* :guilabel:`Insert New Position` adds an empty row to the table.
|
||||
* :guilabel:`Add Current Position` adds a row containing the current stage position to the table.
|
||||
* :guilabel:`Add New Position(s)` yields a popup that asks the user how many new rows to add and then inserts that number of empty rows upon confirmation.
|
||||
* :guilabel:`Delete Position(s)` deletes the selected positions. Selection is indicated by a blue highlight of the integer to the left of a row.
|
||||
|
||||
-------------------
|
||||
|
||||
Display Notebooks
|
||||
==================
|
||||
|
||||
The display notebooks provide visual feedback of the images taken on the camera and of the galvo and remote focus waveforms sent to the DAQ.
|
||||
|
||||
-------------------
|
||||
|
||||
Camera View
|
||||
-----------
|
||||
|
||||
.. image:: images/display_camera.png
|
||||
|
||||
The :guilabel:`Camera View` Notebook is a tab (optionally, a popup) that is split into two parts. The left part displays the latest image acquired by the camera. The right part modifies this display and is split into :guilabel:`LUT`, :guilabel:`Image Metrics`, and :guilabel:`Image Display`.
|
||||
|
||||
:kbd:`Left-clicking` on the image toggles crosshairs that indicate the center of the field of view.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_lut:
|
||||
|
||||
LUT
|
||||
^^^
|
||||
|
||||
The :guilabel:`LUT` section of the camera view allows the user to change the lookup table the image uses to display. The options are :guilabel:`Gray`, :guilabel:`Gradient`, and :guilabel:`Rainbow`.
|
||||
|
||||
:guilabel:`Flip XY` transposes the image in the display. This can produce intuitive results in the display when clicking on the ``X`` or ``Y`` stage movements buttons (i.e. with :guilabel:`Flip XY` enabled, the sample moves along the direction expected when a stage movement button is clicked).
|
||||
|
||||
:guilabel:`Autoscale` toggles automatic image histogram scaling on and off. When :guilabel:`Autoscale` is enabled, the image automatically scales intensity between the minimum and maximum pixel value in the image produced by the camera. When :guilabel:`Autoscale` is disabled, the image is scaled between :guilabel:`Min Counts` and :guilabel:`Max Counts`.
|
||||
|
||||
-------------------
|
||||
|
||||
Image Metrics
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
:guilabel:`Frames to Avg` is unimplemented, but should average this many frames coming from the camera and display the average in the viewer. It will be implemented in future releases of the software.
|
||||
|
||||
:guilabel:`Image Max Counts` displays the maximum pixel count in the image.
|
||||
|
||||
:guilabel:`Channel` indicates which color channel is displayed. It indexes into the selected channels in the :ref:`Channel Settings <ui_channel_settings>` (i.e. ``0`` is the first selected channel).
|
||||
|
||||
-------------------
|
||||
|
||||
Image Display
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
This toggles between a live mode and maximum projections in multiple dimensions. This is useful for visual inspection of the data as it is being acquired, and will be implemented in future releases of the software.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_waveform_settings:
|
||||
|
||||
Waveform Settings
|
||||
-----------------
|
||||
|
||||
.. image:: images/display_waveform.png
|
||||
|
||||
:guilabel:`Waveform Settings` is a tab (optionally, a popup) split into two sections: a waveform display section at the top and a :guilabel:`Settings` section at the bottom.
|
||||
|
||||
-------------------
|
||||
|
||||
Waveform Display
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The waveform display shows the waveforms sent to the remote focus devices (top) and the galvos (bottom). Each channel and each device gets its own color, which is then displayed in the legend. The dotted black line indicates when the camera is acquiring in relation to the waveforms. This can be considered identical to what is sent to the DAQ.
|
||||
|
||||
-------------------
|
||||
|
||||
Settings
|
||||
^^^^^^^^
|
||||
|
||||
:guilabel:`Sample Rate` changes the frequency of the samples sent to the DAQ. It is not recommended that a user change this.
|
||||
|
||||
:guilabel:`Waveform Template` changes the :ref:`waveform template <configure_waveform_templates>` used to generate the waveforms.
|
||||
|
||||
-------------------
|
||||
|
||||
Additional GUIs
|
||||
===============
|
||||
|
||||
This section includes popups and other non-main sections of the GUI.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_file_save_dialog:
|
||||
|
||||
File Saving Dialog
|
||||
------------------
|
||||
|
||||
.. image:: images/save_dialog.png
|
||||
|
||||
The file saving dialog pops up if an :ref:`acquisition mode <ui_acquisition_bar>` other than "Continuous Scan" is selected and :ref:`Save Data <ui_timepoint_settings>` is checked.
|
||||
|
||||
* :guilabel:`Root Directory` indicates the local directory to which the software will save the data.
|
||||
* :guilabel:`User` is the name of the user acquiring the data.
|
||||
* :guilabel:`Tissue Type` is the type of tissue being imaged.
|
||||
* :guilabel:`Cell Type` is the cell type being imaged.
|
||||
* :guilabel:`Label` indicates the dyes used in the acquisition.
|
||||
* :guilabel:`Solvent` indicates the immersion solvent of the tissue/cell.
|
||||
* :guilabel:`File Type` indicates what type of file to save to.
|
||||
* :guilabel:`Notes` is for any additional information the user wants to store with the file.
|
||||
|
||||
.. _ui_waveform_parameters:
|
||||
|
||||
Waveform Parameters
|
||||
-------------------
|
||||
|
||||
.. image:: images/waveform_parameters.png
|
||||
|
||||
This is used to update the waveforms shown in :ref:`Waveform Settings <ui_waveform_settings>`.
|
||||
|
||||
* For each laser, the :guilabel:`Amplitude` and :guilabel:`Offset` correspond to the amplitude and offset of the waveform sent to the remote focus device.
|
||||
* For each galvo, the :guilabel:`Amplitude` and :guilabel:`Offset` correspond to the amplitude and offset of the waveform sent to the galvo, by default a triangle wave.
|
||||
|
||||
* The :guilabel:`Galvo 0 Frequency (Hz)` sets the frequency of the waveform sent to the galvo. :guilabel:`Estimate Frequency` estimates the frequency needed for a sawtooth wave to sweep over the camera region of interest without aliasing with the light-sheet for a given rolling shutter size and speed (e.g., in a digitally scanned light-sheet format).
|
||||
* Additional galvos from the :ref:`configuration file <configuration_file>` file are incrementally added here (e.g., :guilabel:`Galvo 1 Frequency (Hz)`, ...).
|
||||
* :guilabel:`Percent Delay` introduces a delay before the remote focus waveform starts.
|
||||
* :guilabel:`Percent Smoothing` smooths the remote focus waveform.
|
||||
* :guilabel:`Settle Duration (ms)` introduces a delay after the remote focus sawtooth ends.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_configure_microscopes:
|
||||
|
||||
Configure Microscopes
|
||||
---------------------
|
||||
|
||||
.. image:: images/configure_microscopes.png
|
||||
|
||||
The :guilabel:`Configure Microscopes` window allows a user with multiple microscopes defined in their :ref:`configuration file <configuration_file>` to select which microscope is primary and launch both microscopes simultaneously. The primary microscope will have control over any hardware shared between both microscopes. This window also provides a GUI interface to look at what hardware is in use.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_multiposition_tiling_wizard:
|
||||
|
||||
Multi-Position Tiling Wizard
|
||||
----------------------------
|
||||
|
||||
.. image:: images/tiling_wizard.png
|
||||
|
||||
The tiling wizard helps the user set up a tiled acquisition of a sample large enough that it cannot be imaged in a single field of view.
|
||||
|
||||
* :guilabel:`Set <axis> Start` indicates the starting position of an axis.
|
||||
* :guilabel:`Set <axis> End` indicates the end position of an axis.
|
||||
* :guilabel:`<axis> Distance` indicates difference between the start and end position.
|
||||
* :guilabel:`<axis> FOV Dist` indicates the field of view along that axis. The Distance between start and end will be split into tiles of this size along this axis.
|
||||
* :guilabel:`Num. Tiles` indicates how many tiles exist along this axis. It is roughly (End - Start)/FOV dist.
|
||||
* :guilabel:`% Overlap` indicates the percent of the tile that should overlap along each axis. It is a percent of the FOV Dist.
|
||||
* :guilabel:`Populate Multi-Position Table` puts all of the tiles in the :ref:`multi-position table <ui_multiposition_table>`.
|
||||
|
||||
For an example of how to use the tiling wizard, see :ref:`Tiling a sample larger than the field of view <acquire_mesospimbt_tiling>`.
|
||||
|
||||
-------------------
|
||||
|
||||
.. _ui_autofocus:
|
||||
|
||||
Autofocus Settings
|
||||
------------------
|
||||
|
||||
.. image:: images/autofocus_settings.png
|
||||
|
||||
The :guilabel:`Autofocus Settings` panel controls parameters of the autofocus :ref:`feature <user_guide_features>`.
|
||||
|
||||
* :guilabel:`Device Type` indicates if the autofocus routine should be applied to a stage or to a remote focus device.
|
||||
* :guilabel:`Device Reference` indicates the stage axis, or the DAQ analog output for the remote focus device, to use.
|
||||
* The :guilabel:`Coarse` and :guilabel:`Fine` rows allow users to select a range and step size, both in microns (or volts, if using the remote focus device), over which the autofocus routine should search for an optimal focus value. If coarse and fine are selected, the coarse search will be performed first and the fine search will be performed about the coarse position with the highest value.
|
||||
* :guilabel:`Inverse Power Tent Fit` will attempt to find a more accurate position for the optimal focus based on fitting a power tent to the search values. It will only use the fit if its :math:`R^2` value is higher than ``0.9``.
|
||||
* :guilabel:`Autofocus` runs the autofocus with the set parameters.
|
||||
|
||||
Once the settings have been updated here, any run autofocus operation will use the new settings.
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
@@ -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>`.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 112 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 128 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 109 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1013 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 763 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 132 KiB |
@@ -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
|
||||
28
docs/source/02_user_guide/04_microscope_setup/03_snr/snr.rst
Normal file
28
docs/source/02_user_guide/04_microscope_setup/03_snr/snr.rst
Normal file
@@ -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.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user