Documentation

This is machine translation

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

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this 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

This property is read-only.

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

Data Types: double

This property is read-only.

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

Data Types: double

Object Functions

addboundaryAdd polyshape boundary
rmboundaryRemove polyshape boundary
rmholesRemove holes in polyshape
rmsliversRemove polyshape boundary outliers
simplifySimplify polyshape boundaries
boundaryVertex coordinates of polyshape boundary
isequalDetermine if polyshape objects are equal
isholeDetermine if polyshape boundary is a hole
isinteriorQuery points inside polyshape
issimplifiedDetermine if polyshape is well-defined
numboundariesNumber of polyshape boundaries
numsidesNumber of polyshape sides
areaArea of polyshape
boundingboxBounding box of polyshape
centroidCentroid of polyshape
convhullConvex hull of polyshape
perimeterPerimeter of polyshape
triangulationTriangulate polyshape
intersectIntersection of polyshape objects
subtractDifference of two polyshape objects
unionUnion of polyshape objects
xorExclusive OR of two polyshape objects
polybufferBuffer polyshape
rotateRotate polyshape
scaleScale polyshape
translateTranslate polyshape
holesConvert polyshape hole boundaries to array of polyshape objects
plotPlot polyshape
regionsPerimeter of polyshape
sortboundariesSort polyshape boundaries
sortregionsSort 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.

Introduced in R2017b

Was this topic helpful?