# Documentation

### This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

# surf

3-D shaded surface plot

## Syntax

`surf(Z)surf(Z,C)surf(X,Y,Z)surf(X,Y,Z,C)surf(...,'PropertyName',PropertyValue)surf(ax,...)h = surf(...)`

## Description

`surf(Z)` creates a three-dimensional shaded surface from the z components in matrix `Z`, using `x` `=` `1:n` and `y` `=` `1:m`, where `[m,n] = size(Z)`. The height, `Z`, is a single-valued function defined over a geometrically rectangular grid. `Z` specifies the color data, as well as surface height, so color is proportional to surface height. The values in `Z` can be numeric or datetime or duration values.

`surf(Z,C)` plots the height of `Z`, a single-valued function defined over a geometrically rectangular grid, and uses matrix `C`, assumed to be the same size as `Z`, to color the surface. See Coloring Mesh and Surface Plots for information on defining `C`.

`surf(X,Y,Z)` uses `Z` for the color data and surface height. `X` and `Y` are vectors or matrices defining the `x` and `y` components of a surface. If `X` and `Y` are vectors, `length(X)` `=` `n` and `length(Y)` `=` `m`, where `[m,n]` `=` `size(Z)`. In this case, the vertices of the surface faces are (X(j), Y(i), Z(i,j)) triples. To create X and Y matrices for arbitrary domains, use the `meshgrid` function. The values in `X`, `Y`, or `Z` can be numeric or datetime or duration values.

`surf(X,Y,Z,C)` uses `C` to define color. MATLAB® performs a linear transformation on this data to obtain colors from the current colormap.

`surf(...,'PropertyName',PropertyValue)` specifies surface properties along with the data. For a list of properties, see Chart Surface Properties.

`surf(ax,...)` plots into the axes `ax` instead of the current axes (`gca`).

`h = surf(...)` returns a handle to a chart surface graphics object.

## Examples

collapse all

Use the `peaks` function to define `X`, `Y`, and `Z` as 25-by-25 matrices. Then, create a surface plot.

```[X,Y,Z] = peaks(25); figure surf(X,Y,Z); ```

`surf` creates the surface plot from corresponding values in `X`, `Y`, and `Z`. If you do not define the color data `C`, then `surf` uses `Z` to determine the color, so color is proportional to surface height.

Create a sphere and color it using the pattern from a Hadamard matrix, which is a matrix that contains the values `1` and `-1`. Change the colors used in the plot by setting the colormap to an array of two RGB triplet values.

```k = 5; n = 2^k-1; [x,y,z] = sphere(n); c = hadamard(2^k); figure surf(x,y,z,c); colormap([1 1 0; 0 1 1]) axis equal ```

collapse all

### Tips

`surf` does not accept complex inputs.

### Algorithms

Consider a parametric surface parameterized by two independent variables, `i` and `j`, which vary continuously over a rectangle; for example, `1``i``m` and `1``j``n`. The three functions `x(i,j)`, `y(i,j)`, and `z(i,j)` specify the surface. When `i` and `j` are integer values, they define a rectangular grid with integer grid points. The functions `x(i,j)`, `y(i,j)`, and `z(i,j)` become three `m`-by-`n` matrices, `X`, `Y`, and `Z`. Surface color is a fourth function, `c(i,j)`, denoted by matrix `C`.

Each point in the rectangular grid can be thought of as connected to its four nearest neighbors.

``` i-1,j | i,j-1 - i,j - i,j+1 | i+1,j ```

This underlying rectangular grid induces four-sided patches on the surface. To express this another way, `[X(:)` `Y(:)` `Z(:)]` returns a list of triples specifying points in 3-D space. Each interior point is connected to the four neighbors inherited from the matrix indexing. Points on the edge of the surface have three neighbors. The four points at the corners of the grid have only two neighbors. This defines a mesh of quadrilaterals or a quad-mesh.

You can specify surface color in two different ways: at the vertices or at the centers of each patch. In this general setting, the surface need not be a single-valued function of `x` and `y`. Moreover, the four-sided surface patches need not be planar. For example, you can have surfaces defined in polar, cylindrical, and spherical coordinate systems.

The `shading` function sets the shading. If the shading is `interp`, `C` must be the same size as `X`, `Y`, and `Z`; it specifies the colors at the vertices. The color within a surface patch is a bilinear function of the local coordinates. If the shading is `faceted` (the default) or `flat`, `C(i,j) `specifies the constant color in the surface patch:

``` (i,j) - (i,j+1) | C(i,j) | (i+1,j) - (i+1,j+1) ```

In this case, `C` can be the same size as `X`, `Y`, and `Z` and its last row and column are ignored. Alternatively, its row and column dimensions can be one less than those of `X`, `Y`, and `Z`.

The `surf` function specifies the viewpoint using `view(3)`.

The range of `X`, `Y`, and `Z` or the current setting of `XLimMode`, `YLimMode`, and `ZLimMode` axes properties determines the axis labels. You can also set these properties using `axis` function.

The range of `C` or the current setting of the `CLim` and `CLimMode` axes properties determines the color scaling. You can also set the properties using `caxis` function. The scaled color values are indices into the current colormap.