The Python Imaging Library | ![]() |
|
Copyright © 1997 by Fredrik Lundh <fredrik@pythonware.com> | ||
Updated 18 Aug 1997 |
< Concepts | The Image Class | The ImageChops Module >
To use the Image class and its related functions, import the Image module.
import Imageim = Image.open("bride.jpg") im.rotate(45).show()import glob for infile in glob.glob("*.jpg"): try: outfile = os.splitext(file)[0] + ".thumbnail" Image.open(infile).resize(128, 128).save(outfile, "JPEG") except: print "Cannot create thumbnail for %s" % infile
new( mode, size ) or new( mode, size, colour ) creates a new image with the given mode and size. Size is given as a 2-tuple. The colour is given as a single numerical value for single-band images, and a tuple for multi-band images. If the colour is omitted, the image is filled with black. If the colour is None, the image is not initialised.
open( infile ) or open(infile, "r" ) opens and identifies the given image file. The actual image data is not read from the file until you try to process the data (or call the load method).
You can use either a string (giving the filename) or a file object. In the latter case, the file object must implement read, seek, and tell methods, and be opened in binary mode.
To read images from streams, use the ImageFileIO class.
blend( image 1, image 2, alpha ) creates a new image by interpolating between the given images, using a constant alpha. Both images must have the same size and mode.
out = image1 * (1.0 - alpha) + image2 * alpha
If alpha is 0.0, a copy of the first image is returned. If alpha is 1.0, a copy of the second image is returned. There are no restrictions on the alpha value. If necessary, the result is clipped to fit into the allowed output range.
composite( image1, image2, mask ) creates a new image by interpolating between the given images, using the mask as alpha. The mask can be either "1", "L", or "RGBA." All images must have the same size.
eval( function, image ) applies the function (which should take one argument) to each pixel in the given image. If the image has more than one band, the same function is applied to each band. Note that the function is evaluated once for each possible pixel value, so you cannot use random components or other generators.
fromstring( mode, size, data ) or fromstring( mode, size, data, decoder, parameters ) constructs an image memory from data in a string. If the decoder is not specified, it defaults to the "raw" decoder, and the decoder rawmode is set equal to the mode. For more information on available decoders, see the section Writing Your Own File Decoder.
merge( mode, bands ) creates a new image from a number of single band images. The bands are given as a tuple or list of images, one for each band described by the mode. All bands must have the same size.
An instance of the Image class have the following methods. Unless otherwise stated, all methods return a new instance of the Image class, holding the resulting image.
convert( mode ) returns a converted copy of an image. For the "P" mode, this 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 release supports all possible conversions between "L", "RGB" and "CMYK."
When translating a colour 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/1000When translating an greyscale image into a bilevel image (mode "1"), all non-zero values are set to 255 (white). To use other thresholds, use the point method.
convert( mode, matrix ) converts an "RGB" image to "L" or "RGB" using a conversion matrix. The matrix is a 4- or 16-tuple. The following example converts an RGB image (linearly calibrated according to ITU-R 709, using the D65 luminant) to the CIE XYZ colour 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)
copy() copies the image. Use this function if you wish to paste things into an image, but still retain the original.
crop( box ) returns a rectangular region from the current image. The box is a 4-tuple defining the left, upper, right, and lower pixel coordinate.
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 colour 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.
filter( filter ) returns a copy of an image filtered by the given filter. For a list of available filters, see the ImageFilter module.
getbbox() calculates the bounding box of the non-zero regions in the image. 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.
getdata() returns the contents of a the image as a sequence object containing pixel values.
getpixel( x, y ) returns the pixel at the given position. If the image is a multi-layer image, this method returns a tuple.
histogram() 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 an greyscale ("L") image by this method.
histogram( mask ) 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").
load() allocates storage for the image and loads it from the file. In normal cases, you don't need to call this method, since the Image class automatically loads an opened image when it is accessed the first time.
offset( xoffset, yoffset ) returns a copy of the image where data have been offset by the given distances. Data wraps around the edges. If yoffset is omitted, it is assumed to be equal to xoffset.
paste( image, box ) or paste( image, box, mask ) pastes an image into self. The box argument is either a 2-tuple giving the left and upper corner, or a 4-tuple defining the left, upper, right, and lower pixel coordinate. If None is given instead of a tuple, all of self is assumed. In any case, the size of the pasted image must match the size of the region. If the mode does not match the mode of self, conversions are automatically applied (see the convert method for details).
If a mask is given, it is interpreted as transparency mask for the image being pasted. 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. Values in-between can be used for transparency effects.
Note that if you paste an "RGBA" image, the alpha band is ignored unless you use the same image as mask.
point( table, mode ) or point( function, mode ) returns a copy of the image where each pixel has been mapped through the given table. The table should contains 256 values per band in the image. If a function is 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.
If the image has mode "F" (floating point), you must use a function, and it must have the form "argument * scale + offset." For example:
out = im.point(lambda i: i * 1.2 + 10)You can leave out the scale or the offset.
If given, the mode argument must be "1". This can be used with "L" and "P" images to map and convert in one step.
resize( size ) returns a resized copy of an image. The size argument gives the requested size in pixels.
rotate( angle ) returns a copy of an image rotated the given number of degrees counter clockwise around its centre.
save( outfile, keyword options ) or save( outfile, format, keyword options ) saves the image under the given filename. If format is omitted, the format is determined from the filename extension, if possible. This method returns None.
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 later in this handbook.
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.
seek( frame ) seeks to the given frame in a sequence file. If you seek beyong 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 format only allows you to seek to the next frame.
show() displays an image. On Unix platforms, this method saves the image to disk as a PPM file, and calls the xv utility. This method returns None.
split() returns a tuple of individual image bands from an image. For example, if you split an "RGB" image, you get three new images, containing copies of the red, green, and blue bands from the original image.
tell() returns the current frame number.
thumbnail( size ) 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. This method returns None.
transform( xsize, ysize, EXTENT, ( x0, y0, x1, y1 )) returns a transformed copy of an image. The four values gives two points in the input image's coordinate system. The resulting image will contain data sampled from between these two points, so that (x0, y0) in the input image will end up at (0,0) in the output image, and (x1, y1) at (xsize, ysize). This method can be used to crop, stretch, shrink, or mirror an arbitrary rectangle in the current image. It is slightly slower than crop, but about as fast as a corresponding resize operation.
transform( xsize, ysize, AFFINE, ( a, b, c, d, e, f )) returns a transformed copy of an image. The six values are the first two rows from an affine transform matrix, which can be used to control scaling, translation, rotation, and shear.
The affine transform matrix defines a coordinate translation from coordinates in the output image to coordinates in the original image. For each pixel (x, y) in the output image, the new value is taken from a position (ax + by + c, dx + ey + f) in the input image, rounded to nearest pixel.
transpose( method ) returns a flipped or rotated copy of an image.
Method Result FLIP_RIGHT_LEFT ![]()
FLIP_TOP_BOTTOM ![]()
ROTATE_90 ![]()
ROTATE_180 ROTATE_270
verify() 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.
The file format that this image was read from. For images created by the library, this attribute is set to None.
Image mode. This is a string specifying the pixel format used by the image, with typical values like "1", "L", "RGB", or "CMYK."
Image size, in pixels. The size is given as a 2-tuple, with the width given first.
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.
A dictionary holding data associated with the image.
The following constants are defined in the Image module.
AFFINE
EXTENT
FLIP_LEFT_RIGHT
FLIP_TOP_BOTTOM
ROTATE_90
ROTATE_180
ROTATE_270
< Concepts | The Image Class | The ImageChops Module >