Pygame详解（十八）：mask 模块

pygame.mask

Pygame 中处理图形遮罩的模块。

函数

• pygame.mask.from_surface()  ——  从指定 Surface 对象中返回一个 Mask
• pygame.mask.from_threshold()  ——  从给定阈值的 Surface 对象中创建一个 Mask

类

• pygame.mask.Mask  ——   用于表示 2d 位掩码（遮罩）的 Pygame 对象

用于快速实现完美的碰撞检测，Mask 可以精确到 1 个像素级别的判断。

Pygame 1.8 新增加的。

函数详解

pygame.mask.from_surface()

从指定 Surface 对象中返回一个 Mask。

from_surface(Surface, threshold = 127) -> Mask

Surface 对象中透明的部分设置为 1，不透明部分设置为 0。

检查每个像素的 alpha 值是否大于 threshold 参数指定的值。（alpha 通道使用 0 ~ 255 描述像素的透明度）

如果 Surface 对象是基于 colorkeys 实现的透明（而不是基于 pixel alphas），则忽略 threshold 参数。

注：关于 Surface 对象的透明实现，可参考：Pygame详解（十二）：Surface 对象

pygame.mask.from_threshold()

从给定阈值的 Surface 对象中创建一个 Mask。

from_threshold(Surface, color, threshold = (0,0,0,255), othersurface = None, palette_colors = 1) -> Mask

从 Surface 对象中获取 Mask，这个方法更有特色。如果只提供一个 Surface 对象，那么 Surface 对象中所有与 threshold 参数提供颜色匹配的像素均被选入 Mask 中。如果指定了 othersurface 可选参数，那么被选入 Mask 中的像素不仅需要与 threshold 参数提供颜色匹配，还需要包含在 othersurface 指定的 Surface 对象中。

class pygame.mask.Mask

用于表示 2d 位掩码（遮罩）的 Pygame 对象。

Mask((width, height)) -> Mask

方法

• pygame.mask.Mask.get_size()  ——  返回 Mask 的大小
• pygame.mask.Mask.get_at()  ——  如果像素 (x, y) 被设置，返回值是非 0
• pygame.mask.Mask.set_at()  ——  设置 Mask 中给定位置的值
• pygame.mask.Mask.overlap()  ——  返回两个 Mask 在指定偏移处的重叠坐标（如果没有返回 None）
• pygame.mask.Mask.overlap_area()  ——  返回两个 Mask 重叠的像素数量
• pygame.mask.Mask.overlap_mask()  ——  将两个 Mask 重叠的部分创建一个新的 Mask
• pygame.mask.Mask.fill()  ——  将所有的位设置为 1
• pygame.mask.Mask.clear()  ——  将所有的位设置为 0
• pygame.mask.Mask.invert()  ——  翻转 Mask 中所有的位（0 变 1，1 变 0）
• pygame.mask.Mask.scale()  ——  缩放 Mask 的尺寸
• pygame.mask.Mask.draw()  ——  将 Mask 绘制到另一个 Mask 上边
• pygame.mask.Mask.erase()  ——  用另一个 Mask 擦除 Mask
• pygame.mask.Mask.count()  ——  返回 Mask 被设置（为 1）的像素的数量
• pygame.mask.Mask.centroid()  ——  返回 Mask 的重心点
• pygame.mask.Mask.angle()  ——  返回像素的方向
• pygame.mask.Mask.outline()  ——  用列表的形式返回组成对象轮廓的点
• pygame.mask.Mask.convolve()  ——  返回其它 Mask 的卷积
• pygame.mask.Mask.connected_component()  ——  返回与某像素区域的连接的 Mask
• pygame.mask.Mask.connected_components()  ——  返回一组连接某像素区域的 Mask 的列表
• pygame.mask.Mask.get_bounding_rects()  ——  返回一组像素边界矩形的列表

方法详解

pygame.mask.Mask.get_size()

返回 Mask 的大小。

get_size() -> width,height

pygame.mask.Mask.get_at()

如果像素 (x, y) 被设置，返回值是非 0。

get_at((x,y)) -> int

跟 Surface 对象一样，(0, 0) 表示左上角坐标。

pygame.mask.Mask.set_at()

设置 Mask 中给定位置的值。

set_at((x,y),value) -> None

pygame.mask.Mask.overlap()

返回两个 Mask 在指定偏移处的重叠坐标（如果没有返回 None）。

overlap(othermask, offset) -> x,y

重叠检测的偏移原理如下（偏移可以为负数）：

+----+----------..
|A   | yoffset
|  +-+----------..
+--|B
|xoffset
|  |
:  :

pygame.mask.Mask.overlap_area()

返回两个 Mask 重叠的像素数量。

overlap_area(othermask, offset) -> numpixels

返回两个 Mask 重叠的像素数量，这可以用于查看在某方向上发生碰撞的部分，或者查看两个 Mask 有多少部分发生碰撞。相似的碰撞一般会通过计算重叠部分的梯度差分被发现。

dx = Mask.overlap_area(othermask,(x+1,y)) - Mask.overlap_area(othermask,(x-1,y))
dy = Mask.overlap_area(othermask,(x,y+1)) - Mask.overlap_area(othermask,(x,y-1))

pygame.mask.Mask.overlap_mask()

将两个 Mask 重叠的部分创建一个新的 Mask。

overlap_mask(othermask, offset) -> Mask

返回的 Mask 尺寸是原始 Mask 和 othermask 参数指定的 Mask 重叠部分。

pygame.mask.Mask.fill()

将所有的位设置为 1。

fill() -> None

将 Mask 中所有的位设置为 1。

pygame.mask.Mask.clear()

将所有的位设置为 0。

clear() -> None

将 Mask 中所有的位设置为 0。

pygame.mask.Mask.invert()

翻转 Mask 中所有的位（0 变 1，1 变 0）。

invert() -> None

翻转 Mask 中所有的位（0 变 1，1 变 0）。

pygame.mask.Mask.scale()

缩放 Mask 的尺寸。

scale((x, y)) -> Mask

Mask 根据指定尺寸缩放后返回一个新的 Mask。

pygame.mask.Mask.draw

将 Mask 绘制到另一个 Mask 上边。

draw(othermask, offset) -> None

将 Mask 绘制到另一个 Mask 上边，执行的是按位 or 操作。

pygame.mask.Mask.erase()

用另一个 Mask 擦除 Mask。

erase(othermask, offset) -> None

从 Mask 上擦除 othermask 指定的像素。

pygame.mask.Mask.count()

返回 Mask 被设置（为 1）的像素的数量。

count() -> pixels

返回 Mask 被设置（为 1）的像素的数量。

pygame.mask.Mask.centroid()

返回 Mask 的重心点。

centroid() -> (x, y)

找到 Mask 的重心点。如果 Mask 是空的，那么返回值是 (0, 0)。

pygame.mask.Mask.angle()

返回像素的方向。

angle() -> theta

找到图像中像素的大致方向（-90 度 ~ 90 度），这对于实现像素对接很有用。如果 Mask 是空的，那么返回值是 0.0。

pygame.mask.Mask.outline()

用列表的形式返回组成对象轮廓的点。

outline(every = 1) -> [(x,y), (x,y) ...]

返回值是一个由点组成的列表，用于描绘穿过 Mask 的第一个对象的轮廓线。

every 可选参数用于设置点的跨度，默认是每 1 个像素。

pygame.mask.Mask.convolve()

返回其它 Mask 的卷积。

convolve(othermask, outputmask=None, offset=(0,0)) -> Mask

返回一个由位组 (i-offset[0], j-offset[1]) 组成的 Mask，如果转换的 othermask 参数在右下角 (i, j) 处，那么会与自身重叠。

如果 outputmask 参数被指定，那么就会在 outputmask 参数上进行绘制，outputmask 参数会被返回。否则这个 Mask 的大小是 self.get_size() + othermask.get_size() - (1, 1)。

pygame.mask.Mask.connected_component()

返回与某像素区域的连接的 Mask。

connected_component((x,y) = None) -> Mask

它会使用 SAUF 算法进行连接需要连接的 Mask。它会连通 8 个点。默认情况下，它会返回在连接图像中最大的 Mask。可选项: 一对指定的坐标，与其相连的组件会被返回。如果像素位置没有被设置，那么返回的这个 Mask 就是空的。这个 Mask 的大小会与原始 Mask 一样。

pygame.mask.Mask.connected_components()

返回一组连接某像素区域的 Mask 的列表。

connected_components(min = 0) -> [Masks]

返回一组连接某像素区的 Mask 的列表。min 可选参数用于对每个连接区的指定部分过滤噪点。

pygame.mask.Mask.get_bounding_rects()

返回一组像素边界矩形的列表。

get_bounding_rects() -> Rects

它会获取连接着像素块的边界矩形。每个边界矩形都是一个连接每个像素的内矩形。