Mask

Mask()

Mask(size: Vec2, filled: bool = False)

Mask(pixel_array: PixelArray, threshold: int = 1)

Overloaded function.

1. Mask()

Create an empty mask with size (0, 0).

2. Mask(size: Vec2, filled: bool = False)

Create a mask with specified size.

Args

• size (Vec2) — The size of the mask as (width, height).
• filled (bool) — Whether to fill the mask with solid pixels. Defaults to False.

3. Mask(pixel_array: PixelArray, threshold: int = 1)

Create a mask from a pixel array based on alpha threshold.

Args

• pixel_array (PixelArray) — The source pixel array to create the mask from.
• threshold (int) — Alpha threshold value (0-255). Pixels with alpha >= threshold are solid.

Raises

• RuntimeError — If the pixel array is invalid.

height: int

The height of the mask in pixels.

size: Vec2

The size of the mask as a Vec2.

width: int

The width of the mask in pixels.

add(self, other: Mask, offset: Vec2 = Vec2(0.000000, 0.000000)) -> None

Add another mask to this mask with an offset.

Performs a bitwise OR operation between the masks.

Args

• other (Mask) — The mask to add.
• offset (Vec2) — Position offset for the other mask. Defaults to (0, 0).

clear(self) -> None

Clear the entire mask, setting all pixels to transparent.

collide_mask(self, other: Mask, offset: Vec2 = Vec2(0.000000, 0.000000)) -> bool

Check collision between this mask and another mask with an offset.

Args

• other (Mask) — The other mask to test collision with.
• offset (Vec2) — Position offset between the masks. Defaults to (0, 0).

Returns

• bool — True if the masks collide, False otherwise.

copy(self) -> Mask

Create a copy of this mask.

Returns

• Mask — A new Mask with the same dimensions and pixel data.

fill(self) -> None

Fill the entire mask with solid pixels.

get_at(self, x: int, y: int) -> bool

Get the pixel value at a specific position.

Args

• x (int) — The x-coordinate of the position to check.
• y (int) — The y-coordinate of the position to check.

Returns

• bool — True if the pixel is solid (above threshold), False otherwise.

get_bounding_rect(self) -> Rect

Get the bounding rectangle that contains all solid pixels.

Returns

• Rect — The smallest rectangle containing all solid pixels. Returns empty rect if mask has no solid pixels.

get_center_of_mass(self) -> Vec2

Calculate the center of mass of all solid pixels.

Returns

• Vec2 — The center of mass position. Returns (0, 0) if mask is empty.

get_collision_points(self, other: Mask, offset: Vec2 = Vec2(0.000000, 0.000000)) -> list[Vec2]

Get all points where this mask collides with another mask.

Args

• other (Mask) — The other mask to test collision with.
• offset (Vec2) — Position offset between the masks. Defaults to (0, 0).

Returns

list[Vec2]: A list of collision points.

get_count(self) -> int

Get the number of solid pixels in the mask.

Returns

• int — The count of solid pixels.

get_outline(self) -> list[Vec2]

Get the outline points of the mask.

Returns a list of points that form the outline of all solid regions.

Returns

list[Vec2]: A list of outline points.

get_overlap_area(self, other: Mask, offset: Vec2 = Vec2(0.000000, 0.000000)) -> int

Get the number of overlapping pixels between this mask and another.

Args

• other (Mask) — The other mask to check overlap with.
• offset (Vec2) — Position offset between the masks. Defaults to (0, 0).

Returns

• int — The number of overlapping solid pixels.

get_overlap_mask(self, other: Mask, offset: Vec2 = Vec2(0.000000, 0.000000)) -> Mask

Get a mask representing the overlapping area between this mask and another.

Args

• other (Mask) — The other mask to check overlap with.
• offset (Vec2) — Position offset between the masks. Defaults to (0, 0).

Returns

• Mask — A new mask containing only the overlapping pixels.

get_pixel_array(self, color: Color = Color(255, 255, 255, 255)) -> PixelArray

Convert the mask to a pixel array with the specified color.

Solid pixels become the specified color, transparent pixels become transparent.

Args

• color (Color) — The color to use for solid pixels. Defaults to white (255, 255, 255, 255).

Returns

• PixelArray — A new pixel array representation of the mask.

Raises

• RuntimeError — If pixel array creation fails.

get_rect(self) -> Rect

Get the bounding rectangle of the mask starting at (0, 0).

invert(self) -> None

Invert all pixels in the mask.

Solid pixels become transparent and transparent pixels become solid.

is_empty(self) -> bool

Check if the mask contains no solid pixels.

Returns

• bool — True if the mask is empty, False otherwise.

set_at(self, x: int, y: int, value: bool) -> None

Set the pixel value at a specific position.

Args

• x (int) — The x-coordinate of the position to set.
• y (int) — The y-coordinate of the position to set.
• value (bool) — The pixel value (True for solid, False for transparent).

subtract(self, other: Mask, offset: Vec2 = Vec2(0.000000, 0.000000)) -> None

Subtract another mask from this mask with an offset.

Removes pixels where the other mask has solid pixels.

Args

• other (Mask) — The mask to subtract.
• offset (Vec2) — Position offset for the other mask. Defaults to (0, 0).