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)[源代码][源代码]#

基类：object

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

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

  • vertices: 一个 (N, 2) 的浮点数组，表示顶点

  • codes：路径代码的 numpy.uint8 数组，长度为 N，或为 None

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

代码类型包括：

  • 停止1 顶点（忽略）

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

  • MOVETO1 顶点

    拿起笔并移动到给定的顶点。

  • LINETO1 顶点

    从当前位置画一条线到给定的顶点。

  • CURVE31 个控制点，1 个终点

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

  • CURVE42 个控制点，1 个终点

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

  • CLOSEPOLY1 顶点（忽略）

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

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

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

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

备注

顶点和代码数组应被视为不可变——在构造函数中，有许多优化和假设是基于初始数据进行的，这些不会在数据变化时改变。

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

参数:
顶点(N, 2) 类似数组

路径顶点，作为数组、掩码数组或成对的序列。如果有掩码值，将被转换为 NaNs，这些值将由 Agg PathIterator 和其他路径数据使用者（如 iter_segments()）正确处理。

代码类似数组或 None，可选

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

_interpolation_stepsint, 可选

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

关闭bool, 可选

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

只读bool, 可选

使路径以不可变的方式运行，并将顶点和代码设置为只读数组。

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}#

一个将路径代码映射到该代码预期顶点数量的字典。

STOP = np.uint8(0)#
classmethod arc(theta1, theta2, n=None, is_wedge=False)[源代码][源代码]#

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

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

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

classmethod circle(center=(0.0, 0.0), radius=1.0, readonly=False)[源代码][源代码]#

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

参数:
中心(float, float), 默认值: (0, 0)

圆的中心。

半径float, 默认值: 1

圆的半径。

只读布尔值

在创建 Path 实例时，是否应设置“readonly”参数。

注释

圆圈使用8个三次贝塞尔曲线近似表示，如所述。

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

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

参见

Path.iter_segments

有关关键字参数的详细信息。

clip_to_bbox(bbox, inside=True)[源代码][源代码]#

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

路径必须由一个或多个封闭的多边形组成。此算法对于未封闭的路径将无法正确运行。

如果 inside 为 True，则裁剪到盒子内部，否则裁剪到盒子外部。

code_type#

uint8 的别名

property codes#

Path 中的代码列表作为一维数组。

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

contains_path(path, transform=None)[源代码][源代码]#

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

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

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

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

路径总是被视为封闭的；即，如果最后一个代码不是 CLOSEPOLY，则假设存在一条从最后一个顶点到第一个顶点的隐式线段。

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

要检查的点 (x, y)。

变换 : Transform, 可选转换，可选

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

半径float, 默认值: 0

路径上 点 坐标中的额外边距。路径会沿着切线方向延伸 半径/2；即，如果你用 半径 的线宽绘制路径，线上所有点仍会被视为包含在区域内。相反，负值会缩小区域：虚线上的点将被视为在区域外。

返回:
布尔值

注释

当前算法有一些局限性：

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

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

  • 如果由于 半径 偏移导致边界线开始交叉，结果可能不正确。

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

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

路径总是被视为封闭的；即，如果最后一个代码不是 CLOSEPOLY，则假设存在一条从最后一个顶点到第一个顶点的隐式线段。

参数:
点(N, 2) 数组

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

变换 : Transform, 可选转换，可选

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

半径float, 默认值: 0

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

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

注释

当前算法有一些局限性：

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

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

  • 如果由于 半径 偏移导致边界线开始交叉，结果可能不正确。

copy()[源代码][源代码]#

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

deepcopy(memo=None)[源代码]#

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

get_extents(transform=None, **kwargs)[源代码][源代码]#

获取路径的边界框。

参数:
变换 : Transform, 可选转换，可选

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

**kwargs

转发到 iter_bezier。

返回:
matplotlib.transforms.Bbox

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

static hatch(hatchpattern, density=6)[源代码][源代码]#

给定一个阴影样式说明符，hatchpattern，生成一个可以在重复阴影模式中使用的 Path。density 是每平方单位内的线条数。

interpolated(steps)[源代码][源代码]#

返回一个新的路径，重新采样为长度 N x steps。

除了 LINETO 之外的代码没有被正确处理。

intersects_bbox(bbox, filled=True)[源代码][源代码]#

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

如果 filled 为 True，那么如果路径完全包围 `.Bbox`（即，路径被视为填充的），则此函数也返回 True。

边界框始终被视为填充。

intersects_path(other, filled=True)[源代码][源代码]#

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

如果 filled 为 True，那么如果一条路径完全包围另一条路径（即，路径被视为填充的），则此函数也返回 True。

iter_bezier(**kwargs)[源代码][源代码]#

遍历 Path 中的每一条 Bézier 曲线（包括线段）。

参数:
**kwargs

转发至 iter_segments。

Yields:
BBezierSegment

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

代码 : code_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)[源代码][源代码]#

遍历路径中的所有曲线段。

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

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

参数:
transform : None 或 Transform无或

如果非 None，给定的仿射变换将被应用于路径。

remove_nansbool, 可选

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

剪辑None 或 (float, float, float, float)，可选

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

快照None 或 bool, 可选

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

stroke_width浮点数，可选

正在绘制的笔画的宽度（用于路径捕捉）。

简化None 或 bool, 可选

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

曲线bool, 可选

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

草图None 或序列，可选

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

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

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

classmethod make_compound_path_from_polys(XY)[源代码][源代码]#

创建一个复合 Path 对象以绘制多个边数相同的多边形。

(Source code, 2x.png, png)

(2x.png, png)

参数:
XY(numpolys, numsides, 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.circle() 将是你想要的。

classmethod unit_circle_righthalf()[源代码][源代码]#

返回单位圆右侧的 Path。

参见 Path.circle 以了解所使用的近似方法的参考。

classmethod unit_rectangle()[源代码][源代码]#

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

classmethod unit_regular_asterisk(numVertices)[源代码][源代码]#

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

classmethod unit_regular_polygon(numVertices)[源代码][源代码]#

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

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

返回一个 路径 ，用于具有给定 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_transform转换

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

路径 : 路径 的列表列表
变换 : Affine2DBase 的列表列表

如果非空，这将覆盖 master_transform。

偏移量(N, 2) 类似数组
offset_transformAffine2DBase

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

注释

路径、变换 和 偏移 的组合方式与集合相同：每个都是独立迭代的，所以如果你有3个路径（A、B、C）、2个变换（α、β）和1个偏移（O），它们的组合如下：

  • (A, α, O)

  • (B, β, O)

  • (C, α, O)

On this page