MATLAB Function Reference    
surface

Create surface object

Syntax

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. These properties are described in the "Surface Properties" section.

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

Remarks

Unlike high-level area creation functions, such as surf or mesh, 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,

is equivalent to:

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.

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.

See Also

ColorSpec, mesh, patch, pcolor, surf

Properties for surface graphics objects

Creating Surfaces and Meshes and Object Creation Functions for related functions

Object Hierarchy

Setting Default Properties

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

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.

Property List

The following table lists all surface properties and provides a brief description of each. The property name links take you to an expanded description of the properties.

Property Name
Property Description
Property Value
Data Defining the Object
XData
The x-coordinates of the vertices of the surface
Values: vector or matrix
YData
The y-coordinates of the vertices of the surface
Values: vector or matrix
ZData
The z-coordinates of the vertices of the surface
Values: matrix
Specifying Color
CData
Color data
Values: scalar, vector, or matrix
Default: [] empty matrix
CDataMapping
Controls mapping of CData to colormap
Values: scaled, direct
Default: scaled
EdgeColor
Color of face edges
Values: ColorSpec, none, flat, interp
Default: ColorSpec
FaceColor
Color of face
Values: ColorSpec, none, flat, interp
Default: ColorSpec
MarkerEdgeColor
Color of marker or the edge color for filled markers
Values: ColorSpec, none, auto
Default: auto
MarkerFaceColor
Fill color for markers that are closed shapes
Values: ColorSpec, none, auto
Default: none
Specifying Transparency


AlphaData
The transparency data
m-by-n matrix of double or uint8
AlphaDataMapping
Transparency mapping method
none, direct, scaled
Default: scaled
EdgeAlpha
Transparency of the edges of patch faces
scalar, flat, interp
Default: 1 (opaque)
FaceAlpha
Transparency of the patch face
scalar, flat, interp, texture
Default: 1 (opaque)
Controlling the Effects of Lights
AmbientStrength
Intensity of the ambient light
Values: scalar >=0 and <=1
Default: 0.3
BackFaceLighting
Controls lighting of faces pointing away from camera
Values: unlit, lit, reverselit
Default: reverselit
DiffuseStrength
Intensity of diffuse light
Values: scalar >=0 and <=1
Default: 0.6
EdgeLighting
Method used to light edges
Values: none, flat, gouraud, phong
Default: none
FaceLighting
Method used to light edges
Values: none, flat, gouraud, phong
Default: none
NormalMode
MATLAB-generated or user-specified normal vectors
Values: auto, manual
Default: auto
SpecularColorReflectance
Composite color of specularly reflected light
Values: scalar 0 to 1
Default: 1
SpecularExponent
Harshness of specular reflection
Values: scalar >= 1
Default: 10
SpecularStrength
Intensity of specular light
Values: scalar >=0 and <=1
Default: 0.9
VertexNormals
Vertex normal vectors
Values: matrix
Defining Edges and Markers
LineStyle
Linestyle of the edge. Select from five line styles.
Values: -, --, :, -., none
Default: -
LineWidth
The width of the edge in points
Values: scalar
Default: 0.5 points
Marker
Marker symbol to plot at data points
Values: see Marker property
Default: none
MarkerSize
Size of marker in points
Values: size in points
Default: 6
Controlling the Appearance
Clipping
Clipping to axes rectangle
Values: on, off
Default: on
EraseMode
Method of drawing and erasing the surface (useful for animation)
Values: normal, none, xor, background
Default: normal
MeshStyle
Specifies whether to draw all edge lines or just row or column edge lines
Values: both, row, column
Defaults: both
SelectionHighlight
Highlight surface when selected (Selected property set to on)
Values: on, off
Default: on
Visible
Make the surface visible or invisible
Values: on, off
Default: on
Controlling Access to Objects
HandleVisibility
Determines if and when the surface's handle is visible to other functions
Values: on, callback, off
Default: on
HitTest
Determines if the surface can become the current object (see the figure CurrentObject property)
Values: on, off
Default: on
Properties Related to Callback Routine Execution
BusyAction
Specifies how to handle callback routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
Defines a callback routine that executes when a mouse button is pressed on over the surface
Values: string or function handle
Default: '' (empty string)
CreateFcn
Defines a callback routine that executes when an surface is created
Values: string or function handle
Default: '' (empty string)
DeleteFcn
Defines a callback routine that executes when the surface is deleted (via close or delete)
Values: string or function handle
Default: '' (empty string)
Interruptible
Determines if callback routine can be interrupted
Values: on, off
Default: on (can be interrupted)
UIContextMenu
Associates a context menu with the surface
Values: handle of a uicontextmenu
General Information About the Surface
Children
Surface objects have no children
Values: [] (empty matrix)
Parent
The parent of a surface object is always an axes object
Value: axes handle
Selected
Indicates whether the surface is in a "selected" state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read only)
Value: the string 'surface'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)


  surf2patch Surface Properties