bwtraceboundary

Trace object in binary image

Syntax

B = bwtraceboundary(BW,P,fstep)

B = bwtraceboundary(BW,P,fstep,conn)

B = bwtraceboundary(BW,P,fstep,conn,m,dir)

Description

B = bwtraceboundary(BW,P,fstep) traces the outline of an object in binary image BW. Nonzero pixels belong to an object and zero-valued pixels constitute the background. P specifies the row and column coordinates of the point on the object boundary where you want the tracing to begin. fstep specifies the initial search direction for the next object pixel connected to P. B holds the row and column coordinates of the boundary pixels for the region.

B = bwtraceboundary(BW,P,fstep,conn) traces the boundary, where conn specifies the desired connectivity.

B = bwtraceboundary(BW,P,fstep,conn,m,dir) specifies m, the maximum number of boundary pixels to extract, and dir, the direction in which to trace the boundary. By default, bwtraceboundary identifies all the pixels on the boundary.

Examples

Trace Boundary and Visualize Contours

Read an image and display it.

BW = imread('blobs.png');
imshow(BW)

Pick an object in the image and trace the boundary. To select an object, specify a pixel on its boundary. This example uses the coordinates of a pixel on the boundary of the thick white circle, obtained through visual inspection using impixelinfo. By default, bwtraceboundary identifies all pixels on the boundary.

r1 = 163;
c1 = 37;
contour = bwtraceboundary(BW,[r1 c1],'W');

Plot the contour on the image.

hold on
plot(contour(:,2),contour(:,1),'g','LineWidth',2)

Pick a point on the boundary of a second object. This example uses the coordinates of a pixel near the upper-left corner of the largest rectangle. Trace the first fifty boundary pixels in the clockwise direction.

r2 = 68;
c2 = 95;
contourCW = bwtraceboundary(BW,[r2 c2],'W',8,50,'clockwise');

Starting at the same point on the second object boundary, trace the first fifty boundary pixels in the counterclockwise direction.

contourCCW = bwtraceboundary(BW,[r2 c2],'W',8,50,'counterclockwise');

Plot the clockwise contour on the image in red. Plot the counterclockwise contour on the image in blue.

plot(contourCW(:,2),contourCW(:,1),'r','LineWidth',2)
plot(contourCCW(:,2),contourCCW(:,1),'b','LineWidth',2)

Input Arguments

BW — Binary image

2-D numeric matrix | 2-D logical matrix

Binary image, specified as a 2-D numeric or logical matrix.

P — Coordinates of starting point

2-element vector

Coordinates of starting point on the object boundary where you want the tracing to begin, specified as a 2-element vector of the format [row column].

Data Types: double

fstep — Initial search direction

"N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW"

Initial search direction for the next object pixel connected to P, specified as a character vector or string scalar as depicted in the diagram.

Note

When the connectivity conn is 4, fstep is limited to the values "N", "E", "S", and "W".

Data Types: char | string

conn — Pixel connectivity

8 (default) | 4

Pixel connectivity, specified as 8 or 4.

Value	Meaning
Two-Dimensional Connectivities
4	Pixels are connected if their edges touch. The neighborhood of a pixel are the adjacent pixels in the horizontal or vertical direction.	Current pixel is shown in gray.
8	Pixels are connected if their edges or corners touch. The neighborhood of a pixel are the adjacent pixels in the horizontal, vertical, or diagonal direction.	Current pixel is shown in gray.

Data Types: double

m — Maximum number of boundary pixels to extract

Inf (default) | positive integer

Maximum number of boundary pixels to extract, specified as a positive integer. By default, m is Inf and bwtraceboundary identifies all the pixels on the boundary.

Data Types: double

dir — Direction in which to trace boundary

"clockwise" (default) | "counterclockwise"

Direction in which to trace boundary, specified as "clockwise" or "counterclockwise".

Data Types: char | string

Output Arguments

B — Row and column coordinates of boundary pixels

q-by-2 matrix

Row and column coordinates of the boundary pixels for the region, returned as a q-by-2 matrix. Each row in B has the form [row column].

Algorithms

The bwtraceboundary 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, by Gonzalez, R. C., R. E. Woods, and S. L. Eddins, New Jersey, Pearson Prentice Hall, 2004.

References

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

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• bwtraceboundary supports the generation of C code (requires MATLAB^® Coder™). For more information, see Code Generation for Image Processing.

• When generating code, the dir, fstep, and conn 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, the dir, fstep, and conn arguments must be compile-time constants.

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.

Version History

Introduced before R2006a

R2022b: Support for thread-based environments

bwtraceboundary now supports thread-based environments.