Page History

----
{center}
!MotorControls.png!  !MotorControls_4D.png!
*MOTOR CONTROLS Panel*
3 dimensions (left); 4 dimensions (right)
{center}
-----
* [Overview|#Overview]
* [Section A: Current Motor Position|#Sec A]
* [Section B: _Image Stack_ Acquisition|#Sec B]
* [Section C: Storing/Loading Motor Positions|#Sec C]
----
{set-data:MDF|hidden=true}[Machine Data File|Getting Started Guide (r4.1)]{set-data}
{set-data:VolIm|hidden=true}[Volume Imaging|FastZ Controls (r4.1)]{set-data}

{anchor:Overview}
h3. Overview
The *MOTOR CONTROLS* window pertains to (optional) control of a stage/motor controller system supported by ScanImage. 

The *Motor Controls* panel only appears on ScanImage startup if a _motorControllerType_ is specified in the {get-data:MDF}. Other _motorXXX_ settings in the {get-data:MDF} pertain to this controller, if specified - e.g. the COM port controller is connected to if it is serial-port controlled.

If a _Secondary Z_ motor controller is activated in the {get-data:MDF} (by specifying the _motor2ControllerType_), and the primary motor controller is configured with _motorDimensions_='XYZ' (the default value), then *MOTOR CONTROLS* controls 4 dimensions in total (termed the _XYZ\-Z_ configuration), as shown at right above. In all other configurations  (_XY_, _Z_, _XYZ_, _XY\-Z_), 3 dimensions are shown, as at left above (inactive dimensions, if any, are shown with value 0). 
 

{anchor:Sec A}
h3. Section A: Current Motor Position

{tip:title=ScanImage vs Motor Relative}ScanImage has its own notion of _relative_ positions, independent of the relative coordinates maintained by some motor controllers, such as the [Sutter MP285|http://www.sutter.com/products/product_sheets/MP-285.html]. To make this distinction clear, the coordinate sets are referred to below as _ScanImage Relative_ and _Motor Relative_.{tip}

* {blue:X/Y/Z}: These controls play two roles -- 
** They _display_ the most recent position read from the motor controller in each of the 3-4 axes. 
** Entering a value for any of the axes commands the motor to _move_ to the specified position for that axis. Following the move, the position will be read and updated for all three axes. 

(i) ScanImage _always_ reads the _Motor Absolute_ position from the motor. By default (at ScanImage startup), ScanImage displays and interprets positions in _Motor Absolute_ coordinates. This remains true until (and only if) coordinates are converted to _ScanImage Relative_ coordinates by pressing one of the {blue:Zero XYZ/Zero XY/Zero X} buttons. 

* {blue:Read Pos}: Forces ScanImage to read the current motor position in all three axes and to update the displayed {blue:X/Y/Z} values, e.g. following manual adjustment of the motor position using the motor controller outside of ScanImage control. 

* {blue:R}: Read-only control that displays the squared-sum of the 3-4 displayed {blue:X/Y/Z} values

* {blue:Zero XYZ/Zero XY/Zero Z}: Pressing these buttons forces _ScanImage Relative_ positions to be used in the specified axes (if not used already) and resets the relative origin in the specified axes to the current position (which is first read from the motor controller). 

(i) Once _ScanImage Relative_ positions are used in a particular axes, there is no returning to _Motor Absolute_ coordinates. Pressing {blue:Zero XYZ/XY/Z} again simply sets a new _ScanImage Relative_ origin (in the specified axes).

* {blue:Sec Z}: In 4-dimension _XYZ\-Z_ case, enabling/disabling this checkbox determines whether primary (disabled) or secondary (enabled) Z motor controller pertains for:
** {blue:Zero Z} operation
** {blue:Z} step with arrow controls
** Image Stack acquisitions (for standard, stepping stacks)

{tip:title=Matching Relative Coordinates}A common and recommended approach is to set both the motor controller and ScanImage to operate in matched _Relative_ coordinates. The procedure to accomplish this is as follows:\\ \\
&nbsp;&nbsp;1. Adjust the motor controller to display _Motor Relative_ positions, if not already. (For the [MP-285|http://www.sutter.com/products/product_sheets/MP-285.html], display of _Motor Absolute_ and _Motor Relative_ positions is toggled by hitting <ENTR>)\\&nbsp;&nbsp;2. Set the _Motor Relative_ position to zero at some desired position. (For the [MP-285|http://www.sutter.com/products/product_sheets/MP-285.html], this is done by hitting <0>,<ENTR>).\\&nbsp;&nbsp;3. Immediately afterwards, press {blue:Zero XYZ} to set the _ScanImage Relative_ position.\\ \\At this point, both the motor controller and ScanImage are operating in _Relative_ coordinates, at position (0,0,0). If desired, these steps can be repeated later at new physical position(s), updating both _Relative_ origins in tandem.{tip}

* {blue:XY and Z} Arrows/Steps: Increment or decrement stage position in X, Y, or Z dimension by the specified step, in microns. In 4-dimension _XYZ\-Z_ case, the {blue:Sec Z} value determines which motor controller is used when incrementing/decrementing the Z position.

{anchor:Sec B}
h3. Section B: _Image Stack_ Acquisition
These controls configure Image Stack acquisitions, of which ScanImage supports two types: 
* Standard ('Slow Z') stepping stacks
* Volume Imaging ('Fast Z') stacks (when {blue:Enable} is selected in the *FAST Z CONTROLS*)

When value of {blue:# Slices} is greater than 1, an image stack acquisition is implied for each GRAB or LOOP Repeat. For standard stacks, each _Slice_ is an individually triggered acquisition taken at a distinct axial (Z) position, consisting of one or more Frames, as specified by {blue:# Frames} on the *MAIN CONTROLS* window. See {get-data:VolIm} for more information about FastZ stacks. 

h5. Core Image Stack Controls

* {blue:# Slices}
** For standard stacks, specifies number of _Slices_ to collect during an Image Stack acquisition. 
** For {get-data:VolIm}, specifies the number of frames acquired during each volume period.

* {blue:Step/Slice}
** For standard stacks, specifies axial (Z) step to take with the motor controller between each _Slice_. 
** For {get-data:VolIm}, specifies the axial distance traversed (e.g. swept) between successive frames in each volume period.
(/) Either a positive or negative value can be specified, so motion may proceed in either axial direction

{multi-excerpt:name=StackControls}
* {blue:Return Home}: If enabled, motor controller returns to _Home_ position -- the initial axial position when a GRAB or LOOP was initiated -- following the GRAB acquisition or each LOOP Repeat. This ensures subsequent acquisitions or Repeats traverse the same axial positions.
(!) For LOOP acquisitions, this option should typically be enabled. If not enabled, successive Repeats will image progressively further along the axial direction specified, which is typically not desired.

* {blue:Centered Stack}: If enabled, axial position at start of Image Stack acquisition is taken as the center of the stack. Motor is moved backwards by half the total span implied by {blue:# Slices} and {blue:Step/Slice} prior to the start of the stack acquisition.{multi-excerpt}
(i) If {blue:Centered Stack} is enabled and {blue:# Slices} is even, then no Slice will be obtained or centered on the starting axial position at time of GRAB/LOOP initiation

h5. Image Stack Endpoint & Power Controls
Often, users may wish to select the starting and ending axial positions, as well as the imaging power, interactively, i.e. during FOCUS when the axial position and power can each be adjusted during live imaging. 

{info:title=Endpoints for Slow Z Only}As of ScanImage 4.1, the stack position and power start/endpoint constraints only apply to standard (Slow Z) stacks. However, using interactive stack start & endpoint selection can still be useful for {get-data:VolIm} to determine/set the {blue:Lz} (length constant) value in *POWER CONTROLS* by using {blue:Override Lz}.{info}

* {blue:Posn start}: The starting axial position of stack can be {blue:set} interactively. Motor controller will be moved to specified axial position at start of subsequent (standard) Image Stack acquisitions. 

* {blue:Posn end}: The ending axial position of stack can be {blue:set} interactively. When both {blue:Posn start} and {blue:Posn end} are set, the values of {blue:# Slices} and {blue:Step/Slice} are constrained so that Image Stacks traverse the specified axial extent. 

(/) The constraint on {blue:# Slices} and {blue:Step/Slice} remains in effect until either {blue:clr all} or {blue:clr end} is pressed. 

If {blue:P/z Adjust} is enabled for a particular {blue:Beam} on the *POWER CONTROLS* window, the following controls pertain:

{blue:Power start}: Power to use at starting axial position of stack can be {blue:set} interactively. If {blue:Use start pwr} is enabled, then power is adjusted to this level (for selected/displayed {blue:Beam}) at start of subsequent (standard) Image Stack acquisitions.

{blue:Power end}: Power to use at ending axial position of stack can be {blue:set} interactively. When both {blue:Posn start} and {blue:Posn end} are set, user can choose to automatically or manually {blue:Override Lz}, i.e. override the length constant {blue:Lz} set on the *POWER CONTROLS* for the selected {blue:Beam}, with the exponential length-constant value implied by (computed from) the start/end positions and powers.

{blue:Override Lz}: When {blue:Position start/end} and {blue:Power start/end} values are all {blue:set}, the {blue:Lz} (length constant) value in *POWER CONTROLS* can be overridden with value computed from the specified position/power endpoints. 
* With checkbox enabled, the *POWER CONTROLS* {blue:Lz} value is automatically overridden when all endpoints are set
* With checkbox disabled, button can be used to manually override *POWER CONTROLS* {blue:Lz} value

(i) When {blue:Power start} or {blue:Power end} are {blue:set}, current power values are captured/stored for each Beam. Stored value for only the currently selected {blue:Beam} in *POWER CONTROLS* is shown at a time. 
(i) {blue:Power end} values are stored for Beams for which {blue:P/z Adjust} is disabled on *POWER CONTROLS* have no effect

{tip:title=Set Lz Once}The {blue:Lz} length constant values for each Beam are saved as part of the ScanImage User Settings (*.USR) file. For a given specimen type, the length constant describing the additional power required as a function of depth can be expected to remain generally constant. Thus, users may typically set the power and position levels interactively (spanning a wide axial extent) and manually select {blue:OverrideLz} to compute the length constant. Then this value can be saved to the *.USR file, avoiding requirement to interactively set/determine the length constant in future ScanImage sessions.{tip}


{anchor:Sec C}
h3. Section C: Motor Positions
ScanImage can store sets of motor controller coordinates ('positions') which can be later revisited and/or stored into position (.POS) files. 

* {blue:ADD}: Reads motor controller coordinates (including Secondary Z coordinate if _XYZ\-Z_ configuration is used) updating {blue:X/Y/Z} values. Creates new Position ID at these coordinates, shown in the *POSITION CONTROLS* window.

* {blue:POSN >>/<<}: Show/hide the *POSITION CONTROLS* window, which allows user to revisit previously stored motor positions.