# Convolution

Apply a convolution kernel to an image.

## Overview

Convolution functions implement various techniques for smoothing or sharpening an image by replacing a pixel with a weighted sum of itself and nearby pixels. Image convolution does not alter the size of an image.

Each convolution function requires that you pass it a convolution kernel, which determines how the values of neighboring pixels are used to compute the value of a destination pixel. A kernel is a packed array, without padding at the ends of the rows. The elements of the array must be of type `uint8_t` (for the Planar8 and ARGB8888 formats) or of type `float` (for the PlanarF and ARGBFFFF formats). The height and the width of the array must both be odd numbers.

For example, a 3 x 3 convolution kernel for a Planar8 image consist of nine 8-bit (1-byte) values, arranged consecutively. The first three values represent the first row of the kernel, the next three values the second row, and the last three values the third row.

Typically, you use normalized values for the convolution kernel. For floating-point formats, this means the sum of the elements of the kernel is 1.0. For integer formats, the sum of the elements of the kernel, divided by the given divisor, is 1. A non-normalized kernel either lightens or darkens the image.

For integer formats, the sum of any subset of elements of the kernel must be in the range –224 to 224 – 1, inclusive to prevent integer overflow. If your kernel does not meet this restriction, either use a floating-point format or scale the kernel to use smaller values.

A convolution function transforms a source image as follows:

1. Places the kernel over the image so that the center element of the kernel lies over the source pixel.

2. For floating-point formats, performs this calculation:

For integer formats, performs this calculation:

3. Assigns the result to the destination pixel.

If the image is in a planar format, the convolution operation uses the single-channel values of the pixels directly. If the image is in an interleaved format, the convolution operation processes each channel (alpha, red, green, and blue) separately. In both the planar and interleaved format, the kernel itself is always planar.

When the pixel to be transformed is near the edge of the image—not merely the region of interest, but the entire image of which it is a part—the kernel may extend beyond the edge of the image, so that there are no existing pixels beneath some of the kernel elements. In these cases you must pass a flag that specifies a technique for the convolution function to use: `kvImageCopyInPlace`, `kvImageBackgroundColorFill`, `kvImageEdgeExtend`, and `kvImageTruncateKernel`. For a discussion of these options, see Data Types and Constants.

## Topics

### Deconvolving

`vImageRichardsonLucyDeConvolve_ARGBFFFF`

Sharpens an ARGBFFFF image by undoing a previous convolution that blurred the image, such as diffraction effects in a camera lens.

`vImageRichardsonLucyDeConvolve_ARGB8888`

Sharpens an ARGB8888 image by undoing a previous convolution that blurred the image, such as diffraction effects in a camera lens.

`vImageRichardsonLucyDeConvolve_PlanarF`

Sharpens a PlanarF image by undoing a previous convolution that blurred the image, such as diffraction effects in a camera lens.

`vImageRichardsonLucyDeConvolve_Planar8`

Sharpens a Planar8 image by undoing a previous convolution that blurred the image, such as diffraction effects in a camera lens.

### Convolving Without Bias

`vImageConvolve_ARGBFFFF`

Convolves a region of interest within an ARGBFFFF source image by an M x N kernel.

`vImageConvolve_ARGB8888`

Convolves a region of interest within a source image by an M x N kernel, then divides the pixel values by a divisor.

`vImageConvolve_PlanarF`

Convolves a region of interest within a source image by an M x N kernel.

`vImageConvolve_Planar8`

Convolves a region of interest within a source image by an M x N kernel, then divides the pixel values by a divisor.

### Convolving With a Bias

`vImageConvolveWithBias_ARGB8888`

Convolves a region of interest within an ARGB8888 source image by an M x N kernel, then normalizes the pixel values.

`vImageConvolveWithBias_PlanarF`

Convolves a region of interest within a PlanarF source image by an M x N kernel.

`vImageConvolveWithBias_Planar8`

Convolves a region of interest within a Planar8 source image by an M x N kernel, then normalizes the pixel values.

`vImageConvolveWithBias_ARGBFFFF`

Convolves a region of interest within an ARGBFFFF source image by an M x N kernel.

### Convolving With Multiple Kernels

`vImageConvolveMultiKernel_ARGBFFFF`

Convolves each channel of a region of interest within an ARGBFFFF source image by one of the four M x N kernels.

`vImageConvolveMultiKernel_ARGB8888`

Convolves each channel of a region of interest within an ARGB8888 source image by one of the four M x N kernels, then divides the pixel values by one of the four divisors.

### Convolving With High-Speed Box and Tent Filters

`vImageBoxConvolve_Planar8`

Convolves a region of interest within a Planar8 source image by an implicit M x N kernel that has the effect of a box filter.

`vImageBoxConvolve_ARGB8888`

Convolves a region of interest within an ARGB8888 source image by an implicit M x N kernel that has the effect of a box filter.

`vImageTentConvolve_Planar8`

Convolves a region of interest within a Planar8 source image by an implicit M x N kernel that has the effect of a tent filter.

`vImageTentConvolve_ARGB8888`

Convolves a region of interest within an ARGB8888 source image by an implicit M x N kernel that has the effect of a tent filter.

### Getting the Minimum Buffer Size

`vImageGetMinimumTempBufferSizeForConvolution`

Returns the minimum size, in bytes, for the temporary buffer that the caller supplies to any of the convolution functions.

## See Also

### Convolution and Morphology

Blurring an Image

Filter an image by convolving it with custom and high-speed kernels.

Adding a Bokeh Effect

Simulate a bokeh effect by applying dilation.

Morphology

Dilate and erode images.