Matplotlib 3.5.0 新特性 (2021年11月15日)#

有关自上次修订以来的所有问题和拉取请求列表，请参阅 3.10.3 (2025年5月8日) 的 GitHub 统计数据。

Figure 和 Axes 创建/管理 #

Figure 现在有了 `draw_without_rendering` 方法 #

图形的某些方面只在绘制时确定，例如文本 Artist 的确切位置或自动数据限制等延迟计算。如果需要这些值，可以使用 figure.canvas.draw() 强制进行完整绘制。然而，这会产生副作用，有时需要打开文件，并且做了超出需要的工作。

新的 Figure.draw_without_rendering 方法运行 draw() 所做的所有更新，但跳过了图形的渲染。因此，如果需要更新后的值来配置图形的进一步方面，它会更高效。

Figure 的 `init` 方法会将关键字参数传递给 set #

与许多其他 Artist 的子类类似，FigureBase、SubFigure 和 Figure 类现在会将任何额外的关键字参数传递给 set，以便在初始化时设置新创建对象的属性。例如：

from matplotlib.figure import Figure
fig = Figure(label='my figure')

绘图方法 #

添加 `Annulus` 补丁 #

Annulus 是一个用于绘制椭圆环的新类。

(源代码, 2x.png, png)

`FancyArrow` 补丁的 `set_data` 方法 #

FancyArrow 是由 ax.arrow 返回的补丁，现在有一个 set_data 方法，允许在创建后修改箭头，例如用于动画。

`ArrowStyle` 和 `ConnectionPatch` 中的新箭头样式 #

ArrowStyle 的新参数 arrow 替代了在创建箭头时使用 beginarrow 和 endarrow 参数。它接收像 '<-'、']-[' 和 ']->' 这样的箭头字符串，而不是单独的布尔值。

通过这种机制还添加了两种新样式：']->' 和 '<-['。ConnectionPatch 通过其 arrowstyle 参数接受箭头样式，也支持这些新样式。

(源代码, 2x.png, png)

初始化后设置集合偏移变换 #

添加的 collections.Collection.set_offset_transform 可用于在初始化后设置偏移变换。这在 Axes 对象外部创建 collections.Collection，然后使用 Axes.add_collection() 添加并将其偏移变换设置为 Axes.transData 时非常有用。

颜色和颜色映射 #

颜色映射注册表（实验性）#

颜色映射现在通过 matplotlib.colormaps（或 pyplot.colormaps）进行管理，它是一个 ColormapRegistry。虽然我们确信 API 已最终确定，但我们正式将其标记为 3.5 的实验性，因为我们希望保留在 3.6 版本中根据需要修改 API 的选项。

颜色映射可以使用项目访问方式获取：

import matplotlib.pyplot as plt
cmap = plt.colormaps['viridis']

要注册新的颜色映射，请使用：

plt.colormaps.register(my_colormap)

对于新代码，我们建议使用新的 API，而不是 matplotlib.cm.get_cmap 和 matplotlib.cm.register_cmap 函数。matplotlib.cm.get_cmap 和 matplotlib.cm.register_cmap 最终将被弃用并移除。在 pyplot 中，plt.get_cmap() 和 plt.register_cmap() 将继续受支持以实现向后兼容性。

图像插值现在可以在 RGBA 阶段进行 #

通过 imshow 在 Matplotlib 中创建的图像会被重新采样以匹配当前画布的分辨率。在下采样时应用抗锯齿滤波器以减少莫尔效应是很有用的。默认情况下，插值在数据上进行，然后应用范数，最后执行颜色映射。

然而，通常期望抗锯齿插值发生在 RGBA 空间中，其中颜色而不是数据被插值。这通常会导致颜色超出颜色映射范围，但在视觉上可以混合相邻颜色，这也是浏览器和其他图像处理软件所做的方式。

为 imshow 提供了一个新的关键字参数 interpolation_stage，用于设置抗锯齿插值发生的阶段。默认值为当前的“data”行为，另一种选择是“rgba”用于新提供的行为。

../../_images/sphx_glr_image_antialiasing_001.png — 插值阶段选项示例。#

更多详细信息请参阅图像重采样中新关键字参数的讨论。

`imshow` 支持半浮点数组 #

imshow 方法现在支持半浮点数组，即 dtype 为 np.float16 的 NumPy 数组。

Normalize 对象已添加回调注册表 #

colors.Normalize 对象现在有一个回调注册表 callbacks，其他对象可以通过它连接，以在规范更新时收到通知。当规范被修改时，回调会发出键 changed。cm.ScalarMappable 现在是一个监听器，当规范的 vmin、vmax 或其他属性发生更改时，它会注册一个更改。

标题、刻度和标签 #

在 `set_ticks` 中同时设置刻度位置和标签 #

Axis.set_ticks (以及对应的 Axes.set_xticks / Axes.set_yticks) 现在有一个新参数 labels，允许同时设置刻度位置和标签。

以前，设置刻度标签是使用 Axis.set_ticklabels（或相应的 Axes.set_xticklabels / Axes.set_yticklabels）完成的；这通常只有在刻度位置先前已用 set_ticks 固定后才有意义

ax.set_xticks([1, 2, 3])
ax.set_xticklabels(['a', 'b', 'c'])

组合功能现在在 set_ticks 中可用

ax.set_xticks([1, 2, 3], ['a', 'b', 'c'])

不鼓励使用 Axis.set_ticklabels，但为保持向后兼容性，它将继续可用。

注意：此添加使得 set_ticks 的 API 更类似于 pyplot.xticks / pyplot.yticks，后者已经有了额外的 labels 参数。

字体和文本 #

三重和四重圆点数学文本重音符号 #

除了单点和双点重音符号外，数学文本现在支持三重和四重圆点重音符号。

fig = plt.figure(figsize=(3, 1))
fig.text(0.5, 0.5, r'$\dot{a} \ddot{b} \dddot{c} \ddddot{d}$', fontsize=40,
         horizontalalignment='center', verticalalignment='center')

(源代码, 2x.png, png)

图例标题的字体属性可配置 #

标题的字体属性可以通过 title_fontproperties 关键字参数设置，例如：

(源代码, 2x.png, png)

`Text` 和 `TextBox` 添加了 parse_math 选项 #

Text 和 TextBox 对象现在允许使用 parse_math 关键字参数，该参数控制是否从显示的字符串中解析数学。如果为 True，字符串将被解析为数学文本对象。如果为 False，字符串将被视为字面量，不进行解析。

简化 usetex 模式的字体设置 #

现在 rcParams["font.family"]（默认值：['sans-serif']）接受一些字体名称作为值，以便更方便用户设置。

plt.rcParams.update({
    "text.usetex": True,
    "font.family": "Helvetica"
})

PDF/PS 后端现在支持 Type 42 子集 #

backend_pdf 和 backend_ps 现在借助 fontTools 使用统一的 Type 42 字体子集接口。

将 rcParams["pdf.fonttype"]（默认值：3）或 rcParams["ps.fonttype"]（默认值：3）设置为 42 以触发此工作流。

# for PDF backend
plt.rcParams['pdf.fonttype'] = 42

# for PS backend
plt.rcParams['ps.fonttype'] = 42

fig, ax = plt.subplots()
ax.text(0.4, 0.5, 'subsetted document is smaller in size!')

fig.savefig("document.pdf")
fig.savefig("document.ps")

rcParams 改进 #

允许全局设置默认图例标签颜色 #

一个新的 rcParams["legend.labelcolor"]（默认值：'None'）设置了 Figure.legend 的默认 labelcolor 参数。特殊值 'linecolor'、'markerfacecolor'（或 'mfc'）或 'markeredgecolor'（或 'mec'）将使图例文本与标记的相应颜色匹配。

(源代码, 2x.png, png)

3D 坐标轴改进 #

Axes3D 现在允许手动控制绘制顺序 #

Axes3D 类现在有了 computed_zorder 参数。当设置为 False 时，Artist 将使用它们的 zorder 属性进行绘制。

(源代码, 2x.png, png)

允许更改 3D 绘图中的垂直轴 #

view_init 现在有了参数 vertical_axis，允许切换哪个轴垂直对齐。

(源代码, 2x.png, png)

`plot_surface` 支持遮罩数组和 NaNs #

axes3d.Axes3D.plot_surface 支持遮罩数组和 NaNs，现在会隐藏包含遮罩或 NaN 值的四边形。其行为类似于 Axes.contour 并设置 corner_mask=True。

(源代码, 2x.png, png)

3D 绘图方法支持 data 关键字参数 #

为了与所有 2D 绘图方法匹配，3D Axes 现在支持 data 关键字参数。这允许从 DataFrame 类结构中间接传递参数。

data = {  # A labelled data set, or e.g., Pandas DataFrame.
    'x': ...,
    'y': ...,
    'z': ...,
    'width': ...,
    'depth': ...,
    'top': ...,
}

fig, ax = plt.subplots(subplot_kw={'projection': '3d')
ax.bar3d('x', 'y', 'z', 'width', 'depth', 'top', data=data)

交互式工具改进 #

颜色条现在具有平移和缩放功能 #

带有颜色条的交互式绘图现在可以在颜色条轴上进行缩放和平移。这会调整与颜色条关联的 ScalarMappable 的 vmin 和 vmax。目前，此功能仅适用于连续规范。与 contourf 和分类变量一起使用的规范，例如 BoundaryNorm 和 NoNorm，默认禁用交互功能。cb.ax.set_navigate() 可用于设置颜色条轴是否交互。

Slider 小部件外观更新 #

Slider 和 RangeSlider 小部件的外观已更新，并为新增的拖动条提供了新的样式参数。

(源代码, 2x.png, png)

在 PolygonSelector 上移除点 #

完成 PolygonSelector 后，现在可以通过右键单击来移除单个点。

拖动选择器 #

SpanSelector、RectangleSelector 和 EllipseSelector 有一个新的关键字参数 drag_from_anywhere，当设置为 True 时，允许您在选择器内部的任何位置点击并拖动以移动它。以前，只能通过激活移动修改按钮或点击中心句柄来移动。

SpanSelector 的大小现在可以使用边缘手柄进行更改。

清除选择器 #

选择器（EllipseSelector、LassoSelector、PolygonSelector、RectangleSelector 和 SpanSelector）有一个新方法 clear，它将清除当前选择并使选择器准备好进行新选择。这等同于按下 escape 键。

设置选择器的 Artist 属性 #

EllipseSelector、LassoSelector、PolygonSelector、RectangleSelector 和 SpanSelector 选择器的 Artist 属性可以使用 set_props 和 set_handle_props 方法进行更改。

忽略选择外部的事件 #

EllipseSelector、RectangleSelector 和 SpanSelector 选择器有一个新的关键字参数 ignore_event_outside，当设置为 True 时，将忽略当前选择之外的事件。此时可以使用手柄或新的拖动功能来更改选择。

`CallbackRegistry` 对象获得了一个临时阻塞信号的方法 #

上下文管理器 blocked 可用于阻止 CallbackRegistry 处理回调信号。可选的关键字 signal 可用于阻止特定信号被处理，并允许所有其他信号通过。

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.imshow([[0, 1], [2, 3]])

# Block all interactivity through the canvas callbacks
with fig.canvas.callbacks.blocked():
    plt.show()

fig, ax = plt.subplots()
ax.imshow([[0, 1], [2, 3]])

# Only block key press events
with fig.canvas.callbacks.blocked(signal="key_press_event"):
    plt.show()

定向大小调整光标 #

画布现在支持设置定向大小调整光标，即水平和垂直双箭头。这些光标用于选择器小部件等。请尝试鼠标光标示例，以在您想要的后端中查看光标。

Sphinx 扩展 #

后端特定改进 #

GTK 后端 #

已添加支持 GTK4 的后端。Agg 和 Cairo 渲染器均受支持。GTK4 后端可以被选择为 GTK4Agg 或 GTK4Cairo。

Qt 后端 #

已添加对 Qt6（使用 PyQt6 或 PySide6）的支持，支持 Agg 或 Cairo 渲染器。同时，对 Qt4 的支持已停止。Qt6 和 Qt5 都由一个组合后端（QtAgg 或 QtCairo）支持，加载的版本由已导入的模块、QT_API 环境变量和可用软件包决定。有关详细信息，请参阅 Qt 绑定。带版本号的 Qt5 后端名称（Qt5Agg 或 Qt5Cairo）仍受支持以实现向后兼容性。

基于 Cairo、GTK 和 Tk 后端的 HiDPI 支持 #

GTK3 后端现在完全支持 HiDPI，包括混合显示器情况（仅限于 Wayland）。新添加的 GTK4 后端也支持 HiDPI。

TkAgg 后端现在仅在 Windows 上 支持 HiDPI，包括混合显示器情况。

所有基于 Cairo 的后端都像它们的 Agg 对应物一样正确支持 HiDPI（即，如果工具包支持 HiDPI，那么 *Cairo 后端现在将支持它，否则不支持）。