MATLAB Function Reference | Search  Help Desk |
surface | Examples See Also |
surface(Z) surface(Z,C) surface(X,Y,Z) surface(X,Y,Z,C) surface(...'PropertyName',PropertyValue,...) h = surface(...)
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,C)
plots the parametric surface specified by X
, Y
and Z
, with color specified by C
.
surface(X,Y,Z)
uses C
=
Z
, so color is proportional to surface height above the x-y plane.
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.
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,
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.
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.
load clown surface(peaks,flipud(X),... 'FaceColor','texturemap',... 'EdgeColor','none',... 'CDataMapping','direct') colormap(map) view(-35,45)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
.
ColorSpec
, mesh
, patch
, pcolor
, surf
Setting Default Properties
You can set default Surface properties on the Axes, Figure, and Root 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.
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 |
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 |
Composit 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 |
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 propertyDefault: 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 |
Wpecifies 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 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 | ||
|
Specify how to handle callback routine interruption |
Values: cancel , queue Default: queue |
|
Define a callback routine that executes when a mouse button is pressed on over the Surface |
Values: string Default: '' (empty string) |
|
Define a callback routine that executes when an Surface is created |
Values: string Default: '' (empty string) |
|
Define a callback routine that executes when the Surface is deleted (via close or delete ) |
Values: string Default: '' (empty string) |
|
Determine if callback routine can be interrupted |
Values: on , off Default: on (can be interrupted) |
|
Associate a context menu with the Surface |
Values: handle of a Uicontrextmenu |
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 |
Indicate 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' |
|
User-specified data |
Values: any matrix Default: [] (empty matrix) |