ordfilt2

R2026b

2-D order-statistic filtering

Syntax

B = ordfilt2(A,order,domain)

B = ordfilt2(A,order,domain,S)

B = ordfilt2(___,padopt)

Description

B = ordfilt2(A,order,domain) replaces each element in A by the orderth element in the sorted set of neighbors specified by the nonzero elements in the neighborhood defined by domain.

B = ordfilt2(A,order,domain,S) filters A, where ordfilt2 uses the values of S corresponding to the nonzero values of domain as additive offsets. You can use this syntax to implement grayscale morphological operations, including grayscale dilation and erosion.

B = ordfilt2(___,padopt) filters A, where padopt specifies how ordfilt2 pads the matrix boundaries.

Examples

Filter Image with Maximum Filter

Read image into workspace and display it.

A = imread("snowflakes.png");
figure
imshow(A)

Filter the image with a 5-by-5 maximum filter and display the result.

B = ordfilt2(A,25,true(5));
figure
imshow(B)

Perform Grayscale Dilation Using Additive Offsets

Read an image into workspace and display it.

A = imread("snowflakes.png");
A = im2double(A);
figure
imshow(A,[])

Define a skewed 5-by-5 structuring element that has higher intensities in the right columns than the left columns.

SE = repmat([1 1 1 5 5],5,1)

SE = 5×5

     1     1     1     5     5
     1     1     1     5     5
     1     1     1     5     5
     1     1     1     5     5
     1     1     1     5     5

The domain of the ordfilt2 function requires only the positions of the nonzero elements in the structuring element, and not the values. Define the domain as the logical values of the structuring element.

domain = SE > 0

domain = 5×5 logical array

   1   1   1   1   1
   1   1   1   1   1
   1   1   1   1   1
   1   1   1   1   1
   1   1   1   1   1

To perform morphological dilation, the order of the ordfilt2 function must be specified as maximum. Specify the order has the number of nonzero elements in the domain.

order = nnz(domain)

order = 
25

Filter the image with the maximum filter with the structuring element as the additive offset. The additive offset controls the directions in which the morphological effect occurs.

B = ordfilt2(A,order,domain,SE);

Display the filtered image. Observe that the snowflakes dilate in different proportions on the left and right because of the intensities of the structuring element.

figure
imshow(B,[])

Input Arguments

A — Data to filter

2-D numeric matrix | 2-D logical matrix

Data to filter, specified as a 2-D numeric matrix or 2-D logical matrix.

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

order — Element to replace target pixel

positive integer

Element to replace the target pixel, specified as a real scalar integer. The function replaces each element in A by the orderth element in the sorted set of neighbors specified by the nonzero elements in the neighborhood defined by domain.

Data Types: double

domain — Neighborhood

2-D numeric matrix | 2-D logical matrix

Neighborhood, specified as a numeric or logical matrix containing 1s and 0s. domain is equivalent to the structuring element used for binary image operations. The 1-valued elements define the neighborhood for the filtering operation. The table gives examples of some common filters.

Type of Filtering Operation	Sample code	Neighborhood	Sample Image Data, Indicating Selected Element
Median filter	B = ordfilt2(A,5,ones(3,3))
Minimum filter	B = ordfilt2(A,1,ones(3,3))
Maximum filter	B = ordfilt2(A,9,ones(3,3))
Minimum of north, east, south, and west neighbors	B = ordfilt2(A,1,[0 1 0; 1 0 1; 0 1 0])

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

S — Additive offsets

numeric matrix

Additive offsets, specified as a numeric matrix of the same size as domain. The function adds the values of S corresponding to the nonzero values of domain before sorting. You can use additive offsets to implement grayscale morphological operations, including grayscale dilation and erosion. The additive offset controls the directions in which the morphological effect occurs.

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

padopt — Padding option

"zeros" (default) | "symmetric"

Padding option, specified as one of the following values. The nature of padding controls how the function computes the values of the output pixels at the edges of the image.

Option	Description	Example
"zeros"	Pad array boundaries with the value 0.	$$\left[\begin{array}{ccc}3& 1& 4\\ 1& 5& 9\\ 2& 6& 5\end{array}\right]\to \left[\begin{array}{ccccccc}0& 0& 0& 0& 0& 0& 0\\ 0& 0& 0& 0& 0& 0& 0\\ 0& 0& 3& 1& 4& 0& 0\\ 0& 0& 1& 5& 9& 0& 0\\ 0& 0& 2& 6& 5& 0& 0\\ 0& 0& 0& 0& 0& 0& 0\\ 0& 0& 0& 0& 0& 0& 0\end{array}\right]$$
"symmetric"	Pad array with mirror reflections of itself.	$$\left[\begin{array}{ccc}3& 1& 4\\ 1& 5& 9\\ 2& 6& 5\end{array}\right]\to \left[\begin{array}{ccccccc}5& 1& 1& 5& 9& 9& 5\\ 1& 3& 3& 1& 4& 4& 1\\ 1& 3& 3& 1& 4& 4& 1\\ 5& 1& 1& 5& 9& 9& 5\\ 6& 2& 2& 6& 5& 5& 6\\ 6& 2& 2& 6& 5& 5& 6\\ 5& 1& 1& 5& 9& 9& 5\end{array}\right]$$

Data Types: char | string

Output Arguments

B — Filtered data

2-D numeric matrix | 2-D logical matrix

Filtered data, returned as a 2-D numeric matrix or 2-D logical matrix of the same data type as the input data A.

Tips

• When working with large domain matrices that do not contain any zero-valued elements, ordfilt2 can achieve higher performance if A is in an integer data format (uint8, int8, uint16, int16). The gain in speed is larger for uint8 and int8 than for the 16-bit data types. For 8-bit data formats, the domain matrix must contain seven or more rows. For 16-bit data formats, the domain matrix must contain three or more rows and 520 or more elements.

References

[1] Haralick, Robert M., and Linda G. Shapiro, Computer and Robot Vision, Volume I, Addison-Wesley, 1992.

[2] Huang, T. S., G. J. Yang, and G. Y. Tang. "A fast two-dimensional median filtering algorithm.", IEEE transactions on Acoustics, Speech and Signal Processing, Vol ASSP 27, No. 1, February 1979.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• ordfilt2 supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, ordfilt2 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 padopt argument must be a compile-time constant.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• GPU code generation requires the inputs to be bounded. If the input is of variable dimension, the software generates C code.

• When generating code, the padopt argument must be a compile-time constant.

• The generated GPU code is not optimized if the domain value that defines the neighborhood for the filtering operation is of size greater than 11-by-11.

  For better performance, consider setting the StackLimitPerThread option in the coder.gpuConfig (GPU Coder) object to Inf.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The ordfilt2 function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a

R2022b: Support for thread-based environments

ordfilt2 now supports thread-based environments.