Intersection of `polyshape`

objects

collapse all in page

## Syntax

`polyout = intersect(poly1,poly2)`

`polyout = intersect(polyvec)`

`[polyout,shapeID,vertexID] = intersect(poly1,poly2)`

`[polyout,shapeID,vertexID] = intersect(polyvec)`

`[in,out] = intersect(poly1,lineseg)`

`___ = intersect(___,Name=Value)`

## Description

example

`polyout = intersect(poly1,poly2)`

returns a `polyshape`

object whose regions are the geometric intersection of two `polyshape`

objects. The intersection contains the regions of `poly1`

and `poly2`

that overlap. `poly1`

and `poly2`

must have compatible array sizes.

example

`polyout = intersect(polyvec)`

returns a `polyshape`

object whose regions are the intersection of all the `polyshape`

objects in the vector `polyvec`

. The intersection contains the regions where all the `polyshape`

objects in `polyvec`

overlap.

example

`[polyout,shapeID,vertexID] = intersect(poly1,poly2)`

also returns vertex mapping information from the vertices in `polyout`

to the vertices in `poly1`

and `poly2`

. The `intersect`

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 intersection. `vertexID`

maps the vertices of `polyout`

to the vertices of `poly1`

, `poly2`

, or the intersection.

`[polyout,shapeID,vertexID] = intersect(polyvec)`

returns vertex mapping information from `polyout`

to each element of the vector of `polyshape`

objects `polyvec`

.

example

`[in,out] = intersect(poly1,lineseg)`

returns the line segments of `lineseg`

that are inside and outside of `poly1`

. The matrix `lineseg`

has two columns. The first column defines the *x*-coordinates of the line segments and the second column defines the corresponding *y*-coordinates.

`intersect`

supports this syntax only when `poly1`

is a scalar `polyshape`

and `lineseg`

contains no self-intersections.

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

returns a `polyshape`

object whose vertices have not been modified regardless of intersections or improper nesting.

## Examples

collapse all

### Intersection of Two Polygons

Open Live Script

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 onplot(poly2)`

figure

Compute and plot the intersection of `poly1`

and `poly2`

.

polyout = intersect(poly1,poly2)

polyout = polyshape with properties: Vertices: [4x2 double] NumRegions: 1 NumHoles: 0

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

### Vector of Polygons

Open Live Script

Create a vector containing two polygons.

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 = 1x2 polyshape array with properties: Vertices NumRegions NumHoles

`plot(polyvec(1))hold onplot(polyvec(2))`

figure

Compute the intersection of the elements of `poly1`

.

polyout = intersect(polyvec)

polyout = polyshape with properties: Vertices: [4x2 double] NumRegions: 1 NumHoles: 0

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

### Vertex Mapping

Open Live Script

Create two polygons and compute their intersection. Display the vertex coordinates of the intersection and the corresponding vertex mapping information.

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]);[polyout,shapeID,vertexID] = intersect(poly1,poly2);[polyout.Vertices shapeID vertexID]

`ans = `*4×4* 0.7500 0.2500 2.0000 1.0000 0.7500 0.7500 2.0000 2.0000 1.0000 0.7500 0 0 1.0000 0.2500 0 0

The first two vertices of the intersection originated in `poly2`

, since the corresponding values in `shapeID`

are 2.These vertices are the first and second vertices in the property `poly2.Vertices`

, respectively, since their corresponding values in `vertexID`

are 1 and 2. The last two vertices of `polyout`

were created from the intersection because the corresponding values in `shapeID`

and `vertexID`

are 0.

### Intersection of Polygon and Line

Open Live Script

Create a rectangular polygon and a line segment.

poly1 = polyshape([0 0 1 1],[1 0 0 1]);lineseg = [0.5 0.5; 1.5 1.5];

Compute the intersection of the polygon with the line segment, and determine which sections of the line segment are inside or outside of the polygon.

[in,out] = intersect(poly1,lineseg);plot(poly1)hold onplot(in(:,1),in(:,2),'b',out(:,1),out(:,2),'r')legend('Polygon','Inside','Outside','Location','NorthWest')

## Input Arguments

collapse all

`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`

`lineseg`

— Line segment coordinates

two-column matrix

Line segment coordinates, specified as a two-column matrix. The first column defines the *x*-coordinates of the line segments and the second column defines the *y*-coordinates. `lineseg`

must have at least two rows and contain no self-intersections.

**Data Types: **`double`

| `single`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

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

* Before R2021a, use commas to separate each name and value, and enclose* `Name`

*in quotes.*

**Example: **`polyout = intersect(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, 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`

) — Do not modify output vertices regardless of intersections or improper nesting. Computing with ill-defined polygons can lead to inaccurate or unexpected results.

## Output Arguments

collapse all

`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 a vertex in the intersection.

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

**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 intersection.

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 `intersect`

only supports this output argument if they are scalar.

**Data Types: **`double`

`in`

— Inside coordinates

two-column matrix

Inside line segment coordinates, returned as a two-column matrix. The first column of `in`

contains the *x*-coordinates of the line segments inside the input `polyshape`

, and the second column contains the corresponding *y*-coordinates.

**Data Types: **`double`

`out`

— Outside coordinates

two-column matrix

Outside line segment coordinates, returned as a two-column matrix. The first column of `out`

contains the *x*-coordinates of the line segments outside of the input `polyshape`

, and the second column contains the corresponding *y*-coordinates.

**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**

expand all

### R2024a: Control whether to simplify output

Specify the `Simplify`

name-value argument to control whether the `intersect`

function simplifies its output. By default, `Simplify`

is `true`

and `intersect`

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.

## See Also

polyshape | xor

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- Deutsch
- English
- Français

- United Kingdom (English)

Contact your local office