## Syntax

`surface(Z) `

surface(Z,C)

surface(X,Y,Z)

surface(X,Y,Z,C)

surface(x,y,Z)

surface(...'`PropertyName`',PropertyValue,...)

h = surface(...)

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

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

`h = surface(...) ` returns
a handle to the created surface object.

## Examples

expand all

Plot the function
on the domain
and
. 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`.

## Setting Default Properties

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

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

where `Property` is the name of the
surface property whose default value you want to set and `PropertyValue` is
the value you are specifying. Use `set` and `get` to access the surface properties.

## More About

expand all

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

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 the `set` and `get` commands.

## See Also

`ColorSpec` | `patch` | `pcolor` | `surf` | `Surface Properties`