MotionManager

scanimage.components.MotionManager, reachable as hSI.hMotionManager, estimates sample motion from the acquired frames and, optionally, corrects it by moving the galvos, the FastZ actuator or the stage.

Estimation

Property	Description
`enable`	Enable motion estimation.
`estimatorClassName`	Class of the default motion estimator. Defaults to `scanimage.components.motionEstimators.SimpleMotionEstimator`.
`motionHistoryLength`	Number of motion estimates retained. Default 100.
`lastEstimationTimestamp`	Timestamp of the most recent estimate.
`estimateOnNewAveragedFrames`	Estimate on averaged frames rather than every raw frame.
`useAveragedStripe`	Use the averaged stripe when estimating.
`zStackAlignmentFcn`	Function used to align a reference z stack. Defaults to `scanimage.components.motionEstimators.util.alignZRoiData`.

Method	Description
`hME = hSI.hMotionManager.addEstimator(val,className)`	Add an estimator, optionally of a specific class.
`hSI.hMotionManager.removeEstimator(id)`	Remove one estimator.
`hSI.hMotionManager.clearAndDeleteEstimators()`	Remove all of them.
`hSI.hMotionManager.selectEstimatorClass()`	Choose the estimator class interactively.
`hSI.hMotionManager.convertEstimatorsToDefaultClass()`	Convert every estimator to `estimatorClassName`.
`hSI.hMotionManager.reprocessEstimatorsAndCorrector()`	Re-run estimation and correction with the current settings.
`hSI.hMotionManager.loadReferenceFromFile(tifPath)`	Build a reference from a Tiff file.
`hSI.hMotionManager.loadTiffOrMotionEstimatorFromFile(filePaths)`	Load references or serialized estimators.
`hSI.hMotionManager.loadEstimators(filePaths)`	Load estimators from disk.
`hSI.hMotionManager.saveManagedEstimators(filePath)`	Save the managed estimators.
`hSI.hMotionManager.saveEstimators(hMEs,filePath)`	Save a specific set of estimators.
`roiDataAligned = hSI.hMotionManager.alignZStack(roiData)`	Align a z stack using `zStackAlignmentFcn`.

Correction

Property	Description
`correctionEnableXY`, `correctionEnableZ`	Enable lateral and axial correction.
`correctionDeviceXY`	`'galvos'` or `'motor'`.
`correctionDeviceZ`	`'fastz'` or `'motor'`.
`correctionBoundsXY`	`[min max]` allowed lateral correction, in reference-space scan angle.
`correctionBoundsZ`	`[min max]` allowed axial correction, in microns.
`resetCorrectionAfterAcq`	Return the correction to zero when the acquisition ends.
`correctorClassName`	Class of the motion corrector.
`hMotionCorrector`	The corrector object itself.
`motionMarkersXY`	`N x 2` points drawn in the motion correction display. Visualization only.
`plotPerformance`	Show a benchmark plot of the estimators.

Method	Description
`tf = hSI.hMotionManager.activateMotionCorrectionSimple(channel)`	Set up estimation and correction on one channel with default settings. Returns whether it succeeded.
`hSI.hMotionManager.resetMotionCorrection(moveAxes)`	Zero the accumulated correction, optionally moving the axes back.
`hSI.hMotionManager.manualCorrect(dr)`	Apply a manual correction in all axes.
`hSI.hMotionManager.manualCorrectXY(dr)` / `manualCorrectZ(dr)`	Apply a manual correction laterally or axially.
`hSI.hMotionManager.selectCorrectorClass()`	Choose the corrector class interactively.

hSI.hMotionManager.activateMotionCorrectionSimple(1);
hSI.hMotionManager.correctionEnableXY = true;
hSI.hMotionManager.correctionDeviceXY = 'galvos';
hSI.hMotionManager.correctionBoundsXY = [-2 2];

Warning

The correction bounds are a safety limit, not a tuning parameter. Widening them lets a bad estimate drive the galvos or the stage a long way.

Events

Event	Fires when
`newMotionEstimateAvailable`	A new motion estimate has been computed.
`motionEstimatorsChanged`	Estimators were added, removed or replaced.
`motionHistoryReset`	The motion history was cleared.

The motionCorrected user function event fires whenever ScanImage actually moves an actuator to correct motion.

Writing an estimator or corrector

Custom estimators derive from scanimage.interfaces.IMotionEstimator and return a scanimage.interfaces.IMotionEstimatorResult; custom correctors derive from scanimage.interfaces.IMotionCorrector. Shipped implementations live in scanimage.components.motionEstimators and scanimage.components.motionCorrectors and are the best starting point.