roifilt2

Filter region of interest (ROI) in grayscale image

Syntax

J = roifilt2(h,I,BW)

J = roifilt2(I,BW,fun)

Description

J = roifilt2(h,I,BW) filters regions of interest (ROIs) in the 2-D grayscale image I using the 2-D linear filter h. The binary mask BW defines the ROIs in I. roifilt2 returns an image that consists of filtered values for pixels in locations where BW contains 1s, and unfiltered values for pixels in locations where BW contains 0s. This type of filtering is called masked filtering.

J = roifilt2(I,BW,fun) processes the data in ROIs of I using the function fun.

Examples

Filter Image Using Polygonal Mask

Read an image into the workspace.

I = imread("eight.tif");

Define the vertices of the mask polygon.

c = [222 272 300 270 221 194];
r = [21 21 75 121 121 75];

Create the binary mask image.

BW = roipoly(I,c,r);

Filter the region of the image I specified by the mask BW.

H = fspecial("unsharp");
J = roifilt2(H,I,BW);

Display the original image and the filtered image.

imshow(I)

imshow(J)

Input Arguments

h — Linear filter

2-D numeric matrix

Linear filter, specified as a 2-D numeric matrix.

Data Types: double

I — Grayscale image

2-D numeric matrix

Grayscale image, specified as a 2-D numeric matrix.

• If you specify a filter, h, then I can be any of the listed data types.

• If you specify a function handle, fun, then I can be any data type supported by fun.

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

BW — Mask

2-D logical matrix | 2-D numeric matrix

Mask, specified as a 2-D logical matrix or a 2-D numeric matrix of the same size as I. For numeric input, any nonzero pixels are considered to be 1 (true).

fun — Function handle

handle

Function handle, specified as a handle. For more information about function handles, see Create Function Handle.

Output Arguments

J — Filtered image

2-D matrix

Filtered image, returned as a 2-D matrix.

• If you specify a filter, h, then J is of the same data type as the input image, I.

• If you specify a function handle, fun, then the data type of J is determined by fun.

Algorithms

If you specify a filter, h, then roifilt2 calls imfilter to implement the filter. The roifilt2 function is best suited for operations that return data in the same range as in the original image, because the output image takes some of its data, which comes from the unmasked regions, directly from the input image. Certain filtering operations can result in values outside the normal image data range (that is, [0, 1] for images of class double, [0, 255] for images of class uint8, and [0, 65535] for images of class uint16).

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• roifilt2 supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, roifilt2 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.

• If you generate code using the coder function with fun as an argument, then specify fun as a constant string or character vector. For example, to use the adaptthresh function, specify fun as the string "adaptthresh" and convert the string to a constant using the coder.Constant function.

  codegen roifilt2 -args {I,BW,coder.Constant("adaptthresh")}

  If you generate code for a wrapper function, then fun can be a function handle within the wrapper function. For example, this command generates code for a wrapper function named myFunction.

  codegen myFunction -args {I,BW,coder.Constant("adaptthresh")}

  Here is a sample definition for the wrapper function myFunction that includes a call to the roifilt2 function. Within the wrapper function, convert fun from a constant string to a function handle using the str2func function.

  function out = myFunction(I,BW,fun) %#codegen
        fun1 = str2func(fun); % This will become fun1 = @adaptthresh
        out = roifilt2(I,BW,fun1);
  end

GPU Code Generation

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

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Version History

Introduced before R2006a

R2023b: Support for C code generation

roifilt2 now supports the generation of C code (requires MATLAB Coder).