pythonware.com ::: library ::: Python Imaging Library Handbook

Concepts

The Python Imaging Library handles raster images, that is, rectangles of pixel data.

Mode

The mode of an image defines the type and depth of a pixel in the image. The current release supports the following standard modes:

  • 1 (1-bit pixels, black and white, stored as 8-bit pixels)

  • L (8-bit pixels, black and white)

  • P (8-bit pixels, mapped to any other mode using a colour palette)

  • RGB (3x8-bit pixels, true colour)

  • RGBA (4x8-bit pixels, true colour with transparency mask)

  • CMYK (4x8-bit pixels, colour separation)

  • YCbCr (3x8-bit pixels, colour video format)

  • I (32-bit integer pixels)

  • F (32-bit floating point pixels)

PIL also supports a few special modes, including RGBX (true colour with padding) and RGBa (true colour with premultiplied alpha).

You can read the mode of an image through the mode attribute. This is a string containing one of the above values.

Size

You can read the image size through the size attribute. This is a 2-tuple, containing the horizontal and vertical size in pixels.

Coordinate System

The Python Imaging Library uses a Cartesian pixel coordinate system, with (0,0) in the upper left corner. Note that the coordinates refer to the implied pixel corners; the centre of a pixel addressed as (0, 0) actually lies at (0.5, 0.5):

Coordinates are usually passed to the library as 2-tuples (x, y). Rectangles are represented as 4-tuples, with the upper left corner given first. For example, a rectangle covering all of an 800x600 pixel image is written as (0, 0, 800, 600).

Palette

The palette mode ("P") uses a colour palette to define the actual colour for each pixel.

Info

You can attach auxiliary information to an image using the info attribute. This is a dictionary object.

How such information is handled when loading and saving image files is up to the file format handler (see the chapter on Image File Formats).