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