bwlabel

Label connected components in 2-D binary image

Syntax

L = bwlabel(BW)

L = bwlabel(BW,conn)

[L,n]
= bwlabel(___)

Description

L = bwlabel(BW) returns the label matrix L that contains labels for the 8-connected objects found in BW.

example

L = bwlabel(BW,conn) returns a label matrix, where conn specifies the connectivity.

[L,n] = bwlabel(___) also returns n, the number of connected objects found in BW.

Examples

collapse all

Label Components Using 4-connected Objects

Open Live Script

Create a small binary image.

BW = logical ([1     1     1     0     0     0     0     0
               1     1     1     0     1     1     0     0
               1     1     1     0     1     1     0     0
               1     1     1     0     0     0     1     0
               1     1     1     0     0     0     1     0
               1     1     1     0     0     0     1     0
               1     1     1     0     0     1     1     0
               1     1     1     0     0     0     0     0]);

Create the label matrix using 4-connected objects.

L = bwlabel(BW,4)

L = 8×8

     1     1     1     0     0     0     0     0
     1     1     1     0     2     2     0     0
     1     1     1     0     2     2     0     0
     1     1     1     0     0     0     3     0
     1     1     1     0     0     0     3     0
     1     1     1     0     0     0     3     0
     1     1     1     0     0     3     3     0
     1     1     1     0     0     0     0     0

Use the find command to get the row and column coordinates of the object labeled "2".

[r, c] = find(L==2);
rc = [r c]

Input Arguments

collapse all

`BW` — Binary image
2-D numeric matrix | 2-D logical matrix

Binary image, specified as a 2-D numeric matrix or 2-D logical matrix. For numeric input, any nonzero pixels are considered to be 1 (true).

`conn` — Pixel connectivity
`8` (default) | `4`

Pixel connectivity, specified as one of these values.

Value	Meaning
Two-Dimensional Connectivities
`4`	Pixels are connected if their edges touch. Two adjoining pixels are part of the same object if they are both on and are connected along the horizontal or vertical direction.	Current pixel is shown in gray.
`8`	Pixels are connected if their edges or corners touch. Two adjoining pixels are part of the same object if they are both on and are connected along the horizontal, vertical, or diagonal direction.	Current pixel is shown in gray.

Value

Meaning

Two-Dimensional Connectivities

4

Pixels are connected if their edges touch. Two adjoining pixels are part of the same object if they are both on and are connected along the horizontal or vertical direction.

Center pixel connected to four pixels

Current pixel is shown in gray.

8

Pixels are connected if their edges or corners touch. Two adjoining pixels are part of the same object if they are both on and are connected along the horizontal, vertical, or diagonal direction.

Center pixel connected to eight pixels

Current pixel is shown in gray.

Data Types: double | logical

Output Arguments

collapse all

`L` — Label matrix
matrix of nonnegative integers

Label matrix of contiguous regions, returned as matrix of nonnegative integers with the same size as BW. The pixels labeled 0 are the background. The pixels labeled 1 make up one object; the pixels labeled 2 make up a second object; and so on.

Data Types: double

`n` — Number of connected objects
nonnegative integer

Number of connected objects in BW, returned as a nonnegative integer.

Data Types: double

Tips

This function sorts the connected components from left to right based on the top-left extremum of each component. When multiple components have the same horizontal position, the function then sorts those components from top to bottom. This figure illustrates the extrema of two different regions.
The functions bwlabel, bwlabeln, and bwconncomp all compute connected components for binary images. bwconncomp uses significantly less memory and is sometimes faster than the other functions.
Input Dimension Output Form Memory Use Connectivity
bwlabel 2-D Double-precision label matrix High 4 or 8
bwlabeln N-D Double-precision label matrix High Any
bwconncomp N-D CC struct Low Any
You can use the MATLAB^® find function in conjunction with bwlabel to return vectors of indices for the pixels that make up a specific object. For example, to return the coordinates for the pixels in object 2, enter the following:.
```
[r,c] = find(bwlabel(BW)==2)
```
You can display the output matrix as a pseudocolor indexed image. Each object appears in a different color, so the objects are easier to distinguish than in the original image. For more information, see label2rgb.
To extract features from a binary image using regionprops with default connectivity, pass BW directly into regionprops using the command regionprops(BW).
The bwlabel function can take advantage of hardware optimization for data types logical, uint8, and single to run faster. Hardware optimization requires marker and mask to be 2-D images and conn to be either 4 or 8.

	Input Dimension	Output Form	Memory Use	Connectivity
`bwlabel`	2-D	Double-precision label matrix	High	4 or 8
`bwlabeln`	N-D	Double-precision label matrix	High	Any
`bwconncomp`	N-D	CC struct	Low	Any

Algorithms

bwlabel uses the general procedure outlined in reference [1], pp. 40-48:

Run-length encode the input image.
Scan the runs, assigning preliminary labels and recording label equivalences in a local equivalence table.
Resolve the equivalence classes.
Relabel the runs based on the resolved equivalence classes.

References

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

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

bwlabel supports the generation of C code (requires MATLAB Coder™). For more information, see Code Generation for Image Processing.
When generating code, the parameter n must be a compile-time constant.

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

Usage notes and limitations:

When generating code, the parameter n must be a compile-time constant.

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™.

This function fully supports GPU arrays. For more information, see Image Processing on a GPU.

Version History

Introduced before R2006a

expand all

R2022b: Support for thread-based environments

bwlabel now supports thread-based environments.

R2006a: Not recommended

Starting in R2022b, most Image Processing Toolbox™ functions create and perform geometric transformations using the premultiply convention. Accordingly, the affine2d object is not recommended because it uses the postmultiply convention. Although there are no plans to remove the affine2d object at this time, you can streamline your geometric transformation workflows by switching to the affinetform2d object, which supports the premultiply convention. For more information, see Migrate Geometric Transformations to Premultiply Convention.

To update your code:

Change instances of the function name affine2d to affinetform2d.
Specify the transformation matrix as the transpose of the matrix T, where T is either the value of the T property of the affine2d object or the transformation matrix used to create the affine2d object.

Discouraged Usage Recommended Replacement

Discouraged Usage	Recommended Replacement
This example creates an `affine2d` object from transformation matrix `T` in the postmultiply convention. T = [2 0.33 0; 0 1 0; 0 0 1]; tformPost = affine2d(T);	This example creates an `affinetform2d` object from the transpose of the transformation matrix `T`. T = [2 0.33 0; 0 1 0; 0 0 1]; tform = affinetform2d(T'); This example starts with an `affine2d` object called `tformPost` and creates an `affinetform2d` object from the transpose of the `T` property of `tformPost`. T = tformPost.T; tform = affinetform2d(T');

This example creates an affine2d object from transformation matrix T in the postmultiply convention.

T = [2 0.33 0; 0 1 0; 0 0 1];
tformPost = affine2d(T);

This example creates an affinetform2d object from the transpose of the transformation matrix T.

T = [2 0.33 0; 0 1 0; 0 0 1];
tform = affinetform2d(T');

This example starts with an affine2d object called tformPost and creates an affinetform2d object from the transpose of the T property of tformPost.

T = tformPost.T;
tform = affinetform2d(T');

bwlabel

Syntax

Description

Examples

Label Components Using 4-connected Objects

Input Arguments

BW — Binary image 2-D numeric matrix | 2-D logical matrix

conn — Pixel connectivity 8 (default) | 4

Output Arguments

L — Label matrix matrix of nonnegative integers

n — Number of connected objects nonnegative integer

Tips

Algorithms

References

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

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

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

R2022b: Support for thread-based environments

R2006a: Not recommended

See Also

`BW` — Binary image
2-D numeric matrix | 2-D logical matrix

`conn` — Pixel connectivity
`8` (default) | `4`

`L` — Label matrix
matrix of nonnegative integers

`n` — Number of connected objects
nonnegative integer

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

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

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.