Motion Estimation and Correction

ScanImage® can continuously detect XYZ motion of the currently acquired image relative to a reference volume during an active acquisition.

The motion correction can be used to

Note

For 3D motion correction, the GpuMotionEstimator is recommended. This estimator requires the Matlab Parallel Computing Toolbox and a Nvidia CUDA enabled GPU.

Setup

If not already done once, perform a stage-scanner alignment.

Collect a reference Stack. Right click on the volume in the channel view window and select ‘Set as Motion Correction Reference’.


Motion Estimators

ScanImage® ships with 3 Motion Estimators. All estimators uses basic slice-wise phase correlation to find the best match between the acquired slice and the reference volume.

Name

System Requirements

Performance

Description

SimpleMotionEstimator

None

Good

Requires no additional toolboxes. Not well suited for 3D motion correction due to performance issues.

GpuMotionEstimator

Best

Best suited for 3D Motion Correction.

Note

Processing data on the GPU is fast, but transferring data to the GPU is a bottleneck. When imaging with low resolution, the SimpleMotionEstimator might perform better.

ParallelMotionEstimator

Better

Alternative to the GpuMotionEstimator if no GPU is present. This estimator uses parallel workers for precessing and dows not slow down the acquisition. The tasks are queued for processing. The queue size is a user settable property.


Motion Correctors

ScanImage® ships with 1 Motion Corrector.

Name

Description

SimpleMotionCorrector

This motion corrector averages the motion estimates of the last N seconds. If average motion vector is greater than the correction threshold, a correction event is triggered. The minimum time in between correction events is settable by the property correctionInterval_s.


Match Current FOV with Previous Session


Output Files

If data logging and motion correction are both enabled, a motion correction output file will be generated with a [File name stem] + “_Motion_” + [File counter] filename.

This file will contain the following attributes: timestamp, frameNumber, success, quality, xyMotion, roiUuid, motionMatrix, z, and channel.


API

Motion Estimators

Motion estimators derive from the class

scanimage.interfaces.IMotionEstimator

The reference volume and the image data are handed to the Motion Estimator as instance of the class

scanimage.mroi.RoiData.

scanimage.mroi.RoiData contains information about the ROI geometry (hRoi), the channels (channels) and the currently imaged zs (zs). The image data is stored in the property imageData. imageData is a cell array, where the first index is the channelIdx, and the second index is the z index.

The function

motion_estimator_result = estimateMotion(obj,roiData)

does not return the motion estimate directly, but instead returns an object of type scanimage.interfaces.IMotionEstimatorResult. ScanImage then polls this class to obtain the estimation results. The purpose of this class is to enable asynchronous processing.

Motion Correctors

Motion estimators derive from the class

scanimage.interfaces.IMotionCorrector

When a new motion estimate is available, ScanImage® populates the estimate by calling the function updateMotionHistory. This hands the entire motion history to the corrector. The corrector can then analyze the history and determine if a correction is required. When the corrector wants to initiate a correction, it notifies its event correctNow. ScanImage® then queries the function getCorrection to get the correction value.

Note

if the corrector returns an invalid value (e.g. values outside the allowable correction range), ScanImage discards the correction event.

After a correction is performed, ScanImage® calls the function correctedMotion.

Using Averaged frames

ScanImage 2023.0.0 introduces two checkboxes to the Motion Display window allowing use of averaged live frames to compare against the reference (which can also be an averaged frame). All that is required is to set a Frame Rolling Average Factor` > 1, and then place a check in the Average checkbox.

There is also a throttle checkbox. Checking this have motion detected every n frames where n is the Frame Rolling Average Factor.