.. include:: common.txt

:class:`pygame.PixelArray`
==========================

.. currentmodule:: pygame

.. class:: PixelArray

   | :sl:`pygame object for direct pixel access of surfaces`
   | :sg:`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 :mod:`pygame.pixelcopy` methods and NumPy
   arrays.

   A PixelArray pixel item can be assigned a raw integer values, a
   :class:`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 :meth:`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.

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

   .. versionadded:: 1.9.2

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

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


   .. versionadded: 1.8.0
      Subscript support

   .. versionadded: 1.8.1
      Methods :meth:`make_surface`, :meth:`replace`, :meth:`extract`, and
      :meth:`compare`

   .. versionadded: 1.9.2
      Properties :attr:`itemsize`, :attr:`ndim`, :attr:`shape`,
      and :attr:`strides`

   .. versionadded: 1.9.2
      Array struct interface

   .. versionadded: 1.9.4
      Methods :meth:`close`

   .. attribute:: surface

      | :sl:`Gets the Surface the PixelArray uses.`
      | :sg:`surface -> Surface`

      The Surface the PixelArray was created for.

      .. ## PixelArray.surface ##

   .. attribute:: itemsize

      | :sl:`Returns the byte size of a pixel array item`
      | :sg:`itemsize -> int`

      This is the same as :meth:`Surface.get_bytesize` for the
      pixel array's surface.

      .. versionadded:: 1.9.2

   .. attribute:: ndim

      | :sl:`Returns the number of dimensions.`
      | :sg:`ndim -> int`

      A pixel array can be 1 or 2 dimensional.

      .. versionadded:: 1.9.2

   .. attribute:: shape

      | :sl:`Returns the array size.`
      | :sg:`shape -> tuple of int's`

      A tuple or length :attr:`ndim` giving the length of each
      dimension. Analogous to :meth:`Surface.get_size`.

      .. versionadded:: 1.9.2

   .. attribute:: strides

      | :sl:`Returns byte offsets for each array dimension.`
      | :sg:`strides -> tuple of int's`

      A tuple or length :attr:`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).

      .. versionadded:: 1.9.2

   .. method:: make_surface

      | :sl:`Creates a new Surface from the current PixelArray.`
      | :sg:`make_surface() -> Surface`

      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 ()

      .. versionadded:: 1.8.1

      .. ## PixelArray.make_surface ##

   .. method:: replace

      | :sl:`Replaces the passed color in the PixelArray with another one.`
      | :sg:`replace(color, repcolor, distance=0, weights=(0.299, 0.587, 0.114)) -> None`

      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.

      .. versionadded:: 1.8.1

      .. ## PixelArray.replace ##

   .. method:: extract

      | :sl:`Extracts the passed color from the PixelArray.`
      | :sg:`extract(color, distance=0, weights=(0.299, 0.587, 0.114)) -> 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.

      .. versionadded:: 1.8.1

      .. ## PixelArray.extract ##

   .. method:: compare

      | :sl:`Compares the PixelArray with another one.`
      | :sg:`compare(array, distance=0, weights=(0.299, 0.587, 0.114)) -> PixelArray`

      Compares the contents of the PixelArray with those from the passed in
      PixelArray. It returns a new PixelArray with a black/white color mask
      that indicates the differences (black) 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 a threshold for the color detection. This causes the
      comparison to mark pixels with a similar, but not exactly identical
      color, as white.

      .. versionadded:: 1.8.1

      .. ## PixelArray.compare ##

   .. method:: transpose

      | :sl:`Exchanges the x and y axis.`
      | :sg:`transpose() -> PixelArray`

      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.

      .. versionadded:: 1.9.2

      .. ## PixelArray.transpose ##

   .. method:: close

      | :sl:`Closes the PixelArray, and releases Surface lock.`
      | :sg:`transpose() -> PixelArray`

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

      .. versionadded:: 1.9.4

      .. ## PixelArray.close ##


   .. ## pygame.PixelArray ##