Pygame详解（十八）：mask 模块

关注

转载最新推荐文章于 2026-07-03 12:37:33 发布 1.6k 阅读 AI 写同款· GEO 优化 ›

Pygame学习笔记7：精灵冲突及Zombie Mob游戏上一章我们对于冲突的检测只是使用的pygame的最简单的冲突检测，即只是两个精灵之间的冲突检测，但是pygame支持多种冲突检测技术，因此这一章就来学习一下这些冲突检测技术。冲突检测技术两个精灵之间的矩形检测这个方法在上一章中已经讲过了，就是使用pygame.sprite.collide_rect()方法进行一对一的检测，需要传递两个参数，都是pygame.sprite.Sprite派生出来的对象，具体来讲就是关键要有一个rect的Rect属性可用，实例如下：对于如下的类： # 类中的X、Y、pos 阅读详情

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）。