Page History

{composition-setup}
{alias:SI3.7Doc}
{cache: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 
and 2) contains updated _Getting Started_ and _Window Reference_ guides

ScanImage 3.7 isOtherwise, quite similar to 3.6. The the various _keyKey conceptsConcepts_ described in the [ScanImage r3.6.x Documentation] are, broadly speaking, still applicable. The _keyKey conceptsConcepts_ 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. {note}

{cache}
* +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], with [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}


h1. 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 make this adjustment automatically, using a simple exponential length constant (_Lz_).

The {report-info:data:PowerControls|render=wiki|source=SI3.7 Data} panel allows this capability to 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}{center}!Motor Controls (r3.7)^MotorControls.bmp!{center}{excerpt-include:Motor Controls (r3.7)|nopanel=true}{panel}
{cloak}

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

ScanImage 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 feature:
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}.

ScanImage 3.7 adds the option to average, rather than sum, the samples obtained at each pixel. This is available from the {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 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:
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}