The Convolution command performs a spatial convolution over an image using a convolution kernel (also known as a convolution mask), and returns a new image giving the result of this operation.

The img parameter specifies the image on which to perform the convolution.

The kernel parameter specifies the convolution kernel. It must be a Vector, Matrix, or 2D Array with numeric entries.

The Convolution operation consists of "flipping" the kernel (horizontally and vertically), then "sliding" it over the input image, moving it by one pixel each time, and computing a new pixel value for the output image.

The pixels covered by the flipped kernel are multiplied by the corresponding entries (weights) in the kernel and summed to produce a pixel in the output image.

Edge Pixels: each pixel computed in the output image corresponds to the center of the kernel in its incremented position. For an M x N kernel, the center indices of the kernel (assuming the indices start from 1, which is not a requirement) are [iquo(M+1,2), iquo(N+1,2)], before flipping. Because the kernel is flipped, there are iquo(M-1,2) rows along the top and iquo(M,2) rows along the bottom of the image that do not have the required M*N-1 neighbors. Likewise for iquo(N-1,2) columns along the left side and iquo(N,2) columns along the right side of the image. These are the edge pixels. The computation of their convolution depends on the setting of the edges option.

shape = full, same, or valid

Controls which pixels of the convolution are to be part of the output. The default is same.

full: full mathematical convolution is performed. Any position of the kernel that overlaps the image produces an output pixel. The output image is larger than the input by one less than the width and height of the kernel. When part of the kernel protrudes past the edge of the input image, the values used for pixels exterior to the image are controlled by the exterior option described below.

same: the output image is the same size as the input image. The treatment of the edge pixels is controlled by the edges option, described below.

valid: pixels with too few neighbors are omitted from the convolution. The output image is smaller than the input image by one less than the width and height of the kernel.

edges = compute, leave, or numeric

Controls what is to be done with the edge pixels when shape = same. The default is compute.

compute: the edge pixels are computed in a manner controlled by the exterior option described below.

leave: the edge pixels are left unmodified (copied from the input into the output image verbatim). Depending on the convolution kernel, there will be a visible difference between these and the processed pixels. For example, if the kernel is designed to blur the image, the edge pixels will still be sharp.

numeric: specifies an intensity value for the edge pixels.

exterior = ignore or numeric

Controls how pixels exterior to the image are interpreted when shape=same and edges=compute, or when shape=full. The default is ignore.

ignore: exterior pixels are ignored when part of the kernel falls outside the image. Only the pixels within the image are multiplied by the corresponding kernel entries. The result is then reweighted by the ratio of total kernel weight to the sum of the kernel entries falling within the image. This avoids fading around the edges of the result.

numeric: specifies an intensity value for the exterior pixels. This results in a fade-to-gray (or black or white) effect at the edges of the output.

weight = none or numeric

Controls how the weighted sum of the input pixels (as specified by the kernel) is used. The default is none.

none: the weighted sum is used as-is. This corresponds to the mathematical definition of convolution.

numeric: the weighted sum (specified by the kernel) is multiplied by the weight and divided by the sum of the kernel entries. If the kernel entries sum to zero, the division step is not done.

A convolution corresponding to the mathematical definition can be obtained by specifying the options shape=full, exterior=0, and weight=none.

   0.0    0.0    0.0    0.5    1.0    1.0    1.0
   0.0    0.0    0.0    0.5    1.0    1.0    1.0
   0.0    0.0    0.0    0.5    1.0    1.0    1.0
   0.0    0.0    0.0    0.5    1.0    1.0    1.0

   0.0    0.0    0.0    0.0    0.0    0.0    0.0
   0.0    0.0    1.5    4.5    7.5    9.0    0.0
   0.0    0.0    1.5    4.5    7.5    9.0    0.0
   0.0    0.0    0.0    0.0    0.0    0.0    0.0

   0.0    0.0    0.0    0.0    0.0    0.0    0.0
   0.0    0.0    0.2    0.5    0.8    1.0    0.0
   0.0    0.0    0.2    0.5    0.8    1.0    0.0
   0.0    0.0    0.0    0.0    0.0    0.0    0.0