Python Imaging Library Handbook
ISBN : -
Cover Design - Python Imaging Library Handbook
For your free electronic copy of this book please verify the numbers below.
(We need to do this to make sure you're a person and not a malicious script)
Sample Chapter From Python Imaging Library Handbook
Copyright © Fredrik Lundh, Matthew Ellis
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.
Let\'s look at a few possible uses of this library:
The Python Imaging Library is ideal for for image archival and batch processing applications. You can use the library to create thumbnails, convert between file formats, print images, etc.
The current version identifies and reads a large number of formats. Write support is intentionally restricted to the most commonly used interchange and presentation formats.
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.
The library contains some basic image processing functionality, including point operations, filtering with a set of built-in convolution kernels, and colour space conversions.
The library also supports image resizing, rotation and arbitrary affine transforms.
There\'s a histogram method allowing you to pull some statistics out of an image. This can be used for automatic contrast enhancement, and for global statistical analysis.
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
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
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" (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:
(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 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 of the Image class. When saving files, the name becomes important. Unless you specify the format, the library uses the filename extension to discover which file storage format to use.
Convert files to JPEG
import os, sys
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:
Create JPEG Thumbnails
import os, sys
It is important to note 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 size and compression type. Here\'s a simple script to quickly identify a set of image files:
Identify Image Files
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.
Copying a subrectangle from an image
box = (100, 100, 400, 400)
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 exactly 300x300 pixels.
The region could now be processed in a certain manner and pasted back.
Processing a subrectangle, and pasting it back
region = region.transpose(Image.ROTATE_180)
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:
Rolling an image
def roll(image, delta):
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:
Splitting and merging bands
r, g, b = im.split()
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.
Simple geometry transforms
out = im.resize((128, 128))
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.
Transposing an image
out = im.transpose(Image.FLIP_LEFT_RIGHT)
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.
The Python Imaging Library allows you to convert images between different pixel representations using the convert function.
Converting between modes
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).
The Python Imaging Library provides a number of methods and modules that can be used to enhance images.
The ImageFilter module contains a number of pre-defined enhancement filters that can be used with the filter method.
The point method can be used to translate the pixel values of an image (e.g. image contrast manipulation). In most cases, a function object expecting one argument can be passed to the this method. Each pixel is processed according to that function:
Applying point transforms
# multiply each pixel by 1.2
Using the above technique, you can quickly apply any simple expression to an image. You can also combine the point and paste methods to selectively modify an image:
Processing individual bands
# split the image into individual bands
Note the syntax used to create the mask:
imout = im.point(lambda i: expression and 255)
Python only evaluates the portion of a logical expression as is necessary to determine the outcome, and returns the last value examined as the result of the expression. So if the expression above is false (0), Python does not look at the second operand, and thus returns 0. Otherwise, it returns 255.
For more advanced image enhancement, use the classes in the ImageEnhance module. Once created from an image, an enhancement object can be used to quickly try out different settings.
You can adjust contrast, brightness, colour balance and sharpness in this way.
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 move between different frames:
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 allow 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:
A sequence iterator class
The Python Imaging Library includes functions to print images, text and graphics on Postscript printers. Here\'s a simple example:
More on Reading Images
As described earlier, the open function of the Image module is used to open an image file. In most cases, you simply pass it the filename as an 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 object must implement read, seek and tell methods, and be opened in binary mode.
Reading from an open file
fp = open("lena.ppm", "rb")
To read an image from string data, use the StringIO class:
Reading from a string
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.
Reading from a tar archive
Controlling the Decoder
Some decoders allow you to manipulate the image while reading it from a file. This can often be used to speed up decoding when creating thumbnails (when speed is usually more important than quality) and printing to a monochrome laser printer (when only a greyscale version of the image is needed).
The draft method manipulates an opened but not yet loaded image so it as closely as possible matches the given mode and size. This is done by reconfiguring the image decoder.
Reading in draft mode
im = Image.open(file)
This prints something like:
original = RGB (512, 512)
Note that the resulting image may not exactly match the requested mode and size. To make sure that the image is not larger than the given size, use the thumbnail method instead.