Accelerating the pace of engineering and science

# Documentation Center

• Trial Software

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

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

### Create Surface Plot

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.

### Display Image Along Surface Plot

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,'DefaultSurfaceProperty',PropertyValue...)
set(gcf,'DefaultSurfaceProperty',PropertyValue...)
set(gca,'DefaultSurfaceProperty',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.

## Tutorials

For examples, see Representing a Matrix as a Surface.

expand all

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