# sdl2.ext.pixelaccess - Array-like Access to SDL Surface Contents

The `sdl2.ext.pixelaccess` module offers a number of methods for reading, modifying, and copying the contents SDL surface objects.

In most cases, the Numpy-based `pixels2d()`, `pixels3d()`, and `surface_to_ndarray()` functions are the fastest and most flexible way of directly accessing the pixels of an SDL surface. However, the pure-Python `PixelView` class can be used instead to avoid adding Numpy as a dependency for your project.

class sdl2.ext.pixelaccess.PixelView(source)

  A 2D memory view for reading and writing SDL surface pixels.

  This class uses a `view[y][x]` layout, with the y-axis as the first dimension and the x-axis as the second. `PixelView` objects currently do not support array slicing, but support negative indexing as of PySDL2 0.9.10.

  If the source surface is RLE-accelerated, it will be locked automatically when the view is created and you will need to re-lock the surface using `SDL_UnlockSurface()` once you are done with the view.

  Warning

  The source surface should not be freed or deleted until the view is no longer needed. Accessing the view for a freed surface will likely cause Python to hard-crash.

  Note

  This class is implemented on top of the `MemoryView` class. As such, it makes heavy use of recursion to access rows and will generally be much slower than the `numpy`-based `pixels2d()` and `pixels3d()` functions.

  Parameters:

    source (`SDL_Surface`, `SoftwareSprite`) – The SDL surface to access with the view.

class sdl2.ext.pixelaccess.SurfaceArray(shape, dtype=<class 'float'>, buffer_=None, offset=0, strides=None, order=None, source=None, surface=None)

  A Numpy array that keeps a reference to its parent SDL surface.

  This class is used to keep track of the original source object for `pixels2d()` or `pixels3d()` to prevent it from being automatically freed during garbage collection. It should never be used for any other purpose.

sdl2.ext.pixelaccess.pixels2d(source, transpose=True)

  Creates a 2D Numpy array view for a given SDL surface.

  This function casts the surface pixels to a 2D Numpy array view, providing read and write access to the underlying surface. If the source surface is RLE-accelerated, it will be locked automatically when the view is created and you will need to re-lock the surface using `SDL_UnlockSurface()` once you are done with the array.

  By default, the array is returned in `arr[x][y]` format with the x-axis as the first dimension, contrary to PIL and PyOpenGL convention. To obtain an `arr[y][x]` array, set the `transpose` argument to `False`.

  Warning

  The source surface should not be freed or deleted until the array is no longer needed. Accessing the array for a freed surface will likely cause Python to hard-crash.

  Note

  This function requires Numpy to be installed in the current Python environment.

  Parameters:

    - source (`SDL_Surface`, `SoftwareSprite`) – The SDL surface to cast to a numpy array.

    - transpose (bool, optional) – Whether the output array should be transposed to have `arr[x][y]` axes instead of `arr[y][x]` axes. Defaults to `True`.

  Returns:

    A 2-dimensional Numpy array containing the integer color values for each pixel in the surface.

  Return type:

    `numpy.ndarray`

  Raises:

    RuntimeError – If Numpy could not be imported.

sdl2.ext.pixelaccess.pixels3d(source, transpose=True)

  Creates a 3D Numpy array view for a given SDL surface.

  This function casts the surface pixels to a 3D Numpy array view, providing read and write access to the underlying surface. If the source surface is RLE-accelerated, it will be locked automatically when the view is created and you will need to re-lock the surface using `SDL_UnlockSurface()` once you are done with the array.

  By default, the array is returned in `arr[x][y]` format with the x-axis as the first dimension, contrary to PIL and PyOpenGL convention. To obtain an `arr[y][x]` array, set the `transpose` argument to `False`.

  When creating a 3D array view, the order of the RGBA values for each pixel may be reversed for some common surface pixel formats (e.g. ‘BGRA’ for a `SDL_PIXELFORMAT_ARGB8888` surface). To correct this, you can call `numpy.flip(arr, axis=2)` to return a view of the array with the expected channel order.

  Warning

  The source surface should not be freed or deleted until the array is no longer needed. Accessing the array for a freed surface will likely cause Python to hard-crash.

  Note

  This function requires Numpy to be installed in the current Python environment.

  Parameters:

    - source (`SDL_Surface`, `SoftwareSprite`) – The SDL surface to cast to a numpy array.

    - transpose (bool, optional) – Whether the output array should be transposed to have `arr[x][y]` axes instead of `arr[y][x]` axes. Defaults to `True`.

  Returns:

    A 3-dimensional Numpy array containing the values of each byte for each pixel in the surface.

  Return type:

    `numpy.ndarray`

  Raises:

    RuntimeError – If Numpy could not be imported.

sdl2.ext.pixelaccess.surface_to_ndarray(source, ndim=3)

  Returns a copy of an SDL surface as a Numpy array.

  The main difference between this function and `pixels2d()` or `pixels3d()` is that it returns a copy of the surface instead of a view, meaning that modifying the returned array will not affect the original surface (or vice-versa). This function is also slightly safer, as it does not assume that the source surface has been kept in memory.

  When creating a 3D array copy, the order of the RGBA values for each pixel may be reversed for some common surface pixel formats (e.g. ‘BGRA’ for a `SDL_PIXELFORMAT_ARGB8888` surface). To correct this, you can call `numpy.flip(arr, axis=2)` to return a view of the array with the expected channel order.

  Note

  Unlike `pixels2d()` or `pixels3d()`, this function always returns arrays with the y-axis as the first dimension (e.g. `arr[y][x]`).

  Note

  This function requires Numpy to be installed in the current Python environment.

  Parameters:

    - source (`SDL_Surface`, `SoftwareSprite`) – The SDL surface to convert to a numpy array.

    - ndim (int, optional) – The number of dimensions for the returned array, must be either 2 (for a 2D array) or 3 (for a 3D array). Defaults to 3.

  Returns:

    A Numpy array containing a copy of the pixel data for the given surface.

  Return type:

    `numpy.ndarray`

  Raises:

    RuntimeError – If Numpy could not be imported.