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.

If you want to create a regular polygon, you can also use the nsidedpoly function. nsidedpoly enables you to optionally specify parameters such as the center point and side length of the 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(X,Y), where X and Y are 1-by-M cell arrays of vectors for the x- and y-coordinates, creates a polygon consisting of M boundaries. Each vector in X must have the same length as the corresponding vector in Y, but the number of vertices can vary between 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 vector can vary, but must match the length of the corresponding y 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 vector can vary, but must match the length of the corresponding y vector.

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

Data Types: cell

Name-Value Pair Arguments

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 name and value pair arguments in either order as Name1,Value1,Name2,Value2.

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

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

Collinear vertices, specified as the comma-separated pair consisting of 'KeepCollinearPoints' and one of the following:

• false — Remove collinear points when creating the polyshape so that it contains the fewest vertices necessary to define the boundaries.

• true — Keep all collinear points as vertices when creating the polyshape.

After creating a polyshape, the value of 'KeepCollinearPoints' is automatically carried over when you use the addboundary or simplify object functions.

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. A region is an area bounded by an outer boundary, which may contain hole boundaries that lie entirely inside the outer boundary.

Data Types: double

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

Data Types: double

Object Functions

expand all

 addboundary Add polyshape boundary polybuffer Create buffer around points, lines, or polyshape objects rmboundary Remove polyshape boundary rmholes Remove holes in polyshape rmslivers Remove polyshape boundary outliers rotate Rotate polyshape scale Scale polyshape simplify Simplify polyshape boundaries sortboundaries Sort polyshape boundaries sortregions Sort polyshape regions translate Translate polyshape
 boundary Vertex coordinates of polyshape boundary holes Convert polyshape hole boundaries to array of polyshape objects ishole Determine if polyshape boundary is a hole isinterior Query points inside polyshape issimplified Determine if polyshape is well-defined nearestvertex Query nearest polyshape vertex numboundaries Number of polyshape boundaries numsides Number of polyshape sides overlaps Determine whether polyshape objects overlap plot Plot polyshape regions Access polyshape regions
 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 turningdist Compute turning distance between polyshape objects
 intersect Intersection of polyshape objects subtract Difference of two polyshape objects union Union of polyshape objects xor Exclusive OR of two polyshape objects

Examples

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