About this Documentation
ScanImage 3.7 is quite similar to 3.6. documentation describes changes and new features since ScanImage 3.6. Aside from these changes, the [ScanImage 3.6 Documentation] still applies.
Version Compatibility
Please note/follow the Matlab and NI version compatability information. Use of other versions will likely result in trouble. 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 (Important Changes)
- Major New Features
- Other New Features
New Features in ScanImage 3.7
Major New Features
Other New Features
Upgrading from ScanImage 3.5 or 3.6 (Important Changes)
- 3.7 has a new model INI file
, which is thoroughly self-documenting. 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
Unknown macro: {blue}values are replaced byUnknown macro: {blue}values, in theUnknown macro: {report-info}dialog. They now represent the full-angle (peak-peak) of the scan range, specified in optical degrees, rather than half-angle as in 3.6 (and half-voltage of command signal in earlier versions). Therefore new values will generally be twice theUnknown macro: {blue}values in ScanImage 3.6.
In general, the new default
Unknown macro: {blue}values of 15 optical degrees 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 theUnknown macro: {blue}value/notes in the INI file.
- If using two boards (i.e. second board for Pockels and/or new clock export signals), ScanImage 3.7 requires the clock synchronization between boards be on RTSI 7, not RTSI 6 as with ScanImage 3.6.
If running both 3.6 & 3.7 (see below), you should connect both RTSI 6 and RTSI 7(or connect all, with a ribbon cable).
If running both 3.5 & 3.7 (see below), no change is required
- The INI file now contains a
Unknown macro: {blue}value which should be set correctly to convert optical degree values specified in ScanImage to correctly scaled voltage commands. Please read the comments carefully!
If the
Unknown macro: {blue}value in 3.7 differs compared to yourUnknown macro: {blue}setting in 3.6 , you will need to (further) adjust yourUnknown macro: {blue}values compared to previousUnknown macro: {blue}values.
- The
Unknown macro: {blue}andUnknown macro: {blue}values that previously were specified as X & Y are now referred to as FAST & SLOW. A new control inUnknown macro: {report-info}dialog indicates mapping from X/Y to FAST/*SLOW*axes. Adjusting this allows you to rotate the image 90 degrees.
- The INI file now contains the separate mapping of X/Y to DA Channels 0 & 1 (
Unknown macro: {vi-statevar}values) which is fixed on initialization.
- 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
Unknown macro: {blue}values from 3.6 will not be applied in 3.7. The newUnknown macro: {blue}values should be adjusted before saving each CFG file.
Running ScanImage 3.7 together with earlier versions
You can run 3.7 together on same machine that is running 3.6.x or 3.5.x
- 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.
- Note that maintaining multiple Matlab versions on same machine does not require an additional license or count as an additional activation.
Major 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.
The
panel allows control over this new feature:
From the
panel, ScanImage 3.7 also provides a facility to measure the Lz value suited for the given preparation:
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)
- Gate Active: (Only available for Line Clock at this time). Specifies that clock signal is 'gated' by the parent clock (frame->line and line->pixel are parent/child pairs). Gating is required to prevent clock ticks when acquisition is not active. The default settings should apply for most cases.
When Gate Active is selected, the Phase Shift of the parent clock is added to the value for the child clock.
Enabling Gate Active for the Line Clock suppresses clock tick for final line if Discard Flyback Line is enabled in the CONFIGURATION dialog. However, this prevents Phase Shift values for Frame and Line clocks from being independent.
- 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
Unknown macro: {report-info}window
- Next Triggers: Trigger signals which stop or advance data file of ongoing GRAB/LOOP acquisition. They may also act as a Start trigger and initiate acquisitions.
External trigger signals to ScanImage are input on one of the PFI (programmable function interface) lines specified in the INI file as
and
. These specify the list of available trigger sources on a particular rig/setup.
The
dialog, accessed from Settings >> Triggers... on the
menu, allows selection of which trigger source to use:
: Selects which of the
specified in the INI file will be used to initiate GRAB/LOOP acquisitions IF external start triggering is enabled on
(using the
- This can only be enabled if a
- If enabled, the
- This can only be enabled if a
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.
Common Next Triggering applications
Two common applications of Next Triggering are shown here:
- (a) The Next Trigger can be used to advance output data file (opening and writing to newly numbered data file)
- (b) 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.
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 Functions. 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 new
, accessed from Settings >> User Functions..., controls this feature:
The /
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.
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 'Plugins'.
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:
: Launches file browser to select CFG file to attach to numbered (1-6) Fast Configuration
: Removes association of current file to particular numbered Fast Configuration
- button)
Note that full path of selected file is stored/used. To see the full path of an already specified Fast Configuration, press button – the file selector dialog will start in the current file's directory (can hit Cancel to abort new selection).
Loading/Starting Fast Configurations
Fast Configurations are loaded (or auto-started, if applicable) in one of two ways:
- Press the desired Fast Configuration numbered button on the
- Press the <F1>-<F6> key (using CTRL at same time, if specified)
Six numbered buttons on the MAIN CONTROLS window are used to load (or optionally auto-start) specified Fast Configuration with one button. When is enabled for particular Fast Configuration, the button appears as green.
When 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 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 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
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.
Other New Features
Finite LOOP acquisitions
In earlier versions, LOOP mode acquisitions were indefinite – the user was required to
the acquisition manually. In ScanImage 3.7, the
panel contains a new control specifying the
. LOOP acquisitions will automatically terminate after specified number of Repeats. The value Inf (default) can be entered to mimic the original, indefinite looping behavior.
Fractional zoom adjustment
In earlier versions, the
control in the
panel allowed the zoom value to be specified in only integer increments. ScanImage r3.7 now allows fractional zoom values, providing greater control over the scan range directly from the
panel.
The
value simply represents a division of (both) the
values in the
panel. For most users, the
values do not require modification – the
control should provide sufficient adjustment flexibility over the scanned range.
When a Scan Parameter Array is specified in the
panel, any non-integer
values are rounded to determine the scan parameters (
,
, and
) in effect at specified
.
Slider adjustment of power during FOCUS
In ScanImage 3.7, a new
control on the
panel allows the slider to be adjusted during [*FOCUS*], if selected:
The
control (rarely used) previously on the
panel has been relocated to the
dialog.
More image display colormap options
In earlier versions, the Image Display windows are always displayed with a grayscale colormap, with the possibility of displaying
In ScanImage 3.7, most Colormap controls are moved to the
panel. The
menu allows a wider selection of colormaps, including the Matlab jet colormap and options to display Channels 1 and 2 as red & green (in either order).
In addition, a user-specified colormap can be specified, for each Channel, in the
dialog.
Option to average binned samples
To date, ScanImage has summed the input samples obtained at each pixel of the scanned image (see Input Data Processing). The number of samples at each pixel is computed as the
, displayed on the
panel; its value is determined by the
,
, and
.
Some users may prefer to average, rather than sum, the samples obtained at each pixel. This makes the intensity values for each Image Display window (and hence the
and
levels that are appropriate) independent of the
(and hence the
,
, and
values).
ScanImage 3.7 adds an
control to select this option. See the
panel documentation.
Support for shutter located before Pockels
The Shutter control signal feature in earlier ScanImage versions assumed that shutter is located after any/all Pockels/modulators in system – i.e. a single shutter is used for all the Beams in use.
ScanImage 3.7 adds option for the Pockels/EOM to be located before the Pockels. This is most commonly used when there is only one beam. To select this option, the
value in the INI file should be set to 1.
The one & only effect of selecting this option is that shutter is opened/closed at start/end of Pockels calibration
One effect of the
value is that the beam is transmitted through to scope, and potentially specimen, during Pockels calibration. Careful attention should be paid to the
INI file values; the scanner is directed to this angle during Pockels calibration.
Ability to set root save file path
ScanImage requires that user select save path, via File >> Set Save Path... dialog on the
panel before a
acquisition with
selected.
ScanImage 3.7 speeds this folder selection by allowing the
to be specified as a User Setting in the
dialog. This path is used as the starting point for the folder selection dialog in File >> Set Save Path.... For instance, 'c:\data' or 'c:\data\<username>' might be specified as the
.