B. Getting Support
Patches, fixes, updates, and new utilities are welcome. If you
stumble upon files that the library does not handle as expected, post
a note to the Image SIG mailing list (see below). If you fix such a
problem and supply a patch, you may send me the image file anyway so I
don't mess things up again in later revisions.
Ideas on formats and features that should be added, sample
files, and other contributions are also welcome.
For all sorts of updates, including information on commercial
extensions to PIL, check the PIL product page, at:
You may also find information related to PIL at http://www.pythonware.com or
via the Python home page http://www.python.org
For support and general questions, send e-mail to the Python
Image SIG mailing list:
You can join the Image SIG by sending a mail to
image-sig-request@python.org. Put
subscribe in the message body to automatically
subscribe to the list, or help to get additional
information.
Alternatively, you can use the Python mailing list,
python-list@python.org, or the newsgroup
comp.lang.python.
A. Software License
The Python Imaging Library is:
Copyright © 1997-2001 by Secret Labs AB
Copyright © 1995-2001 by Fredrik Lundh
By obtaining, using, and/or copying this software and/or its
associated documentation, you agree that you have read, understood,
and will comply with the following terms and
conditions:
Permission to use, copy, modify, and distribute this software and its
associated documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appears in all
copies, and that both that copyright notice and this permission notice
appear in supporting documentation, and that the name of Secret Labs
AB or the author not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.
SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
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) RGBThe 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.
Example: Convert files to JPEGimport 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:
Example: Create JPEG Thumbnailsimport 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:
Example: Identify Image Filesimport 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.
Example: Copying a subrectangle from an image 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.
Example: Processing a subrectangle, and pasting 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:
Example: "Rolling" an imagedef 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:
Example: Splitting and merging bandsr, g, b = im.split()
im = Image.merge("RGB", (b, g, r)) Image Enhancement
The Python Imaging Library provides a number of methods and modules
that can be used for image enhancement.
Filters
The ImageFilter
module contains a number of pre-defined enhancement filters that can
be used with the filter method.
Example: Applying filtersimport ImageFilter
out = im.filter(ImageFilter.DETAIL)
Point Operations
The point method can be used to translate the
pixel values of an image. This can for example be used to manipulate
the image contrast. In most cases, you can use pass this function a
function object expecting one argument. Each pixel is processed
according to that function:
Example: Applying point transforms# multiply each pixel by 1.2
out = im.point(lambda i: i * 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:
Example: Processing individual bands# 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)
Note the syntax used to create the mask:
imout = im.point(lambda i: expression and 255)
Python only evaluates as much 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.
Enhancement
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.
Example: Enhancing imagesimport 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:
Example: Reading sequencesimport 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:
Example: A sequence iterator classclass 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:
Example: Drawing Postscriptimport 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.
Example: Reading from an open filefp = open("lena.ppm", "rb")
im = Image.open(fp) To read an image from data that you have in a string, use the
StringIO class:
Example: Reading from a stringimport 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.
Example: Reading from a tar archiveimport TarIO
fp = TarIO.TarIO("Imaging.tar", "Imaging/test/lena.ppm")
im = Image.open(fp) See comments in these modules for details.
Controlling the Decoder
Some decoders allow you to manipulate the image while reading it from
file. This can often be used to speed up decoding when creating
thumbnails (when speed is usually be 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.
Example: Reading in draft modeim = 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)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.
D. Writing Your Own File Decoder
The Python Imaging Library uses a plug-in model which allows you to add your own decoders to the library, without any changes to the library itself. Such plug-ins have names like XxxImagePlugin.py, where Xxx is a unique format name (usually an abbreviation).
A decoder plug-in should contain a decoder class, based on the ImageFile base class defined in the module with the same name. This class should provide an _open method, which reads the file header and sets up at least the mode and size attributes. To be able to load the file, the method must also create a list of tile descriptors. The class must be explicitly registered, via a call to the Image module.
For performance reasons, it is important that the _open method quickly rejects files that do not have the appropriate contents.
Example
The following plug-in supports a simple format, which has a 128-byte header consisting of the words "SPAM" followed by the width, height, and pixel size in bits. The header fields are separated by spaces. The image data follows directly after the header, and can be either bi-level, greyscale, or 24-bit true colour.
Example: File: SpamImagePlugin.pyimport Image, ImageFile
import string
class SpamImageFile(ImageFile.ImageFile):
format = "SPAM"
format_description = "Spam raster image"
def _open(self):
# check header
header = self.fp.read(128)
if header[:4] != "SPAM":
raise SyntaxError, "not a SPAM file"
header = string.split(header)
# size in pixels (width, height)
self.size = string.atoi(header[1]), string.atoi(header[2])
# mode setting
bits = string.atoi(header[3])
if bits == 1:
self.mode = "1"
elif bits == 8:
self.mode = "L"
elif bits == 24:
self.mode = "RGB"
else:
raise SyntaxError, "unknown number of bits"
# data descriptor
self.tile = [("raw", (0, 0) + self.size, 128,
(self.mode, 0, 1))]
Image.register_open("SPAM", SpamImageFile)
Image.register_extension("SPAM", ".spam")
Image.register_extension("SPAM", ".spa") # dos version The format handler must always set the size and mode attributes. If these are not set, the file cannot be opened. To simplify the decoder, the calling code considers exceptions like SyntaxError, KeyError, and IndexError, as a failure to identify the file.
Note that the decoder must be explicitly registered using the register_open function in the Image module. Although not required, it is also a good idea to register any extensions used by this format.
The Tile Attribute
To be able to read the file as well as just identifying it, the tile attribute must also be set. This attribute consists of a list of tile descriptors, where each descriptor specifies how data should be loaded to a given region in the image. In most cases, only a single descriptor is used, covering the full image.
The tile descriptor is a 4-tuple with the following contents:
(decoder, region, offset, parameters)
The fields are used as follows:
decoder. Specifies which decoder to use. The "raw" decoder used here supports uncompressed data, in a variety of pixel formats. For more information on this decoder, see the description below.
region. A 4-tuple specifying where to store data in the image.
offset. Byte offset from the beginning of the file to image data.
parameters. Parameters to the decoder. The contents of this field depends on the decoder specified by the first field in the tile descriptor tuple. If the decoder doesn't need any parameters, use None for this field.
Note that the tile attribute contains a list of tile descriptors, not just a single descriptor.
The Raw Decoder
The raw decoder is used to read uncompressed data from an image file. It can be used with most uncompressed file formats, such as PPM, BMP, uncompressed TIFF, and many others. To use the raw decoder with the fromstring function, use the following syntax:
image = fromstring(
mode, size, data, "raw",
raw mode, stride, orientation
)When used in a tile descriptor, the parameter field should look like:
(raw mode, stride, orientation)
The fields are used as follows:
raw mode. The pixel layout used in the file, and is used to properly convert data to PIL's internal layout. For a summary of the available formats, see the table below.
stride. The distance in bytes between two consecutive lines in the image. If 0, the image is assumed to be packed (no padding between lines). If omitted, the stride defaults to 0.
orientation. Whether the first line in the image is the top line on the screen (1), or the bottom line (-1). If omitted, the orientation defaults to 1.
The raw mode field is used to determine how the data should be unpacked to match PIL's internal pixel layout. PIL supports a large set of raw modes; for a complete list, see the table in the Unpack.c module. The following table describes some commonly used raw modes:
"1". 1-bit bilevel, stored with the leftmost pixel in the most significant bit. 0 means black, 1 means white.
"1;I". 1-bit inverted bilevel, stored with the leftmost pixel in the most significant bit. 0 means white, 1 means black.
"1;R". 1-bit reversed bilevel, stored with the leftmost pixel in the least significant bit. 0 means black, 1 means white.
"L". 8-bit greyscale. 0 means black, 255 means white.
"L;I". 8-bit inverted greyscale. 0 means white, 255 means black.
"P". 8-bit palette-mapped image.
"RGB". 24-bit true colour, stored as (red, green, blue).
"BGR". 24-bit true colour, stored as (blue, green, red).
"RGBX". 24-bit true colour, stored as (blue, green, red, pad).
"RGB;L". 24-bit true colour, line interleaved (first all red pixels, the all green pixels, finally all blue pixels).
Note that for the most common cases, the raw mode is simply the same as the mode.
The Python Imaging Library supports many other decoders, including JPEG, PNG, and PackBits. For details, see the decode.c source file, and the standard plug-in implementations provided with the library.
Decoding Floating Point Data
PIL provides some special mechanisms to allow you to load a wide variety of formats into a mode "F" (floating point) image memory.
You can use the "raw" decoder to read images where data is packed in any standard machine data type, using one of the following raw modes:
"F". 32-bit native floating point.
"F;8". 8-bit unsigned integer.
"F;8S". 8-bit signed integer.
"F;16". 16-bit little endian unsigned integer.
"F;16S". 16-bit little endian signed integer.
"F;16B". 16-bit big endian unsigned integer.
"F;16BS". 16-bit big endian signed integer.
"F;16N". 16-bit native unsigned integer.
"F;16NS". 16-bit native signed integer.
"F;32". 32-bit little endian unsigned integer.
"F;32S". 32-bit little endian signed integer.
"F;32B". 32-bit big endian unsigned integer.
"F;32BS". 32-bit big endian signed integer.
"F;32N". 32-bit native unsigned integer.
"F;32NS". 32-bit native signed integer.
"F;32F". 32-bit little endian floating point.
"F;32BF". 32-bit big endian floating point.
"F;32NF". 32-bit native floating point.
"F;64F". 64-bit little endian floating point.
"F;64BF". 64-bit big endian floating point.
"F;64NF". 64-bit native floating point.
The Bit Decoder
If the raw decoder cannot handle your format, PIL also provides a special "bit" decoder which can be used to read various packed formats into a floating point image memory.
To use the bit decoder with the fromstring function, use the following syntax:
image = fromstring(
mode, size, data, "bit",
bits, pad, fill, sign, orientation
)When used in a tile descriptor, the parameter field should look like:
(bits, pad, fill, sign, orientation)
The fields are used as follows:
bits. Number of bits per pixel (2-32). No default.
pad. Padding between lines, in bits. This is either 0 if there is no padding, or 8 if lines are padded to full bytes. If omitted, the pad value defaults to 8.
fill. Controls how data are added to, and stored from, the decoder bit buffer.
fill=0. Add bytes to the msb end of the decoder buffer; store pixels from the msb end.
fill=1. Add bytes to the lsb end of the decoder buffer; store pixels from the msb end.
fill=2. Add bytes to the msb end of the decoder buffer; store pixels from the lsb end.
fill=3. Add bytes to the lsb end of the decoder buffer; store pixels from the lsb end.
If omitted, the fill order defaults to 0.
sign. If non-zero, bit fields are sign extended. If zero or omitted, bit fields are unsigned.
orientation. Whether the first line in the image is the top line on the screen (1), or the bottom line (-1). If omitted, the orientation defaults to 1.
