Learn more about Image Processing Toolbox

imfilter - N-D filtering of multidimensional images

Syntax

B = imfilter(A, H) B = imfilter(A, H, option1, option2,...)

Description

B = imfilter(A, H) filters the multidimensional array A with the multidimensional filter H. The array A can be logical or a nonsparse numeric array of any class and dimension. The result B has the same size and class as A.

Each element of the output B is computed using double-precision floating point. If A is an integer or logical array, then output elements that exceed the range of the integer type are truncated, and fractional values are rounded.

B = imfilter(A, H, option1, option2,...) performs multidimensional filtering according to the specified options. Option arguments can have the following values.

Boundary Options

Option	Description
`X`	Input array values outside the bounds of the array are implicitly assumed to have the value `X`. When no boundary option is specified, `imfilter` uses `X = 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 Options

Option	Description
`'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

Option	Description
`'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.

N-D convolution is related to N-D correlation by a reflection of the filter matrix.

Remarks

On Intel architecture processors, imfilter can take advantage of the Intel Integrated Performance Primitives (Intel IPP) library, thus accelerating its execution time. The Intel IPP library is activated only if A and H are both two-dimensional and A is of class uint8, uint16, int16, single, or double.

When the Intel IPP library is used, imfilter has different rounding behavior on some processors. Normally, when A is an integer class, filter outputs such as 1.5, 4.5, etc are rounded away from zero. However, when the Intel IPP library is used, these values are rounded toward zero.

Also, a special case exists if A is of class single or double, your input image contains NaN values, and your filtering kernel contains zero values. In this situation, you will receive different results if the Intel IPP library is enabled versus if it is not enabled. If you write code that depends on output values in the same neighborhood as NaN values in an input image, be aware that your code may behave differently on different machines, depending on the availability of the Intel IPP library.

To disable the Intel IPP library, use this command:

iptsetpref('UseIPPL', false)

Example

This example shows the different results obtained with the Intel IPP library enabled versus not enabled in the special case when you are filtering an array containing NaN elements with a filter containing zero values.

First, consider the case in which the Intel IPP library is enabled (the default case).

A = [2 2 2 2; 2 NaN 2 2; 2 2 2 2; 2 2 2 2];
h = [1 0; 0 1];
imfilter(A, h)

ans =

   NaN   NaN     4     2
   NaN   NaN     4     2
     4     4     4     2
     2     2     2     2

Now, compare this result to that obtained when you disable the Intel IPP library.

iptsetpref('UseIPPL', false);
imfilter(A, h)

ans =

   NaN     4     4     2
     4   NaN     4     2
     4     4     4     2
     2     2     2     2

As you can see, your output is not the same.

Examples

Read a color image into the workspace and view it.

originalRGB = imread('peppers.png');
imshow(originalRGB)

Original Image

Create a filter, h, that can be used to approximate linear camera motion.

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

Apply the filter, using imfilter, to the image originalRGB to create a new image, filteredRGB.

filteredRGB = imfilter(originalRGB, h);
figure, imshow(filteredRGB)

Filtered Image

Note that imfilter is more memory efficient than some other filtering operations 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.

whos
Name               Size                Bytes  Class     Attributes

  filteredRGB      384x512x3            589824  uint8               
  h                 37x37                10952  double              
  originalRGB      384x512x3            589824  uint8

Specify the replicate boundary option.

boundaryReplicateRGB = imfilter(originalRGB, h, 'replicate');
figure, imshow(boundaryReplicateRGB)

Image with Replicate Boundary