surfl

具有基于颜色图的光照的曲面图

全页折叠

语法

surfl(X,Y,Z)

surfl(Z)

surfl(___,'light')

surfl(___,s)

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

surfl(___,Name=Value)

surfl(ax,___)

s = surfl(___)

说明

surfl(X,Y,Z) 创建一个带光源高光的三维曲面图。该函数将矩阵 Z 中的值绘制为由 X 和 Y 定义的 x-y 平面中的网格上方的高度。该函数使用光源的默认方向和着色模型的默认光照系数。这会将曲面的颜色数据设置为曲面的反射颜色。

由于曲面法向量的计算方式的原因，surfl 需要大小至少为 3×3 的矩阵。

示例

surfl(Z) 创建曲面，并将 Z 中元素的列索引和行索引用作 x 坐标和 y 坐标。

surfl(___,'light') 创建一个由 MATLAB^® 光源对象提供高光的曲面。这与默认的基于颜色图的光照方法产生的结果不同。将 'light' 对象指定为最后一个输入参量。

示例

surfl(___,s) 还指定光源的方向。

示例

surfl(X,Y,Z,s,k) 还指定反射常量。

示例

surfl(___,Name=Value) 使用一个或多个名称-值参量设置曲面图的属性。例如，您可以设置曲面的颜色和透明度。有关属性列表，请参阅 Surface 属性。 (自 R2024b 起)

surfl(ax,___) 将图形绘制到 ax 指定的坐标区中，而不是当前坐标区中。指定坐标区作为第一个输入参量。

s = surfl(___) 将返回一个图曲面对象。如果使用 'light' 选项将光源指定为光源对象，则 s 将以图形数组形式返回，其中包含图曲面对象和光源对象。在创建曲面和光源对象后，可使用 s 对其进行修改。有关属性列表，请参阅 Surface 属性和 Light 属性。

示例

全部折叠

创建具有基于颜色图的光照的曲面图

打开实时脚本

创建三个相同大小的矩阵。然后使用基于颜色图的光照将它们绘制为一个曲面。曲面使用 Z 表示高度，并同时使用 Z 和光源两者来定义颜色。

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

Figure contains an axes object. The axes object contains an object of type surface.

使用光源对象创建曲面图

打开实时脚本

创建三个相同大小的矩阵。然后将它们绘制为带有来自 MATLAB® 光源对象的高光的曲面。曲面使用 Z 表示高度，并同时使用 Z 和光源对象两者来定义颜色。该函数返回包含曲面对象和光照对象的数组。将它赋值给变量 sl。

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

Figure contains an axes object. The axes object contains an object of type surface.

对 sl 进行索引，以访问和修改所创建的曲面对象和光源对象的属性。可通过 sl(1) 访问曲面图，通过 sl(2) 访问光源对象。例如，通过设置光源对象的 Color 属性来更改光源颜色。

sl(2).Color = 'r';

Figure contains an axes object. The axes object contains an object of type surface.

指定曲面图的光源方向和反射

打开实时脚本

创建三个大小相同的矩阵以绘制为一个曲面。指定光源的方向，使方位角为 45 度，仰角为 20 度。通过增加环境光贡献度和减少漫反射与镜面反射贡献度来提高曲面的反射值。将曲面对象赋给变量 sl。

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

使用光源向量和反射向量绘制数据。

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

Figure contains an axes object. The axes object contains an object of type surface.

在创建曲面对象之后可使用 sl 访问并修改其属性。例如，通过设置 EdgeColor 属性来隐藏边。

sl.EdgeColor = 'none';

Figure contains an axes object. The axes object contains an object of type surface.

输入参数

全部折叠

`X` — x 坐标
矩阵 | 向量

x 坐标，指定为大小与 Z 相同的矩阵或长度为 n 的向量，其中 [m,n] = size(Z)。如果未指定 X 和 Y 的值，surfl 将使用向量 (1:n) 和 (1:m)。

您可以使用 meshgrid 函数创建 X 和 Y 矩阵。

Surface 对象的 XData 属性存储 x 坐标。

示例: X = 1:10

示例: X = [1 2 3; 1 2 3; 1 2 3]

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

`Y` — y 坐标
矩阵 | 向量

y 坐标，指定为大小与 Z 相同的矩阵或长度为 m 的向量，其中 [m,n] = size(Z)。如果未指定 X 和 Y 的值，surfl 将使用向量 (1:n) 和 (1:m)。

您可以使用 meshgrid 函数创建 X 和 Y 矩阵。

曲面对象的 YData 属性存储 y 坐标。

示例: Y = 1:10

示例: Y = [1 1 1; 2 2 2; 3 3 3]

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

`Z` — z 坐标
矩阵

z 坐标，指定为矩阵。Z 必须有至少两行两列。

曲面对象的 ZData 属性存储 z 坐标。

示例: Z = [1 2 3; 4 5 6]

示例: Z = sin(x) + cos(y)

`s` — 光源方向
二元素向量 | 三元素向量

从曲面到光源的方向，指定为一个二元素或三元素向量。该向量的形式为 [sx sy sz] 或 [azimuth elevation]。默认方向是从当前视图方向逆时针旋转 45° 的角。

`k` — 反射常量
`[.55 .6 .4 10]` (默认) | 四元素向量

反射常量，指定为一个四元素向量。该向量以 [ka kd ks shine] 的形式定义环境光、漫反射、镜面反射和镜面发光系数的相对贡献度。默认情况下，k 为 [.55 .6 .4 10]。

`ax` — 绘图所用的坐标区
坐标区对象

要在其中绘图的坐标区，指定为 axes 对象。如果未指定坐标区，则 surfl 在当前坐标区中绘图。

名称-值参数

全部折叠

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但参量对组的顺序无关紧要。

示例: surfl(peaks,FaceAlpha=0.5) 绘制透明度为 50% 的曲面。

注意

此处所列的属性只是一部分。有关完整列表，请参阅 Surface 属性。

`FaceColor` — 面颜色
`'flat'` (默认) | `'interp'` | `'none'` | `'texturemap'` | RGB 三元组 | 十六进制颜色代码 | `'r'` | `'g'` | `'b'` | ...

面颜色，指定为下表中的值之一。

值	描述
`'flat'`	根据 `CData` 属性中的值，对每个面使用不同的颜色。首先您必须将 `CData` 属性指定为矩阵，大小与 `ZData` 相同。每个面的第一个顶点（正 x 和 y 方向）的颜色值决定整个面的颜色。当 `FaceAlpha` 属性设置为 `'interp'` 时，不能使用此值。
`'interp'`	根据 `CData` 属性中的值，对每个面使用插补着色。首先您必须将 `CData` 属性指定为矩阵，大小与 `ZData` 相同。通过基于各顶点处颜色值进行插值，每个面上的颜色会渐变。当 `FaceAlpha` 属性设置为 `'flat'` 时，不能使用此值。
RGB 三元组、十六进制颜色代码或颜色名称	对所有面使用指定的颜色。此选项不会使用 `CData` 属性中的颜色值。
`'texturemap'`	变换 `CData` 中的颜色数据，以便其符合曲面。
`'none'`	不绘制面。

RGB 三元组和十六进制颜色代码对于指定自定义颜色非常有用。

RGB 三元组是包含三个元素的行向量，其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内，例如 [0.4 0.6 0.7]。
十六进制颜色代码是字符向量或字符串标量，以井号 (#) 开头，后跟三个或六个十六进制数字，范围可以是 0 到 F。这些值不区分大小写。因此，颜色代码 "#FF8800" 与 "#ff8800"、"#F80" 与 "#f80" 是等效的。

此外，还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。

颜色名称	短名称	RGB 三元组	十六进制颜色代码
`"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"`

下表列出了浅色和深色主题中绘图的默认调色板。

调色板调色板颜色

调色板	调色板颜色
`"gem"` - 浅色主题默认值在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。
`"glow"` - 深色主题默认值

"gem" - 浅色主题默认值

在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。

Sample of the "gem" color palette

"glow" - 深色主题默认值

Sample of the "glow" color palette

您可以使用 orderedcolors 和 rgb2hex 函数获取这些调色板的 RGB 三元组和十六进制颜色代码。例如，获取 "gem" 调色板的 RGB 三元组并将其转换为十六进制颜色代码。

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

在 R2023b 之前的版本中: 使用 RGB = get(groot,"FactoryAxesColorOrder") 获取 RGB 三元组。

在 R2024a 之前的版本中: 使用 H = compose("#%02X%02X%02X",round(RGB*255)) 获取十六进制颜色代码。

`FaceAlpha` — 面透明度
1 (默认) | 范围 `[0,1]` 中的标量 | `'flat'` | `'interp'` | `'texturemap'`

面透明度，指定为下列值之一：

范围 [0,1] 中的标量 - 在所有面上使用统一的透明度。值为 1 时完全不透明，值为 0 时完全透明。介于 0 和 1 之间的值表示半透明。此选项不会使用 AlphaData 属性中的透明度值。
'flat' - 根据 AlphaData 属性中的值，对每个面使用不同的透明度。第一个顶点的透明度值确定整个面的透明度。首先您必须将 AlphaData 属性指定为矩阵，大小与 ZData 属性相同。FaceColor 属性也必须设置为 'flat'。
'interp' - 根据 AlphaData 属性中的值，对每个面使用插值透明度。通过基于各顶点处透明度数值进行插值，每个面上的透明度会渐变。首先您必须将 AlphaData 属性指定为矩阵，大小与 ZData 属性相同。FaceColor 属性也必须设置为 'interp'。
'texturemap' - 变换 AlphaData 中的数据，以便其符合曲面。

`EdgeColor` — 边缘线条颜色
`'none'` | `'flat'` | `'interp'` | RGB 三元组 | 十六进制颜色代码 | `'r'` | `'g'` | `'b'` | ...

边线颜色，指定为下面列出的值之一。默认颜色 [0 0 0] 对应于黑边。

值	描述
`'none'`	不绘制边。
`'flat'`	根据 `CData` 属性中的值，对每个边使用不同的颜色。首先您必须将 `CData` 属性指定为矩阵，大小与 `ZData` 相同。每个面（正的 x 和 y 方向）的第一个顶点处的颜色值确定相邻边的颜色。当 `EdgeAlpha` 属性设置为 `'interp'` 时，不能使用此值。
`'interp'`	根据 `CData` 属性中的值，对每个边使用插补着色。首先您必须将 `CData` 属性指定为矩阵，大小与 `ZData` 相同。通过基于各顶点处颜色值进行线性插值，每条边上的颜色会渐变。当 `EdgeAlpha` 属性设置为 `'flat'` 时，不能使用此值。
RGB 三元组、十六进制颜色代码或颜色名称	对所有边使用指定的颜色。此选项不会使用 `CData` 属性中的颜色值。

RGB 三元组和十六进制颜色代码对于指定自定义颜色非常有用。

RGB 三元组是包含三个元素的行向量，其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内，例如 [0.4 0.6 0.7]。
十六进制颜色代码是字符向量或字符串标量，以井号 (#) 开头，后跟三个或六个十六进制数字，范围可以是 0 到 F。这些值不区分大小写。因此，颜色代码 "#FF8800" 与 "#ff8800"、"#F80" 与 "#f80" 是等效的。

此外，还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。

颜色名称	短名称	RGB 三元组	十六进制颜色代码
`"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"`

下表列出了浅色和深色主题中绘图的默认调色板。

调色板调色板颜色

调色板	调色板颜色
`"gem"` - 浅色主题默认值在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。
`"glow"` - 深色主题默认值

"gem" - 浅色主题默认值

在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。

Sample of the "gem" color palette

"glow" - 深色主题默认值

Sample of the "glow" color palette

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

在 R2023b 之前的版本中: 使用 RGB = get(groot,"FactoryAxesColorOrder") 获取 RGB 三元组。

在 R2024a 之前的版本中: 使用 H = compose("#%02X%02X%02X",round(RGB*255)) 获取十六进制颜色代码。

`EdgeAlpha` — 边透明度
1 (默认) | 范围 `[0,1]` 中的标量值 | `'flat'` | `'interp'`

边透明度，指定为下列值之一：

[0,1] 范围内的标量 - 在所有边上都使用统一的透明度。值为 1 时完全不透明，值为 0 时完全透明。介于 0 和 1 之间的值表示半透明。此选项不会使用 AlphaData 属性中的透明度值。
'flat' - 根据 AlphaData 属性中的值，对每个边使用不同透明度。首先您必须将 AlphaData 属性指定为矩阵，大小与 ZData 属性相同。第一个顶点上的透明度值确定整条边的透明度。EdgeColor 属性也必须设置为 'flat'。
'interp' - 根据 AlphaData 属性中的值，对每个边使用插值透明度。首先您必须将 AlphaData 属性指定为矩阵，大小与 ZData 属性相同。通过基于各顶点处值进行插值，每条边上的透明度会渐变。EdgeColor 属性也必须设置为 'interp'。

提示

X、Y 和 Z 矩阵中点的排序定义参数曲面的内部和外部。要让曲面的另一侧反射光源，请使用 surfl(X',Y',Z')。

扩展功能

全部展开

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

surfl 函数支持 GPU 数组输入，但有以下用法说明和限制：

此函数接受 GPU 数组，但不在 GPU 上运行。

有关详细信息，请参阅在 GPU 上运行 MATLAB 函数 (Parallel Computing Toolbox)。

分布式数组
使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

用法说明和限制：

此函数在分布式数组上运行，但在客户端 MATLAB 中执行。

有关详细信息，请参阅使用分布式数组运行 MATLAB 函数 (Parallel Computing Toolbox)。

版本历史记录

在 R2006a 之前推出

全部展开

R2024b: 用名称-值参量控制外观和行为

通过指定名称-值参量来控制曲面的外观和行为。以前，surfl 不支持名称-值参量。

另请参阅

函数

colormap | shading | light | imagesc | meshgrid | view | pcolor | surf

属性

Surface 属性 | Light 属性

surfl

语法

说明

示例

创建具有基于颜色图的光照的曲面图

使用光源对象创建曲面图

指定曲面图的光源方向和反射

输入参数

X — x 坐标 矩阵 | 向量

Y — y 坐标 矩阵 | 向量

Z — z 坐标 矩阵

s — 光源方向 二元素向量 | 三元素向量

k — 反射常量 [.55 .6 .4 10] (默认) | 四元素向量

ax — 绘图所用的坐标区 坐标区对象

名称-值参数

FaceColor — 面颜色 'flat' (默认) | 'interp' | 'none' | 'texturemap' | RGB 三元组 | 十六进制颜色代码 | 'r' | 'g' | 'b' | ...

FaceAlpha — 面透明度 1 (默认) | 范围 [0,1] 中的标量 | 'flat' | 'interp' | 'texturemap'

EdgeColor — 边缘线条颜色 'none' | 'flat' | 'interp' | RGB 三元组 | 十六进制颜色代码 | 'r' | 'g' | 'b' | ...

EdgeAlpha — 边透明度 1 (默认) | 范围 [0,1] 中的标量值 | 'flat' | 'interp'

提示

扩展功能

GPU 数组 通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

分布式数组 使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

版本历史记录

R2024b: 用名称-值参量控制外观和行为

另请参阅

函数

属性

主题

`X` — x 坐标
矩阵 | 向量

`Y` — y 坐标
矩阵 | 向量

`Z` — z 坐标
矩阵

`s` — 光源方向
二元素向量 | 三元素向量

`k` — 反射常量
`[.55 .6 .4 10]` (默认) | 四元素向量

`ax` — 绘图所用的坐标区
坐标区对象

`FaceColor` — 面颜色
`'flat'` (默认) | `'interp'` | `'none'` | `'texturemap'` | RGB 三元组 | 十六进制颜色代码 | `'r'` | `'g'` | `'b'` | ...

`FaceAlpha` — 面透明度
1 (默认) | 范围 `[0,1]` 中的标量 | `'flat'` | `'interp'` | `'texturemap'`

`EdgeColor` — 边缘线条颜色
`'none'` | `'flat'` | `'interp'` | RGB 三元组 | 十六进制颜色代码 | `'r'` | `'g'` | `'b'` | ...

`EdgeAlpha` — 边透明度
1 (默认) | 范围 `[0,1]` 中的标量值 | `'flat'` | `'interp'`

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

分布式数组
使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。