Surface plot

collapse all in page

## Syntax

`surf(X,Y,Z)`

`surf(X,Y,Z,C)`

`surf(Z)`

`surf(Z,C)`

`surf(ax,___)`

`surf(___,Name,Value)`

`s = surf(___)`

## Description

example

`surf(X,Y,Z)`

creates a three-dimensional surface plot, which is a three-dimensional surface that has solid edge colors and solid face colors. The function plots the values in matrix `Z`

as heights above a grid in the *x*-*y* plane defined by `X`

and `Y`

. The color of the surface varies according to the heights specified by `Z`

.

example

`surf(X,Y,Z,C)`

additionallyspecifies the surface color.

`surf(Z)`

creates a surface plot and uses the column and row indices of the elements in `Z`

as the *x*- and *y*-coordinates.

`surf(Z,C)`

additionallyspecifies the surface color.

`surf(ax,___)`

plotsinto the axes specified by `ax`

instead of the currentaxes. Specify the axes as the first input argument.

example

`surf(___,Name,Value)`

specifies surface properties using one or more name-value pair arguments. For example, `'FaceAlpha',0.5`

creates a semitransparent surface.

example

`s = surf(___)`

returns the chart surface object. Use `s`

to modify the surface after it is created. For a list of properties, see Surface Properties.

## Examples

collapse all

### Create Surface Plot

Open Live Script

Create three matrices of the same size. Then plot them as a surface. The surface plot uses `Z`

for both height and color.

[X,Y] = meshgrid(1:0.5:10,1:20);Z = sin(X) + cos(Y);surf(X,Y,Z)

### Specify Colormap Colors for Surface Plot

Open Live Script

Specify the colors for a surface plot by including a fourth matrix input, `C`

. The surface plot uses `Z`

for height and `C`

for color. Specify the colors using a *colormap*, which uses single numbers to stand for colors on a spectrum. When you use a colormap, `C`

is the same size as `Z`

. Add a color bar to the graph to show how the data values in `C`

correspond to the colors in the colormap.

[X,Y] = meshgrid(1:0.5:10,1:20);Z = sin(X) + cos(Y);C = X.*Y;surf(X,Y,Z,C)colorbar

### Specify True Colors for Surface Plot

Open Live Script

Specify the colors for a surface plot by including a fourth matrix input, `CO`

. The surface plot uses `Z`

for height and `CO`

for color. Specify the colors using *truecolor*, which uses triplets of numbers to stand for all possible colors. When you use truecolor, if `Z`

is `m`

-by-`n`

, then `CO`

is `m`

-by-`n`

-by-3. The first page of the array indicates the red component for each color, the second page indicates the green component, and the third page indicates the blue component.

[X,Y,Z] = peaks(25);CO(:,:,1) = zeros(25); % redCO(:,:,2) = ones(25).*linspace(0.5,0.6,25); % greenCO(:,:,3) = ones(25).*linspace(0,1,25); % bluesurf(X,Y,Z,CO)

### Modify Surface Plot Appearance

Open Live Script

Create a semitransparent surface by specifying the `FaceAlpha`

name-value pair with `0.5`

as the value. To allow further modifications, assign the surface object to the variable `s`

.

`[X,Y] = meshgrid(-5:.5:5);Z = Y.*sin(X) - X.*cos(Y);s = surf(X,Y,Z,'FaceAlpha',0.5)`

s = Surface with properties: EdgeColor: [0 0 0] LineStyle: '-' FaceColor: 'flat' FaceLighting: 'flat' FaceAlpha: 0.5000 XData: [21x21 double] YData: [21x21 double] ZData: [21x21 double] CData: [21x21 double] Use GET to show all properties

Use `s`

to access and modify properties of the surface object after it is created. For example, hide the edges by setting the `EdgeColor`

property.

`s.EdgeColor = 'none';`

## Input Arguments

collapse all

`X`

— *x*-coordinates

matrix | vector

*x*-coordinates, specified as a matrix the same size as `Z`

, or as a vector with length `n`

, where `[m,n] = size(Z)`

. If you do not specify values for `X`

and `Y`

, `surf`

uses the vectors `(1:n)`

and `(1:m)`

.

You can use the meshgrid function to create `X`

and `Y`

matrices.

The `XData`

property of the `Surface`

object stores the *x*-coordinates.

**Example: **`X = 1:10`

**Example: **`X = [1 2 3; 1 2 3; 1 2 3]`

**Example: **`[X,Y] = meshgrid(-5:0.5:5)`

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `categorical`

| `datetime`

| `duration`

`Y`

— *y*-coordinates

matrix | vector

*y*-coordinates, specified as a matrix the same size as `Z`

or as a vector with length `m`

, where `[m,n] = size(Z)`

. If you do not specify values for `X`

and `Y`

, `surf`

uses the vectors `(1:n)`

and `(1:m)`

.

You can use the meshgrid function to create the `X`

and `Y`

matrices.

The `YData`

property of the surface object stores the *y* -coordinates.

**Example: **`Y = 1:10`

**Example: **`Y = [1 1 1; 2 2 2; 3 3 3]`

**Example: **`[X,Y] = meshgrid(-5:0.5:5)`

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `categorical`

| `datetime`

| `duration`

`Z`

— *z*-coordinates

matrix

*z*-coordinates, specified as a matrix. `Z`

must have at least two rows and two columns.

`Z`

specifies the height of the surface plot at each *x*-*y* coordinate. If you do not specify the colors, then `Z`

also specifies the surface colors.

The `ZData`

property of the surface object stores the *z* -coordinates.

**Example: **`Z = [1 2 3; 4 5 6]`

**Example: **`Z = sin(x) + cos(y)`

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `categorical`

| `datetime`

| `duration`

`C`

— Color array

matrix | `m`

-by-`n`

-by-`3`

array of RGB triplets

Color array, specified as an `m`

-by-`n`

matrix of colormap indices or as an `m`

-by-`n`

-by-`3`

array of RGB triplets, where `Z`

is `m`

-by-`n`

.

To use colormap colors, specify

`C`

as a matrix. For each grid point on the surface,`C`

indicates a color in the colormap. The`CDataMapping`

property of the surface object controls how the values in`C`

correspond to colors in the colormap.To use truecolor colors, specify

`C`

as an array of RGB triplets.

For more information, see Differences Between Colormaps and Truecolor.

The `CData`

property of the surface object stores the color array. For additional control over the surface coloring, use the FaceColor and EdgeColor properties.

`ax`

— Axes to plot in

axes object

Axes to plot in, specified as an `axes`

object. If you do not specify the axes, then `surf`

plots into the current axes.

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`

, where `Name`

is the argument name and `Value`

is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

* Before R2021a, use commas to separate each name and value, and enclose* `Name`

*in quotes.*

**Example: **`surf(X,Y,Z,'FaceAlpha',0.5,'EdgeColor','none')`

createsa semitransparent surface with no edges drawn.

**Note**

The properties listed here are only a subset. For a full list,see Surface Properties.

## Extended Capabilities

### GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

This function accepts GPU arrays, but does not run on a GPU.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

### Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

This function operates on distributed arrays, but executes in the client MATLAB.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

## Version History

**Introduced before R2006a**

## See Also

### Functions

- colormap | pcolor | meshgrid | imagesc | shading | view | mesh

### Properties

- Surface Properties

### Topics

- Representing Data as a Surface
- How Surface Plot Data Relates to a Colormap

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- Deutsch
- English
- Français

- United Kingdom (English)

Contact your local office