bwboundaries

Trace region boundaries in binary image

Syntax

B = bwboundaries(BW)
B = bwboundaries(BW,conn)
B = bwboundaries(BW,conn,options)
[B,L] = bwboundaries(...)
[B,L,N,A] = bwboundaries(...)

Description

B = bwboundaries(BW) traces the exterior boundaries of objects, as well as boundaries of holes inside these objects, in the binary image BW. bwboundaries also descends into the outermost objects (parents) and traces their children (objects completely enclosed by the parents). BW must be a binary image where nonzero pixels belong to an object and 0 pixels constitute the background. The following figure illustrates these components.

bwboundaries returns B, a P-by-1 cell array, where P is the number of objects and holes. Each cell in the cell array contains a Q-by-2 matrix. Each row in the matrix contains the row and column coordinates of a boundary pixel. Q is the number of boundary pixels for the corresponding region.

B = bwboundaries(BW,conn) specifies the connectivity to use when tracing parent and child boundaries. conn can have either of the following scalar values.

Value

Meaning

4

4-connected neighborhood

8

8-connected neighborhood. This is the default.

B = bwboundaries(BW,conn,options) specifies an optional argument, where options can have either of the following values:

Value

Meaning

'holes'

Search for both object and hole boundaries. This is the default.

'noholes'

Search only for object (parent and child) boundaries. This can provide better performance.

[B,L] = bwboundaries(...) returns the label matrix L as the second output argument. Objects and holes are labeled. L is a two-dimensional array of nonnegative integers that represent contiguous regions. The kth region includes all elements in L that have value k. The number of objects and holes represented by L is equal to max(L(:)). The zero-valued elements of L make up the background.

[B,L,N,A] = bwboundaries(...) returns N, the number of objects found, and A, an adjacency matrix. The first N cells in B are object boundaries. A represents the parent-child-hole dependencies. A is a square, sparse, logical matrix with side of length max(L(:)), whose rows and columns correspond to the positions of boundaries stored in B.

The boundaries enclosed by a B{m} as well as the boundary enclosing B{m} can both be found using A as follows:

enclosing_boundary  = find(A(m,:));
enclosed_boundaries = find(A(:,m));

Class Support

BW can be logical or numeric and it must be real, two-dimensional, and nonsparse. L and N are double. A is sparse logical.

Examples

Example 1

Read in and threshold an intensity image. Display the labeled objects using the jet colormap, on a gray background, with region boundaries outlined in white.

BW = im2bw(I, graythresh(I));
[B,L] = bwboundaries(BW,'noholes');
imshow(label2rgb(L, @jet, [.5 .5 .5]))
hold on
for k = 1:length(B)
boundary = B{k};
plot(boundary(:,2), boundary(:,1), 'w', 'LineWidth', 2)
end

Example 2

Read in and display a binary image. Overlay the region boundaries on the image. Display text showing the region number (based on the label matrix) next to every boundary. Additionally, display the adjacency matrix using the MATLAB® spy function.

After the image is displayed, use the zoom tool to read individual labels.

[B,L,N,A] = bwboundaries(BW);
figure, imshow(BW); hold on;
colors=['b' 'g' 'r' 'c' 'm' 'y'];
for k=1:length(B)
boundary = B{k};
cidx = mod(k,length(colors))+1;
plot(boundary(:,2), boundary(:,1),...
colors(cidx),'LineWidth',2);
%randomize text position for better visibility
rndRow = ceil(length(boundary)/(mod(rand*k,7)+1));
col = boundary(rndRow,2); row = boundary(rndRow,1);
h = text(col+1, row-1, num2str(L(row,col)));
set(h,'Color',colors(cidx),...
'FontSize',14,'FontWeight','bold');
end
figure; spy(A);

Example 3

Display object boundaries in red and hole boundaries in green.

[B,L,N] = bwboundaries(BW);
figure; imshow(BW); hold on;
for k=1:length(B),
boundary = B{k};
if(k > N)
plot(boundary(:,2),...
boundary(:,1),'g','LineWidth',2);
else
plot(boundary(:,2),...
boundary(:,1),'r','LineWidth',2);
end
end

Example 4

Display parent boundaries in red (any empty row of the adjacency matrix belongs to a parent) and their holes in green.

[B,L,N,A] = bwboundaries(BW);
figure; imshow(BW); hold on;
for k=1:length(B),
if(~sum(A(k,:)))
boundary = B{k};
plot(boundary(:,2),...
boundary(:,1),'r','LineWidth',2);
for l=find(A(:,k))'
boundary = B{l};
plot(boundary(:,2),...
boundary(:,1),'g','LineWidth',2);
end
end
end

collapse all

Algorithms

The bwboundaries function implements the Moore-Neighbor tracing algorithm modified by Jacob's stopping criteria. This function is based on the boundaries function presented in the first edition of Digital Image Processing Using MATLAB[1].

References

[1] Gonzalez, R. C., R. E. Woods, and S. L. Eddins, Digital Image Processing Using MATLAB, New Jersey, Pearson Prentice Hall, 2004.