Tutorial

Using the Image Class

The most important class in the Python Imaging Library is the Image class, defined in the module with the same name. You can create instances of this class in several ways; either by loading images from files, processing other images, or creating images from scratch.

To load an image from a file, use the open function in the Image module.

    >>> import Image
    >>> im = Image.open("lena.ppm")

If successful, this function returns an Image object. You can now use instance attributes to see what the file really contained.

    >>> print im.format, im.size, im.mode
    PPM (512, 512) RGB

The format attribute identifies the source of an image. If the image was not read from a file, it is set to None. The size attribute is a 2-tuple containing width and height (in pixels). The mode attribute defines the number and names of the bands in the image, and also the pixel type and depth. Common modes are "L" (for luminance) for greyscale images, "RGB" for true colour images, and "CMYK" for pre-press images.

If the file cannot be opened, an IOError exception is raised.

Once you have an instance of the Image class, you can use the methods defined by this class to process and manipulate the image. For example, let's display the image we just loaded:

    >>> im.show()

(The standard version of show is not very efficient, since it saves the image to a temporary file and calls the xv utility to display the image. If you don't have xv installed, it won't even work. When it does work, it is very handy for debugging and tests, though.)

The following sections provide an overview of the different functions provided in this library.

Reading and Writing Images

The Python Imaging Library supports a wide variety of image file formats. To read files from disk, you use the open function in the Image module. You don't have to know the file format to open a file. The library automatically determines the format based on the contents of the file.

To save a file, use the save method in the Image class. When saving files, the name becomes important. Unless you specify the format, the library use the filename extension to figure out which file format to use when storing the file.

import os, sys
import Image

for infile in sys.argv[1:]:
    outfile = os.path.splitext(infile)[0] + ".jpg"
    if infile != outfile:
        try:
            Image.open(infile).save(outfile)
        except IOError:
            print "cannot convert", infile

You can use a second argument to the save method in order to explicitly specify a file format. If you use a non-standard extension, you must always specify the format this way:

import os, sys
import Image

for infile in sys.argv[1:]:
    outfile = os.path.splitext(infile)[0] + ".thumbnail"
    if infile != outfile:
        try:
            im = Image.open(infile)
            im.thumbnail((128, 128))
            im.save(outfile, "JPEG")
        except IOError:
            print "cannot create thumbnail for", infile

An important detail is that the library doesn't decode or load the raster data unless it really has to. When you open a file, the file header is read to determine the file format and extract things like mode, size, and other properties required to decode the file, but the rest of the file is not processed until later.

This also means that opening an image file is a fast operation, independent of the file size and compression type. Here's a simple script to quickly identify a set of image files:

import sys
import Image

for infile in sys.argv[1:]:
    try:
        im = Image.open(infile)
        print infile, im.format, "%dx%d" % im.size, im.mode
    except IOError:
        pass

Cutting, Pasting and Merging Images

The Image class contains methods allowing you to manipulate regions within an image. To extract a sub-rectangle from an image, use the crop method.

    box = (100, 100, 400, 400)
    region = im.crop(box)

The region is defined by a 4-tuple, where coordinates are (left, upper, right, lower). The Python Imaging Library uses a coordinate system with (0, 0) in the upper left corner. Also note that coordinates refer to positions between the pixels, so the region in the above example is 300x300 pixels and nothing else.

You can now process the region in some fashion, and possibly paste it back.

    region = region.transpose(Image.ROTATE_180)
    im.paste(region, box)

When pasting regions back, the size of the region must match the given region exactly. In addition, the region cannot extend outside the image. However, the modes of the original image and the region do not need to match. If they don't, the region is automatically converted before being pasted (see the section on Colour Transforms below for details).

Here's an additional example:

def roll(image, delta):
    "Roll an image sideways"

    xsize, ysize = image.size

    delta = delta % xsize
    if delta == 0: return image

    part1 = image.crop((0, 0, delta, ysize))
    part2 = image.crop((delta, 0, xsize, ysize))
    image.paste(part2, (0, 0, xsize-delta, ysize))
    image.paste(part1, (xsize-delta, 0, xsize, ysize))

    return image

For more advanced tricks, the paste method can also take a transparency mask as an optional argument. In this mask, the value 255 indicates that the pasted image is opaque in that position (that is, the pasted image should be used as is). The value 0 means that the pasted image is completely transparent. Values in between indicate different levels of transparency.

The Python Imaging Library also allows you to work with the individual bands of an multi-band image, such as an RGB image. The split method creates a set of new images, each containing one band from the original multi-band image. The merge function takes a mode and a tuple of images, and combines them into a new image. The following sample swaps the three bands of an RGB image:

r, g, b = im.split()
im = Image.merge("RGB", (b, g, r))

Geometrical Transforms

The Image class contains methods to resize and rotate an image. The former takes a tuple giving the new size, the latter the angle in degrees counter-clockwise.

out = im.resize((128, 128))
out = im.rotate(45) # degrees counter-clockwise

To rotate the image in full 90 degree steps, you can either use the rotate method or the transpose method. The latter can also be used to flip an image around its horizontal or vertical axis.

out = im.transpose(Image.FLIP_LEFT_RIGHT)
out = im.transpose(Image.FLIP_TOP_BOTTOM)
out = im.transpose(Image.ROTATE_90)
out = im.transpose(Image.ROTATE_180)
out = im.transpose(Image.ROTATE_270)

There's no difference in performance or result between transpose(ROTATE) and corresponding rotate operations.

A more general form of image transformations can be carried out via the transform method. See the reference section for details.

Colour Transforms

The Python Imaging Library allows you to convert images between different pixel representations using the convert function.

    im = Image.open("lena.ppm").convert("L")

The library supports transformations between each supported mode and the "L" and "RGB" modes. To convert between other modes, you may have to use an intermediate image (typically an "RGB" image).

Image Enhancement

The Python Imaging Library provides a number of methods and modules that can be used for image enhancement.

import ImageFilter
out = im.filter(ImageFilter.DETAIL)

# multiply each pixel by 1.2
out = im.point(lambda i: i * 1.2)

# split the image into individual bands
source = im.split()

R, G, B = 0, 1, 2

# select regions where red is less than 100
mask = source[R].point(lambda i: i < 100 and 255)

# process the green band
out = source[G].point(lambda i: i * 0.7)

# paste the processed band back, but only where red was < 100
source[G].paste(out, None, mask)

# build a new multiband image
im = Image.merge(im.mode, source)

    imout = im.point(lambda i: expression and 255)

import ImageEnhance

enh = ImageEnhance.Contrast(im)
enh.enhance(1.3).show("30% more contrast")

Image Sequences

The Python Imaging Library contains some basic support for image sequences (also called animation formats). Supported sequence formats include FLI/FLC, GIF, and a few experimental formats. TIFF files can also contain more than one frame.

When you open a sequence file, PIL automatically loads the first frame in the sequence. You can use the seek and tell methods to change which frame to work with:

import Image

im = Image.open("animation.gif")
im.seek(1) # skip to the second frame

try:
    while 1:
        im.seek(im.tell()+1)
        # do something to im
except EOFError:
    pass # end of sequence

As seen in this example, you'll get an EOFError exception when the sequence ends.

Note that most drivers in the current version of the library only allows you to seek to the next frame (as in the above example). To rewind the file, you may have to reopen it.

The following iterator class lets you to use the for-statement to loop over the sequence:

class ImageSequence:
    def __init__(self, im):
        self.im = im
    def __getitem__(self, ix):
        try:
            if ix:
                self.im.seek(ix)
            return self.im
        except EOFError:
            raise IndexError # end of sequence

for frame in ImageSequence(im):
    # ...do something to frame...

Postscript Printing

The Python Imaging Library includes functions to print images, text and graphics on Postscript printers. Here's a simple example:

import Image
import PSDraw

im = Image.open("lena.ppm")
title = "lena"
box = (1*72, 2*72, 7*72, 10*72) # in points

ps = PSDraw.PSDraw() # default is sys.stdout
ps.begin_document(title)
 
# draw the image (75 dpi)
ps.image(box, im, 75)
ps.rectangle(box) 

# draw centered title
ps.setfont("HelveticaNarrow-Bold", 36)
w, h, b = ps.textsize(title)
ps.text((4*72-w/2, 1*72-h), title) 

ps.end_document()

More on Reading Images

As described earlier, you use the open function in the Image module to open an image file. In most cases, you simply pass it the filename as argument:

im = Image.open("lena.ppm")

If everything goes well, the result is an Image object. Otherwise, an IOError exception is raised.

You can use a file-like object instead of the filename. The file object must implement the read, seek and tell methods, and be opened in binary mode.

fp = open("lena.ppm", "rb")
im = Image.open(fp)

To read an image from data that you have in a string, use the StringIO class:

import StringIO

im = Image.open(StringIO.StringIO(buffer))

Note that the library rewinds the file (using seek(0)) before reading the image header. In addition, seek will also be used when the image data is read (by the load method). If the image file is embedded in a larger file, such as a tar file, you can use the ContainerIO or TarIO modules to access it.

import TarIO

fp = TarIO.TarIO("Imaging.tar", "Imaging/test/lena.ppm")
im = Image.open(fp)

See comments in these modules for details.

im = Image.open(file)
print "original =", im.mode, im.size

im.draft("L", (100, 100))
print "draft =", im.mode, im.size

    original = RGB (512, 512)
    draft = L (128, 128)