pil-handbook.pdf

Python Imaging Library Overview

PIL 1.1.3 | March 12, 2002 | Fredrik Lundh, Matthew Ellis

Introduction

The Python Imaging Library adds image processing capabilities to your Python

interpreter.

This library provides extensive file format support, an efficient internal representation,

and fairly powerful image processing capabilities.

The core image library is designed for fast access to data stored in a few basic pixel

formats. It should provide a solid foundation for a general image processing tool.

intentionally restricted to the most commonly used interchange and presentation formats.

Image Display

The current release includes Tk PhotoImage and BitmapImage interfaces, as well as a

Windows DIB interface that can be used with PythonWin. For X and Mac displays, you can

use Jack Jansen's img library.

For debugging, there's also a show method in the Unix version which calls xv to display the

image.

Image Processing

The library contains some basic image processing functionality, including point operations,

filtering with a set of built-in convolution kernels, and colour space conversions.

Tutorial

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 examine the file contents.

>>> 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

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 though, it is very handy for debugging and tests.)

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, use the open function in the Image module. You don't have to know the file

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

A second argument can be supplied to the save method which explicitly specifies a file

format. If you use a non-standard extension, you must always specify the format this way:

Example: Create JPEG Thumbnails

im = Image.open(infile)

im.thumbnail((128, 128))

im.save(outfile, "JPEG")

except IOError:

print "cannot create thumbnail for", infile

It is important to note 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 means that opening an image file is a fast operation, which is independent of the file

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.

Example: Copying a subrectangle from an image

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

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:

Example: Rolling an image

def roll(image, delta):

"Roll an image sideways"

xsize, ysize = image.size

delta = delta % xsize

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:

Example: Splitting and merging bands

r, g, b = im.split()

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

To rotate the image in 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.

Example: Transposing an image

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)

The Python Imaging Library provides a number of methods and modules that can be used

to enhance images.