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.

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

Label Components Using 4-connected Objects

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]

rc = 4×2

     2     5
     3     5
     2     6
     3     6

Input Arguments

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

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

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.

Data Types: double | logical

Output Arguments

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.

Algorithms

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

1. Run-length encode the input image.

2. Scan the runs, assigning preliminary labels and recording label equivalences in a local equivalence table.

3. Resolve the equivalence classes.

4. 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 and 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

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
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');