imbinarize

R2026b

Binarize 2-D grayscale image or 3-D volume by thresholding

Syntax

BW = imbinarize(I)

BW = imbinarize(I,method)

BW = imbinarize(___,Name=Value)

BW = imbinarize(I,threshInit)

[BW,thresh] = imbinarize(___)

Description

BW = imbinarize(I) creates a binary image from 2-D or 3-D grayscale image I by replacing all values above a globally determined threshold with 1 and setting all other values to 0. The imbinarize function minimizes the intraclass variance of the thresholded black and white pixels by using Otsu's method [1].

BW = imbinarize(I,method) creates a binary image from image I using either a global thresholding method or a locally adaptive thresholding method.

BW = imbinarize(___,Name=Value) creates a binary image from image I using name-value arguments to control aspects of the thresholding, in addition to any combination of input arguments from previous syntaxes.

BW = imbinarize(I,threshInit) creates a binary image from image I based on the initial threshold threshInit.

[BW,thresh] = imbinarize(___) also returns the threshold used to binarize the image, using any combination of input arguments from previous syntaxes (since R2026b).

Examples

Binarize Image Using Global Threshold

Read grayscale image into the workspace.

I = imread("coins.png");

Convert the image into a binary image.

BW = imbinarize(I);

Display the original image next to the binary version.

montage({I,BW})

Binarize Image Using Locally Adaptive Thresholding

Read a grayscale image into workspace.

I = imread("rice.png");

Convert the grayscale image to a binary image.

BW = imbinarize(I,"adaptive");

Display the original image next to the binary version.

montage({I,BW})

Binarize Images with Darker Foreground Than Background

Read and display a grayscale image.

I = imread("printedtext.png");
imageshow(I)

Convert the image to a binary image using adaptive thresholding. Use the ForegroundPolarity argument to indicate that the foreground is darker than the background.

BW = imbinarize(I,"adaptive",ForegroundPolarity="dark",Sensitivity=0.4);

Display the binary version of the image.

imageshow(BW)

Binarize 3-D Volume Using Global Thresholding

Load 3-D grayscale intensity data into the workspace.

load mristack;
V = mristack;

View the 3-D volume.

figure
slice(double(V),size(V,2)/2,size(V,1)/2,size(V,3)/2)
colormap gray 
shading interp

Convert the intensity volume into a 3-D binary volume.

J = imbinarize(V);

View the 3-D binary volume.

figure
slice(double(J),size(J,2)/2,size(J,1)/2,size(J,3)/2)
colormap gray 
shading interp

Binarize 12-Bit Bayer Data

Read a color filter array (CFA) image and the metadata from a RAW file. This data was captured using a 12-bit sensor and is stored using data type uint16.

file = "colorCheckerTestImage.NEF";
cfa = rawread(file);
info = rawinfo(file);

Get the Bayer pattern from the metadata. Demosaic the image using 12 bits per sample, then convert the image to grayscale.

sensorAlignment = info.CFALayout;
rgbout = demosaic(cfa,sensorAlignment,BitsPerSample=12);
grayout = rgb2gray(rgbout);
imageshow(grayout,DisplayRange=[0 2^12])

First, try converting the image to binary using the range of the uint16 data type. The patches of the test chart have poor separation because most of the chart is in the foreground.

[bwType,threshType] = imbinarize(grayout);
threshType

threshType = 
257

imageshow(bwType)

Now convert the image to binary using the 12 bit range of the image data. The threshold is larger, and more pixels are classified as background. Patches appear more distinct and there is more separation of patches into foreground and background.

[bwData,threshData] = imbinarize(grayout,"global",HistogramRangeMode="data-range");
threshData

threshData = 
525.2824

imageshow(bwData)

Input Arguments

I — Input image

2-D grayscale image | 3-D grayscale volume

Input image, specified as a 2-D grayscale image or a 3-D grayscale volume. The imbinarize function expects images of data type double and single to have values in the range [0, 1]. If I has values outside the range [0, 1], then you can rescale values to the expected range by using the rescale function.

Note

imbinarize interprets an RGB image as a volumetric grayscale image and does not binarize each channel separately. To produce a binary image from an RGB image, first convert the image to a grayscale image using im2gray.

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

method — Method used to binarize image

"global" (default) | "adaptive"

Method used to binarize image, specified as one of these values.

Values	Meaning
"global"	Calculate a global image threshold using Otsu's method [1].
"adaptive"	Calculate a locally adaptive image threshold chosen using local first-order image statistics around each pixel [2]. If the image contains Inf or NaN pixels, then the behavior of imbinarize for the "adaptive" method is undefined. Propagation of Inf or NaN might not be localized to the neighborhood around Inf and NaN pixels.

Data Types: char | string

threshInit — Initial threshold

numeric scalar | numeric array

Initial threshold to use for binarizing the image, specified as a numeric scalar or numeric array with values in the range [0, 1].

• If threshInit is a numeric scalar, then imbinarize interprets threshInit as a global image threshold. To calculate a global image threshold, you can use the graythresh, otsuthresh, or imbinarize function.

• If threshInit is a numeric array, then imbinarize interprets threshInit as a locally adaptive threshold. To calculate a locally adaptive threshold, you can use the adaptthresh or imbinarize function.

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

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: BW = imbinarize(I,"adaptive",Sensitivity=0.4); specifies the sensitivity factor as 0.4.

HistogramRangeMode — Histogram range mode

"type-range" (default) | "data-range"

Since R2026b

Histogram range mode, specified as one of these values.

Value	Meaning
"type-range"	The histogram spans the range of the data type.
"data-range"	The histogram spans the range of the image data. Specify this value when the image data has a small dynamic range compared to the data type.

Specify this argument only when method is "global".

Data Types: char | string

Sensitivity — Sensitivity factor for adaptive thresholding

0.5 (default) | number in range [0, 1]

Sensitivity factor for adaptive thresholding, specified as a number in the range [0, 1]. A high sensitivity value leads to thresholding more pixels as foreground, at the risk of including some background pixels.

Specify this argument only when method is "adaptive".

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

ForegroundPolarity — Polarity of foreground pixels

"bright" (default) | "dark"

Polarity of foreground pixels for adaptive thresholding, specified as one of these values.

Value	Meaning
"bright"	The foreground is brighter than the background.
"dark"	The foreground is darker than the background.

Specify this argument only when method is "adaptive".

Data Types: char | string

Output Arguments

BW — Binary image

logical matrix | logical array

Binary image, returned as a logical matrix or logical array of the same size as I.

Data Types: logical

thresh — Threshold used to binarize image

numeric scalar | numeric matrix | numeric array

Since R2026b

Threshold used to binarize the image, returned as a numeric scalar for a global threshold, or as a numeric matrix or numeric array of the same size as I for a locally adaptive threshold. Values are normalized to the range [0, 1].

Data Types: double

Tips

• imbinarize does not calculate an effectiveness metric. If you want to know the effectiveness metric for a global threshold, use graythresh before calling imbinarize.

• By default, imbinarize calculates a global threshold by binning the image data into a 256-bin histogram. To specify a different histogram, use the otsuthresh function.

Algorithms

The "adaptive" method binarizes the image using a locally adaptive threshold. imbinarize computes a threshold for each pixel using the local mean intensity around the neighborhood of the pixel. This technique is also called Bradley's method [2]. The "adaptive" method also uses a neighborhood size of approximately 1/8th of the size of the image (computed as 2*floor(size(I)/16)+1). To use a different first order local statistic or a different neighborhood size, see adaptthresh.

References

[1] Otsu, N., "A Threshold Selection Method from Gray-Level Histograms." IEEE Transactions on Systems, Man, and Cybernetics. Vol. 9, No. 1, 1979, pp. 62–66.

[2] Bradley, D., G. Roth, "Adapting Thresholding Using the Integral Image," Journal of Graphics Tools. Vol. 12, No. 2, 2007, pp.13–21.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• imbinarize supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, imbinarize 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, all string input arguments must be compile-time constants.

GPU Code Generation

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

Usage notes and limitations:

• When generating code, all string input arguments must be compile-time constants.

Version History

Introduced in R2016a

R2026b: Return threshold

The imbinarize function can now return the threshold that it used to binarize the input image.

R2026b: Calculate global threshold based on range of image data

The imbinarize function can now calculate global image thresholds based on the range of the image data. To apply a threshold based on the range of the image data, specify method as "global" and the new HistogramRangeMode name-value argument as "data-range". Use this option when the image data has a small dynamic range compared to the data type.