subtract

Difference of two polyshape objects

Syntax

polyout = subtract(poly1,poly2)

[polyout,shapeID,vertexID] = subtract(poly1,poly2)

___ = subtract(___,Name=Value)

Description

polyout = subtract(poly1,poly2) returns a polyshape object whose regions are the geometric difference of two polyshape objects. The output polyout contains the regions of poly1 minus any part of poly2 that overlaps with poly1. The input arguments poly1 and poly2 must have compatible array sizes.

[polyout,shapeID,vertexID] = subtract(poly1,poly2) also returns vertex mapping information from the vertices in polyout to the vertices in poly1 and poly2. The subtract function only supports this syntax when poly1 and poly2 are scalar polyshape objects.

The shapeID elements identify whether the corresponding vertex in polyout originated in poly1, poly2, or was created from the difference. vertexID maps the vertices of polyout to the vertices of poly1, poly2, or the difference.

___ = subtract(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. You can use any of the output argument combinations in previous syntaxes. For example, polyout = subtract(poly1,poly2,Simplify=false) returns a polyshape object whose vertices have not been modified regardless of intersections or improper nesting.

Examples

Difference of Two Polygons

Create and plot two polygons poly1 and poly2 that partially overlap.

poly1 = polyshape([0 0 1 1],[1 0 0 1]);
poly2 = polyshape([0.75 1.25 1.25 0.75],[0.25 0.25 0.75 0.75]);
plot(poly1)
hold on
plot(poly2)

figure

Subtract poly2 from poly1. The resulting polygon is poly1 minus any part of poly2 that overlaps with poly1.

polyout1 = subtract(poly1,poly2)

polyout1 = 
  polyshape with properties:

      Vertices: [8×2 double]
    NumRegions: 1
      NumHoles: 0

plot(polyout1)

Now subtract the two polygons in the opposite order, that is, subtract poly1 from poly2. The resulting polygon is poly2 minus any part of poly1 that overlaps poly2.

polyout2 = subtract(poly2,poly1)

polyout2 = 
  polyshape with properties:

      Vertices: [4×2 double]
    NumRegions: 1
      NumHoles: 0

plot(polyout2)
xlim([-0.2 1.4]);
ylim([-0.2 1.2]);

Vertex Mapping

Create two polygons, and compute and plot their difference. When calling the subtract function, specify three output arguments to return the vertex mapping information.

poly1 = polyshape([0 0 1 1],[1 0 0 1]);
poly2 = translate(poly1,[0.5 0.5]);
[polyout,shapeID,vertexID] = subtract(poly1,poly2);
plot(polyout)
axis equal

Display the vertex coordinates of the difference and the corresponding vertex mapping information.

Vertices = polyout.Vertices;
table(Vertices,shapeID,vertexID)

ans=6×3 table
     Vertices     shapeID    vertexID
    __________    _______    ________

      0      1       1          1    
    0.5      1       0          0    
    0.5    0.5       2          4    
      1    0.5       0          0    
      1      0       1          3    
      0      0       1          4    

The first, fifth, and sixth values in shapeID are 1, indicating that the corresponding vertices of the difference originated in poly1. The corresponding values in vertexID are 1, 3, and 4, indicating that the vertices are the first, third, and fourth vertices in the property poly1.Vertices. Similarly, the third vertex of the difference originated in poly2, and it is the fourth vertex in the property poly2.Vertices. The second and fourth vertices of the difference were created from the subtraction computation, and the corresponding values of shapeID and vertexID are 0.

Polygons with Holes and Multiple Regions

Create and plot two polygons. The first polygon represents a square with a hole at its center, and the second polygon is a square without holes.

poly1 = polyshape([0.25 0.25 0.75 0.75], ...
                  [0.75 0.25 0.25 0.75]);
poly2 = polyshape([0 0 1 1],[1 0 0 1]);
poly1 = subtract(poly2,poly1);
poly2 = translate(scale(poly2,2),[-0.5 -0.5]);

plot([poly1 poly2])
axis equal

Subtract the polygon with the hole from the square. Plot the difference.

[polyout,shapeID,vertexID] = subtract(poly2,poly1);
plot(polyout)
axis equal

Display the vertex coordinates of the resulting polyshape object and the corresponding vertex mapping information.

Vertices = polyout.Vertices;
table(Vertices,shapeID,vertexID)

ans=14×3 table
      Vertices      shapeID    vertexID
    ____________    _______    ________

    -0.5     1.5        1          1   
     1.5     1.5        1          2   
     1.5    -0.5        1          3   
    -0.5    -0.5        1          4   
     NaN     NaN      NaN        NaN   
       0       1        2          1   
       0       0        2          4   
       1       0        2          3   
       1       1        2          2   
     NaN     NaN      NaN        NaN   
    0.25    0.75        2          6   
    0.75    0.75        2          9   
    0.75    0.25        2          8   
    0.25    0.25        2          7   

The resulting difference has three boundaries. In the Vertices property of the output polyshape object, the three sets of boundary coordinates are separated by a row of NaN values. The corresponding values in shapeID and vertexID are also NaN.

Input Arguments

poly1 — First input polyshape

scalar | vector | matrix | multidimensional array

First input polyshape, specified as a scalar, vector, matrix, or multidimensional array.

poly2 — Second input polyshape

scalar | vector | matrix | multidimensional array

Second input polyshape, specified as a scalar, vector, matrix, or multidimensional array.

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.

Example: polyout = subtract(poly1,poly2,Simplify=false)

KeepCollinearPoints — Keep collinear points as vertices

true or 1 | false or 0

Keep collinear points as vertices, specified as one of these numeric or logical values:

• 1 (true) — Keep all collinear points as vertices.

• 0 (false) — Remove collinear points so that the output polyshape contains the fewest vertices necessary to define the boundaries.

If you do not specify the KeepCollinearPoints name-value argument, the function assigns its value according to the values used during creation of the input polyshape objects.

• If each input polyshape kept collinear points as vertices during creation, then the function sets KeepCollinearPoints to true.

• If each input polyshape removed collinear points during creation, then the function sets KeepCollinearPoints to false.

• If the collinear points of the input polyshape objects were treated differently, then the function sets KeepCollinearPoints to false.

Simplify — Modify polygon vertices to simplify output

true or 1 (default) | false or 0

Modify polygon vertices to simplify output, specified as one of these numeric or logical values:

• 1 (true) — Modify polygon vertices to produce a well-defined polygon when the output vertices produce intersections or improper nesting.

• 0 (false) — Produce a polygon that may contain intersecting edges, improper nesting, duplicate points, or degeneracies. Computing with ill-defined polygons can lead to inaccurate or unexpected results.

Output Arguments

polyout — Resulting difference

polyshape object | array of polyshape objects

Resulting difference, returned as a polyshape object or an array of polyshape objects.

The two polyshape input arguments must have compatible sizes. For example, if two polyshape input vectors have different lengths M and N, then they must have different orientations (one must be a row vector and one must be a column vector). polyout is then M-by-N or N-by-M depending on the orientation of each input vector. For more information on compatible array sizes, see Compatible Array Sizes for Basic Operations.

If the Vertices property of polyout contains NaN values, then that shape has multiple regions or holes and, therefore, has more than one boundary. NaN values separate the sets of vertices for each boundary.

shapeID — Shape ID

column vector

Shape ID, returned as a column vector whose elements each represent the origin of the vertex in the difference.

• The length of shapeID is equal to the number of rows in the Vertices property of the output polyshape.

• The value of an element in shapeID is 1 when the corresponding vertex originated from poly1, and 2 when it originated from poly2. An element is 0 when the corresponding vertex of the output polyshape was created by the subtraction.

• The subtract function supports this output argument only if the poly1 and poly2 input arguments are scalar polyshape objects.

• NaN values in shapeID indicate that polyout has multiple regions or holes and, therefore, has more than one boundary. NaN values separate the sets of vertices for each boundary.

Data Types: double

vertexID — Vertex ID

column vector

Vertex ID, returned as a column vector whose elements map the vertices in the output polyshape to the vertices in the polyshape of origin.

• The length of vertexID is equal to the number of rows in the Vertices property of the output polyshape.

• The elements of vertexID contain the row numbers of the corresponding vertices in the Vertices property of the input polyshape. An element is 0 when the corresponding vertex of the output polyshape was created by the difference.

• The subtract function supports this output argument only if poly1 and poly2 input arguments are scalar polyshape objects.

• NaN values in vertexID indicate that polyout has multiple regions or holes and, therefore, has more than one boundary. NaN values separate the sets of vertices for each boundary.

Data Types: double

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Dynamic memory allocation must be enabled for code generation.

• Name-value pair must be compile time constant.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Version History

Introduced in R2017b

R2024b: Control whether to simplify output

Specify the Simplify name-value argument to control whether the subtract function simplifies its output. By default, Simplify is true and subtract returns a well-defined polygon by resolving boundary intersections and improper nesting and also by removing duplicate points and degeneracies.

You can specify Simplify=false to gain performance when performing a series of exclusive ors or subtractions. In this case, you can simplify the output once at the end either by specifying Simplify=true in the final function call or by using the simplify function on the final output polygon.