MATLAB Function Reference |

**Syntax**

surface(Z) surface(Z,C) surface(X,Y,Z) surface(X,Y,Z,C) surface(...'

*PropertyName*',PropertyValue,...) h = surface(...)

`surface`

is the low-level function for creating surface graphics objects. Surfaces are plots of matrix data created using the row and column indices of each element as the *x*- and *y*-coordinates and the value of each element as the *z*-coordinate.

```
surface(Z)
```

plots the surface specified by the matrix `Z`

. Here, `Z`

is a single-valued function, defined over a geometrically rectangular grid.

```
surface(Z,C)
```

plots the surface specified by `Z`

and colors it according to the data in `C`

(see "Examples").

```
surface(X,Y,Z)
```

uses `C`

`=`

`Z`

, so color is proportional to surface height above the *x*-*y* plane.

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

plots the parametric surface specified by `X`

, `Y`

, and `Z`

, with color specified by `C`

.

```
surface(x,y,Z), surface(x,y,Z,C)
```

replaces the first two matrix arguments with vectors and must have `length(x) = n`

and `length(y) = m`

where `[m,n] = size(Z)`

. In this case, the vertices of the surface facets are the triples `(x(j),y(i),Z(i,j))`

. Note that `x`

corresponds to the columns of `Z`

and `y`

corresponds to the rows of `Z`

. For a complete discussion of parametric surfaces, see the `surf`

function.

`surface(...'`

follows the

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

, `Y`

, `Z`

, and `C`

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

```
h = surface(...)
```

returns a handle to the created surface object.

**Remarks**

`surface`

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

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

If you do not specify separate color data (`C`

), MATLAB uses the matrix (`Z`

) to determine the coloring of the surface. In this case, color is proportional to values of `Z`

. You can specify a separate matrix to color the surface independently of the data defining the area of the surface.

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

and `get`

for examples of how to specify these data types).

`surface`

provides convenience forms that allow you to omit the property name for the `XData`

, `YData`

, `ZData`

, and `CData`

properties. For example,

When you specify only a single matrix input argument,

MATLAB assigns the data properties as if you specified

The `axis`

, `caxis`

, `colormap`

, `hold`

, `shading`

, and `view`

commands set graphics properties that affect surfaces. You can also set and query surface property values after creating them using the `set`

and `get`

commands.

**Example**

This example creates a surface using the `peaks`

M-file to generate the data, and colors it using the clown image. The `ZData`

is a 49-by-49 element matrix, while the `CData`

is a 200-by-320 matrix. You must set the surface's `FaceColor`

to `texturemap`

to use `ZData`

and `CData`

of different dimensions.

load clown surface(peaks,flipud(X),... 'FaceColor','texturemap',... 'EdgeColor','none',... 'CDataMapping','direct') colormap(map) view(-35,45)

Note the use of the `surface(Z,C)`

convenience form combined with property name/property value pairs.

Since the clown data (`X`

) is typically viewed with the `image`

command, which MATLAB normally displays with `'ij' `

axis numbering and `direct CDataMapping`

, this example reverses the data in the vertical direction using `flipud`

and sets the `CDataMapping`

property to `direct`

.

**Object Hierarchy**

**Setting Default Properties**

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

set(0,'DefaultSurface

*Property*',PropertyValue...) set(gcf,'DefaultSurface*Property*',PropertyValue...) set(gca,'DefaultSurface*Property*',PropertyValue...)

where

is the name of the surface property whose default value you want to set and *Property*`PropertyValue`

is the value you are specifying. Use `set`

and `get`

to access the surface properties.

**See Also**

`ColorSpec`

, `patch`

, `pcolor`

, `surf`

Properties for surface graphics objects

Repersenting a Matrix as a Surface for examples

Creating Surfaces and Meshes and Object Creation Functions for related functions

Surface Properties for property descriptions

surf2patch | Surface Properties |

© 1994-2005 The MathWorks, Inc.