Matplotlib 函数手册：3D 绘图

Matplotlib 的三维绘图并不是一套独立系统而是在原有 Figure、Axes 与子图机制上的扩展。三维图仍沿用标题、坐标轴标签与布局调整等基本框架只是绘图对象从二维平面延伸到了三维空间。在较新的 Matplotlib 版本中只要使用 projection3d 创建坐标轴通常不必再显式导入 Axes3D。但从概念上说三维坐标轴对象仍然属于 mplot3d 提供的 Axes3D 体系。注本文只对三维绘图中独有或特别关键的函数参数进行说明。一、三维坐标轴创建函数三维图形的前提是先创建三维坐标轴。add_subplot(..., projection3d)在 Figure 对象中添加一个三维子图并返回对应的三维 Axes 对象。ax fig.add_subplot(nrows, ncols, index, projection3d)参数说明• projection3d指定当前子图为三维投影坐标轴若省略该参数则创建的是普通二维子图返回值返回一个三维 Axes 对象通常记作 ax。示例import matplotlib.pyplot as plt fig plt.figure(figsize(6, 4))ax fig.add_subplot(111, projection3d) plt.show()说明这是一种非常常见、也较清晰的三维坐标轴创建方式。它保留了 Matplotlib 一贯的“先创建图形再在图形中添加子图”的结构。axes(projection3d)用于创建一个三维坐标区域。ax plt.axes(projection3d)也可与位置参数一起使用ax plt.axes([left, bottom, width, height], projection3d)参数说明• projection3d指定创建三维坐标轴返回值返回一个三维 Axes 对象。示例import matplotlib.pyplot as plt ax plt.axes(projection3d)plt.show()说明plt.axes() 在二维绘图中也可以使用但在三维绘图中必须明确加上 projection3d否则得到的仍然是二维坐标轴。subplots()一次性创建 Figure 和一个或多个 Axes 对象。fig, ax plt.subplots(nrows1, ncols1, figsizeNone, subplot_kw{projection: 3d})参数说明• subplot_kw传递给每个子图的关键字参数。在三维绘图中通常写为 {projection: 3d}用于指定创建三维坐标轴subplots() 的完整接口还包含 sharex、sharey、squeeze、gridspec_kw、**fig_kw 等参数。返回值返回一个元组• figFigure 对象表示整张画布• ax 或 axs子图对象当创建的是三维子图时这里得到的是三维坐标轴对象示例import matplotlib.pyplot as plt fig, axs plt.subplots( 1, 2, figsize(10, 4), subplot_kw{projection: 3d}) axs[0].set_title(3D Subplot 1)axs[1].set_title(3D Subplot 2) plt.show()说明subplots() 的优势在于能够一次性完成画布与子图的创建写法紧凑特别适合规则的单图或多子图布局。不过在三维绘图的教学中很多示例仍常写成“先 plt.figure()再 fig.add_subplot(..., projection3d)”的形式因为这种写法更容易体现三维坐标轴是如何附加到 Figure 上的。二、三维基础绘图函数与二维图形不同这一组函数需要处理空间中的点、线、面或立体对象。scatter()用于绘制三维散点图展示离散点在三维空间中的分布情况。ax.scatter(xs, ys, zs0, zdirz, sNone, cNone, depthshadeTrue, **kwargs)参数说明• zs第三维坐标数据即各点的 z 值• zdir指定第三维所对应的方向默认是 z• depthshade是否启用深度阴影效果用于增强空间层次感返回值返回一个 PathCollection 对象。示例import matplotlib.pyplot as pltimport numpy as np np.random.seed(42)x np.random.rand(50)y np.random.rand(50)z np.random.rand(50) fig plt.figure()ax fig.add_subplot(111, projection3d)ax.scatter(x, y, z) plt.show()说明与二维散点图相比三维散点图多了 z 方向因此每个点由 (x, y, z) 三个值共同确定。它适合观察三维点云分布、聚类结构或三个变量之间的空间关系。plot()用于绘制三维折线图也可理解为在三维空间中绘制连续轨迹。ax.plot(xs, ys, zs, **kwargs)参数说明• zs第三维坐标数据。在 3D 坐标轴中第三维数据通常作为第三组位置参数传入返回值返回一个由线对象组成的列表。示例import matplotlib.pyplot as pltimport numpy as np t np.linspace(0, 10 * np.pi, 500)x np.cos(t)y np.sin(t)z t fig plt.figure()ax fig.add_subplot(111, projection3d)ax.plot(x, y, z) plt.show()说明三维折线图常用于绘制空间轨迹例如螺旋线、参数曲线或路径变化过程。从本质上说它仍然是“按顺序连接数据点”只是连接发生在三维空间中。plot_surface()用于绘制三维曲面图是三维绘图中最重要的函数之一。它通常用来展示二元函数的整体形状或某个平面区域上的高度变化。ax.plot_surface(X, Y, Z, *, normNone, vminNone, vmaxNone, lightsourceNone, axlim_clipFalse, **kwargs)参数说明• X、Y网格坐标矩阵• Z与 X、Y 对应的高度矩阵• rcount行方向参与绘制的最大采样数默认 50• ccount列方向参与绘制的最大采样数默认 50• cmap颜色映射方案用于根据高度显示不同颜色viridisMatplotlib 默认的常用渐变色颜色层次清楚适合大多数连续数据plasma由深紫到亮黄色彩对比更强inferno由深色到亮黄整体偏暖色调magma由深紫到浅黄视觉较柔和cividis对比平稳适合强调可读性coolwarm冷暖对比明显适合表现正负变化或中心对称数据jet早期较常见但颜色跳跃较大一般不作为首选rainbow彩虹渐变视觉鲜艳但不太适合严肃的数据表达• edgecolor曲面网格边界颜色None不显示边界线曲面更平滑black 或 k黑色边界线网格结构更清楚white 或 w白色边界线适合深色曲面gray灰色边界线效果较柔和其它合法颜色名如 red、blue、green 等• rstride行方向采样步长• cstride列方向采样步长• linewidth网格线宽• antialiased是否启用抗锯齿• alpha透明度返回值返回一个 Poly3DCollection 对象。示例import matplotlib.pyplot as pltimport numpy as np x np.linspace(-5, 5, 100)y np.linspace(-5, 5, 100)X, Y np.meshgrid(x, y)Z np.sin(np.sqrt(X**2 Y**2)) fig plt.figure()ax fig.add_subplot(111, projection3d)ax.plot_surface(X, Y, Z, cmapviridis, edgecolornone) plt.show()说明plot_surface() 与散点图、折线图不同它要求输入数据通常是二维网格结构。因此在使用前往往需要先通过 np.meshgrid() 构造 X、Y 网格再计算对应的 Z 值。plot_surface() 默认会通过 rcount 和 ccount 控制每个方向参与绘制的最大采样数默认均为 50也可以改用 rstride、cstride 指定步长。对于网格非常密集的数据这一机制有助于控制绘图开销。plot_wireframe()用于绘制三维线框图。ax.plot_wireframe(X, Y, Z, **kwargs)参数说明• X、Y、Z二维数组表示曲面上各点的坐标• rcount、ccount每个方向上用于绘制的最大采样数默认均为 50• rstride、cstride行和列的步长可用于控制线框稀疏程度• color线框颜色• linewidth线宽• axlim_clip是否裁剪坐标轴范围外的线框默认 False。返回值返回一个 Line3DCollection 对象。示例import matplotlib.pyplot as pltimport numpy as np fig plt.figure(figsize(8, 6))ax fig.add_subplot(111, projection3d) x np.linspace(-5, 5, 50)y np.linspace(-5, 5, 50)X, Y np.meshgrid(x, y)Z np.sin(np.sqrt(X**2 Y**2)) ax.plot_wireframe(X, Y, Z, colorblue, linewidth0.6)ax.set_title(3D Wireframe)ax.set_xlabel(X)ax.set_ylabel(Y)ax.set_zlabel(Z) plt.show()说明plot_wireframe() 与 plot_surface() 类似都用于展示曲面形状不同的是线框图更强调网格结构本身适合观察曲面的整体轮廓与起伏变化。官方文档还说明若输入数据点过多函数会按 rcount 和 ccount 自动下采样。plot_trisurf()用于绘制基于三角剖分的三维曲面图。ax.plot_trisurf(*args, colorNone, **kwargs)参数说明plot_trisurf() 的参数形式比 plot_surface() 更灵活常见写法有两类第一类直接传入三角剖分对象ax.plot_trisurf(triangulation, Z, ...)第二类直接传入点坐标ax.plot_trisurf(X, Y, Z, ...)常用参数包括• X、Y、Z曲面点坐标• triangles三角形顶点索引• cmap颜色映射方案• color整体颜色• linewidth边界线宽• antialiased是否抗锯齿• axlim_clip是否裁剪坐标轴范围外的内容。返回值返回一个 Poly3DCollection 对象。示例import matplotlib.pyplot as pltimport numpy as np # 固定随机种子便于复现np.random.seed(42) # 构造平面上的不规则散点x np.random.uniform(-4, 4, 200)y np.random.uniform(-4, 4, 200) # 根据 x、y 计算对应的 z 值z np.sin(np.sqrt(x**2 y**2)) fig plt.figure(figsize(8, 6))ax fig.add_subplot(111, projection3d) # 基于不规则散点自动进行三角剖分并绘制曲面ax.plot_trisurf(x, y, z, cmapplasma, linewidth0.2, antialiasedTrue) ax.set_title(3D Triangulated Surface)ax.set_xlabel(X)ax.set_ylabel(Y)ax.set_zlabel(Z) plt.show()说明plot_surface() 通常要求输入规则网格数据因此常常需要先用 np.meshgrid() 构造二维网格而 plot_trisurf() 不要求点必须落在规则网格上它会根据平面散点自动进行三角剖分再生成曲面。正因为如此它更适合处理实验采样点、地形离散点、传感器测量点等不规则空间数据。bar3d()用于绘制三维柱状图在三维空间中显示立体柱体。ax.bar3d(x, y, z, dx, dy, dz, colorNone, zsortaverage, shadeTrue, **kwargs)参数说明• x柱体底部起点的 x 坐标• y柱体底部起点的 y 坐标• z柱体底部起点的 z 坐标• dx柱体在 x 方向上的宽度• dy柱体在 y 方向上的宽度• dz柱体在 z 方向上的高度• zsort柱体排序方式影响渲染顺序average按柱体相关顶点 z 值的平均值决定绘制顺序这是默认值min按柱体相关顶点 z 值的最小值决定绘制顺序max按柱体相关顶点 z 值的最大值决定绘制顺序• shade是否启用阴影效果返回值返回一个 Poly3DCollection 对象。示例import matplotlib.pyplot as pltimport numpy as np fig plt.figure()ax fig.add_subplot(111, projection3d) x np.array([0, 1, 2, 0, 1, 2])y np.array([0, 0, 0, 1, 1, 1])z np.zeros_like(x) dx np.ones_like(x) * 0.5dy np.ones_like(y) * 0.5dz np.array([1, 3, 2, 4, 2, 5]) ax.bar3d(x, y, z, dx, dy, dz, shadeTrue) plt.show()说明三维柱状图可以看作二维柱状图在空间中的扩展。不过由于三维图存在遮挡与透视问题它虽然更立体却不一定总比二维柱状图更清晰。因此在正式分析中应根据任务选择。contour()用于绘制三维等高线图展示曲面的等值线结构。ax.contour(X, Y, Z, levelsNone, zdirz, offsetNone, cmapNone, **kwargs)参数说明• X网格点的 x 坐标二维数组• Y网格点的 y 坐标二维数组• Z对应位置的高度值二维数组• levels等高线层级数量或具体层级值• zdir指定等高线投影方向• offset投影偏移位置• cmap颜色映射方案返回值返回一个 QuadContourSet 对象。示例import matplotlib.pyplot as pltimport numpy as np x np.linspace(-5, 5, 100)y np.linspace(-5, 5, 100)X, Y np.meshgrid(x, y)Z np.sin(np.sqrt(X**2 Y**2)) fig plt.figure()ax fig.add_subplot(111, projection3d)ax.contour(X, Y, Z, 20, cmapplasma) plt.show()说明这里的 ax.contour() 是在三维坐标轴上绘制等高线可直接显示在三维空间中也可结合 zdir 与 offset 做投影。三维等高线图常用于辅助观察曲面的层级变化。它既可以单独绘制也可以与 plot_surface() 配合使用使曲面的高低结构更加清晰。contourf()用于绘制三维填充等高线图。ax.contourf(X, Y, Z, *args, zdirz, offsetNone, **kwargs)参数说明• *args等高线层级等额外参数• zdir等高线延伸或投影的方向可取 x、y、z• offset若指定则将填充等高线投影到与 zdir 垂直的平面上• cmap颜色映射方案• axlim_clip是否裁剪坐标轴范围外的内容默认 False返回值返回一个 QuadContourSet 对象。示例import matplotlib.pyplot as pltimport numpy as np fig plt.figure(figsize(8, 6))ax fig.add_subplot(111, projection3d) x np.linspace(-4, 4, 100)y np.linspace(-4, 4, 100)X, Y np.meshgrid(x, y)Z np.sin(np.sqrt(X**2 Y**2)) ax.contourf(X, Y, Z, zdirz, offset-1.5, cmapviridis)ax.set_title(3D Filled Contour)ax.set_xlabel(X)ax.set_ylabel(Y)ax.set_zlabel(Z) plt.show()说明contourf() 可以看作 contour() 的填充版本。它不仅能显示等值分层还能通过颜色填充增强层次感若配合 offset 使用还可以把填充等高线投影到某个坐标平面上。quiver()用于绘制三维箭头场。ax.quiver(X, Y, Z, U, V, W, **kwargs)参数说明• X、Y、Z箭头起点坐标• U、V、W箭头在三个方向上的分量• length箭头长度缩放因子默认 1• arrow_length_ratio箭头头部相对于整体长度的比例默认 0.3• pivot箭头锚点位置可取 tail、middle、tip• normalize是否将箭头长度归一化默认 False• axlim_clip是否裁剪坐标轴范围外的箭头默认 False返回值返回一个 Line3DCollection 对象。示例import matplotlib.pyplot as pltimport numpy as np fig plt.figure(figsize(8, 6))ax fig.add_subplot(111, projection3d) x, y, z np.meshgrid(np.arange(-1, 2), np.arange(-1, 2), np.arange(-1, 2)) u xv yw z ax.quiver(x, y, z, u, v, w, length0.2, normalizeTrue)ax.set_title(3D Quiver)ax.set_xlabel(X)ax.set_ylabel(Y)ax.set_zlabel(Z) plt.show()说明quiver() 常用于展示方向、速度、力场、梯度等向量信息。与散点图展示“位置”不同箭头图同时表达了“位置 方向 大小”三类信息。三、三维图形修饰函数三维图除了常见的标题、横轴标签、纵轴标签之外还多了 z 轴和观察角度等三维特有信息。因此这一组函数在三维图中尤其重要。set_title()用于设置三维子图标题。ax.set_title(label, fontdictNone, locNone, padNone, **kwargs)参数说明该函数与二维绘图中的 set_title() 用法相同三维绘图中没有新增的独有参数。返回值返回一个 Text 对象。示例ax.set_title(三维曲面图)说明该函数虽然不是三维绘图独有但在三维图中同样用于说明图形内容常与 set_xlabel()、set_ylabel()、set_zlabel() 配合使用。set_xlabel() / set_ylabel()用于设置三维坐标轴中的 x 轴与 y 轴标签。ax.set_xlabel(xlabel, fontdictNone, labelpadNone, **kwargs)ax.set_ylabel(ylabel, fontdictNone, labelpadNone, **kwargs)参数说明与二维绘图中的同名函数一致三维场景中没有额外独有参数。返回值返回一个 Text 对象。示例ax.set_xlabel(X)ax.set_ylabel(Y)set_zlabel()用于设置三维坐标轴的 z 轴标签。ax.set_zlabel(zlabel, fontdictNone, labelpadNone, **kwargs)参数说明• zlabelz 轴标签文本• 其余参数含义与 set_xlabel()、set_ylabel() 类似返回值返回一个 Text 对象。示例import matplotlib.pyplot as pltimport numpy as np fig plt.figure()ax fig.add_subplot(111, projection3d) t np.linspace(0, 10, 100)ax.plot(np.cos(t), np.sin(t), t) ax.set_zlabel(Z) plt.show()set_zlim()用于设置三维坐标轴 z 轴的显示范围。ax.set_zlim(bottomNone, topNone)参数说明• bottomz 轴下界• topz 轴上界返回值返回设置后的 z 轴范围。示例ax.set_zlim(0, 20)说明当 z 方向数据跨度较大或者希望突出某一高度区间时set_zlim() 很有用。它与二维图中的 set_xlim()、set_ylim() 在作用逻辑上是一致的。view_init()用于设置三维图的观察角度。它决定读者从什么方向观看当前三维图形因此在三维绘图中非常重要。ax.view_init(elevNone, azimNone, rollNone, vertical_axisz, shareFalse)参数说明• elev仰角即从竖直方向上观察的角度• azim方位角即绕垂直轴旋转的角度• roll绕观察方向的旋转角度• vertical_axis指定哪个轴视为竖直方向默认是 z返回值无返回值主要起视角设置作用。示例import matplotlib.pyplot as pltimport numpy as np t np.linspace(0, 10 * np.pi, 500)x np.cos(t)y np.sin(t)z t fig plt.figure()ax fig.add_subplot(111, projection3d)ax.plot(x, y, z) ax.view_init(elev25, azim45) plt.show()说明三维图的可读性在很大程度上依赖视角。同一组数据如果观察角度不合适空间结构可能会变得难以辨认。因此view_init() 不是单纯的美化函数而是三维表达的重要组成部分。set_proj_type()用于设置三维图的投影方式。它决定三维场景是采用透视投影还是正交投影从而影响图形的空间视觉效果。ax.set_proj_type(proj_type, focal_lengthNone)参数说明• proj_type投影类型常见取值为persp透视投影远处对象看起来更小更符合日常视觉经验ortho正交投影不表现近大远小更适合强调几何结构与尺寸关系• focal_length焦距参数主要用于透视投影效果调节返回值无返回值。示例import matplotlib.pyplot as pltimport numpy as np t np.linspace(0, 10 * np.pi, 500)x np.cos(t)y np.sin(t)z t fig plt.figure()ax fig.add_subplot(111, projection3d)ax.plot(x, y, z) ax.set_proj_type(ortho)ax.set_title(Orthographic Projection) plt.show()说明view_init() 解决的是“从哪个方向看”而 set_proj_type() 解决的是“用什么投影方式看”。二者共同决定三维图的视觉呈现。官方专门提供了 3D plot projection types 示例来展示不同投影方式的效果差异。set_box_aspect()用于设置三维坐标轴盒子的显示比例。ax.set_box_aspect(aspect, *, zoom1)参数说明• aspect三维坐标轴盒子的比例通常写成三元组如 (1, 1, 1) 或 (2, 1, 1)• zoom缩放系数默认 1返回值无返回值。示例import matplotlib.pyplot as pltimport numpy as np fig plt.figure(figsize(8, 6))ax fig.add_subplot(111, projection3d) t np.linspace(0, 10, 200)x np.cos(t)y np.sin(t)z t ax.plot(x, y, z)ax.set_box_aspect((1, 1, 2))ax.set_title(3D Box Aspect)ax.set_xlabel(X)ax.set_ylabel(Y)ax.set_zlabel(Z) plt.show()说明set_box_aspect() 控制的是三维坐标轴外框在显示中的比例而不是数据本身的数值比例。官方文档指出其默认盒子比例为 4:4:3。在三维图中如果默认显示效果让图形显得“过扁”或“过高”这个函数非常有用。tight_layout()自动调整子图间距减少多子图场景中的标题、标签和刻度重叠。plt.tight_layout(pad1.08)或fig.tight_layout(pad1.08)参数说明与二维绘图中的 tight_layout() 基本一致三维绘图中没有新增独有参数。返回值无显式返回值。示例plt.tight_layout()说明tight_layout() 可用于对子图间距做基础性的自动调整但官方文档同时指出它属于较早的布局机制只检查刻度标签、轴标签和标题等元素的范围。在复杂三维多子图场景中它的效果可能有限若布局更复杂通常更推荐使用 constrained_layout。 小结Matplotlib 三维绘图的关键是先创建三维坐标轴再根据数据特点选择点、线、曲面、柱体或向量场等函数最后结合 z 轴范围、观察角度、投影方式与盒子比例完善表达。学习时应重点把握不同数据组织形式与函数选择之间的对应关系。“点赞有美意赞赏是鼓励”