# Python Imaging Library/Printable version

The current, editable version of this book is available in Wikibooks, the open-content textbooks collection, at
https://en.wikibooks.org/wiki/Python_Imaging_Library

# Overview
## Modules in PIL

    Image ImageChops ImageColor ImageDraw ImageEnhance ImageFile ImageFileIO ImageFilter ImageFont ImageGrab ImageMath ImageOps ImagePalette ImagePath ImageQt ImageSequence ImageStat ImageTk ImageWin PSDraw

# Getting PIL

Python is obviously a prerequisite for using PIL. The current version of PIL is 1.1.7, and this supports Python up to v.2.6.
PIL is available from PythonWare at this page. Source code can be built for any platform, and Windows binaries are available.

## Installing PIL
### Windows

To install on Windows machines, go to the page given above and download the appropriate binary executable for the version of Python that you have. Run this executable and follow the instructions given by the installer.

### Linux

On Linux, you can either compile the source yourself, or install using your package manager. For Debian-based systems, apt-get can be used:
In Gentoo:

### Mac OS X

To install on a Mac OS X system , visit http://pythonmac.org and download the relevant .dmg file and install as any other application.

## Using PIL

Once install you need to import the PIL modules you want to use. Basic functions are found in the Image module, so the following will work:
    import Image
You can then access functions as usual, e.g. Image.load(filename). Uses of the other modules available are given in the overview section, and these are imported in exactly the same way.

# File IO

File operations in PIL are very simple, and reflect normal Python methods.

## show

Displays a copy of the specified image in a window.

## save
# Editing Pixels

With PIL you can easily access and change the data stored in the pixels of an image. To get the pixel map, call load on an image. The pixel data can then be retrieved by indexing the pixel map as an array.
When you change the pixel data, it is changed in the image it came from (since the pixel map is just a reference to the data rather than a copy).

### Example

The following snippet shows how to change the pixel values in an image based on the index of the pixel:

# Drop Shadows

Drop shadows are a common way to emphasise an image.

## Creating the shadow

The shadow can be created by taking a simple solid rectangle (usually black or grey, but you can also have coloured shadows) and applying the ImageFilter BLUR filter to it repeatedly. This filter uses a 5×5 kernel, so a single iteration will not be smoothly blurred. You can experiment to find the optimum number of iterations for your purpose.
First, let us ignore the last step and concentrate on the shadow. Let's see what we get for various numbers of iterations. The border was set to 8, the background was white and the shadow is 0x444444 grey. The initial image was 30×30pixels.
| 1 iteration | 2 iterations | 3 iterations | 5 iterations | 10 iterations |
Notice that the shadow is always contained in the image boundary - this is caused by the blue filter "hitting" the image boundaries. If the border were to be made larger, you would see the blur spreading out at large numbers of iterations.
Now, we can add the last section and try it. The result is below. This image used an offset of [3,3] with 3 iterations and the same colours as before.
| Original image (the SVG was made into a rectangular PNG) | Resulting image with drop shadow |

### Efficiency

The calculations needed to produce the blurred shadow is computationally expensive, especially for large images or many iterations, but the same shadow can be reused for any image of the same size. So, if you are going to creare lot of identically-sized image tiles, it will be beneficial to compute the shadow just once, and reuse it for each image.
You can also speed up the calculation of the shadow by recognising that the centre of the shadow will be flat fill of the shadow colour - only the edges need to be computed. How far in the lighter border extends depends on the number of iterations. Making this change reduces the problem from quadratic in the size of the image (i.e. doubling the width quadruples the time taken) to linear (doubling the width doubles the time) for large images, but will be unlikely to have a large effect for icons.