Icon
This documentation is for a legacy ScanImage version. The current documentation is ScanImage 2019.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

ScanImage can continuously detect X-Y motion of the currently acquired image relative to a reference image during an active acquisition. ScanImage can also estimate motion in Z by comparing the currently acquired image to a reference volume of images during an active acquisition.

The motion correction can be used for

Setup

HTML
<center><iframe width="960" height="540" src="https://www.youtube.com/embed/SGFMrYDvdD4?controls=1&autoplay=0&loop=0&modestbranding=1&playlist=SGFMrYDvdD4" frameborder="0" allowfullscreen></iframe></center>

Algorithm

ScanImage ships with five algorithms for motion detection:

ScanImage DefaultFunctionPerformanceDescription
Default if GPU acceleration is not availablefftCorrGoodestimates motion by calculating the fft-based circular cross correlation between the reference image and the current image
Default if GPU acceleration is availablefftCorrGpuExcellentsame as fftCorr, but calculates the fft-based cross correlation using the GPU
 fftCorrSideProjExcellentfirst calculates the mean side projections for x and y, then calculates the fft-based circular cross correlation between the side projections of the reference image and the current image; less accurate, but more performant than fftCorr
 fftPhaseCorrVariable

estimates the approximate Z position by calculating the fft-based normalized phase cross correlation between the current image and all images in a reference volume, after determining which plane in the reference volume best matched the current image the X-Y offset is calculated between the current image and reference in the same manner as above. If the reference does not contain multiple images then this behaves the same way as fftCorr.

Info

Performance varies depending on size and resolution of reference volume

 fftPhaseCorrGpuGoodsame as fftPhaseCorr but uses the GPU
Info

GPU acceleration for motion correction is only available if the Matlab Parallel Computing Toolbox is installed and a CUDA enabled GPU is available.

 

The motion correction algorithm is split into two parts:

  • Reference image pre-process function
  • Motion correction algorithm

Use the Motion Correction Windows to select which motion correction algorithm is used.

Info

The Motion Correction Functions are stored in +scanimage\+components\+motionCorrection
When selecting a motion correction function in the Motion Correction Window, make sure to also select the corresponding preprocess function. 

API

The pre-process function is called only when a new reference image is loaded, while the motion correction algorithm is called every time a frame is acquired. This reduces the number of reoccuring calculations. In the fft-based cross correlation, the fft of the reference image is processed once, and then stored for later use. The preprocess function ha two return values:

Return ValueDescription
refDisplayImage

(Required) Used as a reference image in the Motion Correction Display Windows

refImagePreProcessed(Required) The pre-processed reference data passed to the motion correction algorithm whenever a frame is acquired. (Can be a matrix, struct, class..)

The motion-correction function expects two inputs:

InputDescription
refImagePreProcessedpre-processed reference data
imageimage data of current frame
OutputRequiredData typeDescription
successRequiredlogicalIndicates if the motion algorithm found a match between the reference image and the current image
ijkOffsetRequired if success==true\[1x3] \ doubleThe [i,j,k] offset between the reference image and the current image. The k offset is actually the slice number of best match, actual Z position is then determined by the slice number and the step per slice.
qualityCan be emptydoubleA metric describing the quality/certainty of the match
ciiCan be empty\[1xM\] doubleA metric showing the quality/certainty of the match for each possible pixelshift in direction i
cjjCan be empty\[1xN] doubleA metric showing the quality/certainty of the match for each possible pixelshift in direction j
Info

Note: ScanImage internally represents images in column-major order, whereas Matlab uses row-major order for storing matrices. This means that images appear to be transposed when plotted.
As a workaround, images can be transposed, which will result in a performance hit. Alternatively, the axes view can be rotated:

Code Block
view(gca,-90,90);
Info

The motion correction functionality is handled by the ScanImage module hMotionManager. Type

Code Block
hSI.hMotionManager

in the Matlab Command Window to see all availble properties and functions.