camera_stage_mapping.fft_image_tracking

Utility functions to track motion of a microscope using FFT-based correlation.

Cross-correlation is a reasonable way to determine where an object is in an image. It can also be used to track 2D motion. The Fourier Shift Theorem relies on the fact that a correlation (or convolution) becomes a multiplication in the Fourier domain. This means that Fast Fourier Transforms are an efficient way to implement cross-correlation of whole images. This module contains a number of functions to simplify tracking the motion of a microscope stage using FFTs.

(c) Richard Bowman 2020, released under GNU GPL v3 No warranty, express or implied, is given with respect to this code.

Module Contents

Functions

grayscale_and_padding(image[, pad])	Convert to grayscale and prepare for zero padding if needed.
high_pass_fourier_mask(shape, s[, rfft])	Generate a mask performing a high pass filter
high_pass_fft_template(image[, sigma, pad, calculate_peak])	Calculate a high-pass-filtered FT template for tracking
background_subtracted_centre_of_mass(corr[, ...])	Carry out a background subtracted centre of mass measurement
displacement_from_fft_template(template, image[, ...])	Find the displacement, in pixels, of an image from a template
displacement_between_images(image_0, image_1[, sigma, ...])	Calculate the displacement, in pixels, between two images.

camera_stage_mapping.fft_image_tracking.grayscale_and_padding(image, pad=True)

Convert to grayscale and prepare for zero padding if needed.

The FFT-based tracking methods need grayscale images. Also, if we are going to zero-pad, we should convert to floating point and ensure the mean of the image is zero, otherwise the dominant feature will be the edge of the image.

Returns:

image, fft_shape

camera_stage_mapping.fft_image_tracking.high_pass_fourier_mask(shape, s, rfft=True)

Generate a mask performing a high pass filter

The return value is a 2D array, which can be multiplied with the Fourier Transform of an image to perform a high pass filter.

Parameters:

• shape – tuple of 2 integers The shape of the output array

• s – float The standard deviation of the Gaussian in real space, in pixels

camera_stage_mapping.fft_image_tracking.high_pass_fft_template(image, sigma=10, pad=True, calculate_peak=True)

Calculate a high-pass-filtered FT template for tracking

This performs a real FFT, and then attenuates low frequencies. The resulting array can be used as a template for tracking.

sigma is the standard deviation in pixels of the Gaussian used in the high pass filter.

pad enables (default) zero padding - this removes the ambiguity around position, at the cost of making the function slower. We subtract the mean and zero-pad the input array (equivalent to padding with the mean value, to reduce the impact of the edge)

calculate computes the value of the brightest pixel we’d expect in a correlation image (i.e. the peak if we correlate the image passed in with the template we’re generating). This is stored in template.attrs["peak_correlation_value"]

camera_stage_mapping.fft_image_tracking.background_subtracted_centre_of_mass(corr, fractional_threshold=0.05, quadrant_swap=False)

Carry out a background subtracted centre of mass measurement

Parameters:

• corr – a 2D numpy array, to be thresholded

• fractional_threshold – the fraction of the range (from min(corr) to max(corr)) that should remain above the background level. 1 means no thresholding, 0.05 means use only the top 5% of the range.

• quadrant_swap – boolean, default False Set this to true if we are working on the output of a Fourier transform. This will adjust the coordinates such that we effectively perform quadrant swapping, to place the DC component in the centre of the image, and make the coordinate (0,0) correspond to that point, with positive and negative coordinates either side.

exception camera_stage_mapping.fft_image_tracking.TrackingError

Bases: Exception

Common base class for all non-exit exceptions.

camera_stage_mapping.fft_image_tracking.displacement_from_fft_template(template, image, fractional_threshold=0.1, pad=True, return_peak=False, error_threshold=0)

Find the displacement, in pixels, of an image from a template

The template should be generated by high_pass_fft_template Fractional_threshold is the fraction of the range (from max to min) of the cross-correlation image that should remain above the threshold before finding the peak by centre-of-mass.

NB because of the periodic boundary conditions of the FFT, this gives a result that is ambiguous - it’s only accurate modulo one image. The result that is returned represents the smalles displacement, positive or negative. You may add or subtract one whole image-width (or height) if that makes sense - use other cues to resolve the ambiguity.

return_peak returns the brightes pixel in the correlation image, as well as the displacement in a tuple.

error_threshold is an optional floating-point number between 0 and 1. Setting it to a value greater than 0 will compare the correlation value with the maximum possible. If the ratio of the current signal to the maximum drops below error_threshold, we raise a TrackingError exception.

camera_stage_mapping.fft_image_tracking.displacement_between_images(image_0, image_1, sigma=10, fractional_threshold=0.1, pad=True)

Calculate the displacement, in pixels, between two images.