surface

Purpose

Create surface object.

Synopsis

surface(X,Y,Z,C)
surface(X,Y,Z)
surface(Z,C)
surface(Z)
surface('PropertyName',PropertyValue,....)
h = surface(...)

Description

surface is a low-level graphics function for creating surface objects. Surface objects are children of axes objects. A surface is a plot of a matrix of data with the element index representing the x- and y- coordinates and the value of each element representing either a height above a plane or an index into the colormap. surface returns the handle of the surface object.

surface accepts property name/property value pairs as input arguments. These properties, which control various aspects of the surface object, are described under "Object Properties." You can also set and query property values after the object is created using the set and get commands.

Unlike high level surface generation functions such as surf or mesh, surface does not clear the axes, set viewing parameters, or perform any actions other than to generate a surface object in the current axes. This is useful if you want to add a surface to existing axes or to tailor the way surfaces are drawn by controlling its properties at creation time. The axis, caxis, colormap, hold, shading, and view commands set graphics properties that affect surface.

surface also provides convenient forms that allow you to omit the property name for certain properties. For example, the following statements are equivalent:

surface('XData',X,'YData',Y,'ZData',Z,'CData',C)
surface(X,Y,Z,C)
surface(X,Y,Z,C) plots the parametric surface specified by X, Y and Z, with color specified by C. In simpler uses, X and Y can be vectors or can be omitted, and C can be omitted. The X and Y arguments can be followed by property name/property value pairs to specify additional surface properties.

surface(X,Y,Z) uses C = Z, so color is proportional to surface height.

surface(x,y,Z) and h = surface(x,y,Z,C), with two vector arguments replacing the first two matrix arguments, must have length(x) = n and length(y) = m where [m,n] = size(Z). In this case, the vertices of the surface patches 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.

surface(Z) and surf(Z,C) use x = 1:n and y = 1:m. In this case, the height, Z, is a single-valued function, defined over a geometrically rectangular grid.

surface('PropertyName',PropertyValue,....) omits the matrix arguments entirely and specifies all values using property name/property value pairs.

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

For a complete discussion of parametric surfaces, see the surf reference page.

Object Properties

This section lists property names along with the type of values each accepts.

ButtonDownFcn
Callback string, object selection.
Any legal MATLAB expression, including the name of an M-file or function. When you select the object, the string is passed to the eval function to execute the specified function. Initially the empty matrix.
CData
Color data.
A matrix of values that specifies the color at every point in ZData. However, CData does not need to be the same size as ZData. If it is not, MATLAB treats it as a texture map. In this case, the image contained in CData is made to conform the surface defined by ZData.
Children
Children of surface.
Always the empty matrix; surface objects have no children.
Clipping
Clipping mode.
on (Default.) Any portion of the surface outside the axes rectangle is not displayed.
off Surface data is not clipped.
EdgeColor
Surface edge color.
ColorSpec A three-element RGB vector or one of MATLAB's predefined names, specifying a single color for edges. The default edge color is black. See the ColorSpec reference page for more information on specifying color.
none Edges are not drawn.
flat Edges are a single color determined by the first CData entry for that face.
interp Edge color is determined by linear interpolation through the values at the vertices.
EraseMode
Erase mode.
This property controls the technique MATLAB uses to draw and erase surface objects. This property is useful in creating animated sequences, where control of individual object redraw is necessary to improve performance and obtain the desired effect.
normal (Default.) Redraws the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and are therefore less accurate.
none The surface is not erased when it is moved or destroyed.
xor The surface is drawn and erased by performing an exclusive OR (XOR) with the color of the screen beneath it. When the surface is erased, it does not damage the objects beneath it. Surface objects are dependent on the color of the screen beneath them, however, and are correctly colored only when over the figure background color.
background The surface is erased by drawing it in the figure's background color. This damages objects that are behind the erased surface, but surface objects are always properly colored.
FaceColor
Surface face color.
ColorSpec A three-element RGB vector or one of MATLAB's predefined names, specifying a single color for faces. See the ColorSpec reference page for more information on specifying color.
none Faces are not drawn. You can still draw edges, however.
flat (Default.) The first value in CData determines face color.
interp Face color is determined by linear interpolation through the mesh points on the surface.
Interruptible
Callback interruptibility.
yes The callback specified by ButtonDownFcn is interruptible by other callbacks.
no (Default.) The ButtonDownFcn callback is not interruptible.
LineStyle
Edge line style.
This property determines the type of line for edges. Specify a linestyle to be plotted through the mesh points or a scalable marker type to be placed only at mesh points:
  • Line styles: solid (-), dashed (- -), dotted (:), dashdot (-.).
  • Marker types: circle (o), plus (+), point (.), star (*), x-mark (x).
    The default line style is solid.
    • LineWidth
    Edge line width.
    The line width for edges. The default width is 0.5.
    MarkerSize
    Marker scale factor.
    A scalar specifying the scale factor, in points, for edge line markers. This applies only to the marker types circle, plus, point, star, and x-mark. The default marker size is 6 points.
    MeshStyle
    Draw row/column lines.
    both (Default.) Draw all edges (lines for both rows and columns).
    row Draw row edges only.
    column Draw column edges only.
    Parent
    Handle of the surface's parent object.
    A read-only property that contains the handle of the surface's parent object. The parent of a surface object is the axes in which it is displayed.
    Type
    Type of object.
    A read-only string; always 'surface' for a surface object.
    UserData
    User-specified data.
    Any matrix you want to associate with the surface object. The object does not use this data, but you can retrieve it using the get command.
    Visible
    Surface visibility.
    on (Default.) Surface is visible on the screen.
    off Surface is not drawn.
    XData
    X-coordinates of surface points.
    X-position of the surface points. If a row vector, surface replicates the row until XData has the same number of rows as ZData.
    YData
    Y-coordinates of surface points.
    Y-position of the surface points. If a column vector, surface replicates the column until YData has the same number of columns as ZData.
    ZData
    Z-coordinates of surface points.
    Z-position of the surface points. See the "Description" section for more information.

    See Also

     mesh, pcolor, surf

    (c) Copyright 1994 by The MathWorks, Inc.