Page History

{alias:SI3.8_MotorControls|parent=Aliases}
----
{center}
!MotorControls.bmp!  !MotorControls_4D.bmp!
*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]
{comment}* [Resetting Motor Operation Following Faults|#MotorReset]{comment}
----

{anchor:Overview}
h3. Overview
The *Motor Controls* panel pertains to the (optional) control of a stage/motor controller system supported by ScanImage. See the [ScanImage Hardware Reference|SI_SupportedHardware] for information about the currently supported controllers/stages.

The *Motor Controls* panel only appears on ScanImage startup if {vi-statevar:state.motor.motorOn} is enabled in the [INI File|SI_INIFile]. Other settings related to the MP-285 must also be properly configured in the [INI File|SI_INIFile], including the correct specification of the COM port used to communicate with the MP-285 over an RS-232 (serial port) connection.

If a _Secondary Z_ motor controller is activated in the [INI File|SI_INIFile] ({vi-statevar:state.motor.controllerTypeZ} specified), and the primary motor controller is configured as {vi-statevar:state.motor.dimensions}='XYZ', then the *Motor Controls* controls 4 dimensions in total (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
(/) This is most useful when using _ScanImage Relative_ coordinates in all 3-4 axes, as it then indicates the distance from the _ScanImage Relative_ origin.

* {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
** [Stack acquisitions|SI3.6_ImageStacks]


(/) In 4-dimension _XYZ\-Z_ case, the {blue:Zero XYZ} operation sets ScanImage relative origin for _all 4 dimensions_ (i.e. regardless of the {blue:Sec Z} checkbox state).

{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 allow the collection of [Image Stack|SI3.6_ImageStacks]. When the value of {blue:# Slices} is greater than 1, an [Image Stack|SI3.6_ImageStacks] is implied for each [GRAB|SI3.8_AcqModes] or [LOOP _Repeat_|SI3.8_AcqModes]. 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*|Main Controls (r3.8)] panel.

The controls in this section also allow the endpoints of the [Image Stack|SI3.6_ImageStacks] to be determined interactively, e.g. by manually focusing to axial (Z) boundaries of a volume-of-interest while using [*FOCUS* mode|SI3.8_AcqModes] acquisition.

* {blue:# Slices:} Specifies the number of _Slices_ to collect during the [Image Stack|SI3.6_ImageStacks] acquisition

* {blue:Z Step/Slice:} Specifies the axial (Z) step to take with the stage/motor controller between each _Slice_
(/) Either a positive or negative value can be specified, so the motion may proceed in either axial direction

* {blue:Return Home}: Specifies that stage/motor controller returns to the _Home_ position -- the initial position when [GRAB or LOOP |SI3.6_AcqModes] is initiated -- following the [GRAB|SI3.6_AcqModes] acquisition or [LOOP _Repeat_|SI3.6_AcqModes], so that subsequent acquisitions or _Repeats_ occur at the same axial positions.
(!) If this option is not enabled when using [LOOP|SI3.6_AcqModes] mode, then successive _Repeats_ will image progressively further along the axial direction specified
(i) If {blue:Centered Stack} is disabled, the first _Slice_ in the _Image Stack_ (or first [Image Stack|SI3.6_ImageStacks] within a [LOOP|SI3.6_AcqModes] acquisition) is taken at the _Home_ position -- i.e. the motor does not move until after the first _Slice_ is acquired.
(!) At this time, [external triggering|SI3.6_Triggering] is not supported for [Image Stack|SI3.6_ImageStacks] acquisitions

* {blue:Centered Stack}: If enabled, motor position at start of [Image Stack|SI3.6_ImageStacks] acquisition is taken as the center of the stack. Motor is moved backwards by half the total span implied by {blue:# Slices} and {blue:Z Step/Slice} prior to the start of the stack acquisition.
(i) If {blue:# Slices} is even, then no _Slice_ acquisition will occur at exactly the starting 

* {blue:GRAB}: Button functions equivalently to {blue:GRAB} button one [*Main Controls*|Main Controls (r3.8)] panel except that, before the acquisition:
** Motor is moved to Z position set as {blue:Start}
** If {blue:P/z Adjust} is enabled on the [*Power Controls*|Power Controls (r3.8)], power is adjusted to value measured for each beam(s) when {blue:Start} was last set
(/) In addition, this {blue:GRAB} button must be used for {blue:Override Lz} to have an effect (see below)

* {blue:Start/End}
Pressing one of these buttons reads the current motor position in the Z axis (updating the {blue:Z} position display) and stores this value as the {blue:Start/End} position displayed alongside the buttons. In addition, the start and end powers are measured and stored, which can be recalled on _Image Stack_ acquisitions started by {blue:GRAB} on *Motor Controls*, subject to other controls described below. 
(i) The {blue:End} value has no effect, unless {blue:Constrain Slice Params} is selected
(i) The coordinates displayed are in either ScanImage _Absolute_ or _Relative_ coordinates, depending on whether {blue:Z} represents _Absolute_ or _Relative_ positions (i.e. whether {blue:Zero Z} or {blue:Zero XYZ} has been selected since ScanImage started). 


* {blue:Constrain Slice Params}
If enabled, adjustments to either {blue:# Slices} or {blue:Z Step/slice} will automatically adjust the other parameter, so  that the {blue:Start/End} values defined remain in effect.
(i) If the checkbox is deselected, any change to the {blue:Z Step/slice} or {blue:# Slices} will clear the stack start/endpoints.


* {blue:Override Lz}: {multi-excerpt:name=OverrideLz}
When {blue:Override Lz} is selected, stack acquisitions initiated via the {blue:GRAB} button on the *Motor Controls* panel (rather than from [*Main Controls*|Main Controls (r3.8)]) will override the {blue:Lz} (power length constant) value on the [*Power Controls*|Power Controls (r3.8)] panel (assuming {blue:P/z Adjust} is enabled on that panel). Instead the _Lz_ value  is computed from power levels measured at the endpoints of the stack determined by the {blue:start/end} buttons.\\ \\With {blue:OverrideLz} selected, user will typically use {blue:FOCUS} mode to adjust power and Z position at both the start and end points of stack, pressing {blue:start} and {blue: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 the [*Power Controls*|Power Controls (r3.8)] panel\\ \\When {blue: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 {blue:Lz} control on the [*Power Controls*|Power Controls (r3.8)] panel 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.

(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 independently at each endpoint.

{multi-excerpt}

{multi-excerpt:LzInf}
{info:Lz=Inf Case}If value of {blue:Lz}=_Inf_ for a particular _Beam_ in the [*Power Controls*|Power Controls (r3.8)] panel, then power auto-adjustment is disabled for that _Beam_, regardless of {blue:OverrideLz} setting. Additionally, the start power is not adjusted for that _Beam_ when {blue:GRAB} is pressed on [*Motor Controls*|Motor Controls (r3.8)].
\\
Thus, to use the {blue:Override Lz} feature and to ensure start power is adjusted to that set on setting {blue:Start}, some (arbitrary) value (other than _Inf_) should be entered for each _Beam_.{info}
{multi-excerpt}

{anchor:Sec C}
h3. Section C: Motor Positions

* {blue:POSN ID}: Indicates the [Position ID|Position Controls (r3.8)] matching the last-read motor position (shown in {blue:X/Y/Z} display), if any, to within the current [Position Tolerance|Position Controls (r3.8)]. User can select another [Position ID|Position Controls (r3.8)] from the dropdown menu to initiate motor move to those stored position coordinates. 
(i) If current position does not match any currently defined [Position ID|Position Controls (r3.8)], then an empty string is displayed. 

* {blue:ADD}: Read the current motor position (updating the {blue:X/Y/Z} display) and create new identified  _Position_ in the [Position Controls|Position Controls (r3.8)]  panel. 

* {blue:POSN >>/<<}: Show/hide the [Position Controls|Position Controls (r3.8)] panel.

{comment}
{info:title=Cycle Mode}The controls in this section are mainly useful in relation to _Cycle Mode_ operation, which allows for automated/repeated imaging at a defined list, or array, of motor positions. This mode is disabled in ScanImage 3.6. It is functional in ScanImage 3.5.1 and is intended to be supported again in a future ScanImage release.{info}

The controls in this section allow triads of {blue:X/Y/Z} position values to be saved and recalled. Selecting {blue:Define} stores the current {blue:X/Y/Z} positions as a triad to the currently indicated {blue:Position #}. Later selecting {blue:Go To} will command motor to move to the currently indicated {blue:Position #}, if a value has been stored.

The entire set of stored {blue:X/Y/Z} position values can be saved to disk as a *.POS* (position) file, by selecting {blue:Save...}. Likewise, an entire set of stored values can be recalled (eliminating any currently stored values) by selecting {blue:Load...}.
{comment}


{comment}
{anchor:#Sec D}
h3. Resetting Motor Operation Following Faults

Occasionally, a motor operation (move, read, or other command) may fail during ScanImage operation. This occurrence should be quite rare.

In the event that a motor operation fails during ScanImage execution, the *Motor Controls* panel will inactivate its controls and display a large {blue:RESET} button as depicted here:
{vi-indent:10}
[!MotorControlsResetButton.bmp!|^MotorControlsResetButton.bmp]
_*Motor Controls* panel displays prominent {blue:RESET} button in event of motor operation error during ScanImage execution_
{vi-indent}

* Pressing the {blue:RESET} button will often restore motor operation, and then causes the {blue:X/Y/Z} positions to be updated. 
* If the {blue:RESET} action is unsuccessful, then it is recommended to physically reset the motor controller (the [MP-285|http://www.sutter.com/products/product_sheets/MP-285.html] has a physical reset button) and then press {blue:RESET} again.

{vi-indent:2}
(i) If the *Motor Controls* panel is in the 'reset' state, ScanImage operation can continue, but no further operations involving the motor controller can be undertaken
{vi-indent}
{comment}