# surf, surfc

## Synopsis

````surf(X,Y,Z,C)`
`surf(X,Y,Z)`
`surf(x,y,Z,C)`
`surf(x,y,Z)`
`surf(Z,C)`
`surf(Z)`
`h = surf(...)`
`h = surfc(...)`
```

## Description

In its most general invocation, `surf` takes four matrix input arguments. `surf(X,Y,Z,C)` plots the colored parametric surface specified by `X`, `Y`, and `Z`, with color specified by `C`. In simpler uses, `X` and `Y` may be vectors, or may be omitted, and `C` may be omitted.

The viewpoint is specified by `view`. The axis labels are determined by the range of `X`, `Y`, and `Z`, or by the current setting of `axis`. The color scaling is determined by the range of `C`, or by the current setting of `caxis`. The scaled color values are used as indices into the current colormap.

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

`surf(x,y,Z,C)` and `surf(x,y,Z)` 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.

`surf(Z,C)` and `surf(Z)` 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.

`h = surf(...)` returns a handle to a `surface` object. `surface` objects are children of `axes` objects.

`surfc(...)` is the same as `surf(...)` except that a contour plot is drawn beneath the surface.

## Algorithm

Abstractly, a parametric surface is parametrized by two independent variables, `i` and `j`, which vary continuously over a rectangle, for example, `1 <= i <= m` and `1 <= j <= n`. The surfaces are specified by three functions, `x(i,j)`, `y(i,j)` and `z(i,j)`. When `i` and `j` are restricted to 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)`, which leads to a fourth 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-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 and the four points at the corners of the grid have only two neighbors. This defines a mesh of quadrilaterals or quad-mesh for short.

Surface color can be specified 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, surfaces defined in polar, cylindrical, and spherical coordinates systems can be represented.

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

```` (i,j)   -   (i,j+1)`
`   |    C(i,j)  |`
`(i+1,j)  -  (i+1,j+1)`
```
In this case, `C` can have the same size as `X`, `Y`, and `Z` and its last row and column are ignored, or its row and column dimensions can be one less than those of `X`, `Y`, and `Z`.

## Examples

Produce a combination surface and contour plot of the `peaks` surface.

````[X,Y] = meshgrid(-3:.125:3);`
`Z = peaks(X,Y);`
`surfc(X,Y,Z)`

```
A more complex example colors a sphere with the pattern of +1 and -1s in a Hadamard matrix.

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

```

````axis`, `caxis`, `colormap`, `contour`, `mesh`, `pcolor`, `shading`, `view`
`axes`, `figure`, and `surface` object properties