MATLAB Function Reference |

**Syntax**

patch(X,Y,C) patch(X,Y,Z,C) patch(FV) patch(...'

*PropertyName*',PropertyValue...) patch('*PropertyName*',PropertyValue...) PN/PV pairs only handle = patch(...)

**Description**

`patch`

is the low-level graphics function for creating patch graphics objects. A patch object is one or more polygons defined by the coordinates of its vertices. You can specify the coloring and lighting of the patch. See Creating 3-D Models with Patches for more information on using patch objects.

```
patch(X,Y,C)
```

adds the filled two-dimensional patch to the current axes. The elements of `X`

and `Y`

specify the vertices of a polygon. If `X`

and `Y`

are matrices, MATLAB draws one polygon per column. `C`

determines the color of the patch. It can be a single `ColorSpec`

, one color per face, or one color per vertex (see "Remarks"). If C is a 1-by-3 vector, it is assumed to be an RGB triplet, specifying a color directly.

```
patch(X,Y,Z,C)
```

creates a patch in three-dimensional coordinates.

```
patch(FV)
```

creates a patch using structure `FV`

, which contains the fields `vertices`

, `faces`

, and optionally `facevertexdata`

. These fields correspond to the `Vertices`

, `Faces`

, and `FaceVertexCData`

patch properties.

`patch(...'`

follows the *PropertyName*',PropertyValue...)
`X`

, `Y`

, `(Z)`

, and `C`

arguments with property name/property value pairs to specify additional patch properties.

`patch('`

specifies all properties using property name/property value pairs. This form enables you to omit the color specification because MATLAB uses the default face color and edge color unless you explicitly assign a value to the *PropertyName*',PropertyValue,...)
`FaceColor`

and `EdgeColor`

properties. This form also allows you to specify the patch using the `Faces`

and `Vertices`

properties instead of *x*-, *y*-, and *z*-coordinates. See the "Examples" section for more information.

```
handle = patch(...)
```

returns the handle of the patch object it creates.

**Remarks**

Unlike high-level area creation functions, such as `fill`

or `area`

, `patch`

does not check the settings of the figure and axes `NextPlot`

properties. It simply adds the patch object to the current axes.

If the coordinate data does not define closed polygons, `patch`

closes the polygons. The data can define concave or intersecting polygons. However, if the edges of an individual patch face intersect themselves, the resulting face may or may not be completely filled. In that case, it is better to break up the face into smaller polygons.

**Specifying Patch Properties**

You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see the `set`

and `get`

reference pages for examples of how to specify these data types).

There are two patch properties that specify color:

`CData`

-- Use when specifying*x*-,*y*-, and*z*-coordinates (`XData`

,`YData`

,`ZData`

).`FaceVertexCData`

-- Use when specifying vertices and connection matrix (`Vertices`

and`Faces`

).

The `CData`

and `FaceVertexCData`

properties accept color data as indexed or true color (RGB) values. See the `CData`

and `FaceVertexCData`

property descriptions for information on how to specify color.

Indexed color data can represent either direct indices into the colormap or scaled values that map the data linearly to the entire colormap (see the `caxis`

function for more information on this scaling). The `CDataMapping`

property determines how MATLAB interprets indexed color data.

**Color Data Interpretation**

You can specify patch colors as

- A single color for all faces
- One color for each face, enabling flat coloring
- One color for each vertex, enabling interpolated coloring

The following tables summarize how MATLAB interprets color data defined by the `CData`

and `FaceVertexCData`

properties.

**Interpretation of the CData Property**

**
**

**Examples**

This example creates a patch object using two different methods:

- Specifying
*x*-,*y*-, and*z*-coordinates and color data (`XData`

,`YData`

,`ZData`

, and`CData`

properties) - Specifying vertices, the connection matrix, and color data (
`Vertices`

,`Faces`

,`FaceVertexCData`

, and`FaceColor`

properties)

**Specifying X, Y, and Z Coordinates**

The first approach specifies the coordinates of each vertex. In this example, the coordinate data defines two triangular faces, each having three vertices. Using true color, the top face is set to white and the bottom face to gray.

x = [0 0;0 1;1 1]; y = [1 1;2 2;2 1]; z = [1 1;1 1;1 1]; tcolor(1,1,1:3) = [1 1 1]; tcolor(1,2,1:3) = [.7 .7 .7]; patch(x,y,z,tcolor)

Notice that each face shares two vertices with the other face (V_{1}-V_{4} and V_{3}-V_{5}).

**Specifying Vertices and Faces**

The `Vertices`

property contains the coordinates of each *unique* vertex defining the patch. The `Faces`

property specifies how to connect these vertices to form each face of the patch. For this example, two vertices share the same location so you need to specify only four of the six vertices. Each row contains the *x**-*, *y**-*, and *z*-coordinates of each vertex.

There are only two faces, defined by connecting the vertices in the order indicated.

To specify the face colors, define a 2-by-3 matrix containing two RGB color definitions.

With two faces and two colors, MATLAB can color each face with flat shading. This means you must set the `FaceColor`

property to `flat`

, since the faces/vertices technique is available only as a low-level function call (i.e., only by specifying property name/property value pairs).

Create the patch by specifying the `Faces`

, `Vertices`

, and `FaceVertexCData`

properties as well as the `FaceColor`

property.

Specifying only unique vertices and their connection matrix can reduce the size of the data for patches having many faces. See the descriptions of the `Faces`

, `Vertices`

, and `FaceVertexCData`

properties for information on how to define them.

MATLAB does not require each face to have the same number of vertices. In cases where they do not, pad the `Faces`

matrix with `NaNs`

. To define a patch with faces that do not close, add one or more `NaNs`

to the row in the `Vertices`

matrix that defines the vertex you do not want connected.

**Object Hierarchy**

**Setting Default Properties**

You can set default patch properties on the axes, figure, and root levels:

set(0,'DefaultPatch

*PropertyName*',PropertyValue...) set(gcf,'DefaultPatch*PropertyName*',PropertyValue...) set(gca,'DefaultPatch*PropertyName*',PropertyValue...)

is the name of the patch property and *PropertyName*`PropertyValue`

is the value you are specifying. Use `set`

and `get`

to access patch properties.

**See Also**

`area`

, `caxis`

, `fill`

, `fill3`

, `isosurface`

, `surface`

Object Creation Functions for related functions

Patch Properties for property descriptions

Creating 3-D Models with Patches for examples that use patches

pascal | Patch Properties |

© 1994-2005 The MathWorks, Inc.