roipoly

Specify polygonal region of interest (ROI)

Syntax

BW = roipoly

BW = roipoly(I)

BW = roipoly(I,xi,yi)

BW = roipoly(xref,yref,I,xi,yi)

[BW,xi2,yi2] = roipoly(___)

[xrefout,yrefout,BW,xi2,yi2] = roipoly(___)

roipoly(___)

Description

Create Polygon Interactively

BW = roipoly creates an interactive polygon tool associated with the image displayed in the current figure. roipoly returns the mask as a binary image, setting pixels inside the ROI to 1 and pixels outside the ROI to 0.

With this syntax and the other interactive syntaxes, the polygon selection tool blocks the MATLAB^® command line until you complete the operation. For more information about using the polygon selection tool, see Interactive Behavior.

BW = roipoly(I) displays the grayscale or RGB image I in a figure window and creates an interactive polygon selection tool associated with the image.

Create Polygon by Specifying Vertices

BW = roipoly(I,xi,yi) specifies the (x, y) coordinates of polygon vertices as (xi, yi).

BW = roipoly(xref,yref,I,xi,yi) specifies the coordinates of polygon vertices in the world coordinate system defined by xref and yref. The polygon vertices have (x, y) coordinates xi and yi in this coordinate system.

Specify Additional Output Options

[BW,xi2,yi2] = roipoly(___) also returns the coordinates of the vertices of the closed polygon, xi2 and yi2. You can use the input arguments of any other syntax.

[xrefout,yrefout,BW,xi2,yi2] = roipoly(___) also returns the image limits in xrefout and yrefout.

roipoly(___) without output arguments displays the resulting mask image in a new figure window.

Examples

Create Polygonal Mask

Read an image into the workspace.

I = imread('eight.tif');

Define the vertices of the mask polygon.

c = [222 272 300 270 221 194];
r = [21 21 75 121 121 75];

Create the binary mask image.

BW = roipoly(I,c,r);

Display the original image and the polygonal mask.

imshow(I)

figure
imshow(BW)

Input Arguments

I — Grayscale or RGB image

m-by-n numeric matrix | m-by-n-by-3 numeric array

Grayscale or RGB image, specified as an m-by-n numeric matrix or an m-by-n-by-3 numeric array, respectively.

xi — x-coordinate of polygon vertices

numeric vector

x-coordinate of polygon vertices, specified as a numeric vector of the same length as yi. If you specify image limits in a world coordinate system using xref, then xi is in this coordinate system. Otherwise, xi is in the default coordinate system.

yi — y-coordinate of polygon vertices

numeric vector

y-coordinate of polygon vertices, specified as a numeric vector of the same length as xi. If you specify image limits in a world coordinate system using yref, then yi is in this coordinate system. Otherwise, yi is in the default coordinate system.

xref — Image limits in world coordinates along x-dimension

2-element numeric vector

Image limits in world coordinates along the x-dimension, specified as a 2-element numeric vector of the form [xmin xmax]. The value of xref sets the image XData.

yref — Image limits in world coordinates along y-dimension

2-element numeric vector

Image limits in world coordinates along the y-dimension, specified as a 2-element numeric vector of the form [ymin ymax]. The value of yref sets the image YData.

Output Arguments

BW — Binary image

m-by-n logical matrix

Binary image, returned as an m-by-n logical matrix.

Data Types: logical

xi2 — x-coordinate of vertices

numeric vector

x-coordinate of vertices of the closed polygon, returned as a numeric vector of the same length as yi2. The first and last element in the vector are identical, so that the polygon is closed. If you specify image limits in a world coordinate system using xref, then xi2 is in this coordinate system. Otherwise, xi2 is in the default coordinate system.

yi2 — y-coordinate of vertices

numeric vector

y-coordinate of vertices of the closed polygon, returned as a numeric vector of the same length as xi2. The first and last element in the vector are identical, so that the polygon is closed. If you specify image limits in a world coordinate system using yref, then yi2 is in this coordinate system. Otherwise, yi2 is in the default coordinate system.

xrefout — Image limits in world coordinates along x-dimension

2-element numeric vector

Image limits in world coordinates along the x-dimension, returned as a 2-element numeric vector of the form [xmin xmax]. If you specify image limits in a world coordinate system using xref, then xrefout is equal to xref. Otherwise, xrefout is equal to the original image XData.

yrefout — Image limits in world coordinates along y-dimension

2-element numeric vector

Image limits in world coordinates along the y-dimension, returned as a 2-element numeric vector of the form [ymin ymax]. If you specify image limits in a world coordinate system using yref, then yrefout is equal to yref. Otherwise, yrefout is equal to the original image YData.

More About

Interactive Behavior

The polygon selection tool enables you to select and adjust polygon vertices interactively using the mouse.

When the polygon tool is active, the pointer changes to cross hairs when you move the pointer over the image in the figure. Using the mouse, you specify the region by selecting vertices of the polygon. You can move or resize the polygon using the mouse. When you are finished positioning and sizing the polygon, create the mask by double-clicking, or by right-clicking inside the region and selecting Create mask from the context menu.

The figure illustrates a polygon defined by multiple vertices. The following table describes all the interactive behavior of the polygon tool.

Interactive Behavior	Description
Closing the polygon. (Completing the region-of-interest.)	Use any of the following mechanisms: Move the pointer over the initial vertex of the polygon that you selected. The pointer changes to a circle . Click either mouse button. Double-click the left mouse button. This action creates a vertex at the point under the mouse pointer and draws a straight line connecting this vertex with the initial vertex. Right-click the mouse. This draws a line connecting the last vertex selected with the initial vertex; it does not create a new vertex at the point under the mouse.
Moving the entire polygon	Move the pointer inside the region. The pointer changes to a fleur shape . Click and drag the polygon over the image.
Deleting the polygon	Press Backspace, Escape or Delete, or right-click inside the region and select Cancel from the context menu. Note: If you delete the ROI, the function returns empty values.
Moving a vertex. (Reshaping the region-of-interest.)	Move the pointer over a vertex. The pointer changes to a circle . Click and drag the vertex to its new position.
Adding a new vertex.	Move the pointer over an edge of the polygon and press the A key. The pointer changes shape to . Click the left mouse button to create a new vertex at that point on the edge.
Deleting a vertex. (Reshaping the region-of-interest.)	Move the pointer over the vertex. The pointer changes to a circle . Right-click and select Delete vertex from the context menu. roipoly draws a new straight line between the two vertices that were neighbors of the deleted vertex.
Changing the color of the polygon	Move the pointer anywhere inside the boundary of the region and click the right mouse button. Select Set color from the context menu.
Retrieving the coordinates of the vertices	Move the pointer inside the region. Right-click and select Copy position from the context menu to copy the current position to the Clipboard. The position is an n-by-2 array containing the x- and y-coordinates of each vertex, where n is the number of vertices.

Tips

• roipoly always produces a closed polygon. If you specify input vertex positions of a closed polygon (such that the last pair of coordinates is identical to the first pair), then the length of the output coordinate vectors is equal to the number of points specified. If the points specified do not describe a closed polygon, then roipoly adds a final point having the same coordinates as the first point. In this case the length of the output coordinate vectors is one greater than the number of points specified.

• For more information about classifying pixels on the ROI boundary, see Classify Pixels That Are Partially Enclosed by ROI.

• For any of the roipoly syntaxes, you can replace the input image I with two arguments, m and n, that specify the row and column dimensions of an arbitrary image. For example, these commands create a 100-by-200 binary mask.

  c = [112 112 79 79];
  r = [37 66 66 37];
  BW = roipoly(100,200,c,r);

  If you specify m and n with an interactive form of roipoly, an m-by-n black image is displayed. Use the mouse to specify a polygon within this image.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

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

• The interactive syntaxes are not supported, including:

  • BW = roipoly

  • BW = roipoly(I)

Version History

Introduced before R2006a

R2023b: Support for C code generation

roipoly now supports the generation of C code (requires MATLAB Coder).