Documentation

imfilter

N-D filtering of multidimensional images

Description

example

B = imfilter(A,h) filters the multidimensional array A with the multidimensional filter h and returns the result in B.

You optionally can filter a multidimensional array with a 2-D filter using a GPU (requires Parallel Computing Toolbox™).

example

B = imfilter(A,h,options,...) performs multidimensional filtering according to one or more specified options.

Examples

collapse all

Read a color image into the workspace and display it.

imshow(originalRGB) Create a motion-blur filter using the fspecial function.

h = fspecial('motion', 50, 45);

Apply the filter to the original image to create an image with motion blur. Note that imfilter is more memory efficient than some other filtering functions in that it outputs an array of the same data type as the input image array. In this example, the output is an array of uint8.

filteredRGB = imfilter(originalRGB, h);
figure, imshow(filteredRGB) Filter the image again, this time specifying the replicate boundary option.

boundaryReplicateRGB = imfilter(originalRGB, h, 'replicate');
figure, imshow(boundaryReplicateRGB) By default, imfilter uses correlation because the toolbox filter design functions produce correlation kernels. Use the optional parameter to use convolution.

Create a sample matrix.

A = magic(5)
A = 5×5

17    24     1     8    15
23     5     7    14    16
4     6    13    20    22
10    12    19    21     3
11    18    25     2     9

Create a filter.

h = [-1 0 1];

Filter using correlation, the default.

imfilter(A,h)
ans = 5×5

24   -16   -16    14    -8
5   -16     9     9   -14
6     9    14     9   -20
12     9     9   -16   -21
18    14   -16   -16    -2

Filter using convolution, specifying imfilter with the optional parameter.

imfilter(A,h,'conv')
ans = 5×5

-24    16    16   -14     8
-5    16    -9    -9    14
-6    -9   -14    -9    20
-12    -9    -9    16    21
-18   -14    16    16     2

In this example, the output of imfilter has negative values when the input is of class double. To avoid negative values, convert the image to a different data type before calling imfilter. For example, when the input type is uint8, imfilter truncates output values to 0. It might also be appropriate to convert the image to a signed integer type.

A = magic(5)
A = 5×5

17    24     1     8    15
23     5     7    14    16
4     6    13    20    22
10    12    19    21     3
11    18    25     2     9

Filter the image with imfilter.

h = [-1 0 1];
imfilter(A,h)
ans = 5×5

24   -16   -16    14    -8
5   -16     9     9   -14
6     9    14     9   -20
12     9     9   -16   -21
18    14   -16   -16    -2

Notice that the result has negative values. To avoid negative values in the output image, convert the input image to uint8 before performing the filtering. Since the input to imfilter is of class uint8, the output also is of class uint8, and imfilter truncates negative values to 0.

A = uint8(magic(5));
imfilter(A,h)
ans = 5x5 uint8 matrix

24    0    0   14    0
5    0    9    9    0
6    9   14    9    0
12    9    9    0    0
18   14    0    0    0

Input Arguments

collapse all

Image to be filtered, specified as a numeric array of dimension.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 | logical

Multidimensional filter, specified as an N-D array of data type double.

Data Types: double

Options that control the filtering operation, specified as a character vector, string scalar, or numeric scalar. The following table lists all supported options.

Boundary Options

Option

Description

numeric scalar, X

Input array values outside the bounds of the array are assigned the value X. When no padding option is specified, the default is 0.

'symmetric'

Input array values outside the bounds of the array are computed by mirror-reflecting the array across the array border.

'replicate'

Input array values outside the bounds of the array are assumed to equal the nearest array border value.

'circular'

Input array values outside the bounds of the array are computed by implicitly assuming the input array is periodic.

Output Size

'same'

The output array is the same size as the input array. This is the default behavior when no output size options are specified.

'full'

The output array is the full filtered result, and so is larger than the input array.

Correlation and Convolution Options

'corr'

imfilter performs multidimensional filtering using correlation, which is the same way that filter2 performs filtering. When no correlation or convolution option is specified, imfilter uses correlation.

'conv'

imfilter performs multidimensional filtering using convolution.

Output Arguments

collapse all

Filtered image, returned as a numeric array of the same size and class as the input image, A.

Tips

• This function may take advantage of hardware optimization for data types uint8, uint16, int16, single, and double to run faster.

Algorithms

• The imfilter function computes the value of each output pixel using double-precision, floating-point arithmetic. If the result exceeds the range of the data type, then imfilter truncates the result to the allowed range of the data type. If it is an integer data type, then imfilter rounds fractional values.

• If you specify an even-sized kernel h, then the center of the kernel is floor((size(h) + 1)/2).

For example, the center of 4-element filter [0.25 0.75 -0.75 -0.25] is the second element, 0.75. This filter gives identical results as filtering with the 5-element filter [0 0.25 0.75 -0.75 -0.25].