Image Archives¶

The Python Imaging Library is ideal 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.

Image Display¶

The current release includes Tk PhotoImage and BitmapImage interfaces, as well as a Windows DIB interface that can be used with PythonWin and other Windows-based toolkits. Many other GUI toolkits come with some kind of PIL support.

For debugging, there’s also a show() method which saves an image to disk, and calls an external display utility.

Image Processing¶

The library contains 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:

>>> from PIL 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:

>>> from __future__ import print_function
>>> 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” (luminance) for greyscale images, “RGB” for true color 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 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.

from __future__ import print_function
import os, sys
from PIL import Image

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

from __future__ import print_function
import os, sys
from PIL import Image

size = (128, 128)

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

from __future__ import print_function
import sys
from PIL import Image

for infile in sys.argv[1:]:
    try:
        with Image.open(infile) as im:
            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)

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

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

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

Geometrical transforms¶

The PIL.Image.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

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)

Color transforms¶

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

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

Image enhancement¶

The Python Imaging Library provides a number of methods and modules that can be used to enhance images.

from PIL 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)

from PIL 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 move between different frames:

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

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:

from PIL import Image
from PIL 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 title
ps.setfont("HelveticaNarrow-Bold", 36)
ps.text((3*72, 4*72), title)

ps.end_document()

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 PIL.Image.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.

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

import StringIO

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

from PIL import TarIO

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

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.

from __future__ import print_function
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)

Bands¶

An image can consist of one or more bands of data. The Python Imaging Library allows you to store several bands in a single image, provided they all have the same dimensions and depth.

To get the number and names of bands in an image, use the getbands() method.

Modes¶

The mode of an image defines the type and depth of a pixel in the image. The current release supports the following standard modes:

• 1 (1-bit pixels, black and white, stored with one pixel per byte)
• L (8-bit pixels, black and white)
• P (8-bit pixels, mapped to any other mode using a color palette)
• RGB (3x8-bit pixels, true color)
• RGBA (4x8-bit pixels, true color with transparency mask)
• CMYK (4x8-bit pixels, color separation)
• YCbCr (3x8-bit pixels, color video format)
• LAB (3x8-bit pixels, the L*a*b color space)
• HSV (3x8-bit pixels, Hue, Saturation, Value color space)
• I (32-bit signed integer pixels)
• F (32-bit floating point pixels)

PIL also provides limited support for a few special modes, including LA (L with alpha), RGBX (true color with padding) and RGBa (true color with premultiplied alpha). However, PIL doesn’t support user-defined modes; if you to handle band combinations that are not listed above, use a sequence of Image objects.

You can read the mode of an image through the mode attribute. This is a string containing one of the above values.

Size¶

You can read the image size through the size attribute. This is a 2-tuple, containing the horizontal and vertical size in pixels.

Coordinate System¶

The Python Imaging Library uses a Cartesian pixel coordinate system, with (0,0) in the upper left corner. Note that the coordinates refer to the implied pixel corners; the centre of a pixel addressed as (0, 0) actually lies at (0.5, 0.5).

Coordinates are usually passed to the library as 2-tuples (x, y). Rectangles are represented as 4-tuples, with the upper left corner given first. For example, a rectangle covering all of an 800x600 pixel image is written as (0, 0, 800, 600).

Palette¶

The palette mode (P) uses a color palette to define the actual color for each pixel.

Info¶

You can attach auxiliary information to an image using the info attribute. This is a dictionary object.

How such information is handled when loading and saving image files is up to the file format handler (see the chapter on Image file formats). Most handlers add properties to the info attribute when loading an image, but ignore it when saving images.

Filters¶

For geometry operations that may map multiple input pixels to a single output pixel, the Python Imaging Library provides four different resampling filters.

NEAREST

Pick the nearest pixel from the input image. Ignore all other input pixels.

BILINEAR

For resize calculate the output pixel value using linear interpolation on all pixels that may contribute to the output value. For other transformations linear interpolation over a 2x2 environment in the input image is used.

BICUBIC

For resize calculate the output pixel value using cubic interpolation on all pixels that may contribute to the output value. For other transformations cubic interpolation over a 4x4 environment in the input image is used.

LANCZOS

Calculate the output pixel value using a high-quality Lanczos filter (a truncated sinc) on all pixels that may contribute to the output value. In the current version of PIL, this filter can only be used with the resize and thumbnail methods.

New in version 1.1.3.

Release¶

Details about making a Pillow release.

PIL/__init__.py _imaging.c setup.py

Examples¶

The following script loads an image, rotates it 45 degrees, and displays it using an external viewer (usually xv on Unix, and the paint program on Windows).

from PIL import Image
im = Image.open("bride.jpg")
im.rotate(45).show()

from PIL import Image
import glob, os

size = 128, 128

for infile in glob.glob("*.jpg"):
    file, ext = os.path.splitext(infile)
    im = Image.open(infile)
    im.thumbnail(size)
    im.save(file + ".thumbnail", "JPEG")

Functions¶

PIL.Image.open(fp, mode='r')¶

Opens and identifies the given image file.

This is a lazy operation; this function identifies the file, but the file remains open and the actual image data is not read from the file until you try to process the data (or call the load() method). See new().

Parameters:	file – A filename (string) or a file object. The file object must implement read(), seek(), and tell() methods, and be opened in binary mode. mode – The mode. If given, this argument must be “r”.
Returns:	An Image object.
Raises IOError:	If the file cannot be found, or the image cannot be opened and identified.

Warning

To protect against potential DOS attacks caused by “decompression bombs” (i.e. malicious files which decompress into a huge amount of data and are designed to crash or cause disruption by using up a lot of memory), Pillow will issue a DecompressionBombWarning if the image is over a certain limit. If desired, the warning can be turned into an error with warnings.simplefilter(‘error’, Image.DecompressionBombWarning) or suppressed entirely with warnings.simplefilter(‘ignore’, Image.DecompressionBombWarning). See also the logging documentation to have warnings output to the logging facility instead of stderr.

The Image Class¶

class PIL.Image.Image¶

This class represents an image object. To create Image objects, use the appropriate factory functions. There’s hardly ever any reason to call the Image constructor directly.

• open()
• new()
• frombytes()

An instance of the Image class has the following methods. Unless otherwise stated, all methods return a new instance of the Image class, holding the resulting image.

Image.convert(mode=None, matrix=None, dither=None, palette=0, colors=256)¶

Returns a converted copy of this image. For the “P” mode, this method translates pixels through the palette. If mode is omitted, a mode is chosen so that all information in the image and the palette can be represented without a palette.

The current version supports all possible conversions between “L”, “RGB” and “CMYK.” The matrix argument only supports “L” and “RGB”.

When translating a color image to black and white (mode “L”), the library uses the ITU-R 601-2 luma transform:

L = R * 299/1000 + G * 587/1000 + B * 114/1000

The default method of converting a greyscale (“L”) or “RGB” image into a bilevel (mode “1”) image uses Floyd-Steinberg dither to approximate the original image luminosity levels. If dither is NONE, all non-zero values are set to 255 (white). To use other thresholds, use the point() method.

Parameters:	mode – The requested mode. See: Modes. matrix – An optional conversion matrix. If given, this should be 4- or 16-tuple containing floating point values. dither – Dithering method, used when converting from mode “RGB” to “P” or from “RGB” or “L” to “1”. Available methods are NONE or FLOYDSTEINBERG (default). palette – Palette to use when converting from mode “RGB” to “P”. Available palettes are WEB or ADAPTIVE. colors – Number of colors to use for the ADAPTIVE palette. Defaults to 256.
Return type:	Image
Returns:	An Image object.

The following example converts an RGB image (linearly calibrated according to ITU-R 709, using the D65 luminant) to the CIE XYZ color space:

rgb2xyz = (
    0.412453, 0.357580, 0.180423, 0,
    0.212671, 0.715160, 0.072169, 0,
    0.019334, 0.119193, 0.950227, 0 )
out = im.convert("RGB", rgb2xyz)

Image.copy()¶

Copies this image. Use this method if you wish to paste things into an image, but still retain the original.

Return type:	Image
Returns:	An Image object.

Image.crop(box=None)¶

Returns a rectangular region from this image. The box is a 4-tuple defining the left, upper, right, and lower pixel coordinate.

This is a lazy operation. Changes to the source image may or may not be reflected in the cropped image. To break the connection, call the load() method on the cropped copy.

Parameters:	box – The crop rectangle, as a (left, upper, right, lower)-tuple.
Return type:	Image
Returns:	An Image object.

Image.draft(mode, size)¶

Configures the image file loader so it returns a version of the image that as closely as possible matches the given mode and size. For example, you can use this method to convert a color JPEG to greyscale while loading it, or to extract a 128x192 version from a PCD file.

Note that this method modifies the Image object in place. If the image has already been loaded, this method has no effect.

Parameters:	mode – The requested mode. size – The requested size.

Image.filter(filter)¶

Filters this image using the given filter. For a list of available filters, see the ImageFilter module.

Parameters:	filter – Filter kernel.
Returns:	An Image object.

Image.getbands()¶

Returns a tuple containing the name of each band in this image. For example, getbands on an RGB image returns (“R”, “G”, “B”).

Returns:	A tuple containing band names.
Return type:	tuple

Image.getbbox()¶

Calculates the bounding box of the non-zero regions in the image.

Returns:	The bounding box is returned as a 4-tuple defining the left, upper, right, and lower pixel coordinate. If the image is completely empty, this method returns None.

Image.getcolors(maxcolors=256)¶

Returns a list of colors used in this image.

Parameters:	maxcolors – Maximum number of colors. If this number is exceeded, this method returns None. The default limit is 256 colors.
Returns:	An unsorted list of (count, pixel) values.

Image.getdata(band=None)¶

Returns the contents of this image as a sequence object containing pixel values. The sequence object is flattened, so that values for line one follow directly after the values of line zero, and so on.

Note that the sequence object returned by this method is an internal PIL data type, which only supports certain sequence operations. To convert it to an ordinary sequence (e.g. for printing), use list(im.getdata()).

Parameters:	band – What band to return. The default is to return all bands. To return a single band, pass in the index value (e.g. 0 to get the “R” band from an “RGB” image).
Returns:	A sequence-like object.

Image.getextrema()¶

Gets the the minimum and maximum pixel values for each band in the image.

Returns:	For a single-band image, a 2-tuple containing the minimum and maximum pixel value. For a multi-band image, a tuple containing one 2-tuple for each band.

Image.getpalette()¶

Returns the image palette as a list.

Returns:	A list of color values [r, g, b, ...], or None if the image has no palette.

Image.getpixel(xy)¶

Returns the pixel value at a given position.

Parameters:	xy – The coordinate, given as (x, y).
Returns:	The pixel value. If the image is a multi-layer image, this method returns a tuple.

Image.histogram(mask=None, extrema=None)¶

Returns a histogram for the image. The histogram is returned as a list of pixel counts, one for each pixel value in the source image. If the image has more than one band, the histograms for all bands are concatenated (for example, the histogram for an “RGB” image contains 768 values).

A bilevel image (mode “1”) is treated as a greyscale (“L”) image by this method.

If a mask is provided, the method returns a histogram for those parts of the image where the mask image is non-zero. The mask image must have the same size as the image, and be either a bi-level image (mode “1”) or a greyscale image (“L”).

Parameters:	mask – An optional mask.
Returns:	A list containing pixel counts.

Image.offset(xoffset, yoffset=None)¶

Deprecated since version 2.0.

Note

New code should use PIL.ImageChops.offset().

Returns a copy of the image where the data has been offset by the given distances. Data wraps around the edges. If yoffset is omitted, it is assumed to be equal to xoffset.

Parameters:	xoffset – The horizontal distance. yoffset – The vertical distance. If omitted, both distances are set to the same value.
Returns:	An Image object.

Image.paste(im, box=None, mask=None)¶

Pastes another image into this image. The box argument is either a 2-tuple giving the upper left corner, a 4-tuple defining the left, upper, right, and lower pixel coordinate, or None (same as (0, 0)). If a 4-tuple is given, the size of the pasted image must match the size of the region.

If the modes don’t match, the pasted image is converted to the mode of this image (see the convert() method for details).

Instead of an image, the source can be a integer or tuple containing pixel values. The method then fills the region with the given color. When creating RGB images, you can also use color strings as supported by the ImageColor module.

If a mask is given, this method updates only the regions indicated by the mask. You can use either “1”, “L” or “RGBA” images (in the latter case, the alpha band is used as mask). Where the mask is 255, the given image is copied as is. Where the mask is 0, the current value is preserved. Intermediate values can be used for transparency effects.

Note that if you paste an “RGBA” image, the alpha band is ignored. You can work around this by using the same image as both source image and mask.

Parameters:

im – Source image or pixel value (integer or tuple). box – An optional 4-tuple giving the region to paste into. If a 2-tuple is used instead, it’s treated as the upper left corner. If omitted or None, the source is pasted into the upper left corner. If an image is given as the second argument and there is no third, the box defaults to (0, 0), and the second argument is interpreted as a mask image. mask – An optional mask image.

Image.point(lut, mode=None)¶

Maps this image through a lookup table or function.

Parameters:

lut – A lookup table, containing 256 (or 65336 if self.mode==”I” and mode == “L”) values per band in the image. A function can be used instead, it should take a single argument. The function is called once for each possible pixel value, and the resulting table is applied to all bands of the image. mode – Output mode (default is same as input). In the current version, this can only be used if the source image has mode “L” or “P”, and the output has mode “1” or the source image mode is “I” and the output mode is “L”.

Returns:

An Image object.

Image.putalpha(alpha)¶

Adds or replaces the alpha layer in this image. If the image does not have an alpha layer, it’s converted to “LA” or “RGBA”. The new layer must be either “L” or “1”.

Parameters:	alpha – The new alpha layer. This can either be an “L” or “1” image having the same size as this image, or an integer or other color value.

Image.putdata(data, scale=1.0, offset=0.0)¶

Copies pixel data to this image. This method copies data from a sequence object into the image, starting at the upper left corner (0, 0), and continuing until either the image or the sequence ends. The scale and offset values are used to adjust the sequence values: pixel = value*scale + offset.

Parameters:	data – A sequence object. scale – An optional scale value. The default is 1.0. offset – An optional offset value. The default is 0.0.

Image.putpalette(data, rawmode='RGB')¶

Attaches a palette to this image. The image must be a “P” or “L” image, and the palette sequence must contain 768 integer values, where each group of three values represent the red, green, and blue values for the corresponding pixel index. Instead of an integer sequence, you can use an 8-bit string.

Parameters:	data – A palette sequence (either a list or a string).

Image.putpixel(xy, value)¶

Modifies the pixel at the given position. The color is given as a single numerical value for single-band images, and a tuple for multi-band images.

Note that this method is relatively slow. For more extensive changes, use paste() or the ImageDraw module instead.

See:

• paste()
• putdata()
• ImageDraw

Parameters:	xy – The pixel coordinate, given as (x, y). value – The pixel value.

Image.quantize(colors=256, method=None, kmeans=0, palette=None)¶

Convert the image to ‘P’ mode with the specified number of colors.

Parameters:	colors – The desired number of colors, <= 256 method – 0 = median cut 1 = maximum coverage 2 = fast octree kmeans – Integer palette – Quantize to the PIL.ImagingPalette palette.
Returns:	A new image

Image.resize(size, resample=0)¶

Returns a resized copy of this image.

Parameters:	size – The requested size in pixels, as a 2-tuple: (width, height). resample – An optional resampling filter. This can be one of PIL.Image.NEAREST (use nearest neighbour), PIL.Image.BILINEAR (linear interpolation), PIL.Image.BICUBIC (cubic spline interpolation), or PIL.Image.LANCZOS (a high-quality downsampling filter). If omitted, or if the image has mode “1” or “P”, it is set PIL.Image.NEAREST.
Returns:	An Image object.

Image.rotate(angle, resample=0, expand=0)¶

Returns a rotated copy of this image. This method returns a copy of this image, rotated the given number of degrees counter clockwise around its centre.

Parameters:

angle – In degrees counter clockwise. resample – An optional resampling filter. This can be one of PIL.Image.NEAREST (use nearest neighbour), PIL.Image.BILINEAR (linear interpolation in a 2x2 environment), or PIL.Image.BICUBIC (cubic spline interpolation in a 4x4 environment). If omitted, or if the image has mode “1” or “P”, it is set PIL.Image.NEAREST. expand – Optional expansion flag. If true, expands the output image to make it large enough to hold the entire rotated image. If false or omitted, make the output image the same size as the input image.

Returns:

An Image object.

Image.save(fp, format=None, **params)¶

Saves this image under the given filename. If no format is specified, the format to use is determined from the filename extension, if possible.

Keyword options can be used to provide additional instructions to the writer. If a writer doesn’t recognise an option, it is silently ignored. The available options are described in the image format documentation for each writer.

You can use a file object instead of a filename. In this case, you must always specify the format. The file object must implement the seek, tell, and write methods, and be opened in binary mode.

Parameters:	fp – File name or file object. format – Optional format override. If omitted, the format to use is determined from the filename extension. If a file object was used instead of a filename, this parameter should always be used. options – Extra parameters to the image writer.
Returns:	None
Raises:	KeyError – If the output format could not be determined from the file name. Use the format option to solve this. IOError – If the file could not be written. The file may have been created, and may contain partial data.

Image.seek(frame)¶

Seeks to the given frame in this sequence file. If you seek beyond the end of the sequence, the method raises an EOFError exception. When a sequence file is opened, the library automatically seeks to frame 0.

Note that in the current version of the library, most sequence formats only allows you to seek to the next frame.

See tell().

Parameters:	frame – Frame number, starting at 0.
Raises EOFError:
	If the call attempts to seek beyond the end of the sequence.

Image.show(title=None, command=None)¶

Displays this image. This method is mainly intended for debugging purposes.

On Unix platforms, this method saves the image to a temporary PPM file, and calls the xv utility.

On Windows, it saves the image to a temporary BMP file, and uses the standard BMP display utility to show it (usually Paint).

Parameters:	title – Optional title to use for the image window, where possible. command – command used to show the image

Image.split()¶

Split this image into individual bands. This method returns a tuple of individual image bands from an image. For example, splitting an “RGB” image creates three new images each containing a copy of one of the original bands (red, green, blue).

Returns:	A tuple containing bands.

Image.tell()¶

Returns the current frame number. See seek().

Returns:	Frame number, starting with 0.

Image.thumbnail(size, resample=3)¶

Make this image into a thumbnail. This method modifies the image to contain a thumbnail version of itself, no larger than the given size. This method calculates an appropriate thumbnail size to preserve the aspect of the image, calls the draft() method to configure the file reader (where applicable), and finally resizes the image.

Note that this function modifies the Image object in place. If you need to use the full resolution image as well, apply this method to a copy() of the original image.

Parameters:	size – Requested size. resample – Optional resampling filter. This can be one of PIL.Image.NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC, or PIL.Image.LANCZOS. If omitted, it defaults to PIL.Image.BICUBIC. (was PIL.Image.NEAREST prior to version 2.5.0)
Returns:	None

Image.tobitmap(name='image')¶

Returns the image converted to an X11 bitmap.

Note

This method only works for mode “1” images.

Parameters:	name – The name prefix to use for the bitmap variables.
Returns:	A string containing an X11 bitmap.
Raises ValueError:
	If the mode is not “1”

Image.tobytes(encoder_name='raw', *args)¶

Return image as a bytes object

Parameters:	encoder_name – What encoder to use. The default is to use the standard “raw” encoder. args – Extra arguments to the encoder.
Return type:	A bytes object.

Image.tostring(*args, **kw)¶

Deprecated alias to tobytes.

Deprecated since version 2.0.

Image.transform(size, method, data=None, resample=0, fill=1)¶

Transforms this image. This method creates a new image with the given size, and the same mode as the original, and copies data to the new image using the given transform.

Parameters:

size – The output size. method – The transformation method. This is one of PIL.Image.EXTENT (cut out a rectangular subregion), PIL.Image.AFFINE (affine transform), PIL.Image.PERSPECTIVE (perspective transform), PIL.Image.QUAD (map a quadrilateral to a rectangle), or PIL.Image.MESH (map a number of source quadrilaterals in one operation). data – Extra data to the transformation method. resample – Optional resampling filter. It can be one of PIL.Image.NEAREST (use nearest neighbour), PIL.Image.BILINEAR (linear interpolation in a 2x2 environment), or PIL.Image.BICUBIC (cubic spline interpolation in a 4x4 environment). If omitted, or if the image has mode “1” or “P”, it is set to PIL.Image.NEAREST.

Returns:

An Image object.

Image.transpose(method)¶

Transpose image (flip or rotate in 90 degree steps)

Parameters:	method – One of PIL.Image.FLIP_LEFT_RIGHT, PIL.Image.FLIP_TOP_BOTTOM, PIL.Image.ROTATE_90, PIL.Image.ROTATE_180, PIL.Image.ROTATE_270 or PIL.Image.TRANSPOSE.
Returns:	Returns a flipped or rotated copy of this image.

Image.verify()¶

Verifies the contents of a file. For data read from a file, this method attempts to determine if the file is broken, without actually decoding the image data. If this method finds any problems, it raises suitable exceptions. If you need to load the image after using this method, you must reopen the image file.

Image.fromstring(*args, **kw)¶

Deprecated alias to frombytes.

Deprecated since version 2.0.

Image.load()¶

Allocates storage for the image and loads the pixel data. In normal cases, you don’t need to call this method, since the Image class automatically loads an opened image when it is accessed for the first time. This method will close the file associated with the image.

Returns:	An image access object.
Return type:	PixelAccess Class or PIL.PyAccess

Image.close()¶

Closes the file pointer, if possible.

This operation will destroy the image core and release its memory. The image data will be unusable afterward.

This function is only required to close images that have not had their file read and closed by the load() method.

Attributes¶

Instances of the Image class have the following attributes:

PIL.Image.format¶

The file format of the source file. For images created by the library itself (via a factory function, or by running a method on an existing image), this attribute is set to None.

Type:	string or None

PIL.Image.mode¶

Image mode. This is a string specifying the pixel format used by the image. Typical values are “1”, “L”, “RGB”, or “CMYK.” See Modes for a full list.

Type:	string

PIL.Image.size¶

Image size, in pixels. The size is given as a 2-tuple (width, height).

Type:	(width, height)

PIL.Image.palette¶

Colour palette table, if any. If mode is “P”, this should be an instance of the ImagePalette class. Otherwise, it should be set to None.

Type:	ImagePalette or None

PIL.Image.info¶

A dictionary holding data associated with the image. This dictionary is used by file handlers to pass on various non-image information read from the file. See documentation for the various file handlers for details.

Most methods ignore the dictionary when returning new images; since the keys are not standardized, it’s not possible for a method to know if the operation affects the dictionary. If you need the information later on, keep a reference to the info dictionary returned from the open method.

Unless noted elsewhere, this dictionary does not affect saving files.

Type:	dict

Functions¶

Most channel operations take one or two image arguments and returns a new image. Unless otherwise noted, the result of a channel operation is always clipped to the range 0 to MAX (which is 255 for all modes supported by the operations in this module).

PIL.ImageChops.add(image1, image2, scale=1.0, offset=0)¶

Adds two images, dividing the result by scale and adding the offset. If omitted, scale defaults to 1.0, and offset to 0.0.

out = ((image1 + image2) / scale + offset)

Return type:	Image

PIL.ImageChops.add_modulo(image1, image2)¶

Add two images, without clipping the result.

out = ((image1 + image2) % MAX)

Return type:	Image

PIL.ImageChops.blend(image1, image2, alpha)¶

Blend images using constant transparency weight. Alias for PIL.Image.Image.blend().

Return type:	Image

PIL.ImageChops.composite(image1, image2, mask)¶

Create composite using transparency mask. Alias for PIL.Image.Image.composite().

Return type:	Image

PIL.ImageChops.constant(image, value)¶

Fill a channel with a given grey level.

Return type:	Image

PIL.ImageChops.darker(image1, image2)¶

Compares the two images, pixel by pixel, and returns a new image containing the darker values.

out = min(image1, image2)

Return type:	Image

PIL.ImageChops.difference(image1, image2)¶

Returns the absolute value of the pixel-by-pixel difference between the two images.

out = abs(image1 - image2)

Return type:	Image

PIL.ImageChops.duplicate(image)¶

Copy a channel. Alias for PIL.Image.Image.copy().

Return type:	Image

PIL.ImageChops.invert(image)¶

Invert an image (channel).

out = MAX - image

Return type:	Image

PIL.ImageChops.lighter(image1, image2)¶

Compares the two images, pixel by pixel, and returns a new image containing the lighter values.

out = max(image1, image2)

Return type:	Image

PIL.ImageChops.logical_and(image1, image2)¶

Logical AND between two images.

out = ((image1 and image2) % MAX)

Return type:	Image

PIL.ImageChops.logical_or(image1, image2)¶

Logical OR between two images.

out = ((image1 or image2) % MAX)

Return type:	Image

PIL.ImageChops.multiply(image1, image2)¶

Superimposes two images on top of each other.

If you multiply an image with a solid black image, the result is black. If you multiply with a solid white image, the image is unaffected.

out = image1 * image2 / MAX

Return type:	Image

PIL.ImageChops.offset(image, xoffset, yoffset=None)¶

Returns a copy of the image where data has been offset by the given distances. Data wraps around the edges. If yoffset is omitted, it is assumed to be equal to xoffset.

Parameters:	xoffset – The horizontal distance. yoffset – The vertical distance. If omitted, both distances are set to the same value.
Return type:	Image

PIL.ImageChops.screen(image1, image2)¶

Superimposes two inverted images on top of each other.

out = MAX - ((MAX - image1) * (MAX - image2) / MAX)

Return type:	Image

PIL.ImageChops.subtract(image1, image2, scale=1.0, offset=0)¶

Subtracts two images, dividing the result by scale and adding the offset. If omitted, scale defaults to 1.0, and offset to 0.0.

out = ((image1 - image2) / scale + offset)

Return type:	Image

PIL.ImageChops.subtract_modulo(image1, image2)¶

Subtract two images, without clipping the result.

out = ((image1 - image2) % MAX)

Return type:	Image

Color Names¶

The ImageColor module supports the following string formats:

• Hexadecimal color specifiers, given as #rgb or #rrggbb. For example, #ff0000 specifies pure red.
• RGB functions, given as rgb(red, green, blue) where the color values are integers in the range 0 to 255. Alternatively, the color values can be given as three percentages (0% to 100%). For example, rgb(255,0,0) and rgb(100%,0%,0%) both specify pure red.
• Hue-Saturation-Lightness (HSL) functions, given as hsl(hue, saturation%, lightness%) where hue is the color given as an angle between 0 and 360 (red=0, green=120, blue=240), saturation is a value between 0% and 100% (gray=0%, full color=100%), and lightness is a value between 0% and 100% (black=0%, normal=50%, white=100%). For example, hsl(0,100%,50%) is pure red.
• Common HTML color names. The ImageColor module provides some 140 standard color names, based on the colors supported by the X Window system and most web browsers. color names are case insensitive. For example, red and Red both specify pure red.

Functions¶

PIL.ImageColor.getrgb(color)¶

Convert a color string to an RGB tuple. If the string cannot be parsed, this function raises a ValueError exception.

New in version 1.1.4.

Parameters:	color – A color string
Returns:	(red, green, blue[, alpha])

PIL.ImageColor.getcolor(color, mode)¶

Same as getrgb(), but converts the RGB value to a greyscale value if the mode is not color or a palette image. If the string cannot be parsed, this function raises a ValueError exception.

New in version 1.1.4.

Parameters:	color – A color string
Returns:	(graylevel [, alpha]) or (red, green, blue[, alpha])

Example: Draw a gray cross over an image¶

from PIL import Image, ImageDraw

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

draw = ImageDraw.Draw(im)
draw.line((0, 0) + im.size, fill=128)
draw.line((0, im.size[1], im.size[0], 0), fill=128)
del draw

# write to stdout
im.save(sys.stdout, "PNG")

Concepts¶

Example: Draw Partial Opacity Text¶

from PIL import Image, ImageDraw, ImageFont
# get an image
base = Image.open('Pillow/Tests/images/lena.png').convert('RGBA')

# make a blank image for the text, initialized to transparent text color
txt = Image.new('RGBA', base.size, (255,255,255,0))

# get a font
fnt = ImageFont.truetype('Pillow/Tests/fonts/FreeMono.ttf', 40)
# get a drawing context
d = ImageDraw.Draw(txt)

# draw text, half opacity
d.text((10,10), "Hello", font=fnt, fill=(255,255,255,128))
# draw text, full opacity
d.text((10,60), "World", font=fnt, fill=(255,255,255,255))

out = Image.alpha_composite(base, txt)

out.show()

Functions¶

class PIL.ImageDraw.Draw(im, mode=None)¶

Creates an object that can be used to draw in the given image.

Note that the image will be modified in place.

Parameters:	im – The image to draw in. mode – Optional mode to use for color values. For RGB images, this argument can be RGB or RGBA (to blend the drawing into the image). For all other modes, this argument must be the same as the image mode. If omitted, the mode defaults to the mode of the image.

Methods¶

PIL.ImageDraw.Draw.arc(xy, start, end, fill=None)¶

Draws an arc (a portion of a circle outline) between the start and end angles, inside the given bounding box.

Parameters:	xy – Four points to define the bounding box. Sequence of [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. start – Starting angle, in degrees. Angles are measured from 3 o’clock, increasing clockwise. end – Ending angle, in degrees. fill – Color to use for the arc.

PIL.ImageDraw.Draw.bitmap(xy, bitmap, fill=None)¶

Draws a bitmap (mask) at the given position, using the current fill color for the non-zero portions. The bitmap should be a valid transparency mask (mode “1”) or matte (mode “L” or “RGBA”).

This is equivalent to doing image.paste(xy, color, bitmap).

To paste pixel data into an image, use the paste() method on the image itself.

PIL.ImageDraw.Draw.chord(xy, start, end, fill=None, outline=None)¶

Same as arc(), but connects the end points with a straight line.

Parameters:	xy – Four points to define the bounding box. Sequence of [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.ellipse(xy, fill=None, outline=None)¶

Draws an ellipse inside the given bounding box.

Parameters:	xy – Four points to define the bounding box. Sequence of either [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.line(xy, fill=None, width=0)¶

Draws a line between the coordinates in the xy list.

Parameters:	xy – Sequence of either 2-tuples like [(x, y), (x, y), ...] or numeric values like [x, y, x, y, ...]. fill – Color to use for the line. width – The line width, in pixels. Note that line joins are not handled well, so wide polylines will not look good. New in version 1.1.5. Note This option was broken until version 1.1.6.

PIL.ImageDraw.Draw.pieslice(xy, start, end, fill=None, outline=None)¶

Same as arc, but also draws straight lines between the end points and the center of the bounding box.

Parameters:	xy – Four points to define the bounding box. Sequence of [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.point(xy, fill=None)¶

Draws points (individual pixels) at the given coordinates.

Parameters:	xy – Sequence of either 2-tuples like [(x, y), (x, y), ...] or numeric values like [x, y, x, y, ...]. fill – Color to use for the point.

PIL.ImageDraw.Draw.polygon(xy, fill=None, outline=None)¶

Draws a polygon.

The polygon outline consists of straight lines between the given coordinates, plus a straight line between the last and the first coordinate.

Parameters:	xy – Sequence of either 2-tuples like [(x, y), (x, y), ...] or numeric values like [x, y, x, y, ...]. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.rectangle(xy, fill=None, outline=None)¶

Draws a rectangle.

Parameters:	xy – Four points to define the bounding box. Sequence of either [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. The second point is just outside the drawn rectangle. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.shape(shape, fill=None, outline=None)¶

Warning

This method is experimental.

Draw a shape.

PIL.ImageDraw.Draw.text(xy, text, fill=None, font=None, anchor=None)¶

Draws the string at the given position.

Parameters:	xy – Top left corner of the text. text – Text to be drawn. font – An ImageFont instance. fill – Color to use for the text.

PIL.ImageDraw.Draw.textsize(text, font=None)¶

Return the size of the given string, in pixels.

Parameters:	text – Text to be measured. font – An ImageFont instance.

Legacy API¶

The Draw class contains a constructor and a number of methods which are provided for backwards compatibility only. For this to work properly, you should either use options on the drawing primitives, or these methods. Do not mix the old and new calling conventions.

PIL.ImageDraw.ImageDraw(image)¶

Return type:	Draw

PIL.ImageDraw.Draw.setink(ink)¶

Deprecated since version 1.1.5.

Sets the color to use for subsequent draw and fill operations.

PIL.ImageDraw.Draw.setfill(fill)¶

Deprecated since version 1.1.5.

Sets the fill mode.

If the mode is 0, subsequently drawn shapes (like polygons and rectangles) are outlined. If the mode is 1, they are filled.

PIL.ImageDraw.Draw.setfont(font)¶

Deprecated since version 1.1.5.

Sets the default font to use for the text method.

Parameters:	font – An ImageFont instance.

Example: Vary the sharpness of an image¶

from PIL import ImageEnhance

enhancer = ImageEnhance.Sharpness(image)

for i in range(8):
    factor = i / 4.0
    enhancer.enhance(factor).show("Sharpness %f" % factor)

Also see the enhancer.py demo program in the Scripts/ directory.

Classes¶

All enhancement classes implement a common interface, containing a single method:

class PIL.ImageEnhance._Enhance¶

enhance(factor)¶

Returns an enhanced image.

Parameters:	factor – A floating point value controlling the enhancement. Factor 1.0 always returns a copy of the original image, lower factors mean less color (brightness, contrast, etc), and higher values more. There are no restrictions on this value.
Return type:	Image

class PIL.ImageEnhance.Color(image)¶

Adjust image color balance.

This class can be used to adjust the colour balance of an image, in a manner similar to the controls on a colour TV set. An enhancement factor of 0.0 gives a black and white image. A factor of 1.0 gives the original image.

class PIL.ImageEnhance.Contrast(image)¶

Adjust image contrast.

This class can be used to control the contrast of an image, similar to the contrast control on a TV set. An enhancement factor of 0.0 gives a solid grey image. A factor of 1.0 gives the original image.

class PIL.ImageEnhance.Brightness(image)¶

Adjust image brightness.

This class can be used to control the brighntess of an image. An enhancement factor of 0.0 gives a black image. A factor of 1.0 gives the original image.

class PIL.ImageEnhance.Sharpness(image)¶

Adjust image sharpness.

This class can be used to adjust the sharpness of an image. An enhancement factor of 0.0 gives a blurred image, a factor of 1.0 gives the original image, and a factor of 2.0 gives a sharpened image.

Example: Parse an image¶

from PIL import ImageFile

fp = open("lena.pgm", "rb")

p = ImageFile.Parser()

while 1:
    s = fp.read(1024)
    if not s:
        break
    p.feed(s)

im = p.close()

im.save("copy.jpg")

Parser¶

class PIL.ImageFile.Parser¶

Incremental image parser. This class implements the standard feed/close consumer interface.

In Python 2.x, this is an old-style class.

close()¶

(Consumer) Close the stream.

Returns:	An image object.
Raises IOError:	If the parser failed to parse the image file either because it cannot be identified or cannot be decoded.

feed(data)¶

(Consumer) Feed data to the parser.

Parameters:	data – A string buffer.
Raises IOError:	If the parser failed to parse the image file.

reset()¶

(Consumer) Reset the parser. Note that you can only call this method immediately after you’ve created a parser; parser instances cannot be reused.

Example: Filter an image¶

from PIL import ImageFilter

im1 = im.filter(ImageFilter.BLUR)

im2 = im.filter(ImageFilter.MinFilter(3))
im3 = im.filter(ImageFilter.MinFilter)  # same as MinFilter(3)

Filters¶

The current version of the library provides the following set of predefined image enhancement filters:

• BLUR
• CONTOUR
• DETAIL
• EDGE_ENHANCE
• EDGE_ENHANCE_MORE
• EMBOSS
• FIND_EDGES
• SMOOTH
• SMOOTH_MORE
• SHARPEN

class PIL.ImageFilter.GaussianBlur(radius=2)¶

Gaussian blur filter.

Parameters:	radius – Blur radius.

class PIL.ImageFilter.UnsharpMask(radius=2, percent=150, threshold=3)¶

Unsharp mask filter.

See Wikipedia’s entry on digital unsharp masking for an explanation of the parameters.

Parameters:	radius – Blur Radius percent – Unsharp strength, in percent threshold – Threshold controls the minimum brightness change that will be sharpened

class PIL.ImageFilter.Kernel(size, kernel, scale=None, offset=0)¶

Create a convolution kernel. The current version only supports 3x3 and 5x5 integer and floating point kernels.

In the current version, kernels can only be applied to “L” and “RGB” images.

Parameters:	size – Kernel size, given as (width, height). In the current version, this must be (3,3) or (5,5). kernel – A sequence containing kernel weights. scale – Scale factor. If given, the result for each pixel is divided by this value. the default is the sum of the kernel weights. offset – Offset. If given, this value is added to the result, after it has been divided by the scale factor.

class PIL.ImageFilter.RankFilter(size, rank)¶

Create a rank filter. The rank filter sorts all pixels in a window of the given size, and returns the rank‘th value.

Parameters:	size – The kernel size, in pixels. rank – What pixel value to pick. Use 0 for a min filter, size * size / 2 for a median filter, size * size - 1 for a max filter, etc.

class PIL.ImageFilter.MedianFilter(size=3)¶

Create a median filter. Picks the median pixel value in a window with the given size.

Parameters:	size – The kernel size, in pixels.

class PIL.ImageFilter.MinFilter(size=3)¶

Create a min filter. Picks the lowest pixel value in a window with the given size.

Parameters:	size – The kernel size, in pixels.

class PIL.ImageFilter.MaxFilter(size=3)¶

Create a max filter. Picks the largest pixel value in a window with the given size.

Parameters:	size – The kernel size, in pixels.

class PIL.ImageFilter.ModeFilter(size=3)¶

Create a mode filter. Picks the most frequent pixel value in a box with the given size. Pixel values that occur only once or twice are ignored; if no pixel value occurs more than twice, the original pixel value is preserved.

Parameters:	size – The kernel size, in pixels.

Example¶

from PIL import ImageFont, ImageDraw

draw = ImageDraw.Draw(image)

# use a bitmap font
font = ImageFont.load("arial.pil")

draw.text((10, 10), "hello", font=font)

# use a truetype font
font = ImageFont.truetype("arial.ttf", 15)

draw.text((10, 25), "world", font=font)

Functions¶

PIL.ImageFont.load(filename)¶

Load a font file. This function loads a font object from the given bitmap font file, and returns the corresponding font object.

Parameters:	filename – Name of font file.
Returns:	A font object.
Raises IOError:	If the file could not be read.

PIL.ImageFont.load_path(filename)¶

Load font file. Same as load(), but searches for a bitmap font along the Python path.

Parameters:	filename – Name of font file.
Returns:	A font object.
Raises IOError:	If the file could not be read.

PIL.ImageFont.truetype(font=None, size=10, index=0, encoding='', filename=None)¶

Load a TrueType or OpenType font file, and create a font object. This function loads a font object from the given file, and creates a font object for a font of the given size.

This function requires the _imagingft service.

Parameters:	filename – A truetype font file. Under Windows, if the file is not found in this filename, the loader also looks in Windows fonts/ directory. size – The requested size, in points. index – Which font face to load (default is first available face). encoding – Which font encoding to use (default is Unicode). Common encodings are “unic” (Unicode), “symb” (Microsoft Symbol), “ADOB” (Adobe Standard), “ADBE” (Adobe Expert), and “armn” (Apple Roman). See the FreeType documentation for more information.
Returns:	A font object.
Raises IOError:	If the file could not be read.

PIL.ImageFont.load_default()¶

Load a “better than nothing” default font.

New in version 1.1.4.

Returns:	A font object.

Methods¶

PIL.ImageFont.ImageFont.getsize(text)¶

Returns:	(width, height)

PIL.ImageFont.ImageFont.getmask(text, mode='')¶

Create a bitmap for the text.

If the font uses antialiasing, the bitmap should have mode “L” and use a maximum value of 255. Otherwise, it should have mode “1”.

Parameters:	text – Text to render. mode – Used by some graphics drivers to indicate what mode the driver prefers; if empty, the renderer may return either mode. Note that the mode is always a string, to simplify C-level implementations. New in version 1.1.5.
Returns:	An internal PIL storage memory instance as defined by the PIL.Image.core interface module.

Example: Using the ImageMath module¶

import Image, ImageMath

im1 = Image.open("image1.jpg")
im2 = Image.open("image2.jpg")

out = ImageMath.eval("convert(min(a, b), 'L')", a=im1, b=im2)
out.save("result.png")

PIL.ImageMath.eval(expression, environment)¶

Evaluate expression in the given environment.

In the current version, ImageMath only supports single-layer images. To process multi-band images, use the split() method or merge() function.

Parameters:	expression – A string which uses the standard Python expression syntax. In addition to the standard operators, you can also use the functions described below. environment – A dictionary that maps image names to Image instances. You can use one or more keyword arguments instead of a dictionary, as shown in the above example. Note that the names must be valid Python identifiers.
Returns:	An image, an integer value, a floating point value, or a pixel tuple, depending on the expression.

Expression syntax¶

Expressions are standard Python expressions, but they’re evaluated in a non-standard environment. You can use PIL methods as usual, plus the following set of operators and functions:

Extracting frames from an animation¶

from PIL import Image, ImageSequence

im = Image.open("animation.fli")

index = 1
for frame in ImageSequence.Iterator(im):
    frame.save("frame%d.png" % index)
    index = index + 1