Объект PixelArray оборачивает Surface и предоставляет прямой доступ к пикселям поверхности. Массив пикселей может быть одномерным или двумерным. Двумерный массив, как и его поверхность, индексируется [столбец, строка]. Массивы пикселей поддерживают срезы, как для возвращения подмассива, так и для присваивания. Срез массива пикселей по одному столбцу или строке возвращает одномерный массив пикселей. Арифметические и другие операции не поддерживаются. Массив пикселей можно безопасно присвоить самому себе. Наконец, массивы пикселей экспортируют интерфейс структуры массива, позволяющий им взаимодействовать с методами pygame.pixelcopy и массивами NumPy.

Элемент пикселя PixelArray может быть присвоен целочисленным значением, экземпляром pygame.Color или кортежем (r, g, b[, a]).

pxarray[x, y] = 0xFF00FF
pxarray[x, y] = pygame.Color(255, 0, 255)
pxarray[x, y] = (255, 0, 255)

Однако возвращается только целочисленное значение пикселя. Таким образом, для сравнения пикселя с определённым цветом, цвет сначала необходимо отобразить с помощью метода Surface.map_rgb() объекта Surface, для которого был создан PixelArray.

pxarray = pygame.PixelArray(surface)
# Check, if the first pixel at the topleft corner is blue
if pxarray[0, 0] == surface.map_rgb((0, 0, 255)):
    ...

При присваивании диапазону пикселей можно использовать не кортеж последовательность цветов или PixelArray в качестве значения. Для последовательности длина должна соответствовать ширине PixelArray.

pxarray[a:b] = 0xFF00FF                   # set all pixels to 0xFF00FF
pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # first pixel = 0xFF00FF,
                                          # second pixel  = 0xAACCEE, ...
pxarray[a:b] = [(255, 0, 255), (170, 204, 238), ...] # same as above
pxarray[a:b] = [(255, 0, 255), 0xAACCEE, ...]        # same as above
pxarray[a:b] = otherarray[x:y]            # slice sizes must match

При присваивании PixelArray, если массив справа имеет длину строки 1, то столбец транслируется по строкам целевого массива. Массив высотой 1 транслируется по столбцам целевого массива и эквивалентен присвоению одномерного PixelArray.

Срезы с индексами также могут использоваться для присваивания прямоугольной части целевого PixelArray.

# Create some new PixelArray objects providing a different view
# of the original array/surface.
newarray = pxarray[2:4, 3:5]
otherarray = pxarray[::2, ::2]

Срезы с индексами также могут использоваться для быстрой обработки прямоугольных пиксельных областей вместо итерации по оси x или y.

pxarray[::2, :] = (0, 0, 0)               # Make even columns black.
pxarray[::2] = (0, 0, 0)                  # Same as [::2, :]

В течение своего жизненного цикла PixelArray блокирует поверхность, поэтому вам явно нужно закрыть (close()) его, как только он больше не используется, и поверхность должна выполнять операции в том же объёме. Лучше всего использовать его как менеджер контекста с помощью стиля with PixelArray(surf) as pixel_array:. Таким образом, он работает и в pypy.

Можно опустить простой : индекс среза для столбца.

pxarray[::2, ...] = (0, 0, 0)             # Same as pxarray[::2, :]
pxarray[...] = (255, 0, 0)                # Same as pxarray[:]

Замечание о присваивании PixelArray массиву PixelArray: для массивов с размером элемента 3 (созданных из поверхностей с 24-битным цветом) значения пикселей преобразуются из исходного в формат назначения. Красный, зелёный и синий цветовые компоненты каждого пикселя сдвигаются для соответствия формату целевой поверхности. Для всех других размеров пикселей такого преобразования не происходит. Это должно измениться в будущих версиях pygame, где преобразования форматов будут выполняться для всех размеров пикселей. Чтобы избежать разрыва кода при реализации полного преобразования копий, рекомендуется выполнять копирование PixelArray в PixelArray только между поверхностями с одинаковым форматом.

surface

Возвращает Surface, используемый PixelArray.

surface -> Surface

Surface, для которого был создан PixelArray.

itemsize

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

itemsize -> int

Это то же, что и Surface.get_bytesize() для поверхности массива пикселей.

Добавлено в pygame 1.9.2.

ndim

Возвращает количество измерений.

ndim -> int

Массив пикселей может быть одномерным или двумерным.

Добавлено в pygame 1.9.2.

shape

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

shape -> кортеж из целых чисел

Кортеж длины ndim, содержащий длины каждого измерения. Аналогично Surface.get_size().

Добавлено в pygame 1.9.2.

strides

Возвращает смещения в байтах для каждого измерения массива.

strides -> кортеж из целых чисел

Кортеж длины ndim, содержащий число байт. Умножение смещения на соответствующий индекс даёт смещение этого индекса от начала массива. Смещение является отрицательным для массива, который инвертирован (имеет отрицательный шаг).

Добавлено в pygame 1.9.2.

make_surface()

Создаёт новую поверхность из текущего PixelArray.

make_surface() -> Surface

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

# Create a new surface flipped around the vertical axis.
sf = pxarray[:,::-1].make_surface ()

Добавлено в pygame 1.8.1.

replace()

Заменяет указанный цвет в PixelArray другим.

replace(color, repcolor, distance=0, weights=(0.299, 0.587, 0.114)) -> None

Заменяет пиксели с указанным цветом в PixelArray, изменяя их на указанный цвет-замену.

Использует простую взвешенную формулу евклидова расстояния для расчёта расстояния между цветами. Пространство расстояний варьируется от 0,0 до 1,0 и используется в качестве порога для определения цвета. Это заставляет замену учитывать пиксели с похожим, но не точно идентичным цветом.

Это операция на месте, которая непосредственно влияет на пиксели PixelArray.

Добавлено в pygame 1.8.1.

extract()

Извлекает указанный цвет из PixelArray.

extract(color, distance=0, weights=(0.299, 0.587, 0.114)) -> PixelArray

Извлекает указанный цвет, изменяя все соответствующие пиксели на белый, а несоответствующие — на чёрный. Возвращает новый PixelArray с маской цветов чёрный/белый.

Использует простую взвешенную формулу евклидова расстояния для расчёта расстояния между цветами. Пространство расстояний варьируется от 0,0 до 1,0 и используется в качестве порога для определения цвета. Это заставляет извлечение учитывать пиксели с похожим, но не точно идентичным цветом.

Добавлено в pygame 1.8.1.

compare()

Сравнивает PixelArray с другим.

compare(array, distance=0, weights=(0.299, 0.587, 0.114)) -> PixelArray

Сравнивает содержимое PixelArray с содержимым переданного PixelArray. Возвращает новый PixelArray с маской цветов чёрный/белый, которая указывает на различия (чёрный цвет) обоих массивов. Оба объекта PixelArray должны иметь одинаковую глубину бита и размерность.

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

Добавлено в pygame 1.8.1.

transpose()

Меняет местами оси x и y.

transpose() -> PixelArray

Этот метод возвращает новый вид массива пикселей, в котором строки и столбцы поменяны местами. Таким образом, для массива размером (w, h) возвращается срез (h, w). Если массив одномерный, добавляется размерность 1x, что приводит к двумерному массиву пикселей.

Добавлено в pygame 1.9.2.

close()

Закрывает PixelArray и освобождает блокировку поверхности.

close() -> PixelArray

Этот метод предназначен для явного закрытия PixelArray и освобождения блокировки поверхности.

Добавлена в pygame 1.9.4.