Bands¶

An image can consist of one or more bands of data. The Python Imaging Libraryallows you to store several bands in a single image, provided they all have thesame dimensions and depth. For example, a PNG image might have ‘R’, ‘G’, ‘B’,and ‘A’ bands for the red, green, blue, and alpha transparency values. Manyoperations act on each band separately, e.g., histograms. It is often useful tothink of each pixel as having one value per band.

To get the number and names of bands in an image, use thegetbands() method.

Modes¶

Themode of an image is a string which defines the type and depth of a pixel in theimage. Each pixel uses the full range of the bit depth. So a 1-bit pixel has a range of0-1, an 8-bit pixel has a range of 0-255, a 32-signed integer pixel has the range ofINT32 and a 32-bit floating point pixel has the range of FLOAT32. The current releasesupports the following standard modes:

• 1 (1-bit pixels, black and white, stored with one pixel per byte)

• L (8-bit pixels, grayscale)

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

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

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

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

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

  • Note that this refers to the JPEG, and not the ITU-R BT.2020, standard

• LAB (3x8-bit pixels, the L*a*b color space)

• HSV (3x8-bit pixels, Hue, Saturation, Value color space)

  • Hue’s range of 0-255 is a scaled version of 0 degrees <= Hue < 360 degrees

• I (32-bit signed integer pixels)

• F (32-bit floating point pixels)

Pillow also provides limited support for a few additional modes, including:

• LA (L with alpha)

• PA (P with alpha)

• RGBX (true color with padding)

• RGBa (true color with premultiplied alpha)

• La (L with premultiplied alpha)

• I;16 (16-bit unsigned integer pixels)

• I;16L (16-bit little endian unsigned integer pixels)

• I;16B (16-bit big endian unsigned integer pixels)

• I;16N (16-bit native endian unsigned integer pixels)

Premultiplied alpha is where the values for each other channel have beenmultiplied by the alpha. For example, an RGBA pixel of(10,20,30,127)would convert to an RGBa pixel of(5,10,15,127). The values of the R,G and B channels are halved as a result of the half transparency in the alphachannel.

Apart from these additional modes, Pillow doesn’t yet support multichannelimages with a depth of more than 8 bits per channel.

Pillow also doesn’t support user-defined modes; if you need to handle bandcombinations that are not listed above, use a sequence of Image objects.

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

Size¶

You can read the image size through thesizeattribute. This is a 2-tuple, containing the horizontal and vertical size inpixels.

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 pixelcorners; 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). Rectanglesare represented as 4-tuples, (x1, y1, x2, y2), with the upper left corner givenfirst.

Palette¶

The palette mode (P) uses a color palette to define the actual color foreach pixel.

Colors¶

To specify colors, you can use tuples with a value for each channel in the image, e.g.Image.new("RGB",(1,1),(255,0,0)).

If an image has a single channel, you can use a single number instead, e.g.Image.new("L",(1,1),255). For “F” mode images, floating point values are alsoaccepted. In the case of “P” mode images, these will be indexes for the color palette.

If a single value is used for an image with more than one channel, it will still beparsed:

>>>fromPILimportImage>>>im=Image.new("RGBA",(1,1),0x04030201)>>>im.getpixel((0,0))(1, 2, 3, 4)

Some methods accept other forms, such as color names. SeeColor names.

Info¶

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

How such information is handled when loading and saving image files is up tothe file format handler (see the chapter onImage file formats). Mosthandlers add properties to theinfo attribute whenloading an image, but ignore it when saving images.

Transparency¶

If an image does not have an alpha band, transparency may be specified in theinfo attribute with a “transparency” key.

Most of the time, the “transparency” value is a single integer, describingwhich pixel value is transparent in a “1”, “L”, “I” or “P” mode image.However, PNG images may have three values, one for each channel in an “RGB”mode image, or can have a byte string for a “P” mode image, to specify thealpha value for each palette entry.

Orientation¶

A common element of theinfo attribute for JPG andTIFF images is the EXIF orientation tag. This is an instruction for how theimage data should be oriented. For example, it may instruct an image to berotated by 90 degrees, or to be mirrored. To apply this information to animage,exif_transpose() can be used.

Filters¶

For geometry operations that may map multiple input pixels to a single outputpixel, the Python Imaging Library provides different resamplingfilters.

Resampling.NEAREST

Pick one nearest pixel from the input image. Ignore all other input pixels.

Resampling.BOX

Each pixel of source image contributes to one pixel of thedestination image with identical weights.For upscaling is equivalent ofResampling.NEAREST.This filter can only be used with theresize()andthumbnail() methods.

Added in version 3.4.0.

Resampling.BILINEAR

For resize calculate the output pixel value using linear interpolationon all pixels that may contribute to the output value.For other transformations linear interpolation over a 2x2 environmentin the input image is used.

Resampling.HAMMING

Produces a sharper image thanResampling.BILINEAR, doesn’t havedislocations on local level like withResampling.BOX.This filter can only be used with theresize()andthumbnail() methods.

Added in version 3.4.0.

Resampling.BICUBIC

For resize calculate the output pixel value using cubic interpolationon all pixels that may contribute to the output value.For other transformations cubic interpolation over a 4x4 environmentin the input image is used.

Resampling.LANCZOS

Calculate the output pixel value using a high-quality Lanczos filter (atruncated sinc) on all pixels that may contribute to the output value.This filter can only be used with theresize()andthumbnail() methods.

Added in version 1.1.3.