PixelAccess Class

The PixelAccess class provides read and write access to PIL.Image data at a pixel level.

Note

Accessing individual pixels is fairly slow. If you are looping over all of the pixels in an image, there is likely a faster way using other parts of the Pillow API.

Image, ImageChops and ImageOps have methods for many standard operations. If you wish to perform a custom mapping, check out point().

Example

The following script loads an image, accesses one pixel from it, then changes it.

from PIL import Image

with Image.open("hopper.jpg") as im:
    px = im.load()
print(px[4, 4])
px[4, 4] = (0, 0, 0)
print(px[4, 4])

Results in the following:

(23, 24, 68)
(0, 0, 0)

Access using negative indexes is also possible.

px[-1, -1] = (0, 0, 0)
print(px[-1, -1])

PixelAccess Class

class PixelAccess
__getitem__(self, xy: tuple[int, int]) float | tuple[int, ...]

Returns the pixel at x,y. The pixel is returned as a single value for single band images or a tuple for multi-band images.

Parameters:

xy – The pixel coordinate, given as (x, y).

Returns:

a pixel value for single band images, a tuple of pixel values for multiband images.

__setitem__(self, xy: tuple[int, int], color: float | tuple[int, ...]) None

Modifies the pixel at x,y. The color is given as a single numerical value for single band images, and a tuple for multi-band images.

Parameters:
  • xy – The pixel coordinate, given as (x, y).

  • color – The pixel value according to its mode, e.g. tuple (r, g, b) for RGB mode.