union

Union of polyshape objects

Syntax

polyout = union(poly1,poly2)

polyout = union(polyvec)

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

[polyout,shapeID,vertexID] = union(polyvec)

___ = union(___,Name=Value)

Description

polyout = union(poly1,poly2) returns a polyshape object whose regions are the union of two polyshape objects. The union contains the combined regions of poly1 and poly2, which must have compatible array sizes.

polyout = union(polyvec) returns a polyshape object whose regions are the geometric union of all polyshape objects in the vector polyvec. The union contains the combined regions of the polyshape objects in polyvec.

[polyout,shapeID,vertexID] = union(poly1,poly2) also returns vertex mapping information from the vertices in polyout to the vertices in poly1 and poly2. The union 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 union. vertexID maps the vertices of polyout to the vertices of poly1, poly2, or the union.

[polyout,shapeID,vertexID] = union(polyvec) returns vertex mapping information from polyout to each element of the vector of polyshape objects polyvec.

___ = union(___,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 = union(poly1,poly2,Simplify=false) returns a polyshape object whose vertices have not been modified regardless of intersections or improper nesting.

Examples

Union of Two Polygons

Create and plot two polygons.

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

Compute and plot the union of poly1 and poly2.

polyout = union(poly1,poly2)

polyout = 
  polyshape with properties:

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

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

Vector of Polygons

Create a vector of polygons and plot each polygon.

polyarray1 = polyshape([0 0 1 1],[1 0 0 1]);
polyarray2 = polyshape([0.75 1.25 1.25 0.75],[0.25 0.25 0.75 0.75]);
polyvec = [polyarray1 polyarray2]

polyvec = 
  1×2 polyshape array with properties:

    Vertices
    NumRegions
    NumHoles

plot(polyvec(1))
hold on
plot(polyvec(2))

figure

Compute and plot the union of the two polygons.

polyout = union(polyvec)

polyout = 
  polyshape with properties:

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

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

Vertex Mapping

Create two polygons, and compute and plot their union. Display the vertex coordinates of the union and the corresponding vertex mapping information.

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

[polyout.Vertices shapeID vertexID]

ans = 4×4

         0    1.0000    1.0000    1.0000
    1.5000    1.0000    2.0000    2.0000
    1.5000         0    2.0000    3.0000
         0         0    1.0000    4.0000

The first and last vertices of the union originated in poly1, since the corresponding values in shapeID are 1. These vertices are the first and fourth vertices in the property poly1.Vertices, respectively, since the corresponding values in vertexID are 1 and 4. Similarly, the second and third vertices of the union originated in poly2, and they are the second and third vertices in the property poly2.Vertices, respectively.

Input Arguments

poly1 — First input polyshape

scalar | vector | matrix | multidimensional array

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

Data Types: polyshape

poly2 — Second input polyshape

scalar | vector | matrix | multidimensional array

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

Data Types: polyshape

polyvec — polyshape vector

vector

polyshape vector.

Data Types: polyshape

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 = union(poly1,poly2,Simplify=false)

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

Example: polyout = union(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 — Output polyshape

scalar | vector | matrix | multidimensional array

Output polyshape, returned as a scalar, vector, matrix, or multidimensional array.

• If you input two polyshape arguments, then they must have compatible sizes. For example, if two input polyshape 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 you provide a single input argument polyvec, then polyout is a scalar polyshape object.

shapeID — Shape ID

column vector

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

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

• The elements of shapeID depend on the number of input arguments:

  • If you provide two input arguments poly1 and poly2, then they must be scalar polyshape objects. The value of an element in shapeID is 0 when the corresponding vertex of the output polyshape was created by the union. An element is 1 when the corresponding vertex originated from poly1, and 2 when it originated from poly2.

  • If you provide one input argument polyvec that is a vector of polyshape objects, then shapeID contains the element index of polyvec from which the corresponding output vertex originated. The value of an element is 0 when the corresponding vertex was created by the union.

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 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 union.

The length of vertexID is equal to the number of rows in the Vertices property of the output polyshape. If you provide two input polyshape objects, then union only supports this output argument if they are scalar.

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.

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

Version History

Introduced in R2017b

R2024a: Control whether to simplify output

Specify the Simplify name-value argument to control whether the union function simplifies its output. By default, Simplify is true and union 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 unions or intersections. 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.