Apply a convolution kernel to an image.


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.



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.


Dilate and erode images.