• Created by Unknown User (iyerv), last modified on Nov 04, 2008

toc:minLevel=2|indent=10px}

About Current and Upcoming Releases

This new release has been developed primarily to support ScanImage users who no longer have ready access to the older Matlab version for which earlier ScanImage releases had been developed. It is also now compatible with the newer National Instruments driver (DAQmx), which many users may prefer to install instead of the older drivers ('Traditional NI-DAQ'). It is anticipated that this version will remain compatible with current and upcoming Matlab versions.

In addition, a handful of new features have been added to help support ongoing experiments by ScanImage users at Janelia Farm Research Campus.

Plans are underway to significantly rewrite ScanImage from the ground-up, in order to better support a growing number of laser scanning devices and applications. In addition, ScanImage will become integrated with the Ephus project, in order to allow for consistent conventions for file saving, configuration switching, and other crucial components of a general-purpose neurophysiology data acquisition software package.

We welcome feedback on ScanImage 3.5 and certainly will address any critical deficiencies that may be identified. Please note that any significant requests are more likely to be incorporated into plans for the new ScanImage package.

New Feature Summary

  • Compatibility with current Matlab/National Instruments releases (R2007B/DAQmx 8.6)
  • Real-time RGB channel 'merge' display during Focus mode
  • Disk-logging Grab/Loop acquisitions
  • 'Infinite' focus mode
  • Ability to accept external trigger (using separate trigger input terminal; facilitates Ephus-driven acquisitions)
  • 'Bidirectional' scan capability, enabling fast <1ms/line scans
  • Command-line utility functions for commonly-needed tasks, including beam-parking and 'cusp'-delay optimization
  • Extended 'hot-key' functionality to support rapid configuration switching

New Feature Details

Matlab/National Instruments Version Compatibility

ScanImage 3.5 can be run on Matlab 2007B and has been tested with National Instruments DAQmx driver version 8.6.0.  The previous ScanImage version (3.0) is compatible with up to Matlab version 6.5 (R13) and with up to the last National Instruments 'Traditional NI-DAQ' driver (version 7.4.4).

If both drivers are installed on a machine, then the Traditional NI-DAQ driver will be used. Not all features will be supported. Furthermore, this scenario has not been as fully tested. 

Matlab versions between R13 and 2007A had several problems with the Data Acquisition toolbox and are not recommended. We recommend using either R2007A or 2007B at this time. As of this date, R2008A has not been tested with ScanImage 3.5.

Real-time RGB Channel Merge

Display of an RGB 'merge' acquisition channel can be activated by selecting Settings >> Merge Channel from the Main Controls window menubar (indicated by checkmark). This window is like the other acquisition and max projection windows---its position, size, etc. are stored in the .USR file. The window displays a color merge of each of the channels set to acquire. Channel 1 is green; channel 2 is red; channel 3 is blue. The merge simply combines each of the independent colors into an 8-bit RGB image, with the display of each color determined by the LUT values employed for each channel. 

Disk-Logging Grab Acquisitions


 
 

Infinite Focus & External Triggering



A checkbox on the Main Controls window, when selected, causes Focus mode acquisitions to be run indefinitely. Otherwise, as in v3.0, focus acquisitions terminate after the time given in the state.internal.focusTime parameter in the standard.ini file (defaults to 100s).

A toggle button on the Main Controls window, when depressed, causes Focus and Grab mode acquisitions to await an externally generated trigger. The external trigger should be connected to each of the National Instruments boards used by Scanimage (typically two boards, one for scanner/PMTs and one for the Pockels Cell) onto the terminal specified by the state.init.externalTriggerInputTerminal variable in standard.ini. Upon starting a Focus, Grab, or Loop acquisition, ScanImage will wait for the duration specified in the state.init.externalTriggerTimeout variable in standard.ini.

Bidirectional Scanning

The capability for bidirectional scanning has been added. With bidirectional scanning, the mirror(laser) scans symmetrically in both directions. In the "unidirectional" scans supported in v3.0, the laser returns to its start position rapidly (flyback) at the conclusion of each line scan.

Unidirectional scanning has the advantage of illuminating the specimen uniformly with time. Bidirectional scanning, on the other hand, is advantageous for fast scans, such as 1ms/line scans, which was not routinely possible in v3.0.  This is because bidirectional scans require less bandwidth.


 
Bidirectional scanning is specified via a checkbox in the Configuration window (Edit >> Configuration... from Main Controls menu), as shown below.
 
 

When bidirectional scanning is selected, the line delay parameters (including 'EOM Line Delay') are disabled. Because bidirectional scanning is symmetric, only one parameter -- the Cusp (Servo) Delay -- is required to represent the discrepancy between the control waveform and the actual mirror/servo response.

A utility function has been created to help adjust the 'Cusp (Servo) Delay' parameter correctly.

Note that bidirectional scans are not presently supported for rotated scans - i.e. the rotation value must be 0. This is due to the different sizes of the X & Y galvos. However, zoomed scans are possible.

Command-line Utility Functions

A number of utility functions with the prefix scim_ are made available to the user at the Matlab command-line. They are as follows:

  • scim_exit: Closes ScanImage, deleting all of its windows and underlying objects
  • scim_parkLaser: Allows the user to park the laser at a specified location in (or outside) the field-of-view, by specifying voltage levels to set the mirror command signals at
  • scim_alignBiDiScan: Allows the user to
  • scim_openTif: Opens ScanImage .TIF file. A renamed version of the originally distributed genericOpenTif() function.

Because all of the functions share the same prefix, the user can simply type the prefix ("scim") at the Matlab command-line and use tab-completion to see all of the utility functions listed.

Extended 'Hotkey' Functionality


Changes (from v3.0)

Startup & Initialization File

The startup selection screen is no longer active by default. The file scim_startup.m remains in the ScanImage installation, in the ScanImage\UserTools directory. Its contents can be copied to, or it can be invoked from, the startup.m file for a given Matlab installation (located at <MATLABROOT>\toolbox\local), if desired.

The initialization file supplied in the ScanImage installation (in the init_files folder) is now considered a model and therefor named standard_model.ini. It should not generally be edited directly. Individual users on a rig should copy this file to the same directory where they keep their user configuration (.USR) files. It should be edited to match specifics of their rig and renamed to standard.ini. ScanImage now automatically looks for a file named standard.ini in the same directory where the user file is selected on startup. (If no user file is specified, ScanImage prompts selection of a directory where a standard.ini file can be found; if none is specified, then the installation standard.ini file is used).

There are then two typical arrangements for a rig used by multiple users. In the first case, each user has their own standard.ini file, in their own .USR directory. As an alternative, all users can share a single standard.ini file, provided that all users also share a common .USR file directory.

If multiple .INI files are desired by a single user (not typical), then they should be located in the same directory as the .USR files and not named standard.ini. If no standard.ini file is found after loading a .USR file, ScanImage prompts to select a .INI file in that folder.

A principal advantage of the new scheme is that the configuration file is decoupled from the ScanImage installation. Therefore upgrading ScanImage, as new versions are released, requires simply pointing the path to a new installation folder (and revert by pointing back to a previous folder). The same standard.ini file is employed with each version. Occasionally, upgrades may require additions or changes to the standard.ini file, which will be reflected in the new version's standard_model.ini file. These changes will be clearly documented, to make upgrading/reverting as easy as possible.




Clock Synchronization

The Pockels Cell and mirror output boards are typically not the same. In this case, it is required that the clocks of these boards be synchronized to ensure that flyback blanking remains phase locked with the line scan signal.

In v3.0, this clock synchronization was done by using the RTSI7 terminal (also termed RTSI_OSC) on the RTSI (Real Time Synchronization Interface) available on the National Instruments boards.

In v3.5, synchronization synchronization is now on a terminal specified in the standard.ini file (search for 'outputBoardClockTerminal'). The default is now RTSI6, but can be specified as anything from RTSI<0-6> or PFI<1-9>. Note that RTSI7 is not an option for the clock synchronization terminal at this time. Therefore, RTSI connections made via a pair of wires (as opposed to a RTSI ribbon cable) should be changed from RTSI7 (and its ground) to the selected terminal (and its ground).

Documentation Amendments

The following points were either omitted or unclear in the ScanImage 3.0 documentation.

  • The Image Processing toolbox is required for complete ScanImage functionality. Without the toolbox, features (such as ROI/power box) requiring graphical selection of areas, lines, and sites are not supported.
  • The mirror and acquisition boards must be the same - this ensures timebase synchronization.

Other Changes/Additions

Naive Pockels Cell Calibration
If no photodiode is associated with a particular Pockels Cell (by leaving the photodiodeInputBoardId# property blank in standard.ini), a naive linear calibration is employed. This allows the power level to be adjusted via the Power Control window (in a nonlinear fashion) and also supports flyback blanking.

Improved handling for multiple Pockels Cells
Three Pockels Cells ('beams') are now supported. The specification of which beams are available in each of FOCUS/GRAB/Snapshot, as determined in the 'Laser Function Panel' GUI, is now saved as a user setting, and no longer as a configuration setting. To turn 'off' individual beams for a particular configuration, set the power to 1% (this will set the power to the minimum value as determined by the calibration, if available).

Modified Servo/Mirror Parameter Names
In the Configuration window (Edit>>Configuration... from MainControls menu), the 'Line Delay' parameter has been renamed to 'Line (Flyback) Delay' and the 'Cusp Delay' parameter has been renamed to 'Cusp (Servo) Delay'. See here. The renamings provide better intuition for what each parameter compensates for.

The 'Line (Flyback) Delay' parameter accounts for the time required for the mirror to catch up with the command signal following a rapid mirror flyback time: rapid flybacks in unidirectional scanning mode typically cause the mirror servo slew rate limit to be exceeded, ultimately requiring extra time for the mirror to "catch up" at the beginning of each line scan.

The 'Cusp (Servo) Delay' parameter refers to the constant lag of the mirror position, relative to the command signal. For the bidirectional scanning case, this is specified as a fraction of the 'ms/Line' value, and can vary as the line speed is varied. For unidirectional scanning, the value is specified in time (in milliseconds).

Additional Fast Configurations

'Safe' Hot Key Option
By selecting the 'Safe Hot Key' option in the User Preferences window (Settings>>Edit>>User Preferences... from MainControls), the application hot keys require the *<*CTL> key to be simultaneously pressed in order to be activated.

ROI Cycler Power Modulation
The ROI Cycler contains a Power field that allows the power level to be specified, as a percentage, for each position in the cycle. In ScanImage 3.0, this modulation applied to the beam specified as the 'scanLaserBeam' in the standard.ini file. Now, the modulation applies to the beam selected in the beam pulldown menu. This control is connected to the main Power Control GUI's beam selection menu.


Bug Fixes

  • The 'pixel time' and 'bin factor' parameters now update correctly following changes to the 'Fill Fraction' or 'ms/line' parameters.
  • Power Box
    • 'Constrain to Line' functionality is actually turned off at startup, matching the startup checkbox setting in the GUI
    • Selecting 'Constrain to Line' no longer causes Power Box to 'shift' each time
    •  

Appendix A: Standard.ini Additions

This section summarizes new state variables that have been added to ScanImage via the standard.ini file, including both those that are meant to be user/rig-modified and those which should not generally be modified.

Frequently Modified Variables
  • state.init.triggerInputTerminal: 
  • state.init.externalTriggerInputTerminal:
  • state.init.externalTriggerTimeout:
  • state.init.outputBoardClockTerminal:
  • state.init.shutter.shutterBoardIndex: Specifies board index or name (DAQmx) for board on which the DIO line(s) employed for the shutter(s) are located

Infrequently Modified Variables
  • state.init.minUnidirectionalLinePeriodGUI: Specifies the smallest of the enumerated ms/line options to support for unidirectional scans. Values of ms/line s smaller (faster) than this are exclusively for bidirectional scanning.
  • state.init.maxBufferedGrabTime: Specifies the threshold of time for a Grab acquisition, above which data will be saved during the acquisition, instead of afterwards, where possible.
  • state.init.outputChanBufferTime: Specifies in time (seconds) the length of the data buffer for the output channels (mirrors and Pockels Cell(s)). Increasing this time increases the frame rate at which data logging and/or merge display can occur reliably, at some expense of memory. This will be computer dependent.
  • state.acq.inputVoltageRange:_Specifies input voltage range to use for PMT input boards. Typically 10V, but lower voltages can allow for more dynamic range. (NOTE:_ This feature not currently supported!)
  • state.acq.inputBitDepth: Specifies ADC resolution of PMT input boards -- typically 12 bits
  • state.internal.fastParkFOVFactor: Specifies the multipler of the full FOV amplitude to use when parking the beam quickly, e.g. when stopping-and-restarting focus during zoom or rotation update (Default=1.2)
  •  
Non-modifiable Variables

Other variables added in ScanImage 3.5, which should not be modified by the user in their own .INI files, are simply listed here.

  • state.internal.saveDuringAcquisition
  • state.internal.framesPerFileGUI
  • state.internal.framesPerFile
  • state.internal.triggerTimer
  • state.acq.saveDuringAcquisition
  • state.acq.framesPerFile
  • state.acq.externallyTriggered
  • state.acq.infiniteFocus
  • state.acq.bidirectionalScan
  • state.acq.channelMerge
  • state.acq.mergeFocusOnly
  • state.init.hotKeysNeedCtl
Other standard.ini changes

Appendix B: Hardware Notes


  • No labels