Полезен для быстрого обнаружения столкновений с точностью до пикселя. Маска использует 1 бит на пиксель для хранения информации о столкновении.

pygame.mask.from_surface()

Создаёт маску из заданной поверхности

from_surface(surface) -> Mask

from_surface(surface, threshold=127) -> Mask

Создаёт объект Mask из заданной поверхности, устанавливая все непрозрачные пиксели и не устанавливая прозрачные.

Если поверхность использует цветовой ключ, он используется для определения битов в результирующей маске. Все пиксели, которые не равны цветовому ключу, устанавливаются, а пиксели, равные цветовому ключу, не устанавливаются.

Если цветовой ключ не используется, то используется значение альфа-канала каждого пикселя для определения битов в результирующей маске. Все пиксели, у которых значение альфа-канала больше параметра threshold, устанавливаются, а пиксели со значением альфа-канала меньше или равным параметру threshold, не устанавливаются.

Параметры

• surface (Surface) -- поверхность, из которой создаётся маска

• threshold (int) -- (необязательно) порог значения альфа-канала (по умолчанию 127) для сравнения с значением альфа-канала каждого пикселя поверхности. Если поверхность имеет цветовой ключ, этот параметр игнорируется

Возвращает

новый созданный объект Mask из заданной поверхности

Тип возвращаемого значения

Mask

Примечание

Эта функция используется для создания масок для pygame.sprite.collide_mask().

pygame.mask.from_threshold()

Создаёт маску путём порогового сравнения поверхностей

from_threshold(surface, color) -> Mask

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

Это более функциональный метод получения Mask из поверхности.

Если необязательный othersurface не используется, все пиксели внутри диапазона threshold параметра color устанавливаются в результирующей маске.

Если необязательный othersurface используется, каждый пиксель на первой поверхности, который внутри диапазона threshold соответствующего пикселя в othersurface, устанавливается в результирующей маске.

Параметры

• surface (Surface) -- поверхность, из которой создаётся маска

• color (Color или int или tuple(int, int, int, [int]) или list[int, int, int, [int]]) -- цвет, используемый для проверки, находятся ли пиксели поверхности внутри заданного threshold диапазона. Этот параметр игнорируется, если указан необязательный параметр othersurface

• threshold (Color или int или tuple(int, int, int, [int]) или list[int, int, int, [int]]) -- (необязательно) диапазон порогового значения, используемый для проверки разницы между двумя цветами (по умолчанию (0, 0, 0, 255))

• othersurface (Surface) -- (необязательно) используется для проверки, находятся ли пиксели первой поверхности внутри заданного threshold диапазона пикселей с этой поверхности (по умолчанию None)

• palette_colors (int) -- (необязательно) указывает, использовать ли цвета палитры или нет. Значение, отличное от нуля, вызывает использование цветов палитры, а 0 — нет (по умолчанию 1)

Возвращает

новый созданный объект Mask из заданной поверхности

Тип возвращаемого значения

Mask

pygame.mask.Mask

объект pygame для представления 2D битовых масок

Mask(size=(width, height)) -> Mask

Mask(size=(width, height), fill=False) -> Mask

Объект Mask используется для представления 2D битовой маски. Каждый бит в маске представляет пиксель. 1 используется для обозначения установленного бита, а 0 - для обозначения не установленного бита. Установленные биты в маске могут использоваться для обнаружения столкновений с другими масками и их установленными битами.

В заполненной маске все биты установлены в 1, в то время как в незаполненной/очищенной/пустой маске все биты установлены в 0. Маски могут быть созданы незаполненными (по умолчанию) или заполненными с использованием параметра fill. Маски также могут быть очищены или заполнены с помощью методов pygame.mask.Mask.clear() и pygame.mask.Mask.fill() соответственно.

Координаты маски начинаются в верхнем левом углу в (0, 0), как и у pygame.Surface. Доступ к отдельным битам можно получить с помощью методов pygame.mask.Mask.get_at() и pygame.mask.Mask.set_at().

Методы overlap(), overlap_area(), overlap_mask(), draw(), erase() и convolve() используют параметр смещения для указания смещения верхнего левого угла другой маски относительно верхнего левого угла вызывающей маски. Верхний левый угол вызывающей маски считается началом координат (0, 0). Смещения представляют собой последовательность из двух значений (x_offset, y_offset). Поддерживаются положительные и отрицательные значения смещения.

0 to x (x_offset)
           :    :
   0 ..... +----:---------+
   to      |    :         |
   y .......... +-----------+
(y_offset) |    | othermask |
           |    +-----------+
           | calling_mask |
           +--------------+

Параметры

• size -- размеры маски (ширина и высота)

• fill (bool) -- (необязательно) создать незаполненную маску (по умолчанию: False) или заполненную маску (True)

Возвращает

новый созданный объект Mask

Тип возвращаемого значения

Mask

Изменено в pygame 2.0.0: Добавлена поддержка поверхностного копирования. Класс Mask поддерживает специальный метод __copy__() и поверхностное копирование через copy.copy(mask).

Изменено в pygame 2.0.0: Добавлена поддержка наследования. Класс Mask может быть использован как базовый класс.

Изменено в pygame 1.9.5: Добавлена поддержка ключевых аргументов.

Изменено в pygame 1.9.5: Добавлен необязательный ключевой параметр fill.

Изменено в pygame 1.9.5: Добавлена поддержка масок с шириной и/или высотой 0.

copy()

Возвращает новую копию маски

copy() -> Mask

Возвращает

новую копию этой маски, новая маска будет иметь такую же ширину, высоту и установленные/не установленные биты, как и оригинал

Тип возвращаемого значения

Mask

Примечание

Если подкласс маски должен скопировать какие-либо специфичные для экземпляра атрибуты, то он должен переопределить метод __copy__(). Переопределенный метод __copy__() должен вызвать super().__copy__() и затем скопировать необходимые данные, как в следующем примере кода.

class SubMask(pygame.mask.Mask):
    def __copy__(self):
        new_mask = super().__copy__()
        # Do any SubMask attribute copying here.
        return new_mask

Введено в pygame 2.0.0.

get_size()

Возвращает размеры маски

get_size() -> (width, height)

Возвращает

размеры маски, (ширина, высота)

Тип возвращаемого значения

tuple(int, int)

get_rect()

Возвращает Rect на основе размера маски

get_rect(**kwargs) -> Rect

Возвращает новый объект pygame.Rect() на основе размера этой маски. По умолчанию положение прямоугольника будет (0, 0), а его ширина и высота будут такими же, как у этой маски. Атрибуты прямоугольника можно изменить, передав в этот метод ключевые аргументы/значения атрибутов pygame.Rect(). Например, a_mask.get_rect(center=(10, 5)) создаст pygame.Rect() на основе размера маски, центрированный в заданной позиции.

Параметры

kwargs (dict) -- ключевые аргументы/значения атрибутов pygame.Rect(), которые будут применены к прямоугольнику

Возвращает

новый объект pygame.Rect() на основе размера этой маски с любыми применёнными ключевыми аргументами/значениями атрибутов pygame.Rect()

Тип возвращаемого значения

Rect

Введено в pygame 2.0.0.

get_at()

Получает бит в заданной позиции

get_at(pos) -> int

Параметры

pos -- позиция бита для получения (x, y)

Возвращает

1, если бит установлен, 0, если бит не установлен

Тип возвращаемого значения

int

Исключения

IndexError -- если позиция находится вне границ маски

set_at()

Устанавливает бит в заданной позиции

set_at(pos) -> None

set_at(pos, value=1) -> None

Параметры

• pos -- позиция бита для установки (x, y)

• value (int) -- любое ненулевое целое значение установит бит в 1, 0 установит бит в 0 (по умолчанию 1)

Возвращает

None

Тип возвращаемого значения

NoneType

Исключения

IndexError -- если позиция находится вне границ маски

overlap()

Возвращает точку пересечения

overlap(other, offset) -> (x, y)

overlap(other, offset) -> None

Возвращает первую точку пересечения, найденную между этой маской и other. Точка пересечения — это 2 совпадающих установленных бита.

Текущий алгоритм ищет область пересечения в блоках столбцов шириной sizeof(unsigned long int) * CHAR_BIT бита (значение sizeof(unsigned long int) * CHAR_BIT зависит от платформы, для ясности оно будет обозначено как W). Начиная с верхнего левого угла, он проверяет биты с 0 до W - 1 первой строки ((0, 0) до (W - 1, 0)) и затем переходит к следующей строке ((0, 1) до (W - 1, 1)). После проверки всего этого блока столбца он переходит к следующему (W до 2 * W - 1). Это повторяется до тех пор, пока не будет найдена точка пересечения или вся область пересечения не будет проверена.

Параметры

• other (Mask) -- другая маска для пересечения с этой маской

• offset -- смещение other от этой маски, для более подробной информации см. Примечания по смещению маски

Возвращает

точку пересечения или None при отсутствии пересечения

Тип возвращаемого значения

tuple(int, int) или NoneType

overlap_area()

Возвращает количество совпадающих установленных битов

overlap_area(other, offset) -> numbits

Возвращает количество совпадающих установленных битов между этой маской и other.

Это может быть полезно для обнаружения столкновений. Приблизительное нормальное направление столкновения можно найти, вычислив градиент области перекрытия с помощью конечных разностей.

dx = mask.overlap_area(other, (x + 1, y)) - mask.overlap_area(other, (x - 1, y))
dy = mask.overlap_area(other, (x, y + 1)) - mask.overlap_area(other, (x, y - 1))

Параметры

• other (Mask) -- другая маска для пересечения с этой маской

• offset -- смещение other от этой маски, для более подробной информации см. Примечания по смещению маски

Возвращает

количество совпадающих установленных битов

Тип возвращаемого значения

int

overlap_mask()

Возвращает маску совпадающих установленных битов

overlap_mask(other, offset) -> Mask

Возвращает Mask, имеющую такие же размеры, как и эта маска, содержащую совпадающие установленные биты между этой маской и other.

Параметры

• other (Mask) -- другая маска для пересечения с этой маской

• offset -- смещение other от этой маски, для более подробной информации см. Примечания по смещению маски

Возвращает

новую созданную Mask с установленными совпадающими битами

Тип возвращаемого значения

Mask

fill()

Устанавливает все биты в 1

fill() -> None

Устанавливает все биты в маске в 1.

Возвращает

None

Тип возвращаемого значения

NoneType

clear()

Устанавливает все биты в 0

clear() -> None

Устанавливает все биты в маске в 0.

Возвращает

None

Тип возвращаемого значения

NoneType

invert()

Инвертирует все биты

invert() -> None

Инвертирует все биты в маске. Все установленные биты сбрасываются в 0, а все не установленные — устанавливаются в 1.

Возвращает

None

Тип возвращаемого значения

NoneType

scale()

Изменяет размер маски

scale((width, height)) -> Mask

Создаёт новую Mask заданного размера, масштабируя биты из этой маски.

Параметры

размер -- ширина и высота (размер) создаваемой маски

Возвращает

новый объект Mask с масштабированными битами из этой маски

Тип возвращаемого значения

Mask

Исключения

ValueError -- если width < 0 или height < 0

draw()

Рисует маску на другую

draw(other, offset) -> None

Выполняет побитовое ИЛИ, рисуя othermask на эту маску.

Параметры

• other (Mask) -- маска для рисования на эту маску

• offset -- смещение other от этой маски, для более подробной информации см. Примечания по смещению маски

Возвращает

None

Тип возвращаемого значения

NoneType

erase()

Удаляет маску из другой

erase(other, offset) -> None

Удаляет (очищает) все биты, установленные в other из этой маски.

Параметры

• other (Mask) -- маска для удаления из этой маски

• offset -- смещение other от этой маски, для более подробной информации см. Примечания по смещению маски

Возвращает

None

Тип возвращаемого значения

NoneType

count()

Возвращает количество установленных битов

count() -> bits

Возвращает

количество установленных битов в маске

Тип возвращаемого значения

int

centroid()

Возвращает центр масс установленных битов

centroid() -> (x, y)

Находит центр масс (центр тяжести установленных битов) для этой маски.

Возвращает

кортеж координат, указывающий центр масс маски, возвращает (0, 0) если в маске нет установленных битов

Тип возвращаемого значения

tuple(int, int)

angle()

Возвращает ориентацию установленных битов

angle() -> theta

Находит приблизительное направление (от -90 до 90 градусов) установленных битов в маске. Это работает лучше, если используется маска с только одним соединённым компонентом.

Возвращает

ориентация установленных битов в маске, вернёт 0.0 если в маске нет установленных битов

Тип возвращаемого значения

float

Примечание

См. connected_component() для подробностей о том, как вычисляется соединённый компонент.

outline()

Возвращает список точек, контурирующих объект

outline() -> [(x, y), ...]

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

Возвращает список точек контура первого найденного соединённого компонента в маске. Для поиска соединённого компонента маска просматривается по строкам (слева направо) начиная с левого верхнего угла.

Опциональный параметр every пропускает установленные биты в контуре. Например, задав его значение 10, будет возвращён список каждого 10-го установленного бита в контуре.

Параметры

every (int) -- (необязательно) указывает количество пропускаемых битов в контуре (по умолчанию 1)

Возвращает

список точек, контурирующих первый найденный соединённый компонент, возвращается пустой список, если в маске нет установленных битов

Тип возвращаемого значения

list[tuple(int, int)]

Примечание

См. connected_component() для подробностей о том, как вычисляется соединённый компонент.

convolve()

Возвращает свёртку этой маски с другой маской

convolve(other) -> Mask

convolve(other, output=None, offset=(0, 0)) -> Mask

Производит свёртку этой маски с заданной other маской.

Параметры

• other (Mask) -- маска для свёртки с этой маской

• output (Mask или NoneType) -- (необязательно) маска для вывода (по умолчанию None)

• offset -- смещение other от этой маски, (по умолчанию (0, 0))

Возвращает

маска Mask с установленным битом (i - offset[0], j - offset[1]), если смещение other (такое, что её нижний правый угол находится в (i, j)) приводит к перекрытию с этой маской

Если указана маска output, вывод наносится на неё и возвращается. В противном случае создаётся и возвращается маска размера (MAX(0, width + other mask's width - 1), MAX(0, height + other mask's height - 1))

Тип возвращаемого значения

Mask

connected_component()

Возвращает маску, содержащую соединённый компонент

connected_component() -> Mask

connected_component(pos) -> Mask

Соединённый компонент — это группа (1 или более) соединённых установленных битов (ортогонально и по диагонали). Для нахождения соединённого компонента в маске используется алгоритм SAUF, проверяющий 8-точечную связность.

По умолчанию этот метод возвращает Mask, содержащую наибольший соединённый компонент в маске. Необязательно можно указать координату бита, и будет возвращён соединённый компонент, содержащий её. Если бит в заданном месте не установлен, возвращаемая Mask будет пустой (нет установленных битов).

Параметры

pos -- (необязательно) выбирает соединённый компонент, содержащий бит в этой позиции

Возвращает

объект Mask (того же размера, что и эта маска) с наибольшим соединённым компонентом из этой маски, если в этой маске нет установленных битов, то будет возвращена пустая маска

Если параметр pos задан, то возвращаемая маска будет содержать соединённый компонент, который содержит эту позицию. Пустая маска будет возвращена, если параметр pos выбирает не установленный бит.

Тип возвращаемого значения

Mask

Исключения

IndexError -- если необязательный параметр pos находится за пределами границ маски

connected_components()

Возвращает список масок соединённых компонентов

connected_components() -> [Mask, ...]

connected_components(minimum=0) -> [Mask, ...]

Возвращает список, содержащий объекты Mask для каждого соединённого компонента.

Параметры

minimum (int) -- (необязательно) указывает минимальное количество битов (для фильтрации шумов) на соединённый компонент (по умолчанию 0, что эквивалентно отсутствию минимального значения и эквивалентно его установке в 1, так как соединённый компонент должен иметь по крайней мере 1 установленный бит)

Возвращает

список, содержащий объекты Mask для каждого соединённого компонента, возвращается пустой список, если в маске нет установленных битов

Тип возвращаемого значения

list[Mask]

Примечание

См. connected_component() для подробностей о том, как вычисляется соединённый компонент.

get_bounding_rects()

Возвращает список прямоугольников, ограничивающих соединённые компоненты

get_bounding_rects() -> [Rect, ...]

Возвращает список, содержащий прямоугольник, ограничивающий каждый соединённый компонент.

Возвращает

список, содержащий прямоугольник, ограничивающий каждый соединённый компонент, возвращается пустой список, если в маске нет установленных битов

Тип возвращаемого значения

list[Rect]

Примечание

См. connected_component() для подробностей о том, как вычисляется соединённый компонент.

to_surface()

Возвращает поверхность с нарисованной маской

to_surface() -> Surface

to_surface(surface=None, setsurface=None, unsetsurface=None, setcolor=(255, 255, 255, 255), unsetcolor=(0, 0, 0, 255), dest=(0, 0)) -> Surface

Рисует эту маску на заданной поверхности. Установленные биты (биты, установленные в 1) и сброшенные биты (биты, установленные в 0) могут быть нарисованы на поверхности.

Параметры

• surface (Surface или None) -- (необязательно) Поверхность, на которую нужно нарисовать маску. Если поверхность не указана, будет создана новая (по умолчанию None, что приведет к созданию поверхности с параметрами Surface(size=mask.get_size(), flags=SRCALPHA, depth=32), её отрисовке и возврату)

• setsurface (Surface или None) -- (необязательно) Используйте значения цветов этой поверхности для рисования установленных битов (по умолчанию None), если эта поверхность меньше маски, любые биты за пределами её границ будут использовать значение setcolor

• unsetsurface (Surface или None) -- (необязательно) Используйте значения цветов этой поверхности для рисования сброшенных битов (по умолчанию None), если эта поверхность меньше маски, любые биты за пределами её границ будут использовать значение unsetcolor

• setcolor (Color или str или int или tuple(int, int, int, [int]) или list(int, int, int, [int]) или None) -- (необязательно) Цвет для рисования установленных битов (по умолчанию (255, 255, 255, 255), белый), используйте None, чтобы пропустить рисование установленных битов, параметр setsurface (если задан) будет иметь приоритет над этим параметром

• unsetcolor (Color или str или int или tuple(int, int, int, [int]) или list(int, int, int, [int]) или None) -- (необязательно) Цвет для рисования сброшенных битов (по умолчанию (0, 0, 0, 255), чёрный), используйте None, чтобы пропустить рисование сброшенных битов, параметр unsetsurface (если задан) будет иметь приоритет над этим параметром

• dest (Rect или tuple(int, int) или list(int, int) или Vector2(int, int)) -- (необязательно) Назначение поверхности, где расположить верхний левый угол рисуемой маски (по умолчанию (0, 0)), если в качестве параметра dest используется прямоугольник, его атрибуты x и y будут использоваться в качестве назначения, ПРИМЕЧАНИЕ 1: прямоугольники с отрицательной шириной или высотой не будут нормализованы перед использованием их значений x и y, ПРИМЕЧАНИЕ 2: это значение назначения используется только для позиционирования маски на поверхности, оно не смещает setsurface и unsetsurface от маски, они всегда выровнены с маской (т.е. позиция (0, 0) на маске всегда соответствует позиции (0, 0) на setsurface и unsetsurface)

Возвращает

параметр surface (или новая созданная поверхность, если параметр surface не был предоставлен), на которой нарисована эта маска

Тип возвращаемого значения

Surface

Возможные исключения

ValueError -- если параметр setsurface или параметр unsetsurface не имеют такого же формата (размер байта/размер бита/альфа), как параметр surface

Примечание

Чтобы пропустить рисование установленных битов, как setsurface, так и setcolor должны быть None. Параметр setsurface по умолчанию None, но setcolor по умолчанию имеет значение цвета и поэтому должен быть установлен в None.

Примечание

Чтобы пропустить рисование сброшенных битов, как unsetsurface, так и unsetcolor должны быть None. Параметр unsetsurface по умолчанию None, но unsetcolor по умолчанию имеет значение цвета и поэтому должен быть установлен в None.

Новое в pygame 2.0.0.