Documentation

### This is machine translation

Mouseover text to see original. Click the button below to return to the English version of the page.

# surface

Create surface object

## Syntax

```surface(Z) surface(Z,C) surface(X,Y,Z) surface(X,Y,Z,C) surface(x,y,Z) surface(...'PropertyName',PropertyValue,...) surface(ax,...) h = surface(...) ```

## Properties

For a list of properties, see Surface Properties.

## Description

`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. The values in `Z` can be numeric, datetime, duration, or categorical values.

`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`. The values in `X`, `Y`, and `Z` can be numeric, datetime, duration, or categorical values.

`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. The values in `x`, `y`, and `Z` can be numeric, datetime, duration, or categorical values.

`surface(...'PropertyName',PropertyValue,...) ` follows the `X`, `Y`, `Z`, and `C` arguments with property name/property value pairs to specify additional surface properties. For a description of the properties, see Surface Properties.

`surface(ax,...)` creates the surface in the axes specified by `ax` instead of in the current axes (`gca`). The option `ax` can precede any of the input argument combinations in the previous syntaxes.

`h = surface(...) ` returns a primitive surface object.

## Examples

collapse all

Plot the function $z=x{e}^{-{x}^{2}-{y}^{2}}$ on the domain $-2\le x\le 2$ and $-2\le y\le 2$. Use `meshgrid` to define `X` and `Y`. Then, define `Z` and create a surface plot. Change the view of the plot using `view`.

```[X,Y] = meshgrid(-2:0.2:2,-2:0.2:2); Z = X.*exp(-X.^2 - Y.^2); figure surface(X,Y,Z) view(3)``` `surface` creates the plot from corresponding values in `X`, `Y`, and `Z`. If you do not define the color data `C`, then `surface` uses `Z` to determine the color, so color is proportional to surface height.

Use the `peaks` function to define `XD`, `YD`, and `ZD` as 25-by-25 matrices.

`[XD,YD,ZD] = peaks(25);`

Load the `clown` data set to get the image data `X` and its associated colormap, `map`. Flip `X` using the `flipud` function and define the flipped image as the color data for the surface, `C`.

```load clown C = flipud(X);```

Create a surface plot and display the image along the surface. Since the surface data `ZD` and the color data `C` have different dimensions, you must set the surface `FaceColor` to `'texturemap'`.

```figure surface(XD,YD,ZD,C,... 'FaceColor','texturemap',... 'EdgeColor','none',... 'CDataMapping','direct') colormap(map) view(-35,45)``` The clown data is typically viewed with the `image` function, which uses `'ij'` axis numbering. This example reverses the image data in the vertical direction using `flipud`.

## Tutorials

For examples, see Representing Data as a Surface.

## Tips

`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 or using dot notation.

`surface` provides convenience forms that allow you to omit the property name for the `XData`, `YData`, `ZData`, and `CData` properties. For example,

```surface('XData',X,'YData',Y,'ZData',Z,'CData',C) ```

is equivalent to

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

When you specify only a single matrix input argument,

```surface(Z) ```

MATLAB assigns the data properties as if you specified

```surface('XData',[1:size(Z,2)],... 'YData',[1:size(Z,1)],... 'ZData',Z,... 'CData',Z) ```

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 dot notation.