matplotlib.contour

支持 Axes 类进行等高线绘制和标注的类。

class matplotlib.contour.ContourLabeler

基类： object

为 ContourSet 提供标注功能的 Mixin 类。

add_label(x, y, rotation, lev, cvalue)

添加一个等高线标注，遵循是否设置了 use_clabeltext。

add_label_near(x, y, inline=True, inline_spacing=5, transform=None)

在点 (x, y) 附近添加一个标注。

参数:

x, yfloat

标注的近似位置。

inlinebool, 默认: True

如果为 True，则移除标注下方的等高线段。

inline_spacingint, 默认: 5

放置内嵌标注时，标注两侧保留的像素空间。对于直线上的标注，该间距是精确的，对于弯曲等高线上的标注，精确度较低。

transformTransform 或 False, 默认: self.axes.transData

在标注前应用于 (x, y) 的变换。默认情况下将 (x, y) 解释为数据坐标。False 是 IdentityTransform 的同义词；即 (x, y) 应被解释为显示坐标。

clabel(levels=None, *, fontsize=None, inline=True, inline_spacing=5, fmt=None, colors=None, use_clabeltext=False, manual=False, rightside_up=True, zorder=None)

为等高线图添加标签。

为该 ContourSet（继承自此类）中的等高线添加标注。

参数:

levels类数组对象，可选的

需要标注的等高线数值列表。该列表必须是 cs.levels 的子集。如果未指定，则标注所有层级。

fontsizestr 或 float, 默认: rcParams["font.size"] (默认: 10.0)

磅值或相对大小，例如 'small', 'x-large'。参见 Text.set_size 获取可接受的字符串值。

colors颜色 或 颜色列表 或 None, 默认: None

标注颜色。

• 如果为 None，则每个标注的颜色与对应等高线的颜色匹配。

• 如果是单个字符串颜色（如 colors = 'r' 或 colors = 'red'），则所有标注将使用该颜色绘制。

• 如果是颜色元组（字符串、浮点数、RGB 等），则不同的标注将按照指定的顺序使用不同颜色绘制。

inlinebool, 默认: True

如果为 True，则在放置标注的位置移除下方的等高线。

inline_spacingfloat, 默认: 5

放置内嵌标注时，标注两侧保留的像素空间。

对于直线上的标注，该间距是精确的，对于弯曲等高线上的标注，精确度较低。

fmtFormatter 或 str 或 可调用对象 或 dict, 可选

层级格式化方式。

• 如果是 Formatter，则使用其 format_ticks 方法一次性格式化所有层级。

• 如果是字符串，则将其解释为 % 风格的格式字符串。

• 如果是可调用对象，则一次处理一个层级，并应返回对应的标注文本。

• 如果是字典，则应直接将层级映射为标注。

默认使用标准 ScalarFormatter。

manualbool 或 可迭代对象, 默认: False

如果为 True，则通过鼠标点击手动放置标注。在等高线附近点击第一个按钮添加标注，点击第二个按钮（或同时点击两个）完成标注添加。第三个按钮可用于移除最后添加的标注（仅在非内嵌模式下有效）。键盘也可用于选择标注位置（回车结束放置，删除或退格键作用等同于第三个鼠标按钮，其他按键用于选择标注位置）。

manual 也可以是一个 (x, y) 元组的可迭代对象。标注将如同在每个 (x, y) 位置点击鼠标一样创建。

rightside_upbool, 默认: True

如果为 True，标注旋转始终为层级的正负 90 度以内。

use_clabeltextbool, 默认: False

如果为 True，使用 Text.set_transform_rotates_text 确保在 Axes 纵横比改变时更新标注旋转。

zorderfloat 或 None, 默认: (2 + contour.get_zorder())

等高线标注的 zorder 层级。

返回:

labels

标注的 Text 实例列表。

注意：返回的 Text 实例不应被单独移除或修改其几何属性（如更改文本或字体大小）。如果需要此类修改，请移除整个 ContourSet 并重新创建。

get_text(lev, fmt)

获取标签文本。

labels(inline, inline_spacing)

locate_label(linecontour, labelwidth)

寻找绘制标注的合适位置（等高线相对平坦的部分）。

pop_label(index=-1)

默认为移除最后一个标注，但可提供任意索引。

print_label(linecontour, labelwidth)

返回等高线是否足够长以容纳一个标注。

remove()

too_close(x, y, lw)

返回该位置附近是否已有标注。

class matplotlib.contour.ContourSet(ax, *args, levels=None, filled=False, linewidths=None, linestyles=None, hatches=(None,), alpha=None, origin=None, extent=None, cmap=None, colors=None, norm=None, vmin=None, vmax=None, colorizer=None, extend='neither', antialiased=None, nchunk=0, locator=None, transform=None, negative_linestyles=None, **kwargs)

基类: ContourLabeler, Collection

存储一组等高线或填充区域。

用户调用方法: clabel

参数:

axAxes

levels[level0, level1, ..., leveln]

表示等高线层级的浮点数列表。

allsegs[level0segs, level1segs, ...]

所有 levels 的多边形片段列表。对于等高线，len(allsegs) == len(levels)；对于填充等高线区域，len(allsegs) = len(levels)-1。列表结构应如下所示：

level0segs = [polygon0, polygon1, ...]
polygon0 = [[x0, y0], [x1, y1], ...]

allkindsNone 或 [level0kinds, level1kinds, ...]

所有多边形顶点种类（代码类型）的可选列表，如 Path 中所述。用于支持复合路径，如填充多边形内的孔洞。若不为 None，则 len(allkinds) == len(allsegs)。列表结构应如下所示：

level0kinds = [polygon0kinds, ...]
polygon0kinds = [vertexcode0, vertexcode1, ...]

如果 allkinds 不为 None，通常特定等高线层级的所有多边形会分组在一起，使得 level0segs = [polygon0] 且 level0kinds = [polygon0kinds]。

**kwargs

关键字参数如 contour 的文档字符串中所述。

属性：

levelsarray

等高线层级的值。

layersarray

对于线型等高线，其值与 levels 相同；对于填充等高线，其值位于各 levels 的中间。参见 ContourSet._process_colors。

绘制等高线或填充区域，取决于关键字参数 filled 是 False（默认）还是 True。

调用签名

ContourSet(ax, levels, allsegs, [allkinds], **kwargs)

参数:

axAxes

用于绘制的 Axes 对象。

levels[level0, level1, ..., leveln]

表示等高线层级的浮点数列表。

allsegs[level0segs, level1segs, ...]

所有 levels 的多边形片段列表。对于等高线，len(allsegs) == len(levels)；对于填充等高线区域，len(allsegs) = len(levels)-1。列表结构应如下所示：

level0segs = [polygon0, polygon1, ...]
polygon0 = [[x0, y0], [x1, y1], ...]

allkinds[level0kinds, level1kinds, ...], 可选

所有多边形顶点种类（代码类型）的可选列表，如 Path 中所述。用于支持复合路径，如填充多边形内的孔洞。若不为 None，则 len(allkinds) == len(allsegs)。列表结构应如下所示：

level0kinds = [polygon0kinds, ...]
polygon0kinds = [vertexcode0, vertexcode1, ...]

如果 allkinds 不为 None，通常特定等高线层级的所有多边形会分组在一起，使得 level0segs = [polygon0] 且 level0kinds = [polygon0kinds]。

**kwargs

关键字参数如 contour 的文档字符串中所述。

property allkinds

property allsegs

property alpha

changed()

每当映射对象发生更改时调用此函数，以通知所有 callbackSM 监听器“changed”信号。

draw(renderer)

使用给定的渲染器绘制 Artist（及其子对象）。

如果美工对象不可见（Artist.get_visible 返回 False），则此操作无效。

参数:

rendererRendererBase 子类。

备注

此方法在 Artist 子类中被覆盖。

find_nearest_contour(x, y, indices=None, pixel=True)

寻找等高线图中距离 (x, y) 最近的点。

此方法不支持填充等高线。

参数:

x, yfloat

参考点。

indicesint 列表 或 None, 默认: None

需要考虑的等高线层级索引。如果为 None（默认），则考虑所有层级。

pixelbool, 默认: True

如果为 True，则在像素（屏幕）空间度量距离，这对于手动等高线标注很有用；否则，在坐标轴空间度量距离。

返回:

pathint

距离 (x, y) 最近的路径索引。每条路径对应一个等高线层级。

subpathint

最近路径中距离 (x, y) 最近的子路径索引。每个子路径对应一条连续的等高线。

index整数

该子路径中距离 (x, y) 最近的顶点索引。

xmin, yminfloat

等高线图中距离 (x, y) 最近的点。

d2float

从 (xmin, ymin) 到 (x, y) 的距离平方。

get_transform()

返回此 ContourSet 使用的 Transform 实例。

legend_elements(variable_name='x', str_format=<class 'str'>)

返回适合传递给 legend 以表示此 ContourSet 的艺术家和标注列表。

标注格式为 "0 < x <= 1"，陈述了艺术家所代表的数据范围。

参数:

variable_namestr

标注不等式中使用的字符串变量名。

str_formatfunction: float -> str

用于格式化标注中数字的函数。

返回:

artistslist[Artist]

艺术家列表。

labelslist[str]

标注列表。

property linestyles

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, array=<UNSET>, capstyle=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, gid=<UNSET>, hatch=<UNSET>, hatch_linewidth=<UNSET>, hatchcolor=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, offset_transform=<UNSET>, offsets=<UNSET>, path_effects=<UNSET>, paths=<UNSET>, picker=<UNSET>, pickradius=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, urls=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

一次性设置多个属性。

a.set(a=A, b=B, c=C)

等同于

a.set_a(A)
a.set_b(B)
a.set_c(C)

除全名属性外，还支持别名，例如 set(lw=2) 等同于 set(linewidth=2)，但同时传入两者会报错。

各个 setter 的调用顺序与 set() 中的参数顺序一致。然而，大多数属性并不相互依赖，因此顺序通常无关紧要。

支持的属性包括：

属性	描述
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alpha	类数组或浮点数或 None
animated	布尔值
antialiased 或 aa 或 antialiaseds	布尔值或布尔值列表
array	类数组或 None
capstyle	CapStyle or {'butt', 'projecting', 'round'}
clim	(vmin: 浮点数, vmax: 浮点数)
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	Patch 或 (Path, Transform) 或 None
cmap	Colormap 或 str 或 None
color	颜色 或 RGBA 元组列表
edgecolor 或 ec or edgecolors	颜色 或 颜色 列表 或 'face'
facecolor 或 facecolors 或 fc	颜色 或 颜色 列表
figure	Figure 或 SubFigure
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	未知
hatchcolor	颜色 或 颜色 列表 或 'edge'
in_layout	布尔值
joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
label	object
linestyle 或 dashes 或 linestyles 或 ls	{'-', '--', '-.', ':', '', ...} 或 (offset, on-off-seq) 或其列表
linewidth 或 linewidths 或 lw	浮点数或浮点数列表
mouseover	布尔值
norm	Normalize 或 str 或 None
offset_transform 或 transOffset	变换
offsets	(N, 2) 或 (2,) 类数组
path_effects	AbstractPathEffect 的列表
paths	未知
picker	None 或 布尔值 或 浮点数 或 可调用对象
pickradius	浮点数
rasterized	布尔值
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
transform	变换
url	str
字符串列表或 None	urls
visible	布尔值
zorder	浮点数

class matplotlib.contour.QuadContourSet(ax, *args, levels=None, filled=False, linewidths=None, linestyles=None, hatches=(None,), alpha=None, origin=None, extent=None, cmap=None, colors=None, norm=None, vmin=None, vmax=None, colorizer=None, extend='neither', antialiased=None, nchunk=0, locator=None, transform=None, negative_linestyles=None, **kwargs)

基类: ContourSet

创建并存储一组等高线或填充区域。

此类通常不由用户直接实例化，而是由 contour 和 contourf 调用。

属性：

levelsarray

等高线层级的值。

layersarray

对于线型等高线，其值与 levels 相同；对于填充等高线，其值位于各 levels 的中间。参见 ContourSet._process_colors。

绘制等高线或填充区域，取决于关键字参数 filled 是 False（默认）还是 True。

调用签名

ContourSet(ax, levels, allsegs, [allkinds], **kwargs)

参数:

axAxes

用于绘制的 Axes 对象。

levels[level0, level1, ..., leveln]

表示等高线层级的浮点数列表。

allsegs[level0segs, level1segs, ...]

所有 levels 的多边形片段列表。对于等高线，len(allsegs) == len(levels)；对于填充等高线区域，len(allsegs) = len(levels)-1。列表结构应如下所示：

level0segs = [polygon0, polygon1, ...]
polygon0 = [[x0, y0], [x1, y1], ...]

allkinds[level0kinds, level1kinds, ...], 可选

所有多边形顶点种类（代码类型）的可选列表，如 Path 中所述。用于支持复合路径，如填充多边形内的孔洞。若不为 None，则 len(allkinds) == len(allsegs)。列表结构应如下所示：

level0kinds = [polygon0kinds, ...]
polygon0kinds = [vertexcode0, vertexcode1, ...]

如果 allkinds 不为 None，通常特定等高线层级的所有多边形会分组在一起，使得 level0segs = [polygon0] 且 level0kinds = [polygon0kinds]。

**kwargs

关键字参数如 contour 的文档字符串中所述。

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, array=<UNSET>, capstyle=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, gid=<UNSET>, hatch=<UNSET>, hatch_linewidth=<UNSET>, hatchcolor=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, offset_transform=<UNSET>, offsets=<UNSET>, path_effects=<UNSET>, paths=<UNSET>, picker=<UNSET>, pickradius=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, urls=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

一次性设置多个属性。

a.set(a=A, b=B, c=C)

等同于

a.set_a(A)
a.set_b(B)
a.set_c(C)

除全名属性外，还支持别名，例如 set(lw=2) 等同于 set(linewidth=2)，但同时传入两者会报错。

各个 setter 的调用顺序与 set() 中的参数顺序一致。然而，大多数属性并不相互依赖，因此顺序通常无关紧要。

支持的属性包括：

属性	描述
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alpha	类数组或浮点数或 None
animated	布尔值
antialiased 或 aa 或 antialiaseds	布尔值或布尔值列表
array	类数组或 None
capstyle	CapStyle or {'butt', 'projecting', 'round'}
clim	(vmin: 浮点数, vmax: 浮点数)
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	Patch 或 (Path, Transform) 或 None
cmap	Colormap 或 str 或 None
color	颜色 或 RGBA 元组列表
edgecolor 或 ec or edgecolors	颜色 或 颜色 列表 或 'face'
facecolor 或 facecolors 或 fc	颜色 或 颜色 列表
figure	Figure 或 SubFigure
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	未知
hatchcolor	颜色 或 颜色 列表 或 'edge'
in_layout	布尔值
joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
label	object
linestyle 或 dashes 或 linestyles 或 ls	{'-', '--', '-.', ':', '', ...} 或 (offset, on-off-seq) 或其列表
linewidth 或 linewidths 或 lw	浮点数或浮点数列表
mouseover	布尔值
norm	Normalize 或 str 或 None
offset_transform 或 transOffset	变换
offsets	(N, 2) 或 (2,) 类数组
path_effects	AbstractPathEffect 的列表
paths	未知
picker	None 或 布尔值 或 浮点数 或 可调用对象
pickradius	浮点数
rasterized	布尔值
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
transform	变换
url	str
字符串列表或 None	urls
visible	布尔值
zorder	浮点数