Image Processing Toolbox™

roipoly - Specify polygonal region of interest (ROI)

Syntax

BW = roipoly BW = roipoly(I) BW = roipoly(I, c, r) BW = roipoly(x, y, I, xi, yi) [BW, xi, yi] = roipoly(...) [x, y, BW, xi, yi] = roipoly(...)

Description

Use roipoly to specify a polygonal region of interest (ROI) within an image. roipoly returns a binary image that you can use as a mask for masked filtering.

BW = roipoly creates an interactive polygon tool, associated with the image displayed in the current figure, called the target image. With the polygon tool 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. The following figure illustrates a polygon defined by multiple vertices. The following table describes all the interactive behavior of the polygon tool.

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. roipoly returns the mask as a binary image, BW, the same size as I. In the mask image, roipoly sets pixels inside the region to 1 and pixels outside the region to 0.

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

Note If you call roipoly without specifying any output arguments, roipoly displays the resulting mask image in a new figure window.

BW = roipoly(I) displays the image I and creates an interactive polygon tool associated with that image.

BW = roipoly(I, c, r) returns the ROI specified by the polygon described by vectors c and r, which specify the column and row indices of each vertex, respectively. c and r must be the same size.

BW = roipoly(x, y, I, xi, yi) uses the vectors x and y to establish a nondefault spatial coordinate system. xi and yi are equal-length vectors that specify polygon vertices as locations in this coordinate system.

[BW, xi, yi] = roipoly(...) returns the x- and y-coordinates of the polygon vertices in xi and yi.

Note roipoly always produces a closed polygon. If the points specified describe a closed polygon (i.e., if the last pair of coordinates is identical to the first pair), the length of xi and yi is equal to the number of points specified. If the points specified do not describe a closed polygon, roipoly adds a final point having the same coordinates as the first point. (In this case the length of xi and yi is one greater than the number of points specified.)

[x, y, BW, xi, yi] = roipoly(...) returns the XData and YData in x and y, the mask image in BW, and the polygon coordinates in xi and yi.

Class Support

The input image I can be of class uint8, uint16, int16, single, or double. The output image BW is of class logical. All other inputs and outputs are of class double.

Remarks

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, and you use the mouse to specify a polygon within this image.

Examples

Use roipoly to create a mask image, BW, the same size as the input image, I. The example in roifilt2 continues this example, filtering the specified region in the image. For more examples, especially of the interactive syntaxes, see Specifying a Region of Interest (ROI).

I = imread('eight.tif');
c = [222 272 300 270 221 194];
r = [21 21 75 121 121 75];
BW = roipoly(I,c,r);
figure, imshow(I)
figure, imshow(BW)