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

Create Surface Plot

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.

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.

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.