# Documentation

Convert region of interest (ROI) polygon to region mask

## Syntax

`BW = poly2mask(x, y, m, n)`

## Description

`BW = poly2mask(x, y, m, n)` computes a binary region of interest (ROI) mask, `BW`, from an ROI polygon, represented by the vectors `x` and `y`. The size of `BW` is `m`-by-`n`. `poly2mask` sets pixels in `BW` that are inside the polygon (`X,Y`) to `1` and sets pixels outside the polygon to `0`.

`poly2mask` closes the polygon automatically if it isn't already closed.

### Note on Rectangular Polygons

When the input polygon goes through the middle of a pixel, sometimes the pixel is determined to be inside the polygon and sometimes it is determined to be outside (see Algorithm for details). To specify a polygon that includes a given rectangular set of pixels, make the edges of the polygon lie along the outside edges of the bounding pixels, instead of the center of the pixels.

For example, to include pixels in columns 4 through 10 and rows 4 through 10, you might specify the polygon vertices like this:

```x = [4 10 10 4 4]; y = [4 4 10 10 4]; mask = poly2mask(x,y,12,12) mask = 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0```

In this example, the polygon goes through the center of the bounding pixels, with the result that only some of the desired bounding pixels are determined to be inside the polygon (the pixels in row 4 and column 4 and not in the polygon). To include these elements in the polygon, use fractional values to specify the outside edge of the 4th row (3.5) and the 10th row (10.5), and the outside edge of the 4th column (3.5) and the outside edge of the 10th column (10.5) as vertices, as in the following example:

```x = [3.5 10.5 10.5 3.5 3.5]; y = [3.5 3.5 10.5 10.5 3.5]; mask = poly2mask(x,y,12,12) mask = 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0```

## Class Support

The class of `BW` is `logical`

## Examples

```x = [63 186 54 190 63]; y = [60 60 209 204 60]; bw = poly2mask(x,y,256,256); imshow(bw) hold on plot(x,y,'b','LineWidth',2) hold off```

Create a mask using random points.

```x = 256*rand(1,4); y = 256*rand(1,4); x(end+1) = x(1); y(end+1) = y(1); bw = poly2mask(x,y,256,256); imshow(bw) hold on plot(x,y,'b','LineWidth',2) hold off```

collapse all

### Algorithms

When creating a region of interest (ROI) mask, `poly2mask` must determine which pixels are included in the region. This determination can be difficult when pixels on the edge of a region are only partially covered by the border line. The following figure illustrates a triangular region of interest, examining in close-up one of the vertices of the ROI. The figure shows how pixels can be partially covered by the border of a region-of-interest.

Pixels on the Edge of an ROI Are Only Partially Covered by Border

To determine which pixels are in the region, `poly2mask` uses the following algorithm:

1. Divide each pixel (unit square) into a 5-by-5 grid. See Dividing Pixels into a 5-by-5 Subpixel Grid for an illustration.

2. Adjust the position of the vertices to be on the intersections of the subpixel grid. See Adjusting the Vertices to the Subpixel Grid for an illustration.

3. Draw a path from each adjusted vertex to the next, following the edges of the subpixel grid. See Drawing a Path Between the Adjusted Vertices for an illustration.

4. Determine which border pixels are inside the polygon using this rule: if a pixel's central subpixel is inside the boundaries defined by the path between adjusted vertices, the pixel is considered inside the polygon. See Determing Which Pixels Are in the Region for an illustration.

### Dividing Pixels into a 5-by-5 Subpixel Grid

The following figure shows the pixel that contains the vertex of the ROI shown previously with this 5-by-5 subpixel grid.

### Adjusting the Vertices to the Subpixel Grid

`poly2mask` adjusts each vertex of the polygon so that the vertex lies on the subpixel grid. Note how `poly2mask` rounds up x and y coordinates to find the nearest grid corner. This creates a second, modified polygon, slightly smaller, in this case, than the original ROI. A portion is shown in the following figure.

### Drawing a Path Between the Adjusted Vertices

`poly2mask` forms a path from each adjusted vertex to the next, following the edges of the subpixel grid. In the following figure, a portion of this modified polygon is shown by the thick dark lines.

### Determing Which Pixels Are in the Region

`poly2mask` uses the following rule to determine which border pixels are inside the polygon: if the pixel's central subpixel is inside the modified polygon, the pixel is inside the region.

In the following figure, the central subpixels of pixels on the ROI border are shaded a dark gray color. Pixels inside the polygon are shaded a lighter gray. Note that the pixel containing the vertex is not part of the ROI because its center pixel is not inside the modified polygon.