pygame2.mask – image masks for fast pixel-perfect overlap checks

A module for image masks, suitable for fast pixel-perfect collision detections.

Module Functions

pygame2.mask.from_surface(surface, threshold) → :class:`Mask`

Returns a Mask from the given pygame2.sdl.video.Surface.

Makes the transparent parts of the pygame2.sdl.video.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 pygame2.sdl.video.Surface is color keyed, then threshold is not used.

This requires pygame2 to be built with SDL support enabled.

pygame2.mask.from_threshold(surface, color[, threshold, thressurface]) → :class:`Mask`

Creates a Mask by thresholding surfaces.

This is a more featureful method of getting a Mask from a pygame2.sdl.video.Surface. If supplied with only one pygame2.sdl.video.Surface, all pixels within the threshold of the supplied color are set in the :class`Mask`. If given the optional thressurface, all pixels in surface that are within the threshold of the corresponding pixel in thressurface are set in the Mask.

Mask

class pygame2.mask.Mask(width, height) → Mask
class pygame2.mask.Mask(size) → Mask
Creates a new Mask object with the specified width and height.

Attributes

Mask.angle
Gets the orientation of the pixels. 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.
Mask.centroid
Gets the centroid, the center of pixel mass, of the pixels in a Mask. Returns a coordinate tuple for the centroid of the Mask. If the Mask is empty, it will return (0, 0).
Mask.count
Gets the amount of set bits in the Mask.
Mask.height
Gets the height of the Mask.
Mask.size
Gets the width and height of the Mask as tuple.
Mask.width
Gets the width of the Mask.

Methods

Mask.clear() → None

Clears all bits in the Mask.

Resets the state of all bits in the Mask to 0.

Mask.connected_component([x, y]) → Mask
Mask.connected_component([point]) → Mask

Returns a Mask of a connected region of pixels.

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.

Mask.connected_components([min]) → Mask

Returns a Mask of a connected region of pixels.

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.

Mask.convolve(mask[, outputmask, point]) → Mask
Mask.convolve(mask[, outputmask, x, y]) → Mask

Return the convolution with another Mask.

Returns a Mask with the [x-offset[0], y-offset[1]] bit set if shifting mask so that it’s lower right corner pixel is at (x, y) would cause it to overlap with self.

If an outputmask is specified, the output is drawn onto outputmask and outputmask is returned. Otherwise a mask of size size + mask.:attr:size - (1, 1) is created.

Mask.draw(mask, x, y) → None
Mask.draw(mask, point) → None

Draws the passed Mask onto the Mask.

This performs a bitwise OR operation upon the calling Mask. The passed mask‘s start offset for the draw operation will be the x and y offset passed to the method.

Mask.erase(mask, x, y) → None
Mask.erase(mask, point) → None

Erases the passed Mask from the Mask.

This performs a bitwise NAND operation upon the calling Mask. The passed mask‘s start offset for the erase operation will be the x and y offset passed to the method.

Mask.fill() → None
Sets all bits to 1 within the Mask.
Mask.get_at(x, y) → int
Mask.get_at(point) → int
Gets the bit value at the desired location.
Mask.get_bounding_rects() → [Mask, Mask, ...]

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

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

Mask.invert() → None
Inverts all bits in the Mask.
Mask.outline([skip]) → [(x1, y1), (x2, y2), ...]

Gets the points outlining an object on the mask.

Returns a list of points of the outline of the first object it comes across in the Mask. For this to be useful, there should probably only be one connected component of pixels in the Mask. The skip 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.

Mask.overlap(mask, x, y) → int, int
Mask.overlap(mask, point) → int, int

Returns nonzero if the masks overlap with the given offset.

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

+----+----------...
|A   | yoffset
|  +-+----------...
+--|B
|xoffset
|  |
|  |
:  :
Mask.overlap_area(mask, x, y) → int
Mask.overlap_area(mask, point) → int

Returns the number of overlapping bits of two Masks.

This returns how many pixels overlap with the other mask given. It can be used to see in which direction things collide, or to see how much the two masks collide.

Mask.overlap_mask(mask, x, y) → Mask
Mask.overlap_mask(mask, point) → Mask
Returns a Mask with the overlap of two other masks. A bitwise AND.
Mask.scale(width, height) → Mask
Mask.scale(size) → Mask

Creates a new scaled Mask with the given width and height.

The quality of the scaling may not be perfect for all circumstances, but it should be reasonable. If either width or height is 0 a clear 1x1 mask is returned.

Mask.set_at(x, y) → None
Mask.set_at(point) → None
Sets the bit value at the desired location.