Version Compatibility
ScanImage 3.7 requires Matlab 2009b or higher and DAQmx 8.8 or higher. It has most recently been tested with Matlab 2010b and DAQmx 9.2.2. As discussed further below, it is possible to co-install ScanImage 3.7 with earlier ScanImage versions, by installing multiple Matlab versions on a machine. In such cases, DAQmx 8.8 should be used.
- New Features in ScanImage 3.7
- Upgrading from ScanImage 3.5 or 3.6
- Guide to New Features
New Features in ScanImage 3.7
- Compatibility with latest Matlab (2010b) and DAQmx (9.2.2)
. - Compatibility with X series boards, for the second DAQ board (for Pockels and/or more clock signals)
- DAQ Toolbox no longer required
- Automatic power adjustment during stack collection
- Exports line/frame/pixel clock signals
- External triggering enhancements, including Next Triggering
- Continuous file streaming supported for stacks
- Enhanced User Functions capability
- Enhanced Fast Configurations
Upgrading from ScanImage 3.5 or 3.6
- 3.7 has a new model INI file , which is quite thoroughly documented. You should make a new standard.INI file based on this model, following the comments.
It is recommended to create a separate folder(s) for your INI/CFG/USR files under 3.7, to keep them separate from data files for any older version you may also maintain installed.
- The Shift and Scan Amplitude values that previously referred to X/Y now refer to Fast/Slow. A new control in Configuration dialog indicates mapping from X/Y to Fast/Slow axes. Adjusting this allows you to rotate the image 90 degrees.
The INI file contains the separate mapping of X/Y to DA Channels 0 & 1, which is fixed on initialization.
- The Scan Amplitude values are replaced by Scan Angular Range values, in the Configuration dialog. It now represents the full (peak-peak) angle of the scan range, specified in optical degrees, rather than half angle as in 3.6 (and earlier verisions). Therefore new values will generally be twice the Scan Amplitude values in ScanImage 3.6/3.5.
The model INI file has improved/expanded the explanation of the voltsPerOpticalDegree variable. Please read carefully, and provide feedback if this is not clear!
If the voltsPerOpticalDegree value in 3.7 differs compared to your setting in 3.6 (i.e. because it's clearer now and therefore set correctly), you will need to further adjust your Scan Angular Range values compared to previous Scan Amplitude values.
In general, the new default Scan Angular Range value of 15 should not often require modification by most users. If you see the field-of-view is different (smaller) than you're used to, look closely at the voltsPerOpticalDegree value/notes in the INI file.
- It is recommended to copy your old CFG files to a separate folder for 3.7, and then load and re-save each of them individually. This will make your CFG files 3.7 compatible.
Note the ScanAmplitude values will not be applied in 3.7. The Scan Angular Range values should be adjusted before saving each CFG file.
- 3.7 requires the clock synchronization between boards (main board and Pockels) be on RTSI 7, not RTSI 6 as with ScanImage 3.6.
If running both 3.6 & 3.7, you should connect both RTSI 6 and RTSI 7(or connect all, with a ribbon cable).
If running both 3.5 & 3.7, no change is required
- You can run 3.7 on same machine that is running 3.6 or older version
Typically, your newer Matlab will set path to 3.7 and older Matlab will set path to older version
If running both 3.5/3.6 & 3.7 on same machine, DAQmx 8.8 is required. This is earliest version of DAQmx supported by 3.7, while 3.5/3.6 doesn't run on 8.9 or higher.
Note that X series boards are only supported from 9.0 forward.
Guide to New Features
Power Adjustment During Stacks
When collecting image stacks in scattering tissue, the power level required at each slice in the stack generally increases with depth in order to maintain a fixed signal. ScanImage 3.7 enables this, allowing a simple exponential length constant (Lz) to be specified.
This feature is primarily controlled from the Power Controls window:
P/z Adjust: Checkbox enables/disables automatic 'P vs z' adjustment feature for all beams
Lz: Specifies the exponential length constant for the currently selected beam. Power is increased with depth according to P = P0 * exp^((z-z0)/Lz).
A value of Inf implies no power adjustment should occur for the selected beam.
Value of Lz must be positive
- The zDepthPositive value in the INI file must be set correctly, specifying specify whether larger Z values on the motor controller corresponds to deeper imaging (true by default).
- In general, the user will experiment to identify the Lz value suited for their preparation, which is typically fairly constant from
- The P/z Adjust and Lz controls are User Settings-- i.e. their values are saved to USR files.
Thus during a typical ScanImage session (where USR file is loaded on startup only), the value specified applies to all stack configurations used during session
- Note the power only adjusts in integer increments of the percentage value.
ScanImage 3.7 also provides a facility to measure the Lz value suited for the given preparation, using the Motor Controls window:
When Override Lz is enabled, stack executions initiated via the GRAB button in the Motor Controls dialog (rather than from Main Controls) will use Lz value computed from power levels measured at the endpoints of the stack determined by start and end buttons.
User therefore will typically uses FOCUS mode to adjust power and Z position at both the start and end points of stack, pressing start and end buttons at each point, respectively to record both the Z position and power level(i.e. using a higher power at the deeper endpoint). Then Lz can simply be computed and this value is used instead of that specified in Power Controls window.
If multiple beams are used, a separate Lz value is computed/used for each beam, i.e. power level for each beam is measured at each endpoint.
If value of Lz=Inf in Power Controls window for a beam, then power auto-adjustment is disabled for that beam. Therefore, to use Override Lz feature, some (arbitrary) value (other than Inf) should be entered for each beam for which auto-adjustment is to be used.
When Override Lz is used, the computed Lz value is displayed to Matlab command line, for each beam. Users may find that this is a useful way to measure/determine Lz for their preparation. User can then simply enter this value in the Lz control on the Power Controls window and save value to USR file. Assuming that value is fairly consistent from sample to sample (for given sample type), this avoids need to adjust and record power at both start and end points of each stack.
Frame/Line/Pixel Clock Export
This feature is most powerful with new X series boards. Future ScanImage versions may be able to get more functionality out of other/earlier board families, but this cannot be guaranteed as a development priority.
The Frame/Line/Pixel clock export feature is intended to allow external hardware to be synchronized with start (or end) of each ScanImage Frame, Line, or Pixel.
- Each clock output requires a National Instruments counter/timer channel. These must be specified in the INI file. Both Board and Counter ID values must be specified – i.e. frameClockBoardID & frameClockCtrID must be specified to enable frame clock feature, etc.
Note that Ctr0 on the primary board (acquisitionBoardID) is reserved by ScanImage, and not available for frame/line/pixel clocks
X series boards have 4 counter/timer channels, while other board families have only 2 counter/timer channels
- Finite clock generation is only possible with X series boards. When using a non-X series board, additional clock 'ticks' may appear after acquisition is finished, because the counter output is actually stopped in software.
- Consequently, pixel clock generation – which requires finite clock generation – is only possible with X series boards at this time.
- For Frame/Line clocks, the edge not specified by Polarity signifies the 'end' of Frame/Line. For Pixel clock, the edge not specified by Polarity is controlled by Pixel Fraction.
The 'end' of Frame/Line indicates that acquisition has ended for current line/frame, and acquisition for new line/frame has not begun. This occurs at the scanner flyback or turnaround time at end of line, or end of last line in frame.
The Pixel clock handling is different because there are no gaps between pixel periods; thus the location of the 'stop' edge must be user specified (via Pixel Fraction).
The Frame/Line/Pixel clock feature is controlled by the Exported Clocks... dialog (Settings >> Exported Clocks... from the Main Controls menu):
Unable to render embedded object: File (ExportedClocks.bmp) not found.
- Enable: Each clock can be enabled/disabled. (CFG setting)
- Phase Shift (us): Each clock signal can be phase shifted relative to the true start of frame/line/pixel. Only a positive phase shift (delay) is supported at this time. (CFG setting)
- Polarity: Specifies if rising or falling edge signals the start of frame/line/pixel.
- Pixel Fraction: Specifies at what fraction of the pixel period to generate the edge not specified by the Polarity. Value must be < 1, to allow edge specified by Polarity at start of subsequent pixel period. (CFG setting)
- Export Clocks on FOCUS: If false, the clock signals are only generated during GRAB/LOOP acquisitions, not FOCUS acquisitions. (USR setting)
Settings labeled as CFG settings are considered part of the ScanImage Configuration and saved to CFG files. Different configuration files can save different values of this setting. This is useful, for instance, if you want the frame clock to be exported only for certain experiments, but not others.
Settings labeled as USR settings are considered part of ScanImage User Settings and saved to USR files.
External triggering enhancements, including Next Triggering
ScanImage 3.7 has more options for external triggering. There are now two types of external triggers:
- Start Triggers: Trigger signals which initiate GRAB/LOOP acquisitions, when EXT is enabled in the Main Controls window
- Next Triggers: Trigger signals which can initiate acquisitions, but also can stop or advance data file of ongoing GRAB/LOOP acquisition
External trigger signals to ScanImage are input on one of the PFI (programmable function interface) lines specified in the INI file as externalStartTrigTerminals and nextTrigTerminals. These specify the list of avaialable trigger sources on a particular rig/setup.
The Triggers... dialog, accessed from Settings >> Triggers... from the Main Controls menu, allows selection of which trigger source to use:
- Start Trigger Source: Selects which of the externalStartTrigTerminals specified in the INI file will be used to initiate GRAB/LOOP acquisitions IF external start triggering is enabled on Main Controls (using the EXT button).
- Start Trigger Edge: Specifies whether acquisition is started on rising or falling edge of start trigger signal.
- Next Trigger Only: If enabled, the selected Next Trigger Source serves also as the start trigger.
This can only be enabled if a Next Trigger Source is selected
If enabled, the EXT button on Main Controls is forced ON
- Next Trigger Source: Specifies which, if any, trigger source selected from the nextTrigTerminalsin the INI file will serve as next trigger in GRAB/LOOP acquisitions. If none is selected, then next triggering is not used.
- Next Trigger Edge: Specifies whether rising or falling edge of next trigger signal is used
- Next Mode: One of {Arm, Advance}. Value of Arm specifies that next trigger stops ongoing acquisition, arming next acquisition (i.e. to wait for next start trigger). Value of Advance specifies that acquisition continues uninterrupted (unless Gap is enabled); the Acquisition # file counter is incremented and subsequently acquired data is written to a newly opened file stream.
- Gap: When Gap is enabled and Next Mode=Advance, then acquisition stops when next trigger arrives, and then acquisition is then re-started automatically, using ScanImage default start trigger. This mode is rarely used, but may be useful if a start trigger is needed for each acquisition.
All settings in the Triggers... dialog are Configuration settings, i.e. saved/loaded as part of CFG files.
The option to select from multiple external start triggers is useful, for instance, if ScanImage acquisitions are initiated by physiology software for some experiments and by behavioral software for others. These different conditions can be stored as different ScanImage Configurations.
Two common applications of Next Triggering are shown here:
- (a) The Next Trigger source can function as an acquisition gate. In this case, the same PFI line is specified as both the start and next trigger source, with the rising edge for one and the falling edge for the other. Acquisition start and end will be controlled by the gate signal; each 'gate' will correspond to a new file.
- (b) The Next Trigger can be used to advance output data file (opening and writing to newly numbered data file)
In general, next triggering can be useful for synchronizing to external behavior/stimulus software and ensuring that file names/numbers are aligned.
Enhanced User Functions capability
ScanImage 3.6 and earlier had some support for User Fucntions. The original implementation had a few critical limitations, however:
- Only one event – the end of a GRAB acquisition or LOOP repeat – lead to user function execution
- User functions were required to be on the Matlab search path
- No ability to pass arguments to the user functions, i.e. to modulate their function
ScanImage 3.7 reimplements User Functions to overcome these limitations. The new implementation makes use of the concept of events recently added to Matlab. The feature is controlled by the new User Functions window, accessed from Settings >> User Functions...:
- Event Name: List of events to which user functions (event listeners) can be bound. These are pre-defined by ScanImage, but custom events can be readily added, if required, as discussed below.
- UserFcn Name: Name of user-specified function to execute when event occurs. Generally these are specified by Add..., but they can also be entered directly if the user function is a Matlab built-in function.
- Arguments: User functions can take optional arguments, specified here. This allows behavior of function to be modulated. A single value can be entered if only one argument is expected. If more than one argument is required, it should be entered as a cell array, e.g. {<Arg1Value> <Arg2Value> ...}.
- Enable: Checkbox enables/disables execution of specified user function for particular event.
- Fcn Index: Up to 10 user functions can be bound to each listener. There are then 10 tables of event/user function configuration. This value adjusts which of these is currently displayed and available for editing.
- Enable/Disable All: Enables or disables all of the user functions specified for events with user function specified, at current Fcn Index.
The Add.../Remove operations act on the currently selected event. To select event, the mouse/cursor should be placed in one of the editable controls for given event.
- Add...: Launches file browser dialog allowing selection of user function for currently selected event (and current Fcn Index). The file selected need not be on the Matlab search path.
- Remove: Removes user function, if any, bound to currently selected event (at current Fcn Index).
All settings in the User Functions... dialog are Configuration settings, i.e. saved/loaded as part of CFG files.
The ability to specify optional arguments to user functions is useful, for instance, to specify channels on which to apply custom computation, to provide parameters to an algorithm implemented by the user function, etc.
User Function Signature
User functions, except when a Matlab built-in (rare), should have the following signature:
function myUserFunc(eventName, eventData, optArg1, optArg2,...)
This signature should be used even if the eventName or eventData arguments passed to the user function are not needed. These arguments are supplied by ScanImage. Optional arguments, if any, are passed starting from the third argument – these arguments are supplied by the User Functions dialog.
Using the eventName argument allows, for instance, using the same function bound to multiple events, with a different action occurring based on the particular event – this is readily implemented in the user function with a
statement. This architecture can be used to make a fairly complex 'Plugin':
The eventData argument can contain a single value (possibly a structure of multiple values) that is specified by ScanImage at the time of the event. The value passed – if any – depends on the event. See the ScanImage.EventManager class for information about what data is passed with each event.
The ScanImage.EventManager Class
The list of events generated by ScanImage are specified in the ScanImage.EventManager class – see the +ScanImage folder in the ScanImage 3.7 distribution.
The documentation for each event in this class file provides information about the event, and also specifies what, if any, eventData is passed to user functions for particular events.
End users are encouraged to simply add events to the ScanImage.EventManager class file. These changes should be made to the file when ScanImage is not running and Matlab should typically be restarted following the addition. Then on subsequent ScanImage startup, the added event will appear in the User Functions dialog.
To 'fire' the event at appropriate location(s) in ScanImage code, the following syntax should be used:
state.userFcns.hEventManager.notify(eventName)
state.userFcns.hEventManager.notify(eventName,eventData)
where eventName specifies the event to 'fire', and the optional eventData argument passes value to the user functions invoked by this event.
Enhanced Fast Configurations
ScanImage 3.7 enhances the interface and capabilities of Fast Configurations – configurations which are configured to be rapidly loaded, at the touch of one key or one button. ScanImage users are encouraged to create several configurations, to represent each of the imaging/experimental modes they use.
The new Fast Configurations window is accessed via Settings >> User Functions... on the Main Controls menu:
Unable to render embedded object: File (FastConfigurations.bmp) not found.
- Unable to render embedded object: File (FastConfigAddButton.bmp) not found.: Launches file browser to select CFG file to attach to numbered (1-6) Fast Configuration
- Unable to render embedded object: File (FastConfigRemoveButton.bmp) not found.: Removes association of current file to particular numbered Fast Configuration
- CFG Name: Name of CFG file associated with particular numbered Fast Configuration (selected using Unable to render embedded object: File (FastConfigAddButton.bmp) not found. button)
Note that full path of selected file is stored/used. To see the full path of an already specified Fast Configuration, press Unable to render embedded object: File (FastConfigAddButton.bmp) not found. button – the file selector dialog will start in the current file's directory (can hit Cancel to abort new selection).
- AutoStart?: Specifies that acquisition should be started immediately upon loading the specified Fast Configuration – i.e. this avoids having to press the FOCUS, GRAB, or LOOP buttons.
- AutoStart Type: If AutoStart? is enabled, this specifies the type of acquisition (FOCUS, GRAB, or LOOP) to automatically start on loading the particular numbered Fast Configuration
- Require CTRL+<F1-F6>: Specifies that CTRL key should be pressed at same time as <F1>-<F6> for keyboard-based selection of Fast Configuration to load (and auto-start, if specified)
Fast Configurations are loaded in one of two ways:
- Press the desired Fast Configuration numbered button on the Main Controls window
- Press the <F1>-<F6> key (using CTRL at same time, if specified)
Unable to render embedded object: File (MainControls_FastConfig.png) not found.
Six numbered buttons on Main Controls window are used to load (and optionally auto-start) specified Fast Configuration with one button. When AutoStart is enabled for particular Fast Configuration, the button appears as green.
When AutoStart is enabled, <SHIFT>+<F1-F6> or the right mouse button can be used to suppress the auto-start feature, i.e. to load the chosen fast configuration but not start acquisition immediately.
At present time, the AutoStart feature's utility is somewhat limited by the fairly slow time (>500ms) to load a configuration. This is anticipated to improve in future ScanImage releases.
Continuous File Streaming Improvements
ScanImage 3.5 introduced continuous file streaming as an option for non-stack GRAB/LOOP acquisitions (i.e. acquisitions where # Slices=1). This feature saves files to disk as they are acquired, rather than waiting till the end of an acquisition to save the file. This permits unlimited, uninterrupted acquisitions.
ScanImage 3.7 now uses continuous file streaming for stack acquisitions and removes the ability to enable/disable continuous file streaming mode – this mode is now always used when AutoSave is checked in Main Controls:
AutoSave: When checked, continuous disk streaming is enabled, to the file <Basename><Acquisition #>.tif in the path specified by File >> Set Save Path...
As a consequence, ScanImage 3.7 no longer typically maintains a buffer in memory (RAM) of the entire acquisition. However, there are times when it is useful to data buffered in RAM, e.g. for online processing in User Functions so ScanImage 3.7 maintains a buffer of the most recent acquired frames in the state.acq.acquiredData state variable (in the Matlab global workspace). This is the same variable that was used in ScanImage 3.6 (and earlier) to maintain a buffer of the entire acquisition; however the variable is now somewhat differently structured. The variable was previously a cell-array of 3-d arrays; in ScanImage 3.7, it is now a nested cell array of 2-D images (frames), indexed as follows:
state.acq.acquiredData{<FrameIndex>}{<ChannelIndex>}(<lineIndex>,<pixelIndex>)
where <FrameIndex> counts from the most recent frame.
The User Settings dialog (Settings >> User Settings... from Main Controls menu) has several relevant settings:
Max Buffered Frames (AutoSave ON): When AutoSave is ON, this specifies number of most recent frames to maintain in RAM (in the state.acq.acquiredData variable).
Max Buffered Frames (AutoSave OFF): When AutoSave is OFF, this specifies number of most recent frames to maintain in RAM. Value of Inf implies to keep all frames of the acquisition, i.e. to buffer entire acquisition.
# Frames/File: Limits number of frames saved to each file – data is saved in chunks named <Basename><Acquisition #>_<ChunkIndex>.tif
In addition, there are two useful new settings:
Root Save Path: Specifies root folder to display when selecting File >> Set Save Path... to specify path for file-saving. E.g. can be C:\Data\MyName, so that search/specification of folder is faster.
Root Path is Default Path: Specifies that Root Save Path is the default save path if none other has been specified. Selecting this and saving to USR file loaded on subsequent startup avoids need to specify a save path (File >> Set Save Path...) on the first acquisition.
All settings in User Settings dialog are, unsurprisingly, User Settings, i.e. saved to USR files.
DAQ Toolbox No Longer Required
ScanImage 3.7 no longer requires use of the DAQ toolbox. Instead, it uses a Matlab class which wraps the NI DAQmx library. This approach has several advantages:
- Faster data read times are achieved (>4x faster), which increases amount of time available for user functions
- More comprehensive coverage of DAQmx features is achieved, compared to DAQ toolbox. For example, the DAQ toolbox does not support counter/timer channels which underlie several of the new features in ScanImage 3.7.