convolve_fft¶
-
astropy.convolution.
convolve_fft
(array, kernel, boundary=u'fill', fill_value=0, crop=True, return_fft=False, fft_pad=None, psf_pad=None, interpolate_nan=False, quiet=False, ignore_edge_zeros=False, min_wt=0.0, normalize_kernel=False, allow_huge=False, fftn=<function fftn>, ifftn=<function ifftn>, complex_dtype=<type 'complex'>)[source] [edit on github]¶ Convolve an ndarray with an nd-kernel. Returns a convolved image with shape = array.shape. Assumes kernel is centered.
convolve_fft
differs fromscipy.signal.fftconvolve
in a few ways:- It can treat
NaN
values as zeros or interpolate over them. inf
values are treated asNaN
- (optionally) It pads to the nearest 2^n size to improve FFT speed.
- Its only valid
mode
is ‘same’ (i.e., the same shape array is returned) - It lets you use your own fft, e.g.,
pyFFTW or
pyFFTW3 , which can lead to
performance improvements, depending on your system configuration. pyFFTW3
is threaded, and therefore may yield significant performance benefits on
multi-core machines at the cost of greater memory requirements. Specify
the
fftn
andifftn
keywords to override the default, which isnumpy.fft.fft
andnumpy.fft.ifft
.
Parameters: array :
numpy.ndarray
Array to be convolved with
kernel
kernel :
numpy.ndarray
Will be normalized if
normalize_kernel
is set. Assumed to be centered (i.e., shifts may result if your kernel is asymmetric)boundary : {‘fill’, ‘wrap’}, optional
A flag indicating how to handle boundaries:
- ‘fill’: set values outside the array boundary to fill_value (default)
- ‘wrap’: periodic boundary
interpolate_nan : bool, optional
The convolution will be re-weighted assuming
NaN
values are meant to be ignored, not treated as zero. If this is off, allNaN
values will be treated as zero.ignore_edge_zeros : bool, optional
Ignore the zero-pad-created zeros. This will effectively decrease the kernel area on the edges but will not re-normalize the kernel. This parameter may result in ‘edge-brightening’ effects if you’re using a normalized kernel
min_wt : float, optional
If ignoring
NaN
/ zeros, force all grid points with a weight less than this value toNaN
(the weight of a grid point with no ignored neighbors is 1.0). Ifmin_wt
is zero, then all zero-weight points will be set to zero instead ofNaN
(which they would be otherwise, because 1/0 = nan). See the examples belownormalize_kernel : function or boolean, optional
If specified, this is the function to divide kernel by to normalize it. e.g.,
normalize_kernel=np.sum
means that kernel will be modified to be:kernel = kernel / np.sum(kernel)
. If True, defaults tonormalize_kernel = np.sum
.Returns: default : ndarray
array convolved with
kernel
. Ifreturn_fft
is set, returns fft(array) * fft(kernel
). If crop is not set, returns the image, but with the fft-padded size instead of the input sizeOther Parameters: fft_pad : bool, optional
Default on. Zero-pad image to the nearest 2^n. With
boundary='wrap'
, this will be disabled.psf_pad : bool, optional
Zero-pad image to be at least the sum of the image sizes to avoid edge-wrapping when smoothing. This is enabled by default with
boundary='fill'
, but it can be overridden with a boolean option.boundary='wrap'
andpsf_pad=True
are not compatible.crop : bool, optional
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. For example, if an input image has shape [100,3] but a kernel with shape [6,6] is used, the output will be [100,6].
return_fft : bool, optional
Return the fft(image)*fft(kernel) instead of the convolution (which is ifft(fft(image)*fft(kernel))). Useful for making PSDs.
fftn, ifftn : functions, optional
The fft and inverse fft functions. Can be overridden to use your own ffts, e.g. an fftw3 wrapper or scipy’s fftn, e.g.
fftn=scipy.fftpack.fftn
complex_dtype : np.complex, optional
Which complex dtype to use.
numpy
has a range of options, from 64 to 256.quiet : bool, optional
Silence warning message about NaN interpolation
allow_huge : bool, optional
Allow huge arrays in the FFT? If False, will raise an exception if the array or kernel size is >1 GB
Raises: ValueError:
If the array is bigger than 1 GB after padding, will raise this exception unless allow_huge is True
See also
convolve
- Convolve is a non-fft version of this code. It is more memory efficient and for small kernels can be faster.
Notes
With psf_pad=True and a large PSF, the resulting data can become very large and consume a lot of memory. See Issue https://github.com/astropy/astropy/pull/4366 for further detail.
Examples
>>> convolve_fft([1, 0, 3], [1, 1, 1]) array([ 1., 4., 3.])
>>> convolve_fft([1, np.nan, 3], [1, 1, 1]) array([ 1., 4., 3.])
>>> convolve_fft([1, 0, 3], [0, 1, 0]) array([ 1., 0., 3.])
>>> convolve_fft([1, 2, 3], [1]) array([ 1., 2., 3.])
>>> convolve_fft([1, np.nan, 3], [0, 1, 0], interpolate_nan=True) ... array([ 1., 0., 3.])
>>> convolve_fft([1, np.nan, 3], [0, 1, 0], interpolate_nan=True, ... min_wt=1e-8) array([ 1., nan, 3.])
>>> convolve_fft([1, np.nan, 3], [1, 1, 1], interpolate_nan=True) array([ 1., 4., 3.])
>>> convolve_fft([1, np.nan, 3], [1, 1, 1], interpolate_nan=True, ... normalize_kernel=True, ignore_edge_zeros=True) array([ 1., 2., 3.])
>>> import scipy.fftpack # optional - requires scipy >>> convolve_fft([1, np.nan, 3], [1, 1, 1], interpolate_nan=True, ... normalize_kernel=True, ignore_edge_zeros=True, ... fftn=scipy.fftpack.fft, ifftn=scipy.fftpack.ifft) array([ 1., 2., 3.])
- It can treat