pygame.mask
pygame module for image masks.

pygame.mask.from_surface

Returns 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

Useful for fast pixel perfect collision detection. A mask uses 1 bit per-pixel to store which parts collide.

New in pygame 1.8.

Starting from pygame 1.9.5 masks with width or height 0 are supported.

pygame.mask.from_surface()
Returns a Mask from the given surface.
from_surface(Surface, threshold = 127) -> Mask

Makes the transparent parts of the Surface not set, and the opaque parts set.

The alpha of each pixel is checked to see if it is greater than the given threshold.

If the Surface is color-keyed, then threshold is not used.

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

This is a more-featureful method of getting a Mask from a Surface. If supplied with only one Surface, all pixels within the threshold of the supplied color are set in the Mask. If given the optional othersurface, all pixels in Surface that are within the threshold of the corresponding pixel in othersurface are set in the 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.get_size

Returns the size of the mask.

pygame.mask.Mask.get_at

Returns nonzero if the bit at (x,y) is set.

pygame.mask.Mask.set_at

Sets the position in the mask given by x and y.

pygame.mask.Mask.overlap

Returns the point of intersection if the masks overlap with the given offset - or None if it does not overlap.

pygame.mask.Mask.overlap_area

Returns the number of overlapping 'pixels'.

pygame.mask.Mask.overlap_mask

Returns a mask of the overlapping pixels

pygame.mask.Mask.fill

Sets all bits to 1

pygame.mask.Mask.clear

Sets all bits to 0

pygame.mask.Mask.invert

Flips the bits in a Mask

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 pixels

pygame.mask.Mask.centroid

Returns the centroid of the pixels in a Mask

pygame.mask.Mask.angle

Returns the orientation of the pixels

pygame.mask.Mask.outline

list of points outlining an object

pygame.mask.Mask.convolve

Return the convolution of self with another mask.

pygame.mask.Mask.connected_component

Returns a mask of a connected region of pixels.

pygame.mask.Mask.connected_components

Returns a list of masks of connected regions of pixels.

pygame.mask.Mask.get_bounding_rects

Returns a list of bounding rects of regions of set pixels.

A Mask object is used to represent a 2D bitmask. Each bit in the mask represents a pixel. 1 is used to indicate a set bit and 0 is used to indicate an unset bit. Set bits in a mask can be used to detect collisions with other masks and their set bits.

A filled mask has all of its bits set to 1, conversely an unfilled/cleared mask has all of its bits set to 0. Masks can be created unfilled (default) or filled by using the fill parameter. Masks can also be cleared or filled using the pygame.mask.Mask.clear()Sets all bits to 0 and pygame.mask.Mask.fill()Sets all bits to 1 methods respectively. Individual bits can be accessed using the pygame.mask.Mask.get_at()Returns nonzero if the bit at (x,y) is set. and pygame.mask.Mask.set_at()Sets the position in the mask given by x and y. methods.

Parameters
  • size (tuple(int, int) or list[int, int]) -- the dimensions of the mask (width and height)

  • fill (bool) -- create mask unfilled (False - default) or filled (True)

Return type

Mask

New in pygame 1.9.5: Named parameter size (previously it was an unnamed positional parameter) and the optional keyword parameter fill.

get_size()
Returns the size of the mask.
get_size() -> width,height
get_at()
Returns nonzero if the bit at (x,y) is set.
get_at((x,y)) -> int

Coordinates start at (0,0) is top left - just like Surfaces.

set_at()
Sets the position in the mask given by x and y.
set_at((x,y),value) -> None
overlap()
Returns the point of intersection if the masks overlap with the given offset - or None if it does not overlap.
overlap(othermask, offset) -> x,y

The overlap tests uses the following offsets (which may be negative):

+----+----------..
|A   | yoffset
|  +-+----------..
+--|B
|xoffset
|  |
:  :
overlap_area()
Returns the number of overlapping 'pixels'.
overlap_area(othermask, offset) -> numpixels

You can see how many pixels overlap with the other mask given. This can be used to see in which direction things collide, or to see how much the two masks collide. An approximate collision normal can be found by calculating the gradient of the overlap area through the finite difference.

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))
overlap_mask()
Returns a mask of the overlapping pixels
overlap_mask(othermask, offset) -> Mask

Returns a Mask the size of the original Mask containing only the overlapping pixels between Mask and othermask.

fill()
Sets all bits to 1
fill() -> None

Sets all bits in a Mask to 1.

clear()
Sets all bits to 0
clear() -> None

Sets all bits in a Mask to 0.

invert()
Flips the bits in a Mask
invert() -> None

Flips all of the bits in a Mask, so that the set pixels turn to unset pixels and the unset pixels turn to set pixels.

scale()
Resizes a mask
scale((x, y)) -> Mask

Returns a new Mask of the Mask scaled to the requested size.

draw()
Draws a mask onto another
draw(othermask, offset) -> None

Performs a bitwise OR, drawing othermask onto Mask.

erase()
Erases a mask from another
erase(othermask, offset) -> None

Erases all pixels set in othermask from Mask.

count()
Returns the number of set pixels
count() -> pixels

Returns the number of set pixels in the Mask.

centroid()
Returns the centroid of the pixels in a Mask
centroid() -> (x, y)

Finds the centroid, the center of pixel mass, of a Mask. Returns a coordinate tuple for the centroid of the Mask. In the event the Mask is empty, it will return (0,0).

angle()
Returns the orientation of the pixels
angle() -> theta

Finds the approximate orientation of the pixels in the image from -90 to 90 degrees. This works best if performed on one connected component of pixels. It will return 0.0 on an empty Mask.

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

Returns a list of points of the outline of the first object it comes across in a Mask. For this to be useful, there should probably only be one connected component of pixels in the Mask. The every option allows you to skip pixels in the outline. For example, setting it to 10 would return a list of every 10th pixel in the outline.

convolve()
Return the convolution of self with another mask.
convolve(othermask) -> Mask
convolve(othermask, outputmask=None, offset=(0,0)) -> Mask

Convolve self with the given othermask.

Parameters
  • othermask (Mask) -- mask to convolve with self

  • outputmask (Mask or None) -- mask for output, default is None

  • offset (tuple(int, int) or list[int, int]) -- offset used in convolution of masks, default is (0, 0)

Returns

A mask with the (i - offset[0], j - offset[1]) bit set, if shifting othermask (such that its bottom right corner pixel is at (i, j)) causes it to overlap with self.

If an outputmask is specified, the output is drawn onto it and it is returned. Otherwise a mask of size (MAX(0, width + othermask's width - 1), MAX(0, height + othermask's height - 1)) is created and returned.

Return type

Mask

connected_component()
Returns a mask of a connected region of pixels.
connected_component((x,y) = None) -> Mask

This uses the SAUF algorithm to find a connected component in the Mask. It checks 8 point connectivity. By default, it will return the largest connected component in the image. Optionally, a coordinate pair of a pixel can be specified, and the connected component containing it will be returned. In the event the pixel at that location is not set, the returned Mask will be empty. The Mask returned is the same size as the original Mask.

connected_components()
Returns a list of masks of connected regions of pixels.
connected_components(min = 0) -> [Masks]

Returns a list of masks of connected regions of pixels. An optional minimum number of pixels per connected region can be specified to filter out noise.

get_bounding_rects()
Returns a list of bounding rects of regions of set pixels.
get_bounding_rects() -> Rects

This gets a bounding rect of connected regions of set pixels. A bounding rect is one for which each of the connected pixels is inside the rect.




Edit on GitHub