# scipy.ndimage.filters.convolve¶

scipy.ndimage.filters.convolve(input, weights, output=None, mode='reflect', cval=0.0, origin=0)[source]

Multidimensional convolution.

The array is convolved with the given kernel.

Parameters: input : array_like Input array to filter. weights : array_like Array of weights, same number of dimensions as input output : ndarray, optional The output parameter passes an array in which to store the filter output. mode : {‘reflect’,’constant’,’nearest’,’mirror’, ‘wrap’}, optional the mode parameter determines how the array borders are handled. For ‘constant’ mode, values beyond borders are set to be cval. Default is ‘reflect’. cval : scalar, optional Value to fill past edges of input if mode is ‘constant’. Default is 0.0 origin : array_like, optional The origin parameter controls the placement of the filter. Default is 0. result : ndarray The result of convolution of input with weights.

correlate
Correlate an image with a kernel.

Notes

Each value in result is $$C_i = \sum_j{I_{i+j-k} W_j}$$, where W is the weights kernel, j is the n-D spatial index over $$W$$, I is the input and k is the coordinate of the center of W, specified by origin in the input parameters.

Examples

Perhaps the simplest case to understand is mode='constant', cval=0.0, because in this case borders (i.e. where the weights kernel, centered on any one value, extends beyond an edge of input.

>>> a = np.array([[1, 2, 0, 0],
....    [5, 3, 0, 4],
....    [0, 0, 0, 7],
....    [9, 3, 0, 0]])
>>> k = np.array([[1,1,1],[1,1,0],[1,0,0]])
>>> from scipy import ndimage
>>> ndimage.convolve(a, k, mode='constant', cval=0.0)
array([[11, 10,  7,  4],
[10,  3, 11, 11],
[15, 12, 14,  7],
[12,  3,  7,  0]])


Setting cval=1.0 is equivalent to padding the outer edge of input with 1.0’s (and then extracting only the original region of the result).

>>> ndimage.convolve(a, k, mode='constant', cval=1.0)
array([[13, 11,  8,  7],
[11,  3, 11, 14],
[16, 12, 14, 10],
[15,  6, 10,  5]])


With mode='reflect' (the default), outer values are reflected at the edge of input to fill in missing values.

>>> b = np.array([[2, 0, 0],
[1, 0, 0],
[0, 0, 0]])
>>> k = np.array([[0,1,0],[0,1,0],[0,1,0]])
>>> ndimage.convolve(b, k, mode='reflect')
array([[5, 0, 0],
[3, 0, 0],
[1, 0, 0]])


This includes diagonally at the corners.

>>> k = np.array([[1,0,0],[0,1,0],[0,0,1]])
>>> ndimage.convolve(b, k)
array([[4, 2, 0],
[3, 2, 0],
[1, 1, 0]])


With mode='nearest', the single nearest value in to an edge in input is repeated as many times as needed to match the overlapping weights.

>>> c = np.array([[2, 0, 1],
[1, 0, 0],
[0, 0, 0]])
>>> k = np.array([[0, 1, 0],
[0, 1, 0],
[0, 1, 0],
[0, 1, 0],
[0, 1, 0]])
>>> ndimage.convolve(c, k, mode='nearest')
array([[7, 0, 3],
[5, 0, 2],
[3, 0, 1]])