Main Content

polyshape

2-D polygonal shapes

Description

The polyshape function creates polygon-like shapes from 2-D vertices. However, unlike polygons, a polyshape can have discontiguous regions and holes. The properties of a polyshape object describe 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)

Plot of a square polyshape

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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

This property is read-only.

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

This property is read-only.

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

Data Types: double

Object Functions

expand all

addboundaryAdd polyshape boundary
polybufferCreate buffer around points, lines, or polyshape objects
rmboundaryRemove polyshape boundary
rmholesRemove holes in polyshape
rmsliversRemove polyshape boundary outliers
rotateRotate polyshape
scaleScale polyshape
simplifySimplify polyshape boundaries
sortboundariesSort polyshape boundaries
sortregionsSort polyshape regions
translateTranslate polyshape
boundaryVertex coordinates of polyshape boundary
holesConvert polyshape hole boundaries to array of polyshape objects
isholeDetermine if polyshape boundary is a hole
isinteriorQuery points inside polyshape
issimplifiedDetermine if polyshape is well-defined
nearestvertexQuery nearest polyshape vertex
numboundariesNumber of polyshape boundaries
numsidesNumber of polyshape sides
overlapsDetermine whether polyshape objects overlap
plotPlot polyshape
regionsAccess polyshape regions
areaArea of polyshape
boundingboxBounding box of polyshape
centroidCentroid of polyshape
convhullConvex hull of polyshape
perimeterPerimeter of polyshape
triangulationTriangulate polyshape
turningdistCompute turning distance between polyshape objects
intersectIntersection of polyshape objects
subtractDifference of two polyshape objects
unionUnion of polyshape objects
xorExclusive 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 = 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.

Extended Capabilities

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2017b