matplotlib.path#

一个用于处理 Matplotlib 中使用的多段线的模块。

Matplotlib 中处理多段线的主要类是 Path。几乎所有矢量绘图都在绘图管线的某个地方使用了 Path。

虽然 Path 实例本身不能直接绘制，但一些 Artist 子类，例如 PathPatch 和 PathCollection，可以用于方便地对 Path 进行可视化。

class matplotlib.path.Path(vertices, codes=None, _interpolation_steps=1, closed=False, readonly=False)[source]#

基类: object

一系列可能不连续、可能闭合的直线和曲线段。

底层存储由两个并行的 numpy 数组组成

  • vertices: 一个 (N, 2) 浮点型顶点数组

  • codes: 一个 N 长度的路径代码 numpy.uint8 数组，或 None

这两个数组在第一个维度上总是具有相同的长度。例如，要表示一条三次曲线，您必须提供三个顶点和三个 CURVE4 代码。

代码类型有

  • STOP1个顶点（被忽略）

    整个路径结束的标记（目前不需要且被忽略）

  • MOVETO1个顶点

    抬起画笔并移动到给定顶点。

  • LINETO1个顶点

    从当前位置到给定顶点绘制一条线。

  • CURVE31个控制点，1个终点

    从当前位置绘制一条二次贝塞尔曲线，使用给定控制点，到给定终点。

  • CURVE42个控制点，1个终点

    从当前位置绘制一条三次贝塞尔曲线，使用给定控制点，到给定终点。

  • CLOSEPOLY1个顶点（被忽略）

    绘制一条线段到当前多段线的起始点。

如果 codes 为 None，则它被解释为一个 MOVETO，后跟一系列 LINETO。

Path 对象的用户不应直接访问 vertices 和 codes 数组。相反，他们应该使用 iter_segments 或 cleaned 来获取顶点/代码对。这尤其有助于一致地处理 codes 为 None 的情况。

Path 对象的一些行为可以通过 rcParams 控制。请参阅键以 'path.' 开头的 rcParams。

注意

vertices 和 codes 数组应被视为不可变——构造函数中预先进行了许多优化和假设，这些优化和假设不会随着数据变化而改变。

使用给定的顶点和代码创建一个新路径。

参数:
vertices(N, 2) 数组类

路径顶点，作为数组、掩码数组或对序列。如果存在掩码值，它们将被转换为 NaNs，然后由 Agg PathIterator 和其他路径数据消费者（例如 iter_segments()）正确处理。

codes数组类或 None，可选

表示路径代码的 N 长度整数数组。如果不是 None，codes 的长度必须与 vertices 相同。如果为 None，vertices 将被视为一系列线段。

_interpolation_steps整型，可选

用作对某些投影（例如极坐标）的提示，表示此路径应在绘制前立即进行线性插值。此属性主要是一个实现细节，不适用于公共使用。

closed布尔型，可选

如果 codes 为 None 且 closed 为 True，则 vertices 将被视为闭合多边形的线段。请注意，最后一个顶点将被忽略（因为相应的代码将被设置为 CLOSEPOLY）。

readonly布尔型，可选

使路径表现为不可变，并将 vertices 和 codes 设置为只读数组。

CLOSEPOLY = np.uint8(79)#
CURVE3 = np.uint8(3)#
CURVE4 = np.uint8(4)#
LINETO = np.uint8(2)#
MOVETO = np.uint8(1)#
NUM_VERTICES_FOR_CODE = {np.uint8(0): 1, np.uint8(1): 1, np.uint8(2): 1, np.uint8(3): 2, np.uint8(4): 3, np.uint8(79): 1}#

一个字典，将 Path 代码映射到该代码所需的顶点数量。

STOP = np.uint8(0)#
静态方法 arc(theta1, theta2, n=None, is_wedge=False)[source]#

返回从角度 theta1 到 theta2（以度为单位）的单位圆弧的 Path。

theta2 被解包以产生 360 度内最短的弧。也就是说，如果 theta2 > theta1 + 360，则弧将从 theta1 到 theta2 - 360，而不是一个完整的圆加上一些额外的重叠。

如果提供了 n，它是要生成的样条段的数量。如果未提供 n，则样条段的数量将根据 theta1 和 theta2 之间的增量确定。

静态方法 circle(center=(0.0, 0.0), radius=1.0, readonly=False)[source]#

返回一个表示给定半径和圆心的圆的 Path。

参数:
center(浮点数, 浮点数)，默认值：(0, 0)

圆心。

radius浮点数，默认值：1

圆的半径。

readonly布尔型

创建 Path 实例时，所创建的路径是否应设置 "readonly" 参数。

备注

该圆使用 8 条三次贝塞尔曲线近似，如以下文献所述：

cleaned(transform=None, remove_nans=False, clip=None, *, simplify=False, curves=False, stroke_width=1.0, snap=False, sketch=None)[source]#

返回一个新 Path，其顶点和代码根据参数进行清理。

另请参阅

Path.iter_segments

以获取关键字参数的详细信息。

clip_to_bbox(bbox, inside=True)[source]#

将路径剪裁到给定的边界框。

路径必须由一个或多个闭合多边形组成。此算法对未闭合的路径行为不正确。

如果 inside 为 True，则剪裁到框的内部，否则剪裁到框的外部。

code_type#

uint8 的别名

属性 codes#

Path 中的代码列表，作为一个 1D 数组。

每个代码都是 STOP、MOVETO、LINETO、CURVE3、CURVE4 或 CLOSEPOLY 之一。对于对应于多个顶点（CURVE3 和 CURVE4）的代码，该代码将重复，以便 vertices 和 codes 的长度始终相同。

contains_path(path, transform=None)[source]#

返回此（闭合）路径是否完全包含给定路径。

如果 transform 不是 None，则在检查包含性之前将转换路径。

contains_point(point, transform=None, radius=0.0)[source]#

返回路径所包围的区域是否包含给定点。

路径始终被视为闭合；即，如果最后一个代码不是 CLOSEPOLY，则假定存在一个连接最后一个顶点到第一个顶点的隐式线段。

参数:
point(浮点数, 浮点数)

要检查的点 (x, y)。

transformTransform，可选

如果不是 None，则将 point 与通过 transform 转换的 self 进行比较；即，为了正确检查，transform 应将路径转换为 point 的坐标系。

radius浮点数，默认值：0

路径在 point 坐标中的额外边距。路径会沿切线方向扩展 radius/2；即，如果您以 radius 的线宽绘制路径，线上的所有点仍将被视为包含在该区域内。相反，负值会缩小区域：虚线上的点将被视为区域外。

返回:
布尔值

备注

当前算法有一些限制

  • 对于恰好在边界上的点（即，在路径移动 radius/2 后的位置），结果是未定义的。

  • 如果没有封闭区域，即所有顶点都在一条直线上，则结果是未定义的。

  • 如果由于 radius 偏移导致边界线开始相互交叉，则结果不保证正确。

contains_points(points, transform=None, radius=0.0)[source]#

返回路径所包围的区域是否包含给定点。

路径始终被视为闭合；即，如果最后一个代码不是 CLOSEPOLY，则假定存在一个连接最后一个顶点到第一个顶点的隐式线段。

参数:
points(N, 2) 数组

要检查的点。列包含 x 和 y 值。

transformTransform，可选

如果不是 None，则将 points 与通过 transform 转换的 self 进行比较；即，为了正确检查，transform 应将路径转换为 points 的坐标系。

radius浮点数，默认值：0

路径在 points 坐标中的额外边距。路径会沿切线方向扩展 radius/2；即，如果您以 radius 的线宽绘制路径，线上的所有点仍将被视为包含在该区域内。相反，负值会缩小区域：虚线上的点将被视为区域外。

返回:
长度为 N 的布尔数组

备注

当前算法有一些限制

  • 对于恰好在边界上的点（即，在路径移动 radius/2 后的位置），结果是未定义的。

  • 如果没有封闭区域，即所有顶点都在一条直线上，则结果是未定义的。

  • 如果由于 radius 偏移导致边界线开始相互交叉，则结果不保证正确。

copy()[source]#

返回 Path 的浅拷贝，它将与源 Path 共享顶点和代码。

deepcopy(memo=None)[source]#

返回 Path 的深拷贝。即使源 Path 是只读的，新 Path 也不是只读的。

get_extents(transform=None, **kwargs)[source]#

获取路径的边界框（Bbox）。

参数:
transformTransform，可选

在计算范围之前应用于路径的变换（如果有的话）。

**kwargs

转发给 iter_bezier。

返回:
matplotlib.transforms.Bbox

路径的范围 Bbox([[xmin, ymin], [xmax, ymax]])

静态方法 hatch(hatchpattern, density=6)[source]#

给定一个填充图案（hatch specifier）hatchpattern，生成一个 Path，可用于重复的填充模式。density 是每单位平方的线数。

interpolated(steps)[source]#

返回一个新路径，其中每个线段被分成 steps 部分。

除了 LINETO、MOVETO 和 CLOSEPOLY 之外的代码未正确处理。

参数:
steps整型

新路径中每个原始路径的线段数量。

返回:
路径

插值后的路径。

intersects_bbox(bbox, filled=True)[source]#

返回此路径是否与给定 Bbox 相交。

如果 filled 为 True，则如果路径完全包围 Bbox（即，路径被视为已填充），此方法也返回 True。

边界框始终被视为已填充。

intersects_path(other, filled=True)[source]#

返回此路径是否与另一个给定路径相交。

如果 filled 为 True，则如果一个路径完全包围另一个路径（即，路径被视为已填充），此方法也返回 True。

iter_bezier(**kwargs)[source]#

迭代 Path 中的每条贝塞尔曲线（包括直线）。

参数:
**kwargs

转发给 iter_segments。

生成（Yields）:
BBezierSegment

构成当前路径的贝塞尔曲线。特别注意，自由点是 0 阶贝塞尔曲线，直线是 1 阶贝塞尔曲线（带两个控制点）。

codecode_type

描述返回曲线类型的代码。MOVETO、LINETO、CURVE3 和 CURVE4 分别对应具有 1、2、3 和 4 个控制点的贝塞尔曲线。CLOSEPOLY 是一个 LINETO，其控制点根据当前笔画的起点/终点正确选择。

iter_segments(transform=None, remove_nans=True, clip=None, snap=False, stroke_width=1.0, simplify=None, curves=True, sketch=None)[source]#

迭代路径中的所有曲线段。

每次迭代返回一个对 (vertices, code)，其中 vertices 是 1-3 个坐标对的序列，code 是一个 Path 代码。

此外，此方法可以对路径进行一些标准清理和转换。

参数:
transformNone 或 Transform

如果不是 None，则给定的仿射变换将应用于路径。

remove_nans布尔型，可选

是否从路径中移除所有 NaNs，并使用 MOVETO 命令跳过它们。

clipNone 或 (浮点数, 浮点数, 浮点数, 浮点数)，可选

如果不是 None，则必须是一个四元组 (x1, y1, x2, y2)，定义一个用于剪裁路径的矩形。

snapNone 或 布尔型，可选

如果为 True，则将所有节点对齐到像素；如果为 False，则不对齐。如果为 None，则在路径仅包含与 x 或 y 轴平行的线段且数量不超过 1024 个时进行对齐。

stroke_width浮点数，可选

绘制笔画的宽度（用于路径对齐）。

simplifyNone 或 布尔型，可选

是否通过移除不影响其外观的顶点来简化路径。如果为None，则使用should_simplify属性。另请参阅rcParams["path.simplify"]（默认值：True）和rcParams["path.simplify_threshold"]（默认值：0.111111111111）。

curvesbool 类型，可选

如果为 True，曲线段将作为曲线段返回。如果为 False，所有曲线将转换为线段。

sketchNone 或序列，可选

如果不为 None，则必须是 (scale, length, randomness) 形式的 3 元组，表示草图参数。

classmethod make_compound_path(*args)[源代码]#

将 Path 列表连接成单个 Path，移除所有 STOP。

classmethod make_compound_path_from_polys(XY)[源代码]#

创建一个复合 Path 对象，用于绘制多个边数相等的面。

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

(2x.png, png)

参数:
XY(多边形数量, 边数, 2) 数组
property readonly#

如果 Path 是只读的，则为 True。

property should_simplify#

如果顶点数组应被简化，则为 True。

property simplify_threshold#

像素差异的比例，低于该比例时顶点将被简化。

to_polygons(transform=None, width=0, height=0, closed_only=True)[源代码]#

将此路径转换为多边形或折线列表。每个多边形/折线都是一个 (N, 2) 的顶点数组。换句话说，每个多边形都没有 MOVETO 指令或曲线。这对于不支持复合路径或贝塞尔曲线的后端显示很有用。

如果 width 和 height 都非零，那么线条将被简化，以便剪裁 (0, 0) 和 (width, height) 之外的顶点。

如果路径的 Path.should_simplify 属性为 True，则生成的多边形将被简化。

如果 closed_only 为 True（默认值），则只返回闭合多边形，其中最后一个点与第一个点相同。路径中任何未闭合的折线都将被显式闭合。如果 closed_only 为 False，则路径中任何未闭合的多边形都将作为未闭合多边形返回，而闭合多边形将通过将最后一个点设置为与第一个点相同来显式闭合。

transformed(transform)[源代码]#

返回路径的变换副本。

另请参阅

matplotlib.transforms.TransformedPath

一个专门的路径类，它会缓存变换后的结果并在变换改变时自动更新。

classmethod unit_circle()[源代码]#

返回单位圆的只读 Path。

在大多数情况下，Path.circle() 将是您想要的。

classmethod unit_circle_righthalf()[源代码]#

返回单位圆右半部分的 Path。

请参阅 Path.circle 以了解所用近似的参考。

classmethod unit_rectangle()[源代码]#

返回从 (0, 0) 到 (1, 1) 的单位矩形的 Path 实例。

classmethod unit_regular_asterisk(numVertices)[源代码]#

返回一个单位正规星形 Path，具有给定 numVertices 和半径 1.0，中心位于 (0, 0)。

classmethod unit_regular_polygon(numVertices)[源代码]#

返回一个单位正规多边形的 Path 实例，具有给定 numVertices，使得外接圆半径为 1.0，中心位于 (0, 0)。

classmethod unit_regular_star(numVertices, innerCircle=0.5)[源代码]#

返回一个单位正规星形 Path，具有给定 numVertices 和半径 1.0，中心位于 (0, 0)。

property vertices#

Path 的顶点，表示为 (N, 2) 数组。

classmethod wedge(theta1, theta2, n=None)[源代码]#

返回从角度 theta1 到 theta2（以度为单位）的单位圆扇形的 Path。

theta2 被展开以生成 360 度内最短的扇形。也就是说，如果 theta2 > theta1 + 360，扇形将从 theta1 到 theta2 - 360，而不是一个整圆加上额外的重叠。

如果提供了 n，它是要生成的样条段的数量。如果未提供 n，则样条段的数量将根据 theta1 和 theta2 之间的增量确定。

请参阅 Path.arc 以了解所用近似的参考。

matplotlib.path.get_path_collection_extents(master_transform, paths, transforms, offsets, offset_transform)[源代码]#

获取 PathCollection 内部对象的边界框。

也就是说，给定一个 Path、Transform 对象和偏移量的序列（如 PathCollection 中所发现的），返回包含所有这些对象的边界框。

参数:
master_transformTransform 类型

应用于所有路径的全局变换。

pathsPath 列表
transformsAffine2DBase 列表

如果非空，此项将覆盖 master_transform。

offsets(N, 2) 类数组
offset_transformAffine2DBase 类型

在路径偏移之前应用于偏移量的变换。

备注

paths、transforms 和 offsets 的组合方式与集合相同：每个都独立迭代，因此，如果您有 3 个路径（A、B、C）、2 个变换（α、β）和 1 个偏移量（O），它们的组合如下：

  • (A, α, O)

  • (B, β, O)

  • (C, α, O)

在此页