pygame.mask — pygame v2.1.3 documentation

pygame.mask

pygame module for image masks.

pygame.mask.from_surface	—	Creates a Mask from the given surface
pygame.mask.from_threshold	—	Creates a mask by thresholding Surfaces
pygame.mask.Mask	—	pygame object for representing 2D bitmasks

对于快速的像素完美碰撞检测非常有用。遮罩使用每像素1位来存储哪些部分发生碰撞。

New in pygame 1.8.

Changed in pygame 2.0.2: 掩码函数现在支持关键字参数。

Changed in pygame 2.0.2: 采用位置或偏移量的掩码函数现在支持 pygame.math.Vector2a 2-Dimensional Vector 争论。

pygame.mask.from_surface()¶

Creates a Mask from the given surface
from_surface(surface) -> Mask
from_surface(surface, threshold=127) -> Mask

创建一个 Mask 通过设置所有不透明像素而不设置透明像素，从给定的表面创建对象。

如果曲面使用色键，则使用它来决定设置结果遮罩中的哪些位。所有的像素都是 not 与色键相同的是 set 并且不设置等于色键的像素。

如果没有使用颜色键，则使用每个像素的Alpha值来决定设置结果掩码中的哪些位。具有Alpha值的所有像素大于这个 threshold 参数为 set 和Alpha值小于或等于 threshold 都没有设置。

参数

surface (Surface) -- 要从中创建遮罩的曲面
threshold (int) -- 与每个表面像素的Alpha值进行比较的Alpha阈值(默认为127)，如果 surface 是否设置了颜色键此参数将被忽略

返回

一个新创建的 Mask 对象从给定曲面

返回类型

Mask

备注

此函数用于为以下对象创建掩码 pygame.sprite.collide_mask()Collision detection between two sprites, using masks. 。

pygame.mask.from_threshold()¶

Creates a mask by thresholding Surfaces
from_threshold(surface, color) -> Mask
from_threshold(surface, color, threshold=(0, 0, 0, 255), othersurface=None, palette_colors=1) -> Mask

这是一种更有特色的方法来获取 Mask 从表面上看。

如果可选的 othersurface 不使用，则所有像素在这个 threshold 的 color 参数为 set 在生成的蒙版中。

如果可选的 othersurface ，则第一个曲面中的每个像素都是在这个 threshold 中的相应像素的 othersurface 是 set 在生成的蒙版中。

参数

surface (Surface) -- 要从中创建遮罩的曲面
color (Color or int or tuple(int, int, int, [int]) or list[int, int, int, [int]]) -- 用于检查表面像素是否在给定范围内的颜色 threshold 范围，如果可选的 othersurface 提供了参数
threshold (Color or int or tuple(int, int, int, [int]) or list[int, int, int, [int]]) -- (可选)用于检查两种颜色之间差异的阈值范围(默认为 (0, 0, 0, 255) )
othersurface (Surface) -- (可选)用于检查第一个表面的像素是否在给定的 threshold 此表面的像素范围(默认为 None )
palette_colors (int) -- (可选)指示是否使用调色板颜色，非零值表示使用调色板颜色，0表示不使用调色板颜色(默认为1)

返回

一个新创建的 Mask 对象从给定曲面

返回类型

Mask

pygame.mask.Mask¶

pygame object for representing 2D bitmasks
Mask(size=(width, height)) -> Mask
Mask(size=(width, height), fill=False) -> Mask

pygame.mask.Mask.copy	—	Returns a new copy of the mask
pygame.mask.Mask.get_size	—	Returns the size of the mask
pygame.mask.Mask.get_rect	—	Returns a Rect based on the size of the mask
pygame.mask.Mask.get_at	—	Gets the bit at the given position
pygame.mask.Mask.set_at	—	Sets the bit at the given position
pygame.mask.Mask.overlap	—	Returns the point of intersection
pygame.mask.Mask.overlap_area	—	Returns the number of overlapping set bits
pygame.mask.Mask.overlap_mask	—	Returns a mask of the overlapping set bits
pygame.mask.Mask.fill	—	Sets all bits to 1
pygame.mask.Mask.clear	—	Sets all bits to 0
pygame.mask.Mask.invert	—	Flips all the bits
pygame.mask.Mask.scale	—	Resizes a mask
pygame.mask.Mask.draw	—	Draws a mask onto another
pygame.mask.Mask.erase	—	Erases a mask from another
pygame.mask.Mask.count	—	Returns the number of set bits
pygame.mask.Mask.centroid	—	Returns the centroid of the set bits
pygame.mask.Mask.angle	—	Returns the orientation of the set bits
pygame.mask.Mask.outline	—	Returns a list of points outlining an object
pygame.mask.Mask.convolve	—	Returns the convolution of this mask with another mask
pygame.mask.Mask.connected_component	—	Returns a mask containing a connected component
pygame.mask.Mask.connected_components	—	Returns a list of masks of connected components
pygame.mask.Mask.get_bounding_rects	—	Returns a list of bounding rects of connected components
pygame.mask.Mask.to_surface	—	Returns a surface with the mask drawn on it

A Mask 对象用于表示二维位掩码。掩码中的每一位代表一个像素。1用于指示设置的位，而0用于指示未设置的位。掩码中的设置位可用于检测与其他掩码及其设置位的冲突。

填充掩码的所有位设置为1，反之，未填充/清除/空掩码的所有位设置为0。蒙版可以创建为未填充(默认)，也可以使用 fill 参数。也可以使用 pygame.mask.Mask.clear()Sets all bits to 0 和 pygame.mask.Mask.fill()Sets all bits to 1 方法分别进行比较研究。

蒙版的坐标从左上角开始 (0, 0) 就像 pygame.Surfacepygame object for representing images 。单个位可以使用 pygame.mask.Mask.get_at()Gets the bit at the given position 和 pygame.mask.Mask.set_at()Sets the bit at the given position 方法。

这些方法 overlap() ， overlap_area() ， overlap_mask() ， draw() ， erase() ，以及 convolve() 使用Offset参数指示另一个掩码的左上角相对于调用掩码的左上角的偏移量。调用掩码的左上角被认为是原点 (0, 0) 。偏移量是两个值的序列 (x_offset, y_offset) 。支持正负偏移值。

           0 to x (x_offset)
           :    :
   0 ..... +----:---------+
   to      |    :         |
   y .......... +-----------+
(y_offset) |    | othermask |
           |    +-----------+
           | calling_mask |
           +--------------+

参数

size -- 蒙版的尺寸(宽度和高度)
fill (bool) -- (可选)创建未填充蒙版(默认： False )或填充蒙版 (True )

返回

一个新创建的 Mask 对象

返回类型

Mask

Changed in pygame 2.0.0: 添加了对浅层复制的支持。这个 Mask 类支持该特殊方法 __copy__() 和浅层复制通过 copy.copy(mask) 。

Changed in pygame 2.0.0: 添加了子类化支持。这个 Mask 类可以用作基类。

Changed in pygame 1.9.5: 添加了对关键字参数的支持。

Changed in pygame 1.9.5: 添加了可选的关键字参数 fill 。

Changed in pygame 1.9.5: 添加了对宽度和/或高度为0的蒙版的支持。

copy()¶

Returns a new copy of the mask

copy() -> Mask

返回: 作为此掩码的新副本，新掩码将具有与原始掩码相同的宽度、高度和设置/未设置位
返回类型: Mask

备注

如果掩码子类需要复制任何特定于实例的属性，则它应该重写 __copy__() 方法。被超越的 __copy__() 方法需要调用 super().__copy__() 然后复制所需的数据，如下面的示例代码所示。

class SubMask(pygame.mask.Mask):
    def __copy__(self):
        new_mask = super().__copy__()
        # Do any SubMask attribute copying here.
        return new_mask

New in pygame 2.0.0.

get_size()¶

Returns the size of the mask

get_size() -> (width, height)

返回: 蒙版的大小(宽度、高度)
返回类型: tuple(int, int)

get_rect()¶

Returns a Rect based on the size of the mask

get_rect(**kwargs) -> Rect

返回一个新的 pygame.Rect()pygame object for storing rectangular coordinates 基于此遮罩的大小创建。RECT的默认位置将为 (0, 0) 它的默认宽度和高度将与此掩码的相同。 pygame.Rect()pygame object for storing rectangular coordinates 传入此方法的属性关键字参数/值。举个例子， a_mask.get_rect(center=(10, 5)) 将创建一个 pygame.Rect()pygame object for storing rectangular coordinates 基于在给定位置居中的遮罩大小。

参数: kwargs (dict) -- pygame.Rect()pygame object for storing rectangular coordinates 将应用于RECT的属性关键字参数/值
返回: 一个新的 pygame.Rect()pygame object for storing rectangular coordinates 基于此掩码的大小使用任何 pygame.Rect()pygame object for storing rectangular coordinates 应用于其的属性关键字参数/值
返回类型: Rect

New in pygame 2.0.0.

get_at()¶

Gets the bit at the given position

get_at(pos) -> int

参数: pos -- 要获取的位的位置(x，y)
返回: 如果该位已设置，则为1；如果未设置该位，则为0
返回类型: int
引发: IndexError -- 如果位置在遮罩边界之外

set_at()¶

Sets the bit at the given position
set_at(pos) -> None
set_at(pos, value=1) -> None

参数

pos -- 要设置的位的位置(x，y)
value (int) -- 任何非零整型都会将位设置为1，0会将位设置为0(默认为1)

返回

None

返回类型

NoneType

引发

IndexError -- 如果位置在遮罩边界之外

overlap()¶

Returns the point of intersection
overlap(other, offset) -> (x, y)
overlap(other, offset) -> None

返回在此掩码和之间遇到的第一个交点 other 。交点是2个重叠的集合比特。

当前的算法搜索重叠区域 sizeof(unsigned long int) * CHAR_BIT 位宽列块(的值 sizeof(unsigned long int) * CHAR_BIT 依赖于平台，为了清楚起见，它将被称为 W )。从左上角开始，它检查位0到 W - 1 第一行的 ((0, 0) 至 (W - 1, 0) )，然后继续到下一行 ((0, 1) 至 (W - 1, 1) )。一旦检查完整个列块，它就会继续下一个 (W 至 2 * W - 1 )。重复此操作，直到找到交点或检查整个重叠区域。

参数

other (Mask) -- 要与此遮罩重叠的另一个遮罩
offset -- 的偏移 other 有关更多详细信息，请参阅 Mask offset notes

返回

交点或 None 如果没有交叉点

返回类型

tuple(int, int) or NoneType

overlap_area()¶

Returns the number of overlapping set bits

overlap_area(other, offset) -> numbits

返回此掩码和之间的重叠设置位数 other 。

这对于碰撞检测非常有用。通过有限差分法计算重叠区域的梯度，可以得到近似的碰撞法线。

dx = mask.overlap_area(other, (x + 1, y)) - mask.overlap_area(other, (x - 1, y))
dy = mask.overlap_area(other, (x, y + 1)) - mask.overlap_area(other, (x, y - 1))

参数

other (Mask) -- 要与此遮罩重叠的另一个遮罩
offset -- 的偏移 other 有关更多详细信息，请参阅 Mask offset notes

返回

重叠的集合位数

返回类型

int

overlap_mask()¶

Returns a mask of the overlapping set bits

overlap_mask(other, offset) -> Mask

返回一个 Mask ，与此掩码大小相同，包含此掩码和 other 。

参数

other (Mask) -- 要与此遮罩重叠的另一个遮罩
offset -- 的偏移 other 有关更多详细信息，请参阅 Mask offset notes

返回

一个新创建的 Mask 设置了重叠的位

返回类型

Mask

fill()¶

Sets all bits to 1

fill() -> None

将掩码中的所有位设置为1。

返回: None
返回类型: NoneType

clear()¶

Sets all bits to 0

clear() -> None

将掩码中的所有位设置为0。

返回: None
返回类型: NoneType

invert()¶

Flips all the bits

invert() -> None

翻转掩码中的所有位。所有设置位被清0，所有未设置位被设置为1。

返回: None
返回类型: NoneType

scale()¶

Resizes a mask

scale((width, height)) -> Mask

创建一个新的 Mask 其位从该掩码缩放的请求大小的。

参数: size -- 要创建的蒙版的宽度和高度(大小)
返回: 一个新的 Mask 对象，其位从该掩码缩放
返回类型: Mask
引发: ValueError -- 如果 width < 0 或 height < 0

draw()¶

Draws a mask onto another

draw(other, offset) -> None

执行按位或，绘制 othermask 放在这个面具上。

参数

other (Mask) -- 要绘制到此遮罩上的遮罩
offset -- 的偏移 other 有关更多详细信息，请参阅 Mask offset notes

返回

None

返回类型

NoneType

erase()¶

Erases a mask from another

erase(other, offset) -> None

擦除(清除)中设置的所有位 other 从这个面具上。

参数

other (Mask) -- 要从此掩码中擦除的掩码
offset -- 的偏移 other 有关更多详细信息，请参阅 Mask offset notes

返回

None

返回类型

NoneType

count()¶

Returns the number of set bits

count() -> bits

返回: 掩码中的设置位数
返回类型: int

centroid()¶

Returns the centroid of the set bits

centroid() -> (x, y)

查找此遮罩的质心(设置位的中心质量)。

返回: 指示遮罩质心的坐标元组，则它将返回 (0, 0) 如果掩码没有设置任何位
返回类型: tuple(int, int)

angle()¶

Returns the orientation of the set bits

angle() -> theta

查找掩码中设置位的大致方向(从-90度到90度)。如果在只有一个连接组件的遮罩上执行此操作，效果最好。

返回: 掩码中设置位的方向，它将返回 0.0 如果掩码没有设置任何位
返回类型: float

备注

看见 connected_component() 有关如何计算连接的零部件的详细信息，请参见。

outline()¶

Returns a list of points outlining an object
outline() -> [(x, y), ...]
outline(every=1) -> [(x, y), ...]

返回遮罩中遇到的第一个连接组件的轮廓的点的列表。要查找连接的元件，请从左上角开始逐行(从左到右)搜索遮罩。

这个 every 可选参数跳过大纲中的设置位。例如，将其设置为10将返回大纲中每10个设置位的列表。

参数: every (int) -- (可选)指示大纲中要跳过的位数(默认为1)
返回: 列出遇到的第一个连接组件的点的列表，如果掩码未设置位，则返回空列表
返回类型: list[tuple(int, int)]

备注

看见 connected_component() 有关如何计算连接的零部件的详细信息，请参见。

convolve()¶

Returns the convolution of this mask with another mask
convolve(other) -> Mask
convolve(other, output=None, offset=(0, 0)) -> Mask

将此掩码与给定的 other 面具。

参数

other (Mask) -- 要与此遮罩卷积的遮罩
output (Mask or NoneType) -- (可选)输出掩码(默认为 None )
offset -- 的偏移 other 从该掩码(缺省值为 (0, 0) )

返回

一个 Mask 使用 (i - offset[0], j - offset[1]) 位设置，如果移位 other (使其右下角位于 (i, j) )会导致它与此遮罩重叠 output 如果指定了掩码，则输出将绘制到掩码上并返回。否则，蒙版的大小 (MAX(0, width + other mask's width - 1), MAX(0, height + other mask's height - 1)) 被创建并返回。

返回类型

Mask

connected_component()¶

Returns a mask containing a connected component
connected_component() -> Mask
connected_component(pos) -> Mask

连通分量是一组(1个或更多)(垂直和对角)连接的集合比特。用于检查8点连通性的SARF算法用于在掩码中找到连通分量。

默认情况下，此方法将返回 Mask 包含掩码中最大的连通分量。或者，可以指定位坐标，并返回包含它的连接组件。如果未设置给定位置的位，则返回 Mask 将为空(未设置位)。

参数: pos -- (可选)选择包含此位置的位的连接组件
返回: 一个 Mask 对象(与此掩码大小相同)具有来自此掩码的最大连接组件，如果此掩码没有设置位，则如果 pos 参数，则返回的掩码将具有包含此位置的连接组件。则将返回空掩码 pos 参数选择未设置的位。
返回类型: Mask
引发: IndexError -- 如果可选的 pos 参数超出了掩码的范围

connected_components()¶

Returns a list of masks of connected components
connected_components() -> [Mask, ...]
connected_components(minimum=0) -> [Mask, ...]

提供一个列表，其中包含 Mask 为每个连接的组件创建。

参数: minimum (int) -- (可选)表示每个连接组件的最小位数(用于过滤噪声)(默认为0，等于无最小值，相当于将其设置为1，因为连接组件必须至少设置1位)
返回: 包含一个 Mask 对象，则在掩码未设置位的情况下返回空列表
返回类型: list[Mask]

备注

看见 connected_component() 有关如何计算连接的零部件的详细信息，请参见。

get_bounding_rects()¶

Returns a list of bounding rects of connected components

get_bounding_rects() -> [Rect, ...]

提供一个列表，其中包含每个连接组件的边框。

返回: 包含每个连接组件的边界矩形的列表，如果掩码没有设置位，则返回空列表
返回类型: list[Rect]

备注

看见 connected_component() 有关如何计算连接的零部件的详细信息，请参见。

to_surface()¶

Returns a surface with the mask drawn on it
to_surface() -> Surface
to_surface(surface=None, setsurface=None, unsetsurface=None, setcolor=(255, 255, 255, 255), unsetcolor=(0, 0, 0, 255), dest=(0, 0)) -> Surface

在给定曲面上绘制此遮罩。可以将设置位(位设置为1)和未设置位(位设置为0)绘制到曲面上。

参数

surface (Surface or None) -- (可选)要在其上绘制遮罩的曲面，如果未提供曲面，则将创建一个曲面(默认为 None ，这将导致具有以下参数的曲面 Surface(size=mask.get_size(), flags=SRCALPHA, depth=32) 要创建、绘制和返回)
setsurface (Surface or None) -- (可选)使用此表面的颜色值绘制设置位(默认为 None )，如果该表面小于掩码，则其边界之外的任何位都将使用 setcolor 价值
unsetsurface (Surface or None) -- (可选)使用此表面的颜色值绘制未设置的位(默认为 None )，如果该表面小于掩码，则其边界之外的任何位都将使用 unsetcolor 价值
setcolor (Color or str or int or tuple(int, int, int, [int]) or list(int, int, int, [int]) or None) -- 绘制设置位的颜色(缺省值为 (255, 255, 255, 255) ，白色)，使用 None 若要跳过绘制设置位，请使用 setsurface 参数(如果设置)将优先于此参数
unsetcolor (Color or str or int or tuple(int, int, int, [int]) or list(int, int, int, [int]) or None) -- 绘制未设置位的颜色(默认为 (0, 0, 0, 255) ，黑色)，使用 None 若要跳过绘制未设置位，请使用 unsetsurface 参数(如果设置)将优先于此参数
dest (Rect or tuple(int, int) or list(int, int) or Vector2(int, int)) -- (可选)要放置所绘制蒙版左上角的曲面目标(默认为 (0, 0) )，如果将RECT用作 dest 参数，则其 x 和 y 属性将用作目标， 注1： 宽度或高度值为负值的矩形在使用 x 和 y 价值观， 注2： 此目标值仅用于在表面上定位遮罩，它不会偏移 setsurface 和 unsetsurface 在蒙版中，它们始终与蒙版对齐(即位置 (0, 0) 在蒙版上始终与位置相对应 (0, 0) 在 setsurface 和 unsetsurface )

返回

这个 surface 参数(如果没有，则为新创建的曲面 surface 参数)，并在其上绘制此遮罩

返回类型

Surface

引发

ValueError -- 如果 setsurface 参数或 unsetsurface 参数的格式(字节大小/位大小/Alpha)与 surface 参数

备注

要跳过绘制设置位，两者都 setsurface 和 setcolor 一定是 None 。这个 setsurface 参数默认为 None ，但是 setcolor 默认为颜色值，因此必须设置为 None 。

备注

要跳过绘制未设置的位，两者 unsetsurface 和 unsetcolor 一定是 None 。这个 unsetsurface 参数默认为 None ，但是 unsetcolor 默认为颜色值，因此必须设置为 None 。

New in pygame 2.0.0.

Edit on GitHub

pygame documentation