surfl

Surface plot with colormap-based lighting

• 

Syntax

surfl(X,Y,Z)

surfl(Z)

surfl(___,'light')

surfl(___,s)

surfl(X,Y,Z,s,k)

surfl(___,Name=Value)

surfl(ax,___)

s = surfl(___)

Description

surfl(X,Y,Z) creates a three-dimensional surface plot with highlights from a light source. 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 uses the default direction for the light source and the default lighting coefficients for the shading model. This sets the color data for the surface to be the reflectance of the surface.

Because of the way surface-normal vectors are computed, surfl requires matrices that are at least 3-by-3.

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

surfl(___,'light') creates a surface with highlights from a MATLAB^® light object. This produces different results from the default colormap-based lighting method. Specify the 'light' object as the last input argument.

surfl(___,s) additionally specifies the direction of the light source.

surfl(X,Y,Z,s,k) additionally specifies the reflectance constant.

surfl(___,Name=Value) sets properties of the surface plot using one or more name-value arguments. For example, you can set the color and transparency of the surface. For a list of properties, see Surface Properties. (since R2024b)

surfl(ax,___) plots into the axes specified by ax instead of the current axes. Specify the axes as the first input argument.

s = surfl(___) returns the chart surface object. If the light source is specified as a light object using the 'light' option, then s is returned as a graphics array that includes the chart surface object and the light object. Use s to modify the surface and light object after it is created. For a list of properties, see Surface Properties and Light Properties.

Examples

Create Surface Plot With Colormap-Based Lighting

Create three matrices of the same size. Then plot them as a surface using colormap-based lighting. The surface uses Z for height and both Z and the light source for color.

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

Create Surface Plot With Light Object

Create three matrices of the same size. Then plot them as a surface with highlights from a MATLAB® light object. The surface uses Z for height and both Z and the light object for color. The function returns an array containing a surface object and a lighting object. Assign it to the variable sl.

[X,Y] = meshgrid(1:0.5:10,1:20);
Z = sin(X) + cos(Y);
sl = surfl(X,Y,Z,'light');

Index into sl to access and modify properties of the surface object and the light object after they are created. The surface plot is accessible as sl(1) and the light object as sl(2). For example, change the color of the light by setting the Color property of the light object.

sl(2).Color = 'r';

Specify Light Direction and Reflectance for Surface Plot

Create three matrices of the same size to plot as a surface. Specify the direction of the light source to have an azimuth of 45 degrees and an elevation of 20 degrees. Increase the reflectance of the surface by increasing the contribution of ambient light and decreasing the contibutions of diffused and specular reflection. Assign the surface object to the variable sl.

[X,Y] = meshgrid(1:0.5:10,1:20);
Z = sin(X) + cos(Y);
s = [-45 20];
k = [.65 .4 .3 10];

Plot the data using the source and reflectance vectors.

sl = surfl(X,Y,Z,s,k);

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

sl.EdgeColor = 'none';

Input Arguments

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, surfl 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

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, surfl 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

Z — z-coordinates

matrix

z-coordinates, specified as a matrix. Z must have at least two rows and two columns.

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

s — Direction to light source

two-element vector | three-element vector

Direction from the surface to the light source, specified as a two- or three-element vector. The vector has the form [sx sy sz] or [azimuth elevation]. The default direction is 45° counterclockwise from the current view direction.

k — Reflectance constant

[.55 .6 .4 10] (default) | four-element vector

Reflectance constant, specified as a four-element vector. The vector defines the relative contributions of ambient light, diffused reflection, specular reflection, and the specular shine coefficient using the form [ka kd ks shine]. By default, k is [.55 .6 .4 10].

ax — Axes to plot in

axes object

Axes to plot in, specified as an axes object. If you do not specify the axes, then surfl 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.

Example: surfl(peaks,FaceAlpha=0.5) plots a surface that is 50% transparent.

Note

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

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 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 interpolating the color values at the vertices. You cannot use this value when the FaceAlpha property is set to 'flat'.
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 CData property.
'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 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].

• 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 from 0 to F. 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 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.

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 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, hexadecimal color code, or color name	Use the specified color for all the edges. This option does not use the color values in the CData property.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

• 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].

• 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 from 0 to F. 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"

EdgeAlpha — Edge transparency

1 (default) | scalar value in range[0,1] | 'flat' | 'interp'

Edge transparency, specified as one of these values:

• Scalar in range [0,1] — Use uniform transparency across all of the edges. 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 edge based on the values in the AlphaData property. First you must specify the AlphaData property as a matrix the same size as the ZData property. The transparency value at the first vertex determines the transparency for the entire edge. The EdgeColor property also must be set to 'flat'.

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

Tips

• The ordering of points in the X, Y, and Z matrices defines the inside and outside of parametric surfaces. To have the opposite side of the surface reflect the light source, use surfl(X',Y',Z').

Extended Capabilities

GPU Arrays

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

The surfl 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

R2024b: Control appearance and behavior with name-value arguments

Control the appearance and behavior of surfaces by specifying name-value arguments. Previously, surfl did not support name-value arguments.