pygame.PixelArray

pygame object for direct pixel access of surfaces

PixelArray(Surface) -> PixelArray

The PixelArray wraps a Surface and provides direct access to the surface's pixels. A pixel array can be one or two dimensional. A two dimensional array, like its surface, is indexed [column, row]. Pixel arrays support slicing, both for returning a subarray or for assignment. A pixel array sliced on a single column or row returns a one dimensional pixel array. Arithmetic and other operations are not supported. A pixel array can be safely assigned to itself. Finally, pixel arrays export an array struct interface, allowing them to interact with pygame.pixelcopy methods and NumPy arrays.

A PixelArray pixel item can be assigned a raw integer values, a pygame.Color instance, or a (r, g, b[, a]) tuple.

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

However, only a pixel's integer value is returned. So, to compare a pixel to a particular color the color needs to be first mapped using the Surface.map_rgb() method of the Surface object for which the PixelArray was created.

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)):
    ...

When assigning to a range of of pixels, a non tuple sequence of colors or a PixelArray can be used as the value. For a sequence, the length must match the PixelArray width.

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

For PixelArray assignment, if the right hand side array has a row length of 1, then the column is broadcast over the target array's rows. An array of height 1 is broadcast over the target's columns, and is equivalent to assigning a 1D PixelArray.

Subscript slices can also be used to assign to a rectangular subview of the target 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]

Subscript slices can also be used to do fast rectangular pixel manipulations instead of iterating over the x or y axis. The

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

During its lifetime, the PixelArray locks the surface, thus you explicitly have to close() it once its not used any more and the surface should perform operations in the same scope. It is best to use it as a context manager using the with PixelArray(surf) as pixel_array: style. So it works on pypy too.

A simple : slice index for the column can be omitted.

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

A note about PixelArray to PixelArray assignment, for arrays with an item size of 3 (created from 24 bit surfaces) pixel values are translated from the source to the destinations format. The red, green, and blue color elements of each pixel are shifted to match the format of the target surface. For all other pixel sizes no such remapping occurs. This should change in later pygame releases, where format conversions are performed for all pixel sizes. To avoid code breakage when full mapped copying is implemented it is suggested PixelArray to PixelArray copies be only between surfaces of identical format.

New in pygame 1.9.4

• close() method was added. For explicitly cleaning up.
• being able to use PixelArray as a context manager for cleanup.
• both of these are useful for when working without reference counting (pypy).

New in pygame 1.9.2

• array struct interface
• transpose method
• broadcasting for a length 1 dimension

Changed in pygame 1.9.2

• A 2D PixelArray can have a length 1 dimension. Only an integer index on a 2D PixelArray returns a 1D array.
• For assignment, a tuple can only be a color. Any other sequence type is a sequence of colors.

surface -> Surface

Gets the Surface the PixelArray uses.

The Surface the PixelArray was created for.

itemsize -> int

Returns the byte size of a pixel array item

This is the same as Surface.get_bytesize() for the pixel array's surface.

New in pygame 1.9.2

ndim -> int

Returns the number of dimensions.

A pixel array can be 1 or 2 dimensional.

New in pygame 1.9.2

shape -> tuple of int's

Returns the array size.

A tuple or length ndim giving the length of each dimension. Analogous to Surface.get_size().

New in pygame 1.9.2

strides -> tuple of int's

Returns byte offsets for each array dimension.

A tuple or length ndim byte counts. When a stride is multiplied by the corresponding index it gives the offset of that index from the start of the array. A stride is negative for an array that has is inverted (has a negative step).

New in pygame 1.9.2

make_surface() -> Surface

Creates a new Surface from the current PixelArray.

Creates a new Surface from the current PixelArray. Depending on the current PixelArray the size, pixel order etc. will be different from the original Surface.

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

New in pygame 1.8.1.

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

Replaces the passed color in the PixelArray with another one.

Replaces the pixels with the passed color in the PixelArray by changing them them to the passed replacement color.

It uses a simple weighted Euclidean distance formula to calculate the distance between the colors. The distance space ranges from 0.0 to 1.0 and is used as threshold for the color detection. This causes the replacement to take pixels with a similar, but not exactly identical color, into account as well.

This is an in place operation that directly affects the pixels of the PixelArray.

New in pygame 1.8.1.

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

Extracts the passed color from the PixelArray.

Extracts the passed color by changing all matching pixels to white, while non-matching pixels are changed to black. This returns a new PixelArray with the black/white color mask.

It uses a simple weighted Euclidean distance formula to calculate the distance between the colors. The distance space ranges from 0.0 to 1.0 and is used as threshold for the color detection. This causes the extraction to take pixels with a similar, but not exactly identical color, into account as well.

New in pygame 1.8.1.

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

Compares the PixelArray with another one.

Compares the contents of the PixelArray with those from the passed PixelArray. It returns a new PixelArray with a black/white color mask that indicates the differences (white) of both arrays. Both PixelArray objects must have identical bit depths and dimensions.

It uses a simple weighted Euclidean distance formula to calculate the distance between the colors. The distance space ranges from 0.0 to 1.0 and is used as threshold for the color detection. This causes the comparison to mark pixels with a similar, but not exactly identical color, as black.

New in pygame 1.8.1.

transpose() -> PixelArray

Exchanges the x and y axis.

This method returns a new view of the pixel array with the rows and columns swapped. So for a (w, h) sized array a (h, w) slice is returned. If an array is one dimensional, then a length 1 x dimension is added, resulting in a 2D pixel array.

New in pygame 1.9.2

transpose() -> PixelArray

Closes the PixelArray, and releases Surface lock.

This method is for explicitly closing the PixelArray, and releasing a lock on the Suface.

New in pygame 1.9.4