MATLAB Function Reference
surface

Create surface object

Syntax

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

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,

• ```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.

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.

• ```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`

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.

• ```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.

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 matrixDefault: `[]` 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: scalarDefault: `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 pointsDefault: 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 handleDefault: `'' `(empty string) `CreateFcn` Defines a callback routine that executes when an surface is created Values: string or function handleDefault: `'' `(empty string) `DeleteFcn` Defines a callback routine that executes when the surface is deleted (via `close` or `delete`) Values: string or function handleDefault: `'' `(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 matrixDefault:` [] `(empty matrix)

 surf2patch Surface Properties