surf
Surface plot
Description
surf(
creates a threedimensional surface plot, which is a threedimensional surface
that has solid edge colors and solid face colors. The function plots the values
in matrix X
,Y
,Z
)Z
as heights above a grid in the
xy plane defined by
X
and Y
. The color of the surface
varies according to the heights specified by Z
.
surf(
creates a surface plot and uses the column
and row indices of the elements in Z
)Z
as the
x and ycoordinates.
surf(
plots
into the axes specified by ax
,___)ax
instead of the current
axes. Specify the axes as the first input argument.
surf(___,
specifies surface
properties using one or more namevalue pair arguments. For example,
Name,Value
)'FaceAlpha',0.5
creates a semitransparent surface.
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
Create Surface Plot
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
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
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
byn
, then CO
is m
byn
by3. 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)
Modify Surface Plot Appearance
Create a semitransparent surface by specifying the FaceAlpha
namevalue 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
X
— xcoordinates
matrix  vector
xcoordinates, 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
xcoordinates.
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
— ycoordinates
matrix  vector
ycoordinates, 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
— zcoordinates
matrix
zcoordinates, specified as a matrix. Z
must have at
least two rows and two columns.
Z
specifies the height of the surface plot at each
xy 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
byn
by3
array of RGB triplets
Color array, specified as an m
byn
matrix of colormap indices or as an
m
byn
by3
array of RGB triplets, where Z
is
m
byn
.
To use colormap colors, specify
C
as a matrix. For each grid point on the surface,C
indicates a color in the colormap. TheCDataMapping
property of the surface object controls how the values inC
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.
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue 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')
creates
a semitransparent surface with no edges drawn.
Note
The properties listed here are only a subset. For a full list, see Surface Properties.
EdgeColor
— Edge line color
[0 0 0]
(default)  'none'
 'flat'
 'interp'
 RGB triplet  hexadecimal color code  'r'
 'g'
 'b'
 ...
Edge line color, specified as one of the values listed here.
The default color of [0 0 0]
corresponds to black
edges.
Value  Description 

'none'  Do not draw the edges. 
'flat'  Use a different color for each edge based on the values
in the 
'interp' 
Use interpolated coloring for each edge based on the values in the

RGB triplet, hexadecimal color code, or color name 
Use the specified color for all the edges. This option does not use the color
values in the

RGB triplets and hexadecimal color codes are useful for specifying custom colors.
An RGB triplet is a threeelement 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]
.A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (
#
) followed by three or six hexadecimal digits, which can range from0
toF
. The values are not case sensitive. Thus, the color codes"#FF8800"
,"#ff8800"
,"#F80"
, and"#f80"
are equivalent.
Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.
Color Name  Short Name  RGB Triplet  Hexadecimal Color Code  Appearance 

"red"  "r"  [1 0 0]  "#FF0000"  
"green"  "g"  [0 1 0]  "#00FF00"  
"blue"  "b"  [0 0 1]  "#0000FF"  
"cyan"
 "c"  [0 1 1]  "#00FFFF"  
"magenta"  "m"  [1 0 1]  "#FF00FF"  
"yellow"  "y"  [1 1 0]  "#FFFF00"  
"black"  "k"  [0 0 0]  "#000000"  
"white"  "w"  [1 1 1]  "#FFFFFF" 
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB^{®} uses in many types of plots.
RGB Triplet  Hexadecimal Color Code  Appearance 

[0 0.4470 0.7410]  "#0072BD"  
[0.8500 0.3250 0.0980]  "#D95319"  
[0.9290 0.6940 0.1250]  "#EDB120"  
[0.4940 0.1840 0.5560]  "#7E2F8E"  
[0.4660 0.6740 0.1880]  "#77AC30"  
[0.3010 0.7450 0.9330]  "#4DBEEE"  
[0.6350 0.0780 0.1840]  "#A2142F" 
LineStyle
— Line style
""
(default)  ""
 ":"
 "."
 "none"
Line style, specified as one of the options listed in this table.
Line Style  Description  Resulting Line 

""  Solid line 

""  Dashed line 

":"  Dotted line 

"."  Dashdotted line 

"none"  No line  No line 
FaceColor
— Face color
'flat'
(default)  'interp'
 'none'
 'texturemap'
 RGB triplet  hexadecimal color code  'r'
 'g'
 'b'
 ...
Face color, specified as one of the values in this table.
Value  Description 

'flat'  Use a different color for each face based on the values
in the 
'interp' 
Use interpolated coloring for each face based on the values in the

RGB triplet, hexadecimal color code, or color name 
Use the specified color for all the faces. This option does not use the color
values in the

'texturemap'  Transform the color data in CData so that
it conforms to the surface. 
'none'  Do not draw the faces. 
RGB triplets and hexadecimal color codes are useful for specifying custom colors.
An RGB triplet is a threeelement 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]
.A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (
#
) followed by three or six hexadecimal digits, which can range from0
toF
. The values are not case sensitive. Thus, the color codes"#FF8800"
,"#ff8800"
,"#F80"
, and"#f80"
are equivalent.
Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.
Color Name  Short Name  RGB Triplet  Hexadecimal Color Code  Appearance 

"red"  "r"  [1 0 0]  "#FF0000"  
"green"  "g"  [0 1 0]  "#00FF00"  
"blue"  "b"  [0 0 1]  "#0000FF"  
"cyan"
 "c"  [0 1 1]  "#00FFFF"  
"magenta"  "m"  [1 0 1]  "#FF00FF"  
"yellow"  "y"  [1 1 0]  "#FFFF00"  
"black"  "k"  [0 0 0]  "#000000"  
"white"  "w"  [1 1 1]  "#FFFFFF" 
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.
RGB Triplet  Hexadecimal Color Code  Appearance 

[0 0.4470 0.7410]  "#0072BD"  
[0.8500 0.3250 0.0980]  "#D95319"  
[0.9290 0.6940 0.1250]  "#EDB120"  
[0.4940 0.1840 0.5560]  "#7E2F8E"  
[0.4660 0.6740 0.1880]  "#77AC30"  
[0.3010 0.7450 0.9330]  "#4DBEEE"  
[0.6350 0.0780 0.1840]  "#A2142F" 
FaceAlpha
— Face transparency
1 (default)  scalar in range [0,1]
 'flat'
 'interp'
 'texturemap'
Face transparency, specified as one of these values:
Scalar in range
[0,1]
— Use uniform transparency across all the faces. A value of1
is fully opaque and0
is completely transparent. Values between0
and1
are semitransparent. This option does not use the transparency values in theAlphaData
property.'flat'
— Use a different transparency for each face based on the values in theAlphaData
property. The transparency value at the first vertex determines the transparency for the entire face. First you must specify theAlphaData
property as a matrix the same size as theZData
property. TheFaceColor
property also must be set to'flat'
.'interp'
— Use interpolated transparency for each face based on the values inAlphaData
property. The transparency varies across each face by interpolating the values at the vertices. First you must specify theAlphaData
property as a matrix the same size as theZData
property. TheFaceColor
property also must be set to'interp'
.'texturemap'
— Transform the data inAlphaData
so that it conforms to the surface.
FaceLighting
— Effect of light objects on faces
'flat'
 'gouraud'
 'none'
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.
Extended Capabilities
GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.
The surf
function
supports GPU array input with these 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
Properties
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:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
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
 United Kingdom (English)