====== Micro-manager diSPIM Plugin  ======

Micro-Manager comes with a plugin providing a GUI which facilitates alignment and use of the diSPIM system.

Micro-Manager is a free and open-source software package with many capabilities available at https://micro-manager.org/. If you are not familiar with Micro-Manager it is worth reading the [[https://micro-manager.org/wiki/Micro-Manager_User%27s_Guide|User Guide]] and [[https://micro-manager.org/wiki/Micro-Manager_Configuration_Guide|Configuration Guide]] before proceeding. Micro-manager is continually being improved. If you discover problems there is an easy way to report it to the developers under .

The diSPIM plugin is already fully functional but also continually being improved; accessing new features is as simple as installing the latest Micro-Manager version (nightly builds are usually functional and include the latest improvements to the plugin and the rest of Micro-Manager; a major release happens every quarter). If you encounter problems or have feature requests please contact the plugin authors.

===== Plugin Overview =====

In the main Micro-Manager window you can open the plugin under . Keep the main Micro-Manager window accessible; the plugin generally does not duplicate functionality already provided there. The plugin has different tabbed panels for accessing different plugin features for performing various tasks.

The GUI remembers most of its settings from run to run. Some settings are stored on the Tiger controller (e.g. sheet sizes). Before mid-November 2014 some settings were only stored when the plugin was closed before Micro-Manager.

===== Before Running the Plugin =====

Before running the diSPIM plugin, you should create or load a Micro-Manager hardware configuration with all the relevant devices. In the Hardware Configuration Wizard () add the Tiger controller () and then load all of its peripherals (with the possible exception of the LED shutter). Add the cameras, including creating two devices for the two SPIM cameras for diSPIM systems.

For diSPIM, you should also create a Multi Camera instance (in the Hardware Configuration Wizard, use ). You should assign the properties “MultiCam-Physical Camera 1” and “MultiCam-Physical Camera 2” to the two cameras, ideally using the special “System” configuration group with preset name “Startup” as described in the [[https://micro-manager.org/wiki/Utilities#Multi-Camera|Micro-manager wiki page]].

===== Devices Tab =====

Here you assign Micro-Manager devices to roles within the plugin. This is required before using most of the plugin’s features, but is you will only need to re-visit this tab if you change hardware configurations in Micro-Manager or if you launch the plugin without the devices loaded, thus causing the plugin’s settings to be overwritten.

For diSPIM mounted on non-ASI inverted microscope frames the “Lower Z Drive” device may partially work, depending on support in Micro-Manager support for that linear stage.

“Path A” and “Path B” refer to the two light paths as noted in Section [sub:Connecting-cables] and shown in the figure of the plugin’s Device tab for reference. The scanner (micro-mirror) and illumination piezo will be one one side of the physical microscope, and the imaging piezo and camera will be on the opposite side. For the scanners and piezos care must be taken to match the plugin device assignment with the physical hardware. For ASI’s typical controller configuration, for “Path A” you should select the scanner with axes A and B (usually the left scanner), imaging piezo as axis P (usually right piezo), and the camera which is connected to the right side of the physical microscope. The lower (inverted) Z drive is axis Z, and the upper Z drive (on which the SPIM assembly rides) is axis F. In Figure [fig:Device-tab-example] shows a typical way the Device Tab would be filled out; this is a typical diSPIM configuration except no bottom camera is used.

For single-sided (iSPIM) you can leave the “Path B” devices blank.

<imgcaption plugin_Devices| [fig:Device-tab-example]Device tab example.>{{:docs:manual/plugin_Devices.png?600| [fig:Device-tab-example]Device tab example.}}</imgcaption>

Support for the SPIM cameras must be added to the plugin code on a case-by case basis.((The main reason why arbitrary cameras cannot be used is that the SPIM cameras are TTL-triggered during SPIM acquisition but triggered by Micro-Manager during alignment. Thus, the plugin has to know how to switch the cameras between internal trigger mode and external trigger mode, and thus the relevant properties need to be hard-coded into the plugin. Hopefully in the future there will be a camera API call in Micro-Manager to change triggering modes.
)) Please contact the plugin authors with requests to add support for other cameras. Currently the supported cameras are:

  * Andor sCMOS cameras. Use the AndorSDK3 adapter. The bit depth defaults to 12-bit but if you want different the best fix is to add an assignment in Micro-Manager’s “System” group “Startup” preset (see the [[https://micro-manager.org/wiki/Micro-Manager_Configuration_Guide|Configuration Guide]]).
  * Hamamatsu Flash 4. Use the HamamatsuHam device adapter. Trigger polarity defaults to negative; the best fix is to add an assignment in Micro-Manager’s “System” group “Startup” preset (see the [[https://micro-manager.org/wiki/Micro-Manager_Configuration_Guide|Configuration Guide]]).
  * PCO Edge. Use the PCO_Camera adapter. Property PixelRate defaults to slow, but for fast frame rates you probably want the fast scan; the best fix is to add an assignment in Micro-Manager’s “System” group “Startup” preset (see the [[https://micro-manager.org/wiki/Micro-Manager_Configuration_Guide|Configuration Guide]]).

===== Acquisition Tab =====

In the Acquisition tab, shown in <imgref plugin_acquisition>, you set the parameters for the SPIM acquisition and initiate acquisition. This panel is analogous to the Multi-D acquisition window in Micro-Manager, except that the positions of the imaged volume are not specified here. On this tab the joystick and wheels are not functional by default, although a check box is present to enable the same joystick settings as on the Navigation panel.

<imgcaption plugin_acquisition| The acquisition tab of the diSPIM plugin with advanced timing settings disabled.>{{:docs:manual/plugin_acquisition.png?600| The acquisition tab of the diSPIM plugin with advanced timing settings disabled.}}</imgcaption>

==== Setting the 3D ROI ====

Use the Setup tabs to specify the center slice position. The number of slices per volume and the slice step size determine how far on each side of the center position is imaged.

Use Micro-Manager’s usual mechanism to specify the ROI of the two SPIM cameras. Documentation in the [[https://micro-manager.org/wiki/Micro-Manager_User%27s_Guide#Region_of_Interest_.28ROI.29|Micro-manager User’s Guide]].

==== Time Points ====

Here you specify the number of time points and the interval between them.((The plugin actually triggers separate single-volume acquisitions in the controller. It is technically possible but not currently implemented to use the controller to set up repeated acquisitions.
)) The amount of time for the entire acquisition (all time points) is displayed. If the checkbox is left unchecked then only a single time point will be collected.

==== Data Saving Settings ====

Here specify where and how the data is saved.

  * Separate viewer / file for each time point: performs a separate Micro-Manager acquisition for each time point, implying a separate viewer window and separate file. In general it is better to let Micro-Manager save all time points to a single file. Currently a bug prevents proper operation with separate viewers if “Hide viewer” is also selected.
  * Hide viewer: suppresses the Micro-Manager viewer. Note that hiding the viewer is cosmetic only, it does not improve the computer’s ability to stream acquisition data to disk because the data collection runs in its own thread.
  * Save while acquiring: saves the data to disk; if unchecked then data will be saved in RAM and the user will have the option to save it later. Obviously, for large acquisitions the data must be saved to disk directly.

==== SPIM Mode ====

Currently several modes are supported:

  * Synchronous piezo/slice scan: standard use, the piezo and sheet move together through the sample.
  * Slice scan only: suppresses movement of piezo but still moves the light sheet. It is useful for characterizing light sheet thickness.
  * No piezo or slice scan: neither the piezo nor light sheet moves. It is useful for characterizing vibration in the system.
  * Stage scan: uses the XY stage to move the sample through a fixed light sheet. Requires scan-enabled firmware on the Tiger XY card, and also requires a XY card Rev F2 or later with a jumper in place (standard on systems sold from late 2014, contact ASI if you are unsure).
  * Stage scan interleaved: same as stage scan except that the stage moves half the speed and the two light paths alternate.

==== Acquire Button ====

Obvious function. Click it during an acquisition to abort. The status string informs you which time point is being acquired.

==== Multiple Positions (XY) ====

If the box is checked, the plugin will use Micro-Manager’s position list to acquire volumes and multiple locations. For each time point, each position is visited once. See the section “[[https://micro-manager.org/wiki/Micro-Manager_User%27s_Guide#Position_List_Dialog|Position List Dialog]]” of Micro-Manager’s User’s guide for more details about using the position list.

==== Channels ====

The channels feature is patterned after that of Micro-Manager’s Multi-D Acquisition (documentation in the [[https://micro-manager.org/wiki/Micro-Manager_User%27s_Guide#Multi-dimensional_acquisition|User’s Guide]]). It is most commonly used to take volumes with different colors. Using the channels feature requires creating a group of presets which contain all the settings for that channel. Selecting that group in the pull-down menu and then the desired presets.

Simple per-volume channel switching is implemented and is the only choice unless a Programmable Logic Card (PLC) is present in the controller; this mode is generic and can be used with any Micro-Manager group. PLC-based channel switching is hardware-based, requiring extra setup time but then no delay during acquisition. Using the PLC, channel switching is possible on both a per-volume and per-slice basis. In this case the channel group must contain the property “Output Channel” which is used to select the correct laser to trigger; other properties in the channel group, if any, are ignored.

==== Volume Settings ====

These settings determine Use the parameters in the “Volume Settings” group to set up the stacks collected as follows.

  * Number of sides: 2 for diSPIM, 1 for single-sided.
  * First side: which of Path A or Path B goes first.
  * Delay before side: wait period after initiating the side (moving the illumination objective into position and the imaging piezo to its start position) before beginning stack acquisition.
  * Slices per volume: number of frames to acquire on each side.
  * Slice step size: increment of imaging piezo (and light sheet will follow) for each slice, i.e. the Z-stack step size.
  * Minimize slice period: when checked the plugin will go as fast as possible.
  * Slice period: requested period of each slice, if not minimized.
  * Sample exposure: requested illumination time. Currently limited to half-integer values in milliseconds with integer steps.
  * Calculate slice timing: calculates and populates the controller’s timing parameters based on the current ROI and settings above.
  * Use advanced timing settings: when checked the controller timing settings can be edited directly in a pop-up window. Use this if you want to adjust the values that the plugin computes.

The time required for acquiring each slice, a single volume, and the total acquisition is displayed in the “Durations” box in the upper left.((The actual time of the stack (and also the slice period) may be slightly longer due to the firmware implementation details.))

==== Advanced Timing Settings ====

The detailed controller timing settings are hidden by default but can be changed if the “Use advanced timing settings” box is checked. See ASI’s TG-1000 SPIM documentation for timing diagrams and further details.

The advanced timing settings have correspondence to controller settings (see TG-1000 SPIM documentation) as follows:

  * Delay before scan: time before scan begins (gives piezo stages time to move/settle before sheet acquisition is started). (NV X)
  * Line scans per slice: how many one-way beam scans per slice. (NR X)
  * Line scan period: time for one sweep of the beam (SAF <axis>)
  * Delay before laser: delay before laser trigger is fired. (NV R)
  * Laser duration: duration of the laser trigger. (RT R)
  * Delay before camera: delay before camera trigger is fired. (NV T)
  * Camera duration: duration of camera trigger. (RT T). In current version of the plugin, the camera exposure is set to this value as well for edge triggering, or set to 1 ms for overlap/synchronous mode.((In the future we would like to utilize level triggering as well.))

==== Easy Timing Mode ====

By default the controller’s timing settings are not directly accessible; instead specify the “Slice period [ms]” and “Laser exposure [ms]” in the Volume Settings. Use the button “Calculate slice timing” to automatically calculate the controller’s timing parameters. The timing depends on the reset and readout time of the cameras, which is computed according to the ROI as specified using the main Micro-Manager window. Any extra time in the slice is placed before the camera trigger to allow maximum time for piezo settling. The values computed by the easy timing mode are shown in the slice timing settings and can be subsequently modified manually.

The basic algorithm that the easy timing mode uses is described here for the curious. Only one line scan per slice is used. Each period consists of camera readout time, then any extra delay time, then camera reset time, then beam scan time. During beam scan time, the laser is off for the first 0.25 ms and last 0.25 ms of the scan and on otherwise (because the beam scan is limited to increments of 1 ms then the laser exposure time must be a half-integer number of milliseconds). An empirical scanner delay according to its Bessel filter is included (so the scan signal is shifted slightly earlier). Times are rounded to the nearest 0.25 ms except the camera readout and reset times which are always “rounded up” to the next multiple of 0.25 ms. Camera reset and readout times are computed according to manufacturer’s timing information and the ROI; they try to account for worst-case jitter. The camera readout time is set to 0 if the “Overlap” on “Synchronous” mode of the cameras is used.

===== Setup Tabs =====

There are two setup tabs, one for each optical path. This tab is essential during diSPIM alignment, and it is also used to set the center position of the imaging piezo (by extension the center of the imaged 3D volume). If you have a single-sided (iSPIM) system then ignore the second tab.

<imgcaption plugin_Setup| The Setup panel of the diSPIM plugin.>{{:docs:manual/plugin_Setup.png?600| The Setup panel of the diSPIM plugin.}}</imgcaption>

==== Tab-specific joystick, sheet, and camera controls[sub:Tab-specific-joystick-sheet-camera] ====

Each setup tab has an independent set of joystick/wheel controls, beam controls, and camera control. These settings belong to the tab; e.g. the joystick settings can be separately specified for the two different Setup tabs. The joystick settings become active when switching to the tab. The beams settings on this panel will be automatically set on changing to this tab if the “Change settings on tab activate” box is selected, otherwise the beam settings will remain the same as they were before switching tabs. The beam control uses the scanner “blanking” feature, so it assumes that both scanners have input light (e.g. a passive splitter between the laser and the scanner). Unless the “No change” option is selected, the camera will automatically be set to the specified camera when the tab is selected.

Similar controls exist on the Navigation tab.

==== Imaging center and calibration display ====

The center position for the imaging piezo is shown and can be changed on the top line of the right side. When the “Set” button is clicked, the current imaging piezo position is selected as the new center. This setting is crucial for acquisitions, but can be ignored during alignment.

The up and down arrows in the far upper right of the Setup tab move the piezo and slice together according to the calibration relationship. The amount of piezo travel per button click is set just to the left of the arrow buttons. This is useful for checking whether the calibration relationship is correct, and also for moving through an actual object of interest to make sure that acquisition settings are correct.

==== Position display and sheet control ====

The position of the slice is shown, along with the positions of both the imaging and illumination piezos. You can enter a specific position for the axis to move to using the white-background text entry boxes.

For single-sided operation there is no piezo stage on the illumination side. For diSPIM, the illumination piezo has a special home position where it goes while being used for illumination (recall that the imaging piezo will be moving along with the slice position). The illumination piezo will automatically go to this home position when the tab is selected if the Go home on tab activate is checked.

The sheet width and offset affect the sheet dimensions, i.e.  the width and center position of the illuminated area. The + and - buttons change the value in small amounts; the sliders are easier to use for making large changes.

==== Setting piezo vs. slice calibration ====

After alignment is complete the scanner movement in the slice direction needs to be cross-calibrated with the imaging piezo. During volume acquisition, they will move together through the sample to create a stack of images.

Both the piezo objective movers and micro-mirror-based scanners have decent intrinsic linearity, so it suffices to identify two distinct locations where the piezo is focused on the light sheet and compute a linear relationship between the scanner position and imaging piezo. The plugin identifies these as “Calibration Start Position” and “Calibration End Position”.((It does not matter which of the two points is “start” and which is “end”.
)) After these two special positions are set using the red-bordered button, click the green-bordered button labeled “2-point” (originally “Compute pizeo vs. slice calibration”) to populate the slope and offset of the calibration relationship. The computed values can be manually tweaked if desired. The slope and offset will be used during acquisition along with the (piezo’s) imaging center position to move the piezo and sheet together through the sample while the image stack is acquired.

During normal operation the offset will drift slightly, however the slope will remain relatively constant. Clicking on the green-bordered button labeled “Offset” will adjust the calibration offset without changing the slope. The new calibration offset is based on the //current// position, so the beam should be in focus when you click it.

The recommended procedure to set the calibration start and end positions is as follows:

  - Introduce a fluorescent dye or bead sample where the sheet can be easily visualized, in particular whether the imaging piezo is in focus.
  - Make sure the upper Z stage and illumination piezo are in good positions.
  - Move the imaging piezo to what will be approximately one end of the image. For example, if you are imaging an object that is 50 um across (and the imaging center is close to zero), move the imaging piezo to 25 um. You can do that by manually entering the imaging piezo’s position.
  - Use a joystick knob to move the scanner’s slice position until the beam is in focus. In a dye solution this is easiest when the sheet is turned off, or with a bead slide it is easiest when the sheet is turned on.
  - Click the red-bordered “Set” button under “Calibration Start Position”.
  - Move the imaging piezo to the other end of the imaging piezo’s normal range, e.g. -25 um for this example.
  - Use the joystick knob to move the scanner’s slice position again until the beam is in focus.
  - Click the red-bordered “Set” button under “Calibration End Position”.
  - Click the “Go to” buttons for both start and stop to make sure that the imaging piezo and scanner’s slice position are correct (i.e.  beam in focus) at both points.
  - Click the green-bordered “Compute piezo vs. slice calibration” button to compute the slope and offset of the calibration relationship.
  - Check the computed calibration using the up and down arrows in the upper right of the Setup tab (you may need to increase the increment before doing this).

===== Navigation Tab[sub:Navigation-Tab] =====

The Navigation tab (Figure [fig:Navigation-panel]) allows the user to easily view and change the position of all ten diSPIM axes. The position of all available axes are visible. By default positions they are updated once per second; see the Settings tab to enable/disable updates and change the update interval.

Below the tab names there is a “quick glance” indication of positions to avoid needing to return to the Navigation tab just to make sure an axis is centered. The color code is as follows:

  * Gray = no device
  * Green = centered
  * Orange = near center
  * Red = far from center
  * Pink = making sheet (scanner only)
  * Black = beam turned off (scanner only)

<imgcaption plugin_Navigation| The Navigation panel of the diSPIM plugin.>{{:docs:manual/plugin_Navigation.png?600| The Navigation panel of the diSPIM plugin.}}</imgcaption>

Like the Setup tab, there are tab-specific joystick, beam, and camera controls. See Section [sub:Tab-specific-joystick-sheet-camera] for details. You can enter a specific position for the axis to move to using the white-background text entry boxes to the immediate right of the current position.

The white-background text entry boxes between the “–” and “+” buttons specifies an increment that the “-” and “+” buttons will move each click.

A button is provided to move each axis to the zero position. It is very useful to move the upper and lower Z axes to the imaging position, then use the “Set 0” button to set that position as zero so it can be easily returned there with a single button click.

Finally, clicking the “Halt!” button will send a command to the Tiger controller to stop the movement of all axes; this is useful mainly if a crash is about to happen.

===== Settings Tab =====

The Settings tab (<imgref plugin_Settings>) contains various settings not belonging elsewhere.

<imgcaption plugin_Settings| The Settings panel of the diSPIM plugin.>{{:docs:manual/plugin_Settings.png?600| The Settings panel of the diSPIM plugin.}}</imgcaption>

The micro-mirror drive card has adjustable Bessel output filters to protect the filter from being driven near its mechanical resonance (usually 2 kHz). Settings as high as 0.8 kHz are usually acceptable, and in general the shorter the scan period (and faster frame rates) the more this matters.

The camera triggering mode is specified here. For Andor Zyla and Hamamatsu Flash4 cameras there is the possibility to have consecutive triggers determine the start and end of a image capture; this is termed respectively “Overlap” and “Synchronous” by the manufacturers. Because the image sensor is simultaneously read out and also reset to begin the subsequent exposure, the camera overhead time is reduced and it allows for faster camera frame rates.((t_frame ~= t_global - t_readout, with overlap mode, t_frame ~= t_global - 2*t_readout otherwise)) The same mode is not available with the PCO Edge, however, a new exposure can begin shortly after the readout starts which we refer to as “Pseudo Overlap”.

===== Data Analysis Tab[sub:Data-Analysis-Tab] =====

In the future we would like to include the ability to manipulate the acquired data including registration of the two views and joint deconvolution directly in the diSPIM plugin. At present the Data analysis tab (<imgref plugin_DataAnalysis>) allows exporting the acquired data to the format required by the MIPAV GenerateFusion plugin and Fiji’s Multiview Registration plugin. In the latter case, the XML file that would normally be generated in the “Define Dataset” sub-plugin is performed during data export.

Also in this tab there are some buttons to access commonly-used ImageJ commands. They are simply shortcuts to the ImageJ commands, so they operate on the top-most image window.

<imgcaption plugin_DataAnalysis| The Data Analysis panel of the diSPIM plugin.>{{:docs:manual/plugin_DataAnalysis.png?600| The Data Analysis panel of the diSPIM plugin.}}</imgcaption>