motion_correction.image_registration.fft_tools package

Subpackages

Submodules

motion_correction.image_registration.fft_tools.convolve_nd module

motion_correction.image_registration.fft_tools.correlate2d module

motion_correction.image_registration.fft_tools.correlate2d.correlate2d(im1, im2, boundary='wrap', nthreads=1, use_numpy_fft=False, **kwargs)[source]

Cross-correlation of two images of arbitrary size. Returns an image cropped to the largest of each dimension of the input images

Parameters

return_fft - if true, return fft(im1)*fft(im2[::-1,::-1]), which is the power

spectral density

fftshift - if true, return the shifted psd so that the DC component is in

the center of the image

pad - Default on. Zero-pad image to the nearest 2^n crop - Default on. Return an image of the size of the largest input image.

If the images are asymmetric in opposite directions, will return the largest image in both directions.

boundary: str, optional
A flag indicating how to handle boundaries:
  • ‘fill’set values outside the array boundary to fill_value

    (default)

  • ‘wrap’ : periodic boundary

nthreadsbool

Number of threads to use for fft (only matters if you have fftw installed)

use_numpy_fftbool

Force use numpy’s fft over fftw? (only matters if you have fftw installed)

WARNING: Normalization may be arbitrary if you use the PSD

motion_correction.image_registration.fft_tools.downsample module

motion_correction.image_registration.fft_tools.downsample.downsample(myarr, factor, estimator=<function nanmean>)[source]

Downsample a 2D array by averaging over factor pixels in each axis. Crops upper edge if the shape is not a multiple of factor.

This code is pure np and should be fast.

keywords:
estimator - default to mean. You can downsample by summing or

something else if you want a different estimator (e.g., downsampling error: you want to sum & divide by sqrt(n))

motion_correction.image_registration.fft_tools.downsample.downsample_1d(myarr, factor, estimator=<function nanmean>)[source]

Downsample a 1D array by averaging over factor pixels. Crops right side if the shape is not a multiple of factor.

This code is pure np and should be fast.

keywords:
estimator - default to mean. You can downsample by summing or

something else if you want a different estimator (e.g., downsampling error: you want to sum & divide by sqrt(n))

motion_correction.image_registration.fft_tools.downsample.downsample_axis(myarr, factor, axis, estimator=<function nanmean>, truncate=False)[source]

Downsample an ND array by averaging over factor pixels along an axis. Crops right side if the shape is not a multiple of factor.

This code is pure np and should be fast.

keywords:
estimator - default to mean. You can downsample by summing or

something else if you want a different estimator (e.g., downsampling error: you want to sum & divide by sqrt(n))

motion_correction.image_registration.fft_tools.downsample.downsample_cube(myarr, factor, ignoredim=0)[source]

Downsample a 3D array by averaging over factor pixels on the last two axes.

motion_correction.image_registration.fft_tools.fast_ffts module

motion_correction.image_registration.fft_tools.fast_ffts.get_ffts(nthreads=1, use_numpy_fft=True)[source]

Returns fftn,ifftn using either numpy’s fft or fftw

motion_correction.image_registration.fft_tools.scale module

motion_correction.image_registration.fft_tools.scale.fourier_interp1d(data, out_x, data_x=None, nthreads=1, use_numpy_fft=False, return_real=True)[source]

Use the fourier scaling theorem to interpolate (or extrapolate, without raising any exceptions) data.

Parameters

datandarray

The Y-values of the array to interpolate

out_xndarray

The X-values along which the data should be interpolated

data_xndarray | None

The X-values corresponding to the data values. If an ndarray, must have the same shape as data. If not specified, will be set to np.arange(data.size)

nthreadsint

Number of threads for parallelized FFTs (if available)

use_numpy_fftbool

Use the numpy version of the FFT before any others? (Default is to use fftw3)

Returns

The real component of the interpolated 1D array, or the full complex array if return_real is False

Raises

ValueError if output indices are the wrong shape or the data X array is the wrong shape

motion_correction.image_registration.fft_tools.scale.fourier_interp2d(data, outinds, nthreads=1, use_numpy_fft=False, return_real=True)[source]

Use the fourier scaling theorem to interpolate (or extrapolate, without raising any exceptions) data.

Parameters

datandarray

The data values of the array to interpolate

outindsndarray

The coordinate axis values along which the data should be interpolated CAN BE: ndim x [n,m,…] like np.indices OR (less memory intensive, more processor intensive) ([n],[m],…)

motion_correction.image_registration.fft_tools.scale.fourier_interpnd(data, outinds, nthreads=1, use_numpy_fft=False, return_real=True)[source]

Use the fourier scaling theorem to interpolate (or extrapolate, without raising any exceptions) data. * DOES NOT WORK FOR ANY BUT 2 DIMENSIONS *

Parameters

datandarray

The data values of the array to interpolate

outindsndarray

The coordinate axis values along which the data should be interpolated CAN BE ndim x [n,m,…] like np.indices OR (less memory intensive, more processor intensive) ([n],[m],…)

motion_correction.image_registration.fft_tools.shift module

Shift

Fourier-transform based shifting. scipy.fftpack.shift does about the same thing, but only in one dimension

motion_correction.image_registration.fft_tools.shift.shift2d(data, deltax, deltay, phase=0, nthreads=1, use_numpy_fft=False, return_abs=False, return_real=True)[source]

2D version: obsolete - use ND version instead (though it’s probably easier to parse the source of this one)

FFT-based sub-pixel image shift. Will turn NaNs into zeros

Shift Theorem:

\[FT[f(t-t_0)](x) = e^{-2 \pi i x t_0} F(x)\]

Parameters

datanp.ndarray

2D image

phasefloat

Phase, in radians

motion_correction.image_registration.fft_tools.shift.shiftnd(data, offset, phase=0, nthreads=1, use_numpy_fft=False, return_abs=False, return_real=True)[source]

FFT-based sub-pixel image shift. Will turn NaNs into zeros

Shift Theorem:

\[FT[f(t-t_0)](x) = e^{-2 \pi i x t_0} F(x)\]

Parameters

datanp.ndarray

Data to shift

offset(int,)*ndim

Offsets in each direction. Must be iterable.

phasefloat

Phase, in radians

Other Parameters

use_numpy_fftbool

Force use numpy’s fft over fftw? (only matters if you have fftw installed)

nthreadsbool

Number of threads to use for fft (only matters if you have fftw installed)

return_realbool

Return the real component of the shifted array

return_absbool

Return the absolute value of the shifted array

Returns

The input array shifted by offsets

motion_correction.image_registration.fft_tools.smooth_tools module

motion_correction.image_registration.fft_tools.smooth_tools.make_kernel(kernelshape, kernelwidth=3, kerneltype='gaussian', trapslope=None, normalize_kernel=<function sum>, force_odd=False)[source]

Create a smoothing kernel for use with convolve or convolve_fft

Parameters

kernelshapen-tuple

A tuple (or list or array) defining the shape of the kernel. The length of kernelshape determines the dimensionality of the resulting kernel

kernelwidthfloat

Width of kernel in pixels (see definitions under kerneltype)

kerneltype‘gaussian’, ‘boxcar’, ‘tophat’, ‘brickwall’, ‘airy’, ‘trapezoid’

Defines the type of kernel to be generated. For a gaussian, uses a gaussian with sigma = kernelwidth (in pixels)

i.e. kernel = exp(-r**2 / (2*sigma**2)) where r is the radius

A boxcar is a kernelwidth x kernelwidth square

e.g. kernel = (x < kernelwidth) * (y < kernelwidth)

A tophat is a flat circle with radius = kernelwidth

i.e. kernel = (r < kernelwidth)

A ‘brickwall’ or ‘airy’ kernel is the airy function from optics. It

requires scipy.special for the bessel function. http://en.wikipedia.org/wiki/Airy_disk

The trapezoid kernel is like a tophat but with sloped edges. It is

effectively a cone chopped off at the kernelwidth radius.

trapslopefloat

Slope of the trapezoid kernel. Only used if `kerneltype`==’trapezoid’

normalize_kernelfunction

Function to use for kernel normalization

force_oddboolean

If set, forces the kernel to have odd dimensions (needed for convolve w/o ffts)

Returns

An N-dimensional float array

motion_correction.image_registration.fft_tools.smooth_tools.smooth(image, kernelwidth=3, kerneltype='gaussian', trapslope=None, silent=True, psf_pad=True, interp_nan=False, nwidths='max', min_nwidths=6, return_kernel=False, normalize_kernel=<function sum>, downsample=False, downsample_factor=None, **kwargs)[source]

Returns a smoothed image using a gaussian, boxcar, or tophat kernel

Parameters

kernelwidth :

width of kernel in pixels (see definitions below)

kerneltypegaussian, boxcar, or tophat

  • a gaussian, uses a gaussian with sigma = kernelwidth (in pixels) out to [nwidths]-sigma

  • a boxcar is a kernelwidth x kernelwidth square

  • a tophat is a flat circle with radius = kernelwidth

psf_pad[True]

will pad the input image to be the image size + PSF. Slows things down but removes edge-wrapping effects (see convolve) This option should be set to false if the edges of your image are symmetric.

interp_nan[False]

Will replace NaN points in an image with the smoothed average of its neighbors (you can still simply ignore NaN values by setting ignore_nan=True but leaving interp_nan=False)

silent[True]

turn it off to get verbose statements about kernel types

return_kernel[False]

If set to true, will return the kernel as the second return value

nwidths[‘max’]

number of kernel widths wide to make the kernel. Set to ‘max’ to match the image shape, otherwise use any integer

min_nwidths[6]

minimum number of gaussian widths to make the kernel (the kernel will be larger than the image if the image size is < min_widths*kernelsize)

normalize_kernel :

Should the kernel preserve the map sum (i.e. kernel.sum() = 1) or the kernel peak (i.e. kernel.max() = 1) ? Must be a function that can operate on a numpy array

downsample :

downsample after smoothing?

downsample_factor :

if None, default to kernelwidth

Notes

Note that the kernel is forced to be even sized on each axis to assure no offset when smoothing.

motion_correction.image_registration.fft_tools.upsample module

motion_correction.image_registration.fft_tools.upsample.dftups(inp, nor=None, noc=None, usfac=1, roff=0, coff=0)[source]

Translated from matlab:

  • Original Source

  • Manuel Guizar - Dec 13, 2007

  • Modified from dftus, by J.R. Fienup 7/31/06

Upsampled DFT by matrix multiplies, can compute an upsampled DFT in just a small region.

This code is intended to provide the same result as if the following operations were performed:

  • Embed the array “in” in an array that is usfac times larger in each dimension. ifftshift to bring the center of the image to (1,1).

  • Take the FFT of the larger array

  • Extract an [nor, noc] region of the result. Starting with the [roff+1 coff+1] element.

It achieves this result by computing the DFT in the output array without the need to zeropad. Much faster and memory efficient than the zero-padded FFT approach if [nor noc] are much smaller than [nr*usfac nc*usfac]

Parameters

usfacint

Upsampling factor (default usfac = 1)

nor,nocint,int

Number of pixels in the output upsampled DFT, in units of upsampled pixels (default = size(in))

roff, coffint, int

Row and column offsets, allow to shift the output array to a region of interest on the DFT (default = 0)

motion_correction.image_registration.fft_tools.upsample.dftups1d(inp, usfac=1, outsize=None, offset=0, return_xouts=False)[source]
motion_correction.image_registration.fft_tools.upsample.odddftups(inp, nor=None, noc=None, usfac=1, roff=0, coff=0)[source]
motion_correction.image_registration.fft_tools.upsample.upsample_image(image, upsample_factor=1, output_size=None, nthreads=1, use_numpy_fft=False, xshift=0, yshift=0)[source]

Use dftups to upsample an image (but takes an image and returns an image with all reals)

motion_correction.image_registration.fft_tools.zoom module

motion_correction.image_registration.fft_tools.zoom.zoom1d(inp, usfac=1, outsize=None, offset=0, nthreads=1, use_numpy_fft=False, return_xouts=False, return_real=True)[source]

Zoom in to the center of a 1D array using Fourier upsampling

Parameters

inpnp.ndarray

Input 1D array

usfacint

Upsampling factor

outsizeint

Number of pixels in output array

offsetfloat

Offset from center in original pixel units

Other Parameters

return_xoutsbool

Return the X indices of the output array in addition to the scaled array

return_realbool

Return the real part of the zoomed array (if True) or the complex

Returns

The input array upsampled by a factor usfac with size outsize. If return_xouts, returns a tuple (xvals, zoomed)

motion_correction.image_registration.fft_tools.zoom.zoom_on_pixel(inp, coordinates, usfac=1, outshape=None, nthreads=1, use_numpy_fft=False, return_real=True, return_xouts=False)[source]

Zoom in on a 1D or 2D array using Fourier upsampling (in principle, should work on N-dimensions, but does not at present!)

Parameters

inpnp.ndarray

Input 1D array

coordinatestuple of floats

Pixel to zoom in on

usfacint

Upsampling factor

outshapeint

Number of pixels in output array

Other Parameters

return_xoutsbool

Return the X indices of the output array in addition to the scaled array

return_realbool

Return the real part of the zoomed array (if True) or the complex

Returns

The input array upsampled by a factor usfac with size outshape. If return_xouts, returns a tuple (xvals, zoomed)

motion_correction.image_registration.fft_tools.zoom.zoomnd(inp, offsets=(), middle_convention=<class 'float'>, **kwargs)[source]

Zoom in to the center of a 1D or 2D array using Fourier upsampling (in principle, should work on N-dimensions, but does not at present!)

Parameters

inpnp.ndarray

Input 1D array

offsetstuple of floats

Offset from center in original pixel units”

middle_conventionfunction

What convention to use for the “Middle” of the array. Should be either float (i.e., can be half-pixel), floor, or ceil. I don’t think round makes a ton of sense… should just be ceil.

usfacint

Upsampling factor (passed to zoom_on_pixel())

outshapeint

Number of pixels in output array (passed to zoom_on_pixel())

Other Parameters

return_xoutsbool

Return the X indices of the output array in addition to the scaled array (passed to zoom_on_pixel())

return_realbool

Return the real part of the zoomed array (if True) or the complex (passed to zoom_on_pixel())

Returns

The input array upsampled by a factor usfac with size outshape. If return_xouts, returns a tuple (xvals, zoomed)

Module contents