# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# polyshape

2-D polygons

## Description

The `polyshape` function creates a polygon defined by 2-D vertices, and returns a `polyshape` object with properties describing its vertices, solid regions, and holes. For example, ```pgon = polyshape([0 0 1 1],[1 0 0 1])``` creates the solid square defined by the four points (0,1), (0,0), (1,0), and (1,1).

`>> pgon = polyshape([0 0 1 1],[1 0 0 1])`
```pgon = polyshape with properties: Vertices: [4×2 double] NumRegions: 1 NumHoles: 0```
`>> plot(pgon)`

## Creation

When creating a `polyshape` object, the input vertices should define one or more boundaries of a polygon that have no intersections and are properly nested. Otherwise, the `polyshape` function automatically alters the input vertices as needed to create a well-defined polygon.

### Description

````pgon = polyshape()` creates an empty `polyshape` object.```

example

````pgon = polyshape(x,y)` creates a `polyshape` from 2-D vertices defined by a vector of x-coordinates and a vector of corresponding y-coordinates. `x` and `y` must be the same length with at least three elements.```

example

````pgon = polyshape(P)` creates a `polyshape` from the 2-D vertices defined in the N-by-2 matrix `P`, where N is the number of vertices. The first column of `P` defines the x-coordinates, and the second column defines the `y`-coordinates.```

example

````pgon = polyshape({x1,x2,...,xM}},{y1,y2,...,yM})` creates a polygon consisting of M boundaries, where the vectors of x-coordinates for each boundary are listed together in a cell array, and the corresponding vectors of y-coordinates are also listed together in a cell array. Each xi must have the same length as the corresponding yi, but the number of vertices can vary between any ith and jth boundaries.```

example

````pgon = polyshape(___,Name,Value)` specifies additional parameters for creating a `polyshape` object for any of the previous syntaxes.```

### Input Arguments

expand all

x-coordinates of polygon vertices, specified as a vector. You can represent the coordinates of multiple boundaries at a time by placing a `NaN` between each boundary. For example, ```pgon = polyshape([0 0 1 NaN 1 5 5],[1 0 0 NaN 5 5 1])``` creates a `polyshape` made up of two solid triangles.

Numeric input coordinates that are not of type `double` are automatically converted to type `double`.

Data Types: `double` | `single` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

y-coordinates of polygon vertices, specified as a vector. You can represent the coordinates of multiple boundaries at a time by placing a `NaN` between each boundary. For example, ```pgon = polyshape([0 0 1 NaN 1 5 5],[1 0 0 NaN 5 5 1])``` creates a `polyshape` made up of two solid triangles.

Numeric input coordinates that are not of type `double` are automatically converted to type `double`.

Data Types: `double` | `single` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

2-D vertices of the polygon, specified as a 2-column matrix. The first column of `P` contains the x-coordinates of the vertices, and the second column contains the y-coordinates. `P` must have at least 3 rows.

You can represent the coordinates of multiple boundaries at a time by placing a `NaN` between each boundary. For example, ```pgon = polyshape([1 0; 0 0; 0 1; NaN NaN; 1 5; 5 5; 5 1])``` creates a `polyshape` made up of two solid triangles.

Numeric input coordinates that are not of type `double` are automatically converted to type `double`.

Data Types: `double` | `single` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

x-coordinates of M boundaries, specified as a cell array of vectors. The length of each xi can vary, but must match the length of the corresponding yi vector.

Numeric input coordinates that are not of type `double` are automatically converted to type `double`.

Data Types: `cell`

y-coordinates of M boundaries, specified as a cell array of vectors. The length of each yi can vary, but must match the length of the corresponding xi vector.

Numeric input coordinates that are not of type `double` are automatically converted to type `double`.

Data Types: `cell`

#### Name-Value Pair Arguments

Example: ```pgon = polyshape(P,'SolidBoundaryOrientation','ccw')```

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

expand all

Boundary orientation, specified as the comma-separated pair consisting of `'SolidBoundaryOrientation'` and one of these values:

• `'auto'` — Automatically determine the boundary type based on boundary nesting.

• `'cw'` — Treat clockwise vertex orientation as a solid boundary.

• `'ccw'` — Treat counterclockwise vertex orientation as a solid boundary.

This parameter is typically specified for consistency purposes when polygon data is produced by other software using a particular convention.

Vertex alteration, specified as the comma-separated pair consisting of `'Simplify'` and one of the following:

• `true` — Alter polygon vertices to produce a well-defined polygon when the input vertices produce intersections or improper nesting.

• `false` — Do not alter input vertices regardless of intersections or improper nesting. Computing with ill-defined polygons can lead to inaccurate or unexpected results.

Data Types: `logical`

## Properties

expand all

2-D vertices of the polygon, specified as a 2-column matrix. The vertex matrix contains the vertices for each boundary of the polygon. `NaN` values separate each boundary's set of vertices.

Data Types: `double`

Number of regions making up the polygon, specified as a scalar integer.

Data Types: `double`

Number of holes in the polygon, specified as a scalar integer.

Data Types: `double`

## Object Functions

 `addboundary` Add polyshape boundary `rmboundary` Remove polyshape boundary `rmholes` Remove holes in polyshape `rmslivers` Remove polyshape boundary outliers `simplify` Simplify polyshape boundaries
 `boundary` Vertex coordinates of polyshape boundary `isequal` Determine if polyshape objects are equal `ishole` Determine if polyshape boundary is a hole `isinterior` Query points inside polyshape `issimplified` Determine if polyshape is well-defined `numboundaries` Number of polyshape boundaries `numsides` Number of polyshape sides
 `area` Area of polyshape `boundingbox` Bounding box of polyshape `centroid` Centroid of polyshape `convhull` Convex hull of polyshape `perimeter` Perimeter of polyshape `triangulation` Triangulate polyshape
 `intersect` Intersection of polyshape objects `subtract` Difference of two polyshape objects `union` Union of polyshape objects `xor` Exclusive OR of two polyshape objects
 `polybuffer` Buffer polyshape `rotate` Rotate polyshape `scale` Scale polyshape `translate` Translate polyshape
 `holes` Convert polyshape hole boundaries to array of polyshape objects `plot` Plot polyshape `regions` Perimeter of polyshape `sortboundaries` Sort polyshape boundaries `sortregions` Sort polyshape regions

## Examples

expand all

Create and plot a polygon made up of four points, and compute its area, perimeter, and centroid coordinates.

```pgon = polyshape([0 0 1 3], [0 3 3 0]); plot(pgon)```

`A = area(pgon)`
```A = 6 ```
`P = perimeter(pgon)`
```P = 10.6056 ```
`[Cx Cy] = centroid(pgon)`
```Cx = 1.0833 ```
```Cy = 1.2500 ```

Analyze a polygon with intersecting boundaries.

Create a polygon whose boundary contains a self-intersection. By default, the polyshape function splits the boundary into two distinct boundaries in order to create a well-defined polygon.

```P = [0 0; 1 1; 1 0; 0 1; 0 0]; pgon = polyshape(P)```
```Warning: Polyshape has duplicate vertices, intersections, or other inconsistencies that may produce inaccurate or unexpected results. Input data has been modified to create a well-defined polyshape. ```
```pgon = polyshape with properties: Vertices: [7x2 double] NumRegions: 2 NumHoles: 0 ```

Plot the polygon and compute its area.

`plot(pgon)`

`A = area(pgon)`
```A = 0.5000 ```

If you do not simplify the original input vertices, the areas of the two triangular regions of the polygon cancel each other out.

`pgon2 = polyshape(P,'Simplify',false)`
```pgon2 = polyshape with properties: Vertices: [4x2 double] NumRegions: 1 NumHoles: 0 ```
`A2 = area(pgon2)`
```A2 = 0 ```

Analyze polygons with nested boundaries.

Create a polygon with two properly nested boundaries. `polyshape` defines the outermost boundary as the exterior bound of a solid region. Working inward, the next boundary defines the start of a hole.

```t = 0.05:0.5:2*pi; x1 = cos(t); y1 = sin(t); x2 = 0.5*cos(t); y2 = 0.5*sin(t); pgon = polyshape({x1,x2},{y1,y2})```
```pgon = polyshape with properties: Vertices: [27x2 double] NumRegions: 1 NumHoles: 1 ```
`plot(pgon)`

Use the `addboundary` function to create a second polygon that adds a third, outer boundary to `pgon`.

```x3 = 2*cos(t); y3 = 2*sin(t); pgon2 = addboundary(pgon,x3,y3)```
```pgon2 = polyshape with properties: Vertices: [41x2 double] NumRegions: 2 NumHoles: 1 ```
`plot(pgon2)`

Adding a third, outer boundary requires `polyshape` to reorganize the solid and hole boundaries based on the new nesting pattern. Again, `polyshape` starts with the outermost boundary that indicates the start of a solid region, then alternates between hole and solid with each nested boundary, working inward. The new polygon now has two solid regions and one hole.