chuan/navigate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: init

Browse Source
This commit is contained in:
chuan
2025-12-04 16:07:30 +08:00
commit 262583a57f
681 changed files with 117578 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

288
docs/source/02_user_guide/01_supported_hardware/camera.rst Normal file
View 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
View 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
View 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``

59
docs/source/02_user_guide/01_supported_hardware/deformable_mirror.rst Normal file
View File

@@ -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
View 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
View 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
View 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
|

26
docs/source/02_user_guide/01_supported_hardware/hardware_home.rst Normal file
View File

@@ -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

BIN
docs/source/02_user_guide/01_supported_hardware/images/6259_pinout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

BIN
docs/source/02_user_guide/01_supported_hardware/images/6723_pinout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 70 KiB

BIN
docs/source/02_user_guide/01_supported_hardware/images/6738_pinout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

151
docs/source/02_user_guide/01_supported_hardware/laser.rst Normal file
View 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
View 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
View 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
View 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
View 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
View 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
|