pixelarray - Pygame Documentation

pygame documentation | || Pygame Home || Help Contents || Reference Index || Cdrom || Cursors || Display || Draw || Event || Font || Image || Joystick || Key || Mask || Mixer || Mouse || Movie || Music || Overlay || Pixelarray || Pygame || Rect || Scrap || Sndarray || Sprite || Surface || Surfarray || Time || Transform

pygame.PixelArray

pygame Object for direct pixel access of surfaces
`pygame.PixelArray(Surface): return PixelArray`

PixelArray.surface - Gets the Surface the PixelArray uses. | Gets the Surface the PixelArray uses.

`NOTE:` This is an `EXPERIMENTAL` class and subject to `CHANGE` in future versions.

The PixelArray wraps up a Surface and provides a direct `2D` array access to its pixels using the surface its rows as first and its columns as second axis. It supports slicing and row and pixel manipluation while inplace operations such as addition, subtraction, multiplication, division and slice assignments are not allowed.

While it is possible to assign both, integer color values and `RGB(A)` color tuples, the PixelArray will only use integers for the color representation. Thus, checking for certain colors has to be done using the `Surface.map_rgb - convert a color into a mapped color value` method of the surface, the PixelArray was created for.

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

Pixels can be manipulated using integer values or color tuples.

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

If you operate on a slice, you also can use arbitrary sequences or other PixelArray objects to modify the pixels. They have to match the size of the PixelArray however.

      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

Note, that something like

      pxarray[2:4][3:5] = ...

will not cause a rectangular manipulation. Instead it will be first sliced to a two-column array, which then shall be sliced by columns once more, which will fail due an IndexError. This is caused by the slicing mechanisms in python and an absolutely correct behaviour. Create a single columned slice first, which you can manipulate then:

      pxarray[2][3:5] = ...
      pxarray[3][3:5] = ...

During its lifetime, the PixelArray locks the surface, thus you explicitly have to delete it once its not used anymore and the surface should perform operations in the same scope.

New in pygame `1.8`.

PixelArray.surface

Gets the Surface the PixelArray uses.
`PixelArray.surface: Return Surface`

The Surface, the PixelArray was created for.