scipy.ndimage.

convolve

scipy.ndimage.convolve(input, weights, output=None, mode='reflect', cval=0.0, origin=0, *, axes=None)

多维卷积。

数组与给定的核进行卷积。

参数:

inputarray_like

输入数组。

weightsarray_like

权重数组，与输入具有相同的维度数

outputarray or dtype, optional

放置输出的数组，或返回数组的数据类型。默认情况下，将创建一个与输入具有相同数据类型的数组。

mode{'reflect', 'constant', 'nearest', 'mirror', 'wrap'}，可选

mode 参数确定如何将输入数组扩展到其边界之外。默认值为 'reflect'。每个有效值的行为如下

'reflect' (d c b a | a b c d | d c b a)

输入通过最后像素的边缘反射进行扩展。此模式有时也称为半样本对称。

'constant' (k k k k | a b c d | k k k k)

输入通过用相同的常数值填充边缘之外的所有值进行扩展，该常数值由 cval 参数定义。

'nearest' (a a a a | a b c d | d d d d)

输入通过复制最后像素进行扩展。

'mirror' (d c b | a b c d | c b a)

输入通过最后像素的中心反射进行扩展。此模式有时也称为全样本对称。

'wrap' (a b c d | a b c d | a b c d)

输入通过环绕到对边进行扩展。

为了与插值函数保持一致，还可以使用以下模式名称

‘grid-mirror’

这是 ‘reflect’ 的同义词。

‘grid-constant’

这是 ‘constant’ 的同义词。

‘grid-wrap’

这是 ‘wrap’ 的同义词。

cval标量，可选

如果mode是'constant'，则用于填充输入边缘之外的值。默认值为0.0

originint 或序列，可选

控制过滤器在输入数组像素上的放置。值为0（默认值）表示过滤器居中于像素，正值将过滤器向右移动，负值向左移动。通过传递一个长度等于输入数组维数的一系列原点，可以沿每个轴指定不同的偏移。

axestuple of int or None, optional

如果为None，input将沿所有轴进行滤波。否则，input将沿指定轴进行滤波。当指定axes时，用于mode或origin的任何元组都必须与axes的长度匹配。这些元组中的第i个条目对应于axes中的第i个条目。

返回:

resultndarray

input与weights卷积的结果。

另请参阅

互相关

将图像与核进行关联。

附注

结果中的每个值都是\(C_i = \sum_j{I_{i+k-j} W_j}\)，其中W是weights核，j是\(W\)上的N维空间索引，I是input，k是W中心的坐标，由输入参数中的origin指定。

数组 API 标准支持

convolve除了NumPy之外，还实验性地支持Python Array API Standard兼容的后端。请考虑通过设置环境变量SCIPY_ARRAY_API=1并提供CuPy、PyTorch、JAX或Dask数组作为数组参数来测试这些功能。支持以下后端和设备（或其他功能）组合。

库	CPU	GPU
NumPy	✅	不适用
CuPy	不适用	✅
PyTorch	✅	⛔
JAX	⚠️ 无 JIT	⛔
Dask	⚠️ 计算图	不适用

有关更多信息，请参阅 对数组 API 标准的支持。

示例

在浏览器中试用！

也许最简单易懂的情况是mode='constant', cval=0.0，因为在这种情况下，边界（即weights核，以任何一个值居中，超出input的边缘）被视为零。

>>> import numpy as np
>>> 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]])

设置cval=1.0等同于用1.0填充input的外边缘（然后仅提取结果的原始区域）。

>>> 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]])

使用mode='reflect'（默认值），外部值在input的边缘处反射以填充缺失值。

>>> 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]])

这包括对角线上的角点。

>>> 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]])

使用mode='nearest'，input中离边缘最近的单个值会重复多次，以匹配重叠的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]])

返回在新标签页中打开