imfilter
N-D filtering of multidimensional images
Description
Examples
Create Filter and Apply It
Read a color image into the workspace and display it.
originalRGB = imread("peppers.png");
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 because 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)
Filter Images Using imfilter with Convolution
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
Convert Image Class to Avoid Negative Output Values
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
A
— Image to be filtered
numeric array
Image to be filtered, specified as a numeric array of dimension.
Data Types: single
| double
| int8
| int16
| int32
| uint8
| uint16
| uint32
| logical
h
— Multidimensional filter
N-D array of data type double
Multidimensional filter, specified as an N-D array of data type
double
.
Data Types: double
options
— Options that control the filtering operation
character vector | string scalar | numeric scalar
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 |
---|---|
Padding Options | |
numeric scalar, | Input array values outside the bounds of the array are assigned the value
|
| Input array values outside the bounds of the array are computed by mirror-reflecting the array across the array border. |
| Input array values outside the bounds of the array are assumed to equal the nearest array border value. |
| Input array values outside the bounds of the array are computed by implicitly assuming the input array is periodic. |
Output Size | |
| The output array is the same size as the input array. This is the default behavior when no output size options are specified. |
| The output array is the full filtered result, and so is larger than the input array. |
Correlation and Convolution Options | |
|
|
|
|
Output Arguments
B
— Filtered image
numeric array
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
, anddouble
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, thenimfilter
truncates the result to the allowed range of the data type. If it is an integer data type, thenimfilter
rounds fractional values.If you specify an even-sized kernel
h
, then the center of the kernel isfloor((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]
.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
imfilter
supports the generation of C code (requires MATLAB® Coder™). Note that if you choose the genericMATLAB Host Computer
target platform,imfilter
generates code that uses a precompiled, platform-specific shared library. Use of a shared library preserves performance optimizations but limits the target platforms for which code can be generated. For more information, see Types of Code Generation Support in Image Processing Toolbox.When generating code, the input image,
A
, must be 2-D or 3-D. The value of the input argument,options
, must be a compile-time constant.If you specify a large kernel
h
, a kernel that contains large values, or specify an image containing large values, you can see different results between MATLAB and generated code for floating point data types. This happens because of accumulation errors due to different algorithm implementations.
GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.
Usage notes and limitations:
When generating code, the input image,
A
, must be 2-D or 3-D. The value of the input argument,options
, must be a compile-time constant.If you specify a large kernel
h
, a kernel that contains large values, or specify an image containing large values, you can see different results between MATLAB and generated code for floating point data types. This happens because of accumulation errors due to different algorithm implementations.With CUDA® toolkit v9.0, a bug in the NVIDIA® optimization causes numerical mismatch between the results from the generated code and MATLAB. As a workaround, turn off the optimization by passing the following flags to the configuration object (
cfg
) before generating the code.cfg.GpuConfig.CompilerFlags = ‘-Xptxas -O0’
NVIDIA is expected to fix this bug in CUDA toolkit v9.1.
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.
GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.
Usage notes and limitations:
The filtering kernel
h
must be a vector or 2-D matrix of data typedouble
.If the image is filtered using a GPU, then
imfilter
computes the value of each output pixel using either single- or double-precision floating point, depending on the data type ofA
. IfA
contains double-precision oruint32
values, thenimfilter
uses double-precision values. For all other data types,imfilter
uses single-precision. IfA
is an integer or logical array, thenimfilter
truncates output elements that exceed the range of the given type, and rounds fractional values.
For more information, see Image Processing on a GPU.
Version History
Introduced before R2006aR2022b: Support for thread-based environments
imfilter
now supports thread-based
environments.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)