Page History

{composition-setup}
{toc:maxLevel=5}

h2. New Features in ScanImage 3.7
* Compatibility with latest Matlab (2010b) and [DAQmx (9.2.2)|http://joule.ni.com/nidu/cds/view/p/id/2215/lang/en]. 
* 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_

h2. Upgrading from ScanImage 3.5 or 3.6
* 3.7 has a [new model INI file|http://openwiki.janelia.org/wiki/display/ephus/ScanImage+INI+File+Overview] , 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. 
(i) 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. 
(i) 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|http://openwiki.janelia.org/wiki/display/ephus/Wiring+Your+System+%28r3.6%29#WiringYourSystem%28r3.6%29-ClockSync] 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|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. 
(i) Note that X series boards are only supported from 9.0 forward.


h2. Guide to New Features

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 enables this, allowing a simple exponential length constant (_Lz_) to be specified. 

This feature is primarily controlled from the *Power Controls* window:

{panel}
{center}!PowerControls.bmp!{center}

*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_|Pockels Cell Control (r3.6)]. Power is increased with depth according to _P = P0 * exp^((z-z0)/Lz)_. 
{panel}
(/) A value of _Inf_ implies no  power adjustment should occur for the selected beam.
(i) 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|User Settings & USR Files (r3.6)]-- i.e. their values are saved to *USR* files.
(i) 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:

{panel}
{center}!MotorControls.bmp!{center}

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.
{panel}

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.

(i) If multiple [_beams_|Pockels Cell Control (r3.6)] 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.

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}

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)
* *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_


*& _Next Triggering_ allows external trigger (e.g. from behavior apparatus) to stop an acquisition, or to start a new file with advanced number without stopping acquisition


h3. Enhanced User Functions capability
* Numerous events to which user functions, with optional modulating arguments, can be bound.

h3. Enhanced Fast Configurations


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 {color:green}state.acq.acquiredData{color} 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:
{center}
{color:green}state.acq.acquiredData{<FrameIndex>}{<ChannelIndex>}(<lineIndex>,<pixelIndex>){color}
where <FrameIndex> counts from the most recent frame.
{center}

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 {color:green:}state.acq.acquiredData{color} 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.