Matplotlib 3.5.0 的新功能 (2021 年 11 月 15 日)#

如需自上次修訂以來的所有問題和拉取請求清單，請參閱3.10.0 的 GitHub 統計數據 (2024 年 12 月 13 日)。

圖表和軸的建立/管理 #

圖形現在有 `draw_without_rendering` 方法 #

圖形的某些方面僅在繪製時確定，例如文字藝術家的確切位置或自動數據限制等延遲計算。如果您需要這些值，可以使用 figure.canvas.draw() 來強制完整繪製。但是，這會產生副作用，有時需要開啟檔案，並且執行的工作量超出所需。

新的 Figure.draw_without_rendering 方法會執行 draw() 所做的所有更新，但會跳過渲染圖形。因此，如果您需要更新後的值來配置圖形的其他方面，它會更有效率。

圖形 `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` 方法 #

由 ax.arrow 返回的補丁 FancyArrow 現在有一個 set_data 方法，允許在建立後修改箭頭，例如用於動畫。

`ArrowStyle` 和 `ConnectionPatch` 中的新箭頭樣式 #

ArrowStyle 的新 arrow 參數取代了在建立箭頭時使用 beginarrow 和 endarrow 參數。它接收箭頭字串，例如 '<-'、']-[' 和 ']->'，而不是個別的布林值。

也透過此機制新增了兩種新樣式 ']->' 和 '<-['。ConnectionPatch 透過其 arrowstyle 參數接受箭頭樣式，也接受這些新樣式。

(原始碼, 2x.png, png)

在初始化後設定集合偏移轉換 #

新增的 collections.Collection.set_offset_transform 可用於在初始化後設定偏移轉換。這在軸物件外建立 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，其他物件可以連接這個機制，以便在 norm 更新時收到通知。當 norm 被修改時，回呼會發出 changed 鍵。cm.ScalarMappable 現在是一個監聽器，當 norm 的 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 的改進 #

允許全域設定預設圖例 labelcolor #

新的 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` 支援遮罩陣列和 NaN #

axes3d.Axes3D.plot_surface 支援遮罩陣列和 NaN，並且現在會隱藏包含遮罩或 NaN 點的四邊形。此行為類似於具有 corner_mask=True 的 Axes.contour。

(原始碼, 2x.png, png)

3D 繪圖方法支援 data 關鍵字引數 #

為了與所有 2D 繪圖方法匹配，3D 軸現在支援 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 和 RangeSlider 小工具的外觀，並為新增的控制柄提供了新的樣式參數。

(原始碼, 2x.png, png)

移除 PolygonSelector 上的點 #

在完成 PolygonSelector 之後，現在可以透過在其上按一下滑鼠右鍵來移除個別點。

拖曳選取器 #

SpanSelector、RectangleSelector 和 EllipseSelector 具有新的關鍵字引數 drag_from_anywhere，當設定為 True 時，允許您從選取器內的任何位置按一下並拖曳來移動它。先前僅能透過啟用移動修飾鍵按鈕，或按一下中央控制柄來移動它。

現在可以使用邊緣控制柄來變更 SpanSelector 的大小。

清除選取器 #

選取器（EllipseSelector、LassoSelector、PolygonSelector、RectangleSelector 和 SpanSelector）有一個新的方法 clear，它會清除目前的選取範圍並讓選取器準備好進行新的選取。這相當於按下 escape 鍵。

設定選取器的藝術家屬性 #

可以使用 set_props 和 set_handle_props 方法變更 EllipseSelector、LassoSelector、PolygonSelector、RectangleSelector 和 SpanSelector 選取器的藝術家屬性。

忽略選取範圍外的事件 #

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 擴展 #

`mathmpl` Sphinx 擴展的更多設定 #

matplotlib.sphinxext.mathmpl Sphinx 擴展支援兩個新的組態選項，可以在您的 conf.py 中指定：

mathmpl_fontsize (float)，設定數學文字的字體大小（以點為單位）；
mathmpl_srcset (str 列表)，提供一個大小列表，以支援響應式解析度圖像。此列表應包含額外的 x 描述符（'1.5x'、'2x' 等）來產生（1x 是預設值且總是包含）。

後端特定改進 #

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 的後端都正確地支援 HiDPI，就像它們的 Agg 對應後端一樣（也就是說，如果工具組支援 HiDPI，則 *Cairo 後端現在將支援它，否則將不支援。）