matplotlib.patches.Patch#

class matplotlib.patches.Patch(*, edgecolor=None, facecolor=None, color=None, linewidth=None, linestyle=None, antialiased=None, hatch=None, fill=True, capstyle=None, joinstyle=None, hatchcolor=None, edgegapcolor=None, **kwargs)[源码]#

基类：Artist

Patch（补丁）是一个具有填充颜色和边缘颜色的 2D 艺术家对象（Artist）。

如果 edgecolor、facecolor、linewidth 或 antialiased 中的任何一个为 None，它们将默认使用 rc 参数中的设置。

支持以下关键字参数属性：

属性	描述
`agg_filter`	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
`alpha`	未知
`animated`	布尔值
`antialiased` 或 `aa`	布尔值或 None
`capstyle`	`CapStyle` 或 {'butt', 'projecting', 'round'}
`clip_box`	`BboxBase` 或 None
`clip_on`	布尔值
`clip_path`	Patch 或 (Path, Transform) 或 None
`color`	color
`edgecolor` 或 `ec`	颜色或 None
`edgegapcolor`	颜色或 None
`facecolor` 或 `fc`	颜色或 None
`figure`	`Figure` 或 `SubFigure`
`fill`	布尔值
`gid`	str
`hatch`	{'/', '\', '\|', '-', '+', 'x', 'o', 'O', '.', '*'}
`hatch_linewidth`	未知
`hatchcolor`	color 或 'edge' 或 None
`in_layout`	布尔值
`joinstyle`	`JoinStyle` 或 {'miter', 'round', 'bevel'}
`label`	object
`linestyle` 或 `ls`	{'-', '--', '-.', ':', '', ...} 或 (offset, on-off-seq)
`linewidth` 或 `lw`	浮点数或 None
`mouseover`	布尔值
`path_effects`	`AbstractPathEffect` 列表
`picker`	None 或布尔值或浮点数或可调用对象
`rasterized`	布尔值
`sketch_params`	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
`snap`	布尔值或 None
`transform`	`变换`
`url`	str
`visible`	布尔值
`zorder`	浮点数

contains(mouseevent, radius=None)[源码]#

测试鼠标事件是否发生在补丁内。

参数:

mouseeventMouseEvent

用户点击的位置。

radiusfloat, 可选

在 Patch.get_transform 的目标坐标系中，补丁的额外边距。更多详情请参阅 Path.contains_point。

如果为 None，默认值取决于对象的状态。

如果 Artist.get_picker 是一个数字，则默认值为该数字。这是为了确保拾取（picking）功能符合预期工作。
否则，如果边缘颜色具有非零 alpha 值，默认值为线宽的一半。这是为了确保所有彩色像素都在补丁“内”。
最后，如果边缘的 alpha 为 0，则默认值为 0。这样，没有描边边缘的补丁就不会因为不可见的边缘导致填充区域外的点被报告为“在”补丁内。

返回:

(bool, 空字典)

contains_point(point, radius=None)[源码]#

返回给定点是否在补丁内。

参数:

point(float, float)

要检查的点 (x, y)，处于 .Patch.get_transform() 的目标坐标系中。对于添加到图窗或坐标轴的补丁，这些是显示坐标。

radiusfloat, 可选

在 Patch.get_transform 的目标坐标系中，补丁的额外边距。更多详情请参阅 Path.contains_point。

如果为 None，默认值取决于对象的状态。

如果 Artist.get_picker 是一个数字，则默认值为该数字。这是为了确保拾取（picking）功能符合预期工作。
否则，如果边缘颜色具有非零 alpha 值，默认值为线宽的一半。这是为了确保所有彩色像素都在补丁“内”。
最后，如果边缘的 alpha 为 0，则默认值为 0。这样，没有描边边缘的补丁就不会因为不可见的边缘导致填充区域外的点被报告为“在”补丁内。

返回:

布尔值

备注

此方法的正确使用取决于补丁的变换。孤立的补丁没有变换。在这种情况下，补丁创建坐标与点坐标相匹配。以下示例检查圆心是否在圆内：

>>> center = 0, 0
>>> c = Circle(center, radius=1)
>>> c.contains_point(center)
True

检查变换后补丁的惯例源于该方法主要用于检查显示坐标（例如来自鼠标事件）是否在补丁内。如果您想用数据坐标执行上述检查，则必须先对其进行正确的变换。

>>> center = 0, 0
>>> c = Circle(center, radius=3)
>>> plt.gca().add_patch(c)
>>> transformed_interior_point = c.get_data_transform().transform((0, 2))
>>> c.contains_point(transformed_interior_point)
True

contains_points(points, radius=None)[源码]#

返回给定点集是否在补丁内。

参数:

points(N, 2) 数组

要检查的点，处于 self.get_transform() 的目标坐标系中。对于添加到图窗或坐标轴的补丁，这些是显示坐标。列包含 x 和 y 值。

radiusfloat, 可选

在 Patch.get_transform 的目标坐标系中，补丁的额外边距。更多详情请参阅 Path.contains_point。

如果为 None，默认值取决于对象的状态。

如果 Artist.get_picker 是一个数字，则默认值为该数字。这是为了确保拾取（picking）功能符合预期工作。
否则，如果边缘颜色具有非零 alpha 值，默认值为线宽的一半。这是为了确保所有彩色像素都在补丁“内”。
最后，如果边缘的 alpha 为 0，则默认值为 0。这样，没有描边边缘的补丁就不会因为不可见的边缘导致填充区域外的点被报告为“在”补丁内。

返回:

长度为 N 的布尔数组

备注

此方法的正确使用取决于补丁的变换。请参阅 Patch.contains_point 的说明。

draw(renderer)[源码]#

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

如果该艺术家对象不可见（Artist.get_visible 返回 False），则此操作无效。

参数:

rendererRendererBase 子类。

备注

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

property fill#: 返回补丁是否被填充。

get_aa()[源码]#: get_antialiased 的别名。

get_antialiased()[源码]#: 返回绘图时是否使用抗锯齿。

get_capstyle()[源码]#: 返回端点样式（capstyle）。

get_data_transform()[源码]#: 返回将数据坐标映射到物理坐标的 Transform。

get_ec()[源码]#: get_edgecolor 的别名。

get_edgecolor()[源码]#: 返回边缘颜色。

get_edgegapcolor()[源码]#

返回边缘空隙颜色（edge gap color）。

于版本 3.11 新增。

另请参阅 set_edgegapcolor。

get_extents()[源码]#: 以 Bbox 的形式返回 Patch 轴对齐的范围。

get_facecolor()[源码]#: 返回填充颜色。

get_fc()[源码]#: get_facecolor 的别名。

get_fill()[源码]#: 返回补丁是否被填充。

get_hatch()[源码]#: 返回填充图案（hatching pattern）。

get_hatch_linewidth()[源码]#: 返回填充图案的线宽。

get_hatchcolor()[源码]#: 返回填充图案的颜色。

get_joinstyle()[源码]#: 返回连接样式（joinstyle）。

get_linestyle()[源码]#: 返回线型。

get_linewidth()[源码]#: 以点为单位返回线宽。

get_ls()[源码]#: get_linestyle 的别名。

get_lw()[源码]#: get_linewidth 的别名。

get_patch_transform()[源码]#

返回将补丁坐标映射到数据坐标的 Transform 实例。

例如，可以通过提供单位圆的坐标，并使用一个将坐标（补丁坐标）缩放5倍的变换，来定义一个表示半径为5的圆形补丁。

get_path()[源码]#: 返回此补丁的路径。

get_transform()[源码]#: 返回应用于 Patch 的 Transform。

get_verts()[源码]#

返回补丁所用顶点的副本。

如果补丁包含贝塞尔曲线，曲线将被线段插值。若要以曲线形式访问，请使用 get_path。

get_window_extent(renderer=None)[源码]#

获取美工对象在显示空间中的边界框，忽略裁剪。

边界框的宽度和高度非负。

子类应覆盖此方法，以便将其包含在边界框“紧密”计算中。默认返回一个位于 0, 0 的空边界框。

警告

范围可能会由于变换栈的任何更改而改变，例如更改坐标轴限制、图形大小、使用的画布（保存图形时）或 DPI。

依赖于一次性获取的窗口范围可能会在某些情况下导致意外行为，例如交互式图形被调整大小或移动到具有不同 DPI 的屏幕，或者在屏幕上看起来没问题的图形在保存到文件时渲染不正确。

为了获得准确的结果，您可能需要手动调用 savefig 或 draw_without_rendering 来让 Matplotlib 计算渲染尺寸。

参数:

rendererRendererBase, 可选: 用于绘制图形的渲染器（即 fig.canvas.get_renderer()）。

另请参阅

Artist.get_tightbbox: 获取美工边界框，考虑裁剪。

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, capstyle=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, edgegapcolor=<UNSET>, facecolor=<UNSET>, fill=<UNSET>, gid=<UNSET>, hatch=<UNSET>, hatch_linewidth=<UNSET>, hatchcolor=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<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

未知

animated

布尔值

antialiased

布尔值或 None

capstyle

CapStyle 或 {'butt', 'projecting', 'round'}

clip_box

BboxBase 或 None

clip_on

布尔值

clip_path

Patch 或 (Path, Transform) 或 None

color

color

edgecolor

颜色或 None

edgegapcolor

颜色或 None

facecolor

颜色或 None

figure

Figure 或 SubFigure

fill

布尔值

gid

str

hatch

{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}

hatch_linewidth

未知

hatchcolor

color 或 'edge' 或 None

in_layout

布尔值

joinstyle

JoinStyle 或 {'miter', 'round', 'bevel'}

label

object

linestyle

{'-', '--', '-.', ':', '', ...} 或 (offset, on-off-seq)

linewidth

浮点数或 None

mouseover

布尔值

path_effects

AbstractPathEffect 列表

picker

None 或布尔值或浮点数或可调用对象

rasterized

布尔值

sketch_params

(scale: 浮点数, length: 浮点数, randomness: 浮点数)

snap

布尔值或 None

transform

变换

url

str

visible

布尔值

zorder

浮点数

set_aa(aa)[源码]#: set_antialiased 的别名。

set_alpha(alpha)[源码]#

设置用于混合的alpha值 - 不支持所有后端。

参数:

alpha浮点数或 None: alpha 必须在 0-1 范围内（包含 0 和 1）。

set_antialiased(aa)[源码]#

设置是否使用抗锯齿渲染。

参数:

aabool 或 None

set_capstyle(s)[源码]#

设置 CapStyle。

默认的 capstyle 对于 FancyArrowPatch 为 'round'，对于所有其他补丁则为 'butt'。

参数:

sCapStyle 或 {'butt', 'projecting', 'round'}

set_color(c)[源码]#

同时设置边缘颜色（edgecolor）和填充颜色（facecolor）。

参数:

ccolor

另请参阅

Patch.set_facecolor, Patch.set_edgecolor: 用于分别设置边缘颜色或填充颜色。

set_ec(color)[源码]#: set_edgecolor 的别名。

set_edgecolor(color)[源码]#

设置补丁的边缘颜色。

参数:

colorcolor 或 None

set_edgegapcolor(edgegapcolor)[源码]#

设置用于填充虚线边缘样式中间空隙的颜色。

于版本 3.11 新增。

注意

条纹边缘是通过绘制两条交错的虚线创建的。这两条线之间可能会有重叠，这在使用透明度时可能会导致伪影。

此功能是实验性的，未来可能会发生变化。

参数:

edgegapcolorcolor 或 None: 用于填充空隙的颜色。如果为 None，则空隙不填充。

set_facecolor(color)[源码]#

设置补丁的填充颜色。

参数:

colorcolor 或 None

set_fc(color)[源码]#: set_facecolor 的别名。

set_fill(b)[源码]#

设置是否填充补丁。

参数:

bbool

set_hatch(hatch)[源码]#

设置填充图案。

hatch 可以是以下之一：

/   - diagonal hatching
\   - back diagonal
|   - vertical
-   - horizontal
+   - crossed
x   - crossed diagonal
o   - small circle
O   - large circle
.   - dots
*   - stars

字母可以组合使用，在这种情况下会执行所有指定的填充。如果字母重复，则会增加该图案的填充密度。

参数:

hatch{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}

set_hatch_linewidth(lw)[源码]#: 设置填充线宽。

set_hatchcolor(color)[源码]#

设置补丁填充图案的颜色。

参数:

colorcolor 或 'edge' 或 None

set_joinstyle(s)[源码]#

设置 JoinStyle。

默认的 joinstyle 对于 FancyArrowPatch 为 'round'，对于所有其他补丁则为 'miter'。

参数:

sJoinStyle 或 {'miter', 'round', 'bevel'}

set_linestyle(ls)[源码]#

设置补丁的线型。

参数:

ls{'-', '--', '-.', ':', '', ...} 或 (offset, on-off-seq)

可能的值

字符串

linestyle

描述

'-' 或 'solid'

实线

'--' 或 'dashed'

虚线

'-.' 或 'dashdot'

点划线

':' 或 'dotted'

点线

'' 或 'none' (不推荐使用：'None', ' ')

不绘制任何内容
描述虚线和间隙开始位置及长度的元组

(offset, onoffseq)

其中
- offset 是一个指定偏移量（以点为单位）的浮点数；即虚线模式偏移了多少。
- onoffseq 是以点为单位的绘图和留白的序列。可以有任意数量的绘图和留白值对。
示例：元组 (0, (10, 5, 1, 5)) 表示模式从线段起点开始。它绘制一条 10 点长的虚线，然后是 5 点的间隙，接着是一条 1 点长的虚线，随后是 5 点的间隙，然后循环重复。

有关示例，请参阅线型。

set_linewidth(w)[源码]#

以点为单位设置补丁线宽。

参数:

wfloat 或 None

set_ls(ls)[源码]#: set_linestyle 的别名。

set_lw(w)[源码]#: set_linewidth 的别名。

update_from(other)[源码]#: 从other复制属性到self。

zorder = 1#

使用 `matplotlib.patches.Patch` 的示例#

使用 PatchCollection 从误差条创建框

SkewT-logP 图：使用变换和自定义投影

linestyle	描述
`'-'` 或 `'solid'`	实线
`'--'` 或 `'dashed'`	虚线
`'-.'` 或 `'dashdot'`	点划线
`':'` 或 `'dotted'`	点线
`''` 或 `'none'` (不推荐使用：`'None'`, `' '`)	不绘制任何内容

matplotlib.patches.Patch#

使用 matplotlib.patches.Patch 的示例#

使用 `matplotlib.patches.Patch` 的示例#