Page History

{composition-setup}
{alias:SI3.7Doc}
{composition-setupcache:refresh=10d}

{info:title=About this Documentation}ScanImage 3.7 is quite similar to 3.6. This documentation 1) describes _changes_ and _new features_ since ScanImage 3.6. Asideand from2) thesecontains changes,updated the [ScanImage 3.6 Documentation] still applies.{info}

{info:title=Version Compatibility}Please note/follow the [Matlab and NI version compatability|ScanImage Matlab and NI Version Compatibility] 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 _Getting Started_ and _Window Reference_ guides. Otherwise,  the various _Key Concepts_ described in the [ScanImage r3.6.x Documentation] are, broadly speaking, still applicable. The _Key Concepts_ section/pages thus simply link back to the 3.6 documentation.{info}

{note:title=Version Compatibility}Please note/follow the [Matlab and NI version compatability|ScanImage Matlab and NI Version Compatibility] information. _Other versions are known or likely not to work!_ 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. {infonote}

{toc:maxLevel=5cache}

h2. New Features in ScanImage 3.7
h3. Major New Features
{multi-excerpt-include:pageTitle=ScanImage r3.7 README|name=MajorEnhancements|nopanel=true}
h3. Other New Features
{multi-excerpt-include:pageTitle=ScanImage r3.7 README|name=OtherEnhancements|nopanel=true}

{anchor:UpgradeInfo}
h2. Upgrading from ScanImage 3.5 or 3.6 (Important Changes)
* 3.7 has a [* +Getting Started Guide+
{pagetree:root=Getting Started Guide (r3.7)|startDepth=2}
{cache:refresh=10d}
\\
{toc:maxLevel=3}
\\
{cache}
* +Window Reference Guide+
{pagetree:root=Window Reference Guide (r3.7)|startDepth=1}

* +Key Concepts (r3.6)+
{pagetree:root=Key Concepts (r3.6)|startDepth=1}
{cache:refresh=10d}

h1. New Features in ScanImage 3.7
h3. Major New Features
{multi-excerpt-include:pageTitle=ScanImage r3.7 README|name=MajorEnhancements|nopanel=true}
h3. Other New Features
{multi-excerpt-include:pageTitle=ScanImage r3.7 README|name=OtherEnhancements|nopanel=true}

{anchor:UpgradeInfo}
h1. Upgrading from ScanImage 3.5 or 3.6 (Important Changes)
* 3.7 has a [new model INI file|http://openwiki.janelia.org/wiki/display/ephus/ScanImage+INI+File+Overview] , whichwith is thoroughly self-documenting. You should [several changes|ScanImage r3.7 standard_model.INI] from r3.6. 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 {blue:Scan Amplitude X/Y} values are replaced by {blue:Scan Angular Range Fast/Slow} values, in the {report-info:data:Configuration|render=wiki|source=SI3.7 Data} 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_ the {blue:Scan Amplitude X/Y} values in ScanImage 3.6. 
(/) In general, the new default {blue:Scan Angular Range Fast/Slow} 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 the {blue:voltsPerOpticalDegree} 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|http://openwiki.janelia.org/wiki/display/ephus/Wiring+Your+System+%28r3.6%29#WiringYourSystem%28r3.6%29-ClockSync] 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 {blue:voltsPerOpticalDegree} 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 {blue:voltsPerOpticalDegree} value in 3.7 differs compared to your {blue:opticalDegreesConversion} setting in 3.6 , you will need to (further) adjust your {blue:Scan Angular Range Fast/Slow} values compared to previous {blue:Scan Amplitude X/Y} values.

* The {blue:Shift Fast/Slow} and {blue:Scan Amplitude Fast/Slow} values that previously were specified as *X* & *Y* are now referred to as *FAST* & *SLOW*. A new control in {report-info:data:Configuration|render=wiki|source=SI3.7 Data} 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 ({vi-statevar:state.init.X/YMirrorChannelID} 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 {blue:ScanAmplitude X/Y} values from 3.6 will not be applied in 3.7. The new {blue:Scan Angular Range Fast/Slow} values should be adjusted before saving each *CFG* file. 

{anchor:CoInstallation}
{info:title=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|http://joule.ni.com/nidu/cds/view/p/id/1085/lang/en]  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.{info}


h2h1. Major New Features
{anchor:PZAdjust}
h3. 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 can enablesmake this adjustment automatically, allowingusing a simple exponential length constant (_Lz_) to be specified. 

The {report-info:data:PowerControls|render=wiki|source=SI3.7 Data} panel allows this capability controlto over this new feature:be enabled:
h5. {toggle-cloak:id=PZAdjust} Show...
{cloak:id=PZAdjust}
{panel:title=Power Controls}{center}!Power Controls (r3.7)^PowerControls.bmp!{center}{multi-excerpt-include:name=PZAdjust|pageTitle=Power Controls (r3.7)|nopanel=true}{panel}
{cloak}

From the {report-info:data:MotorControls|render=wiki|source=SI3.7 Data} panel, ScanImage 3.7 also provides a facility to measure the *Lz* value suited for the given preparation:
h5. {toggle-cloak:id=OverrideLz} Show...
{cloak:id=OverrideLz}
{panel:title=Motor Controls}{multi-center}!Motor Controls (r3.7)^MotorControls.bmp!{center}{excerpt-include:name=OverrideLz|pageTitle=Motor Controls (r3.7)|nopanel=true}{panel}
{cloak}

{anchor:ClockExport}
h3. Frame/Line/Pixel Clock Export

{tip}This feature is most powerful with new [X series boards|http://www.ni.com/xseries/]. 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.{tip}

TheScanImage 3.7 introduces a Frame/Line/Pixel clock export feature intended to allow external hardware to be synchronized with start (or end) of each Frame, Line, or Pixel during image acquisition. 

The {report-info:data:ExportedClocks|render=wiki|source=SI3.7 Data} dialog controls 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|http://zone.ni.com/devzone/cda/tut/p/id/9376#toc3]. 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.
(i) Note that Ctr0 on the primary board (_acquisitionBoardID_) is reserved by ScanImage, and not available for frame/line/pixel clocks
(/) [X series boards|http://www.ni.com/xseries/] 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|http://www.ni.com/xseries/]. 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|http://www.ni.com/xseries/] 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*. 
(i) 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.
(i) 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):
{panel}
{center}!ExportedClocks.bmp!{center}

* *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.
(i) When *Gate Active* is selected, the *Phase Shift* of the parent clock is added to the value for the child clock.
(i) 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|http://openwiki.janelia.org/wiki/pages/viewpage.action?pageId=8684238] 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|http://openwiki.janelia.org/wiki/pages/viewpage.action?pageId=8684424] and saved to USR files.
{panel}

h3. 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 {vi-statevar:externalStartTrigTerminals} and {vi-statevar:nextTrigTerminals}. These specify the list of _available_ 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:

{panel}
{center}!Triggers.bmp!{center}

* *Start Trigger Source*: Selects which of the {vi-statevar: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. 
(i) 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 {vi-statevar:nextTrigTerminals} in 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|Configurations, CFG Files, & Fast Configurations (r3.6)] settings, i.e. saved/loaded as part of *CFG* files.
{panel}

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|Configurations, CFG Files, & Fast Configurations (r3.6)].

Two common applications of _Next Triggering_ are shown here:

!NextTriggeringApplications.png|width=400px!

* (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.

h3. Enhanced User Functions capability
ScanImage 3.6 and earlier had some support for [_User Fucntions_|User Functions (r3.6) - Concept]. 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_|http://www.mathworks.com/help/techdoc/matlab_oop/bqvggvt.html] recently added to Matlab. The feature is controlled by the new *User Functions* window, accessed from *Settings >> User Functions...*:
{panel}
{center}!UserFunctions.bmp!{center}
* *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|Configurations, CFG Files, & Fast Configurations (r3.6)] 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.
{panel}

h4. User Function Signature
User functions, except when a Matlab built-in (rare), should have the following signature:
{panel:borderStyle=dashed}{color:blue}function{color} myUserFunc(eventName, eventData, optArg1, optArg2,...){panel}

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 {blue:switch} 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. 

h4. The _ScanImage.EventManager_ Class

The list of events generated by ScanImage are specified in the _ScanImage.EventManager_ [class|http://www.mathworks.com/help/techdoc/matlab_oop/brh2rgw.html] -- 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:

{panel:borderStyle=dashed}state.userFcns.hEventManager.notify(eventName)\\state.userFcns.hEventManager.notify(eventName,eventData){panel}

where _eventName_ specifies the event to 'fire', and the optional _eventData_ argument passes value to the user functions invoked by this event.


{anchor:FastConfig}
h3. Enhanced Fast Configurations

ScanImage 3.7 enhances the interface and capabilities of _Fast Configurations_ -- [configurations|Configurations, CFG Files, & Fast Configurations (r3.6)] 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:

{panel}
{center}!FastConfigurations.bmp!{center}

* !FastConfigAddButton.bmp!: Launches file browser to select *CFG* file to attach to numbered (1-6) Fast Configuration
* !FastConfigRemoveButton.bmp!: Removes association of current file to particular numbered Fast Configuration

* *CFG Name*: Name of *CFG* file associated with particular numbered Fast Configuration (selected using !FastConfigAddButton.bmp! button)
(/) Note that _full path_ of selected file is stored/used. To see the full path of an already specified Fast Configuration, press !FastConfigAddButton.bmp! 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)
{panel}

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)

{panel}
{center}!MainControls_FastConfig.png!{center}
~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.~
{panel}

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.

(i) 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. 


h3. Continuous File Streaming Improvements
ScanImage 3.5 introduced [continuous file streaming|http://openwiki.janelia.org/wiki/display/ephus/Unlimited+and+Uninterrupted+Acquisition] 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*:
{panel}
{center}!MainControls.bmp!{center}
*AutoSave*: When checked, _continuous disk streaming_ is enabled, to the file <Basename><Acquisition #>.tif in the path specified by *File >> Set Save Path...*
{panel}

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 {vi-statevar: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:
{panel:borderStyle=dashed}>> state.acq.acquiredData\{<FrameIndex>\}\{<ChannelIndex>\}(<lineIndex>,<pixelIndex>)
where <FrameIndex> counts from the most recent frame.{panel}

The *User Settings* dialog (*Settings >> User Settings...* from *Main Controls* menu) has several relevant settings:
{panel}
{center}!UserSettings.bmp!{center}
*Max Buffered Frames (AutoSave ON)*: When *AutoSave* is ON, this specifies number of most recent frames to maintain in RAM (in the {vi-statevar: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|User Settings & USR Files (r3.6)], i.e. saved to *USR* files.
{panel}


h3. DAQ Toolbox No Longer Required
ScanImage 3.7 no longer requires use of the DAQ toolbox. Instead, it uses a Matlab [class|http://www.mathworks.com/help/techdoc/matlab_oop/ug_intropage.html] 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|http://zone.ni.com/devzone/cda/tut/p/id/9376#toc3] which underlie several of the new features in ScanImage 3.7.

h2. Other New Features

h3. Finite LOOP acquisitions
In earlier versions, [*LOOP*|SI3.6_AcqModes] mode acquisitions were indefinite -- the user was required to {blue:ABORT} the acquisition manually. In ScanImage 3.7, the {report-info:data:StandardControls|render=wiki|source=SI3.7 Data} panel contains a new control specifying the {blue:# Repeats}. *LOOP* acquisitions will automatically terminate after specified number of _Repeats_. The value _Inf_ (default) can be entered to mimic the original, indefinite looping behavior.

h3. Fractional zoom adjustment
In earlier versions, the {blue:Zoom} control in the {report-info:data:MainControls|render=wiki|source=SI3.7 Data} 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 {report-info:data:MainControls|render=wiki|source=SI3.7 Data} panel.

The {blue:Zoom} value simply represents a division of (both) the {blue:Scan Angular Range} values in the{report-info:data:Configuration|render=wiki|source=SI3.7 Data} panel. For most users, the {blue:Scan Angular Range} values do not require modification -- the {blue:Zoom} control should provide sufficient adjustment flexibility over the scanned range. 

(i) When a [Scan Parameter Array|Scan Configuration (r3.6)#FastScanDetails] is specified in the {report-info:data:Configuration|render=wiki|source=SI3.7 Data} panel, any non-integer {blue:Zoom} values are rounded to determine the scan parameters ({blue:Acquisition Delay}, {blue:Scan Delay}, and {blue:Fill Fraction}) in effect at specified {blue:Zoom}.

h3. Slider adjustment of power during FOCUS
In ScanImage 3.7, a new {blue:Live Adjust} control on the {report-info:data:PowerControls|render=wiki|source=SI3.7 Data} panel allows the slider to be adjusted during [*FOCUS*|SI#.6_AcqModes], if selected: 

{panel:title=POWER CONTROLS}{multi-excerpt-include:name=LiveAdjust|pageTitle=Power Controls (r3.7)|nopanel=true}{panel}

(i) The {blue:Verify Power} control (rarely used) previously on the {report-info:data:PowerControls|render=wiki|source=SI3.7 Data} panel has been relocated to the {report-info:data:UserSettings|render=wiki|source=SI3.7 Data} dialog.

{anchor:Colormap}
h3. More image display colormap options
In earlier versions, the [Image Display windows|SI3.6_ImageDisplay] are always displayed with a grayscale colormap, with the possibility of displaying

In ScanImage 3.7, most Colormap controls are moved to the {report-info:data:ImageControls|render=wiki|source=SI3.7 Data} panel. The {blue:Colormap} menu allows a wider selection of colormaps, including the Matlab [jet colormap|http://www.mathworks.com/help/techdoc/ref/colormap.html] 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 {report-info:data:Channels|render=wiki|source=SI3.7 Data} dialog. :
h5. {toggle-cloak:id=ExportedClocks} Show...
{cloak:id=ExportedClocks}
{panel:title=Exported Clocks}{center}!Exported Clocks (r3.7)^ExportedClocks.bmp!{center}{excerpt-include:Exported Clocks (r3.7)|nopanel=true}{panel}
{cloak}

{anchor:NextTrig}
h3. 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 {report-info:data:MainControls|render=wiki|source=SI3.7 Data} 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*|SI_INIFile] file as {vi-statevar:externalStartTrigTerminals} and {vi-statevar:nextTrigTerminals}. These specify the list of _available_ trigger sources on a particular rig/setup.

The {report-info:data:Triggers|render=wiki|source=SI3.7 Data} dialog, accessed from *Settings >> Triggers...* on the {report-info:data:MainControls|render=wiki|source=SI3.7 Data} menu, allows selection of which trigger source to use:
 
h5. {toggle-cloak:id=Triggers} Show...
{cloak:id=Triggers}
{panel:title=Triggers}{center}!Triggers (r3.7)^Triggers.bmp!{center}{excerpt-include:Triggers (r3.7)|nopanel=true}{panel}
{cloak}


h3. Enhanced User Functions capability
ScanImage 3.6 and earlier had some support for [_User Functions_|User Functions (r3.6) - Concept]. 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 completely re-implements the _User Functions_ feature to overcome these limitations. The new implementation makes use of the concept of [_events_|http://www.mathworks.com/help/techdoc/matlab_oop/bqvggvt.html] recently added to the Matlab language.

The {report-info:data:UserFunctions|render=wiki|source=SI3.7 Data} dialog, accessed from *Settings >> User Functions...*, allows _User Functions_ to be specified:

h5. {toggle-cloak:id=UserFunctions} Show...
{cloak:id=UserFunctions}
{panel:title=User Functions}{center}!User Functions (r3.7)^UserFunctions.bmp!{center}{excerpt-include:User Functions (r3.7)|nopanel=true}{panel}
{cloak} 

{anchor:FastConfig}
h3. Enhanced Fast Configurations

ScanImage 3.7 enhances the interface and capabilities of _Fast Configurations_ -- [configurations|Configurations, CFG Files, & Fast Configurations (r3.6)] 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 {report-info:data:FastConfigurations|render=wiki|source=SI3.7 Data} window is accessed via *Settings >> Fast Configurations...* on the {report-info:data:MainControls|render=wiki|source=SI3.7 Data} menu:

h5. {toggle-cloak:id=FastConfigs} Show...
{cloak:id=FastConfigs}
{panel:title=Fast Configurations}{center}!Fast Configurations (r3.7)^FastConfigurations.bmp!{center}{excerpt-include:Fast Configurations (r3.7)|nopanel=true}{panel}
{cloak}

h3. Continuous File Streaming Improvements
ScanImage 3.5 introduced [continuous file streaming|http://openwiki.janelia.org/wiki/display/ephus/Unlimited+and+Uninterrupted+Acquisition] as an option for non-stack *GRAB/LOOP* acquisitions (i.e. acquisitions where {blue:# 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 _all_ *GRAB/LOOP* acquisitions (when {blue:AutoSave} is enabled), including stack acquisitions. The {blue:Save During Acquisition} option in 3.5.x and 3.6.x has been removed. 

As a consequence, ScanImage 3.7 no longer typically maintains a buffer in memory (RAM) of the entire acquisition. Instead, a configurable circular running buffer of the most recently acquired frames is maintained. 

The {report-info:data:UserSettings|render=wiki|source=SI3.7 Data} dialog, accessed via *Settings >> User Settings...* from the {report-info:data:MainControls|render=wiki|source=SI3.7 Data}menu) allows this  buffer to be configured:

h5. {toggle-cloak:id=UserSettings} Show...
{cloak:id=UserSettings}
{panel:title=User Settings}{center}!User Settings (r3.7)^UserSettings.bmp!{center}{multi-excerpt-include:name=MaxBufferedFrames|pageTitle=User Settings (r3.7)|nopanel=true}{panel}
{cloak}

h3. DAQ Toolbox No Longer Required
ScanImage 3.7 no longer requires use of the DAQ toolbox. Instead, it uses a Matlab [class|http://www.mathworks.com/help/techdoc/matlab_oop/ug_intropage.html] 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|http://zone.ni.com/devzone/cda/tut/p/id/9376#toc3] which underlie several of the new features in ScanImage 3.7.

h1. Other New Features

h3. Finite LOOP acquisitions
In earlier versions, [*LOOP*|SI3.6_AcqModes] mode acquisitions were indefinite -- the user was required to {blue:ABORT} the acquisition manually. 

In ScanImage 3.7, the {report-info:data:StandardControls|render=wiki|source=SI3.7 Data} panel allows user to specify a finite number of _Repeats_ for a [*LOOP*|SI3.6_AcqModes] acquisition: 

h5. {toggle-cloak:id=FiniteLoops} Show...
{cloak:id=FiniteLoops}
{panel:title=Standard Controls}{center}!Standard Controls (r3.7)^StandardControls.bmp!{center}{multi-excerpt-include:name=NumRepeats|pageTitle=Standard Controls (r3.7)|nopanel=true}{panel}
{cloak}


h3. Fractional zoom adjustment
In earlier versions, the {blue:Zoom} control in the {report-info:data:MainControls|render=wiki|source=SI3.7 Data} 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 {report-info:data:MainControls|render=wiki|source=SI3.7 Data} panel.

The {blue:Zoom} value simply represents a division of (both) the {blue:Angular Range Fast/Slow} values in the {report-info:data:Configuration|render=wiki|source=SI3.7 Data} panel. 

(/) For most users, the {blue:Angular Range Fast/Slow} values should not require modification -- the {blue:Zoom} control, with fractional values, should now provide sufficient adjustment flexibility over the scanned image area. 

h5. {toggle-cloak:id=FracZoom} Show...
{cloak:id=FracZoom}
{panel:title=Main Controls}
{center}!Main Controls (r3.7)^MainControls_FracZoomHighlight.png!{center}
(i) When a [Scan Parameter Array|Scan Configuration (r3.6)#FastScanDetails] is specified in the {report-info:data:Configuration|render=wiki|source=SI3.7 Data} panel, any non-integer {blue:Zoom} values are rounded to determine the scan parameters ({blue:Acquisition Delay}, {blue:Scan Delay}, and {blue:Fill Fraction}) in effect at specified {blue:Zoom}.
{panel}
{cloak}

h3. Slider adjustment of power during FOCUS
In ScanImage 3.7, a new {blue:Live Adjust} control on the {report-info:data:PowerControls|render=wiki|source=SI3.7 Data} panel allows the slider to be adjusted during [*FOCUS*|SI3.6_AcqModes], if selected: 

h5. {toggle-cloak:id=LiveAdjust} Show...
{cloak:id=LiveAdjust}
{panel:title=Power Controls}{center}!Power Controls (r3.7)^PowerControls.bmp!{center}
{multi-excerpt-include:name=LiveAdjust|pageTitle=Power Controls (r3.7)|nopanel=true}
(i) The {blue:Verify Power} control (rarely used) previously on the {report-info:data:PowerControls|render=wiki|source=SI3.7 Data} panel has been relocated to the {report-info:data:UserSettings|render=wiki|source=SI3.7 Data} dialog.
{panel}
{cloak}

{anchor:Colormap}
{set-data:ColormapLink|hidden=true}[colormap|http://www.mathworks.com/help/techdoc/ref/colormap.html]{set-data}
h3. More image display colormap options
In ScanImage 3.6.x and earlier, the [Image Display windows|SI3.6_ImageDisplay] are always displayed with a grayscale {report-info:data:ColormapLink|render=wiki}, with a few options to display pixels at or near saturation as colored. 

ScanImage 3.7 offers a wider range of standard {report-info:data:ColormapLink|render=wiki} options, and also provides users the ability to specify their own {report-info:data:ColormapLink|render=wiki} .

The {report-info:data:ImageControls|render=wiki|source=SI3.7 Data} panel provides the standard {report-info:data:ColormapLink|render=wiki} options:

h5. {toggle-cloak:id=ImageControls} Show...
{cloak:id=ImageControls}
{panel:title=Image Controls}{center}!Image Controls (r3.7)^ImageControls.bmp!{center}{multi-excerpt-include:name=ColormapSettings|pageTitle=Image Controls (r3.7)|nopanel=true}{panel}
{cloak}

The {report-info:data:Channels|render=wiki|source=SI3.7 Data} dialog provides the capability for a user-defined/configured {report-info:data:ColormapLink|render=wiki}:

h5. {toggle-cloak:id=Channels} Show...
{cloak:id=Channels}
{panel:title=Channels}{center}!Channels (r3.7)^Channels.bmp!{center}{excerpt-include:Channels (r3.7)|nopanel=true}{panel}
{cloak}

h3. 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|SI3.6_ImageDigitization]). The number of samples at each pixel is computed as the {blue:Bin Factor}, displayed on the {report-info:data:Configuration|render=wiki|source=SI3.7 Data} panel; its value is determined by the {blue:Nominal Ms/Line}, {blue:Pixels/Line}, and {blue:Input Sample Rate}.

Some users may preferScanImage 3.7 adds the option to average, rather than sum, the samples obtained at each pixel. This makesis theavailable intensity values for each [Image Display window|SI3.6_ImageDisplay] (and hence from the {blue:White} and {blue:Black} levels that are appropriate) independent of the {blue:Bin Factor} (and hence the {blue:Nominal Ms/Line}, {blue:Pixels/Line}, and {blue:Input Sample Rate} values). 

ScanImage 3.7 adds an {blue:Average Samples} control to select this option. See the {report-info:data:ImageControls|render=wiki|source=SI3.7 Data} panel documentation.
report-info:data:ImageControls|render=wiki|source=SI3.7 Data} panel:

h5. {toggle-cloak:id=AverageSamples} Show...
{cloak:id=AverageSamples}
{panel:title=Image Controls}{center}!Image Controls (r3.7)^ImageControls.bmp!{center}
{multi-excerpt-include:name=AverageSamples|pageTitle=Image Controls (r3.7)|nopanel=true}{panel}
{cloak}

{anchor:ShutterBeforeEOM}
h3. Support for shutter located before Pockels
The [Shutter control signal|SI3.6_Shutter] 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_|SI3.6_PockelsCell] 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 {vi-statevar:state.shutter.shutterBeforeEOM} value in the [INI file|SI_INIFile] should be set to 1. 

(i) The one & only effect of selecting this option is that shutter is opened/closed at start/end of [Pockels calibration|SI3.6_PockelsCell#PockelsCalibration]

(!) One effect of the {vi-statevar:state.shutter.shutterBeforeEOM} value is that the beam is transmitted through to scope, and potentially specimen, during Pockels calibration. Careful attention should be paid to the {vi-statevar:state.init.parkAngleX/Y} INI file values; the scanner is directed to this angle during Pockels calibration. 

h3. Ability to set root save file path
ScanImage requires that user select save path, via *File >> Set Save Path...* dialog on the {report-info:data:Main Controls|render=wiki|source=SI3.7 Data} panel before a {blue:GRAB/LOOP} acquisition with {blue:AutoSave} selected.

ScanImage 3.7 speeds this folder selection by allowing the {blue:Root Save Path} to be specified as a [User Setting|SI3.6_UserSettings] in to this angle during Pockels calibration. 

h3. Ability to set root save file path
ScanImage 3.7 makes it faster to select the _save path_, which is typically required at the start of each ScanImage session. The option is available from the {report-info:data:UserSettings|render=wiki|source=SI3.7 Data} 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 {blue:Root Save Path}.:
h5. {toggle-cloak:id=RootSavePath} Show...
{cloak:id=RootSavePath}
{panel:title=User Settings}{center}!User Settings (r3.7)^UserSettings.bmp!{center}
{multi-excerpt-include:name=RootSavePath|pageTitle=User Settings (r3.7)|nopanel=true}{panel}
{cloak}

{cache}