# patch

Create one or more filled polygons

## Syntax

• ``patch(X,Y,C)``
example
• ``patch(X,Y,Z,C)``
• ``patch('XData',X,'YData',Y)``
• ``patch('XData',X,'YData',Y,'ZData',Z)``
• ``patch('Face',F,'Vertices',V)``
example
• ``patch(S)``
example
• ``patch(___,Name,Value)``
example
• ``p = patch(___)``

## Description

example

````patch(X,Y,C)` creates one or more filled polygons using the elements of `X` and `Y` as the coordinates for each vertex. `patch` connects the vertices in the order that you specify them. To create one polygon, specify `X` and `Y` as vectors. To create multiple polygons, specify `X` and `Y` as matrices where each column corresponds to a polygon. `C` determines the polygon colors. ```
````patch(X,Y,Z,C)` creates the polygons in 3-D coordinates using `X`, `Y`, and `Z`. To view the polygons in a 3-D view, use the `view(3)` command. `C` determines the polygon colors.```
````patch('XData',X,'YData',Y)` is similar to `patch(X,Y,C)`, except that you do not have to specify color data for the 2-D coordinates.```
````patch('XData',X,'YData',Y,'ZData',Z)` is similar to `patch(X,Y,Z,C)`, except that you do not have to specify color data for the 3-D coordinates.```

example

````patch('Face',F,'Vertices',V)` creates one or more polygons where `V` specifies vertex values and `F` defines which vertices to connect. Specifying only unique vertices and their connection matrix can reduce the size of the data when there are many polygons. Specify one vertex per row in `V`. To create one polygon, specify `F` as a vector. To create multiple polygons, specify `F` as a matrix with one row per polygon. Each face does not have to have the same number of vertices. To specify different numbers of vertices, pad `F` with `NaN` values.```

example

````patch(S)` creates one or more polygons using structure `S`. The structure fields correspond to patch property names and the field values corresponding to property values. For example, `S` can contain the fields `Faces` and `Vertices`.```

example

````patch(___,Name,Value)` creates polygons and specifies one or more patch properties using name-value pair arguments. A patch is the object that contains the data for all of the polygons created. You can specify patch properties with any of the input argument combinations in the previous syntaxes. For example, `'LineWidth',2` sets the outline width for all of the polygons to 2 points. ```
````p = patch(___)` returns the patch object that contains the data for all the polygons. Use `p` to query and modify properties of the patch object after it is created. For a list of properties and descriptions, see Patch Properties.```

## Examples

collapse all

### Specifying Coordinates

Create a single polygon by specifying the (x,y) coordinates of each vertex. Then, add two more polygons to the figure.

Create a red square with vertices at `(0,0)`, `(1,0)`, `(1,1)`, and `(0,1)`. Specify `x` as the x-coordinates of the vertices and `y` as the y-coordinates. `patch` automatically connects the last (x,y) coordinate with the first (x,y) coordinate.

```x = [0 1 1 0]; y = [0 0 1 1]; patch(x,y,'red') ```

Create two polygons by specifying `x` and `y` as two-column matrices. Each column defines the coordinates for one of the polygons. `patch` adds the polygons to the current axes without clearing the axes.

```x2 = [2 5; 2 5; 8 8]; y2 = [4 0; 8 2; 4 0]; patch(x2,y2,'green') ```

### Specifying Faces and Vertices

Create a single polygon by specifying the coordinates of each unique vertex and a matrix that defines how to connect them. Then, add two more polygons to the figure.

Create a red square with corners at `(0,0)`, `(1,0)`, `(1,1)`, and `(0,1)`. Specify `v` so that each row defines the (x,y) coordinates for one vertex. Then, specify `f` as the vertices to connect. Set the color by specifying the `FaceColor` property.

```v = [0 0; 1 0; 1 1; 0 1]; f = [1 2 3 4]; patch('Faces',f,'Vertices',v,'FaceColor','red') ```

Create two polygons by specifying `f` as a two-row matrix. Each row defines the face for one patch.

```v2 = [2 4; 2 8; 8 4; 5 0; 5 2; 8 0]; f2 = [1 2 3; 4 5 6]; patch('Faces',f2,'Vertices',v2,'FaceColor','green') ```

### Different Polygon Face Colors

Create two polygons and use a different color for each polygon face. Use a colorbar to show how the colors map into the colormap.

Create the polygons using matrices `x` and `y`. Specify `c` as an column vector with two elements since there are two polygon faces, and add a colorbar.

```x = [2 5; 2 5; 8 8]; y = [4 0; 8 2; 4 0]; c = [0; 1]; figure patch(x,y,c) colorbar ```

Alternatively, you can get the same result when using `f` and `v` instead. When you create the polygons, set `FaceVertexCData` to a column vector with two elements since there are two polygon faces. Set `FaceColor` to `'flat'`.

```v = [2 4; 2 8; 8 4; 5 0; 5 2; 8 0]; f = [1 2 3; 4 5 6]; col = [0; 1]; figure patch('Faces',f,'Vertices',v,'FaceVertexCData',col,'FaceColor','flat'); colorbar ```

### Interpolated Polygon Face Colors

Interpolate colors across polygon faces by specifying a color at each polygon vertex, and use a colorbar to show how the colors map into the colormap.

Create the polygons using matrices `x` and `y`. Specify `c` as a matrix the same size as `x` and `y` defining one color per vertex, and add a colorbar.

```x = [2 5; 2 5; 8 8]; y = [4 0; 8 2; 4 0]; c = [0 3; 6 4; 4 6]; figure patch(x,y,c) colorbar ```

Alternatively, you can get the same result using `f` and `v` instead. When you create the polygons, set `FaceVertexCData` to a column vector with one value per vertex and set `FaceColor` to `'interp'`.

```v = [2 4; 2 8; 8 4; 5 0; 5 2; 8 0]; f = [1 2 3; 4 5 6]; col = [0; 6; 4; 3; 4; 6]; figure patch('Faces',f,'Vertices',v,'FaceVertexCData',col,'FaceColor','interp'); colorbar ```

### Polygon Edges Without Faces

Create a polygon with green edges and do not display the face. Then, create a second polygon with a different color for each edge.

```v = [0 0; 1 0; 1 1]; f = [1 2 3]; figure patch('Faces',f,'Vertices',v,... 'EdgeColor','green','FaceColor','none','LineWidth',2); ```

Use a different color for each edge by specifying a color for each vertex and setting `EdgeColor` to `'flat'`.

```v = [2 0; 3 0; 3 1]; f = [1 2 3]; c = [1 0 0; % red 0 1 0; % green 0 0 1]; % blue patch('Faces',f,'Vertices',v,'FaceVertexCData',c,... 'EdgeColor','flat','FaceColor','none','LineWidth',2); ```

### Polygons Using Structure

Use a structure to create two polygons. First, create a structure with fields names that match patch property names. Then, use the structure to create the polygons.

```clear S S.Vertices = [2 4; 2 8; 8 4; 5 0; 5 2; 8 0]; S.Faces = [1 2 3; 4 5 6]; S.FaceVertexCData = [0; 1]; S.FaceColor = 'flat'; S.EdgeColor = 'red'; S.LineWidth = 2; figure patch(S) ```

### Semitransparent Polygons

Create two semitransparent polygons by setting the `FaceAlpha` property to a value between `0` and `1`.

```v1 = [2 4; 2 8; 8 4]; f1 = [1 2 3]; figure patch('Faces',f1,'Vertices',v1,'FaceColor','red','FaceAlpha',.3); v2 = [2 4; 2 8; 8 8]; f2 = [1 2 3]; patch('Faces',f2,'Vertices',v2,'FaceColor','blue','FaceAlpha',.5); ```

### Create Multicolored Line

Create a multicolored line with markers at each vertex. Interpolate the colors and use a colorbar to show how the values map to the colormap.

Create the data. Set the last entry of `y` to `NaN` so that `patch` creates a line instead of a closed polygon. Define a color for each vertex using the `y` values. The values in `c` map to colors in the colormap.

```x = linspace(1,10,15); y = sin(x); y(end) = NaN; c = y; ```

Create the line. Show markers at each vertex and set the `EdgeColor` to `'interp'` to interpolate the colors between vertices. Add a colorbar.

```figure patch(x,y,c,'EdgeColor','interp','Marker','o','MarkerFaceColor','flat'); colorbar; ```

## Input Arguments

collapse all

### `X` — x-coordinates for verticesvector | matrix

x-coordinates for the vertices, specified in one of these forms:

• Vector — Create one polygon.

• Matrix — Create `n` polygons with `m` vertices each, where `[m,n] = size(X)`. Each column in the matrix corresponds to one polygon.

If the data does not define closed polygons, then `patch` closes the polygons. If the edges of an individual polygon intersect themselves, the resulting polygons might be partly filled. In that case, it is better to divide the patch object into smaller polygons.

When you specify `X`, the `patch` function sets the `XData` property for the patch object to the same value. The patch object automatically calculates the face and vertex data and sets the `Faces` and `Vertices` properties to the appropriate values.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

### `Y` — y-coordinates for verticesvector | matrix

y-coordinates for the vertices, specified in one of these forms:

• Vector — Create one polygon.

• Matrix — Create `n` polygons with `m` vertices each, where `[m,n] = size(Y)`. Each column in the matrix corresponds to one polygon.

If the data does not define closed polygons, then `patch` closes the polygons. If the edges of an individual polygon intersect themselves, the resulting polygons might be partly filled. In that case, it is better to divide the patch object into smaller polygons.

When you specify `Y`, the `patch` function sets the `YData` property for the patch object to the same value. The patch object automatically calculates the face and vertex data and sets the `Faces` and `Vertices` properties to the appropriate values.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

### `Z` — z-coordinates for verticesvector | matrix

z-coordinates for the vertices, specified in one of these forms:

• Vector — Create one polygon.

• Matrix — Create `m` polygons with `n` vertices each, where `[m,n] = size(Z)`. Each column in the matrix corresponds to one polygon.

When you specify `Z`, the `patch` function sets the `ZData` property for the patch object to the same value. The patch object automatically calculates the face and vertex data and sets the `Faces` and `Vertices` properties to the appropriate values.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

### `C` — Polygon colorsscalar | vector | matrix | color string

Polygon colors, specified as a scalar, vector, matrix, or color string. The format of the input determines whether all polygons have the same color, one color per face, or interpolated face colors.

Desired EffectUse One of These FormatsResults
Single color for all faces
• Color string, for example, `'r'` for red.

• RGB triplet, for example, `[0 .5 .5]`.

• Scalar value, for example, `2`. The `CDataMapping` property determines how the value maps into the colormap.

For an example, see Specifying Coordinates.

One color per face
• `n`-by-1 vector of colormap colors, where `n` is the number of faces. The `CDataMapping` property determines how the values map into the colormap.

• `n`-by-`1`-by-`3` array of RGB values. The first page of the array defines the red components of the colors, the second page defines the blue, and the third page defines the green.

For an example, see Different Polygon Face Colors.

Interpolated face colors
• `m`-by-`n` matrix of colormap values, where `[m,n] = size(X)`. Specify one color per vertex.

• `m`-by-`n`-by-`3` array of RGB values.

For an example, see Interpolated Polygon Face Colors.

### `V` — Polygon verticestwo-column or three-column matrix

Polygon vertices, specified in one of these forms:

• Two-column matrix — Each row contains the (x,y) coordinates for a vertex.

• Three-column matrix — Each row contains the (x,y,Z) coordinates for a vertex.

Specify only unique vertices. You can refer to a vertex more than once when defining the face definitions in `F`.

When you specify `V`, the `patch` function sets the `Vertices` property for the patch object to the same value. The patch object automatically calculates the coordinate data and sets the `XData`, `YData`, and `ZData` to the appropriate values.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

### `F` — Face definitionsrow vector | matrix

Face definitions, specified in one of these forms:

• Row vector — Create a single polygon.

• Matrix — Create multiple polygons where each row corresponds to a polygon.

For example, this code defines three vertices in `V` and creates one polygon by connecting vertex 1 to 2, 2 to 3, and 3 to 1.

```V = [1 1; 2 1; 2 2]; F = [1 2 3 1]; patch('Faces',F,'Vertices',V)```

When you specify `F`, the `patch` function sets the `Faces` property for the patch object to the same value. The patch object automatically calculates the coordinate data and sets the `XData`, `YData`, and `ZData` to the appropriate values.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

### `S` — Patch definitionstructure

Patch definition, specified as a structure with fields that correspond patch property names and field values that correspond to patch property values.

### Name-Value Pair Arguments

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

Example: `patch(x,y,c,'FaceAlpha',.5,'LineStyle',':')` creates semitransparent polygons with dotted edges.

The properties listed here are only a subset of patch properties. For a complete list, see Patch Properties.

### `'FaceColor'` — Face color`[0 0 0]` (default) | RGB triplet or color string | `'flat'` | `'interp'` | `'none'`

Face color, specified as one of these values:

• RGB triplet or color string — Single color for all of the faces. See the following table for more details.

• `'flat'` — Uniform face colors. First, specify `CData` or `FaceVertexCData` as an array containing one color per face or one color per vertex. If you specify a color for each vertex, then the color of the first vertex specified determines the face color.

• `'interp'` — Interpolate the color across each face. First, specify `CData` or `FaceVertexCData` as an array containing one value per vertex. Determine the face colors by using a bilinear interpolation of the values at each vertex.

• `'none'` — No faces displayed.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range `[0,1]`, for example, `[0.4 0.6 0.7]`. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
`'yellow'``'y'``[1 1 0]`
`'magenta'``'m'``[1 0 1]`
`'cyan'``'c'``[0 1 1]`
`'red'``'r'``[1 0 0]`
`'green'``'g'``[0 1 0]`
`'blue'``'b'``[0 0 1]`
`'white'``'w'``[1 1 1]`
`'black'``'k'``[0 0 0]`

### `'FaceAlpha'` — Face transparency1 (default) | scalar in range `[0,1]` | `'flat'` | `'interp'`

Face transparency, specified as one of these values:

• Scalar in range `[0,1]` — Use uniform transparency across all of the faces. A value of `1` is fully opaque and `0` is completely transparent. This option does not use the transparency values in the `FaceVertexAlphaData` property.

• `'flat'` — Use a different transparency for each face based on the values in the `FaceVertexAlphaData` property. First you must specify the `FaceVertexAlphaData` property as a vector containing one transparency value per face or vertex. The transparency value at the first vertex determines the transparency for the entire face.

• `'interp'` — Use interpolated transparency for each face based on the values in `FaceVertexAlphaData` property. First you must specify the `FaceVertexAlphaData` property as a vector containing one transparency value per vertex. The transparency varies across each face by interpolating the values at the vertices.

### `'EdgeColor'` — Edge colors`[0 0 0]` (default) | `'none'` | `'flat'` | `'interp'` | RGB triplet or color string

Edge colors, specified as one of the values in this table. The default edge color is black with an RGB triplet value of ```[0 0 0]```. If multiple polygons share an edge, then the most recently drawn polygon controls the displayed edge color.

ValueDescriptionResult

RGB triplet or a color string

Single color for all of the edges. See the following table for more details.

`'flat'`

Different color for each edge. Use the vertex colors to set the color of the edge that follows it. You must first specify `CData` or `FaceVertexCData` as an array containing one color per vertex. The edge color depends on the order in which you specify the vertices.

`'interp'`

Interpolated edge color. You must first specify `CData` or `FaceVertexCData` as an array containing one color per vertex. Determine the edge color by linearly interpolating the values at the two bounding vertices.

`'none'`No edges displayed.

No edges displayed.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range `[0,1]`, for example, `[0.4 0.6 0.7]`. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
`'yellow'``'y'``[1 1 0]`
`'magenta'``'m'``[1 0 1]`
`'cyan'``'c'``[0 1 1]`
`'red'``'r'``[1 0 0]`
`'green'``'g'``[0 1 0]`
`'blue'``'b'``[0 0 1]`
`'white'``'w'``[1 1 1]`
`'black'``'k'``[0 0 0]`

### `'LineStyle'` — Line style`'-'` (default) | `'--'` | `':'` | `'-.'` | `'none'`

Line style, specified as one of the line style strings listed in this table.

StringLine StyleResulting Line
`'-'`Solid line

`'--'`Dashed line

`':'`Dotted line

`'-.'`Dash-dotted line

`'none'`No lineNo line

## Output Arguments

collapse all

### `p` — patch objectscalar

Patch object, returned as a scalar. Each patch object can consist of one or more polygons. Use `p` to query or change properties of the patch object after it is created.