Documentation

This is machine translation

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

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

surf

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. The function plots the values in matrix Z as heights above a grid in the x-y plane defined by X and Y. The function also uses Z for the color data, so color is proportional to height.

example

surf(X,Y,Z,C) additionally specifies the surface color.

surf(Z) creates a surface and uses the row and column indices of the elements in Z as the x and y coordinates.

surf(Z,C) additionally specifies the surface color.

surf(ax,___) plots into the axes specified by ax instead of the current axes. 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. Specify name-value pairs after all other input arguments.

example

s = surf(___) returns the chart surface object. Use s to modify the surface after it is created. For a list, see Chart Surface Properties.

Examples

collapse all

Create X, Y, and Z as matrices of the same size. Then plot the data as a surface. The surface uses Z for both the height and color data.

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

Specify the colors for a surface plot by including a fourth matrix input, C. Use colormap colors by specifying C as a matrix the same size as Z. Add a colorbar to the graph to show how the data values in C map 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 the colors for a surface plot by including a fourth matrix input, CO. Use true colors by creating CO as an m-by-n-by-3 array of RGB triplet values, where Z is m-by-n. 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); % red
CO(:,:,2) = ones(25).*linspace(0.5,0.6,25); % green
CO(:,:,3) = ones(25).*linspace(0,1,25); % blue
surf(X,Y,Z,CO)

Create a semitransparent surface by setting the FaceAlpha property as a name-value pair argument. 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: [21×21 double]
           YData: [21×21 double]
           ZData: [21×21 double]
           CData: [21×21 double]

  Show all properties

Use s to access and modify properties of the surface object after it is created. For example, turn off the display of the edges by setting the EdgeColor property.

s.EdgeColor = 'none';

Input Arguments

collapse all

x coordinates, specified as a matrix the same size as Z or as a vector with length n, where [m,n] = size(Z). To create a matrix for arbitrary domains, use the meshgrid function.

The XData property of the surface object stores the x values.

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

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | categorical | datetime | duration

y coordinates, specified as a matrix the same size as Z or as a vector with length m, where [m,n] = size(Z). To create a matrix for arbitrary domains, use the meshgrid function.

The YData property of the surface object stores the y values.

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

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | categorical | datetime | duration

z coordinates, specified as a matrix. If you do not specify the colors, then Z also sets the surface colors.

The ZData property of the surface object stores the z values.

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

Color for each vertex, specified as a matrix the same size as Z or as an m-by-n-by-3 array of RGB triplets, where Z is m-by-n.

  • If you want to use colormap colors, then specify C as a matrix. The CDataMapping property of the surface object controls how the values in C map to colors in the colormap.

  • If you want to use true colors, then specify C as an array of RGB triplets.

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

Axes in which to plot, specified as an axes object. If you do not specify the axes, then surf plots into the current axes.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: surf(X,Y,Z,'FaceAlpha',0.5,'EdgeColor','none') creates a semitransparent surface with no edges drawn.

collapse all

Edge line color, specified as one of the values listed here. The default color of [0 0 0] corresponds to black edges.

ValueDescription
'none'Do not draw the edges.
'flat'

Use a different color for each edge based on the values in the CData property. First you must specify the CData property as a matrix the same size as ZData. The color value at the first vertex of each face (in the positive x and y directions) determines the color for the adjacent edges. You cannot use this value when the EdgeAlpha property is set to 'interp'.

'interp'Use interpolated coloring for each edge based on the values in the CData property. First you must specify the CData property as a matrix the same size as ZData. The color varies across each edge by linearly interpolating the color values at the vertices. You cannot use this value when the EdgeAlpha property is set to 'flat'.

RGB triplet or color nameUse the specified color for all the edges. This option does not use the color values in the CData property.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. This table lists the long and short color name options and the equivalent RGB triplet values.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black''k'[0 0 0]

Line style, specified as one of the line styles listed in this table.

Line StyleDescriptionResulting Line
'-'Solid line

'--'Dashed line

':'Dotted line

'-.'Dash-dotted line

'none'No lineNo line

Face color, specified as one of the values in this table.

ValueDescription
'flat'

Use a different color for each face based on the values in the CData property. First you must specify the CData property as a matrix the same size as ZData. The color value at the first vertex of each face (in the positive x and y directions) determines the color for the entire face. You cannot use this value when the FaceAlpha property is set to 'interp'.

'interp'Use interpolated coloring for each face based on the values in the CData property. First you must specify the CData property as a matrix the same size as ZData. The color varies across each face by bilinearly interpolating the color values at the vertices. You cannot use this value when the FaceAlpha property is set to 'flat'.

RGB triplet or color nameUse the specified color for all the faces. This option does not use the color values in the CData property.

'texturemap'Transform the color data in CData so that it conforms to the surface.
'none'Do not draw the faces.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. This table lists the long and short color name options and the equivalent RGB triplet values.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black''k'[0 0 0]

Face transparency, specified as one of these values:

  • Scalar in range [0,1] — Use uniform transparency across all the faces. A value of 1 is fully opaque and 0 is completely transparent. Values between 0 and 1 are semitransparent. This option does not use the transparency values in the AlphaData property.

  • 'flat' — Use a different transparency for each face based on the values in the AlphaData property. The transparency value at the first vertex determines the transparency for the entire face. First you must specify the AlphaData property as a matrix the same size as the ZData property. The FaceColor property also must be set to 'flat'.

  • 'interp' — Use interpolated transparency for each face based on the values in AlphaData property. The transparency varies across each face by interpolating the values at the vertices. First you must specify the AlphaData property as a matrix the same size as the ZData property. The FaceColor property also must be set to 'interp'.

  • 'texturemap' — Transform the data in AlphaData so that it conforms to the surface.

Effect of light objects on faces, specified as one of these values:

  • 'flat' — Apply light uniformly across each face. Use this value to view faceted objects.

  • 'gouraud' — Vary the light across the faces. Calculate the light at the vertices and then linearly interpolate the light across the faces. Use this value to view curved surfaces.

  • 'none' — Do not apply light from light objects to the faces.

To add a light object to the axes, use the light function.

    Note:   The 'phong' value has been removed. Use 'gouraud' instead.

Introduced before R2006a

Was this topic helpful?