## SURF Surface Plot Function

Section: Handle-Based Graphics

### Usage

This routine is used to create a surface plot of data. A surface plot is a 3D surface defined by the xyz coordinates of its vertices and optionally by the color at the vertices. The most general syntax for the `surf` function is
```  h = surf(X,Y,Z,C,properties...)
```

Where `X` is a matrix or vector of `x` coordinates, `Y` is a matrix or vector of `y` coordinates, `Z` is a 2D matrix of coordinates, and `C` is a 2D matrix of color values (the colormap for the current fig is applied). In general, `X` and `Y` should be the same size as `Z`, but FreeMat will expand vectors to match the matrix if possible. If you want the color of the surface to be defined by the height of the surface, you can omit `C`

```  h = surf(X,Y,Z,properties...)
```

in which case `C=Z`. You can also eliminate the `X` and `Y` matrices in the specification

```  h = surf(Z,properties)
```

in which case they are set to `1:size(Z,2)` and `1:size(Y,2)` respectively. You can also specify a handle as the target of the `surf` command via

```  h = surf(handle,...)
```

### Example

Here we generate a surface specifying all four components.
```--> x = repmat(linspace(-1,1),[100,1]);
--> y = x';
--> r = x.^2+y.^2;
--> z = exp(-r*3).*cos(5*r);
--> c = r;
--> surf(x,y,z,c)
--> axis equal
--> view(3)
Warning: Newly defined variable xlim shadows a function of the same name.  Use clear xlim to recover access to the function
Warning: Newly defined variable ylim shadows a function of the same name.  Use clear ylim to recover access to the function
Warning: Newly defined variable zlim shadows a function of the same name.  Use clear zlim to recover access to the function
```

If we allow FreeMat to specify the color component, we see that the colorfield is the same as the height

```--> surf(x,y,z)
--> axis equal
--> view(3)
Warning: Newly defined variable xlim shadows a function of the same name.  Use clear xlim to recover access to the function
Warning: Newly defined variable ylim shadows a function of the same name.  Use clear ylim to recover access to the function
Warning: Newly defined variable zlim shadows a function of the same name.  Use clear zlim to recover access to the function
```