| Wiki Markup |
|---|
{composition-setup}
{cache:refresh=30d}
----
{comment}{toc:type=flat|maxLevel=24}{comment}
{center}
{report-blocklist:depth=01|injected=true}
{local-reporter:page:sorted children}
{report-header}* [About This Release|#AboutThisRelease]{report-header}{report-body}\[[%content:title%|#%content:title%]\] {report-body}
{report-blocklist}
{comment}{hide-from:groups=ephus-users|users=@anonymous}{create-page:prompt=Enter section name|postfix=(%ident%)|addspace=true}Add new section!{create-page}{hide-from}{comment}
{center}
----
{report-block}
{local-reporter:page:sorted children}
{report-body:injected=trueheader}
{anchor:%content:title%AboutThisRelease}
h1. About This Release {hide-from:groups=ephus-users|users=@anonymous}
h1. {link-to:page edit|page=%content:title%}%content:title%ScanImage r3.5.1 README}^\[Edit\]^{link-to}
{hide-from}
{show-to:groups=ephus-users|users=@anonymous}
h1. %content:title%
{show-to}
{include:%content:title%}
{report-bodyinclude:ScanImage r3.5.1 README}
{report-header}
{report-block}
----
{hide-from:users=@anonymous|groups=ephus-users}
h5. [To be added to the documentation]
{hide-from}
{comment}
{toc:minLevel=2|indent=10px}
----
h2. 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.
h2. 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
h2. New Feature Details
h4. 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.
\\
h4. 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.
h4. Disk-Logging Grab Acquisitions
!standardModeGUI.png!
\\
h4. Infinite Focus & External Triggering
!maincontrols_formatted2.png|align=left!\\
\\
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._
h4. 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.
!ScanTypes_2.gif!
Bidirectional scanning is specified via a checkbox in the *Configuration* window (*Edit >> Configuration...* from *Main Controls* menu), as shown below.
{anchor:configWindow}
!advancedConfigurationGUI_formatted2.png!
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|#utilityFunctions] has been created to help adjust the 'Cusp (Servo) Delay' parameter correctly.
{note}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.
{note}{anchor:utilityFunctions}
h4. 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.
h4. Extended 'Hotkey' Functionality
\\
h2. Changes (from v3.0)
h4. 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.
\\
{tip}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.
{tip} 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.
\\
\\
\\
\\
\\
h4. 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).
\\
h4. 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.
h4. 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|(DOC) ScanImage 3.5 Documentation^advancedConfigurationGUI_formatted2.png]. 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.
\\
h4. 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
**
h2. 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.
h5. 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
\\
\\
h5. 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)
*
h5. 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_
h5. Other _standard.ini_ changes
h2. Appendix B: Hardware Notes
\\
{commentbody:injected=true}
{anchor:%content:title%}
h1. %content:title% {hide-from:groups=ephus-users|users=@anonymous}{link-to:page edit|page=%content:title%}^\[Edit\]^{link-to}{hide-from}
{hide-from:groups=ephus-users|users=@anonymous}
{hide-from}
{include:%content:title%}
{report-body}
{report-block}
{cache} |
Page History
Overview
Content Tools