# The Image Module

The `Image` module provides a class with the same name which is used to represent a PIL image. The module also provides a number of factory functions, including functions to load images from files, and to create new images.

## Examples

Example: Open, rotate, and display an image

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

Example: Create thumbnails

    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

## Functions

### new

`new(mode, size [,colour])` ⇒ image

> 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

`open(infile [,mode]) ⇒ image`

> 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). If the mode argument is given, it must be "r".

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

### blend

`blend(image1, image2, alpha) ⇒ image`

> 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

`composite(image1, image2, mask) ⇒ image`

> 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

`eval(function, image) ⇒ 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

`fromstring(mode, size, data) ⇒ image`

> Creates an image memory from pixel data in a string, using the standard "raw" decoder.

`fromstring(mode, size, data, decoder, parameters) ⇒ image`

> Same, but allows you to use any pixel decoder supported by PIL. For more information on available decoders, see the section Writing Your Own File Decoder.

> Note that this function decodes pixel data, not entire images. If you have an entire image in a string, wrap it in a `StringIO` object, and use `open` to load it.

### merge

`merge(mode, bands) ⇒ image`

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

## Methods

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

`convert(mode) ⇒ image`

> 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/1000

> When 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) ⇒ image`

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

> Example: Convert RGB to XYZ

>         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

`copy() ⇒ image`

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

### crop

`crop(box) ⇒ image`

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

### draft

`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(filter) ⇒ image`

> Returns a copy of an image filtered by the given filter. For a list of available filters, see the `ImageFilter` module.

### fromstring

`fromstring(data)`

`fromstring(data, decoder, parameters)`

> Same as the `fromstring` function, but loads data into the current image.

### getbands

`getbands() ⇒ tuple of strings`

> Returns a tuple containing the name of each band. For example, `getbands` on an RGB image returns ("R", "G", "B").

### getbbox

`getbbox() ⇒ tuple`

> 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

`getdata() ⇒ sequence`

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

### getextrema

`getextrema() ⇒ sequence`

> Returns a 2-tuple containing the minimum and maximum values in the image. In this version, this only works for single-band images.

### getpixel

`getpixel(xy) ⇒ value or tuple`

> Returns the pixel at the given position. If the image is a multi-layer image, this method returns a tuple.

### histogram

`histogram() ⇒ list`

> 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) ⇒ list`

> 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

`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

(Deprecated). `offset(xoffset, yoffset) ⇒ image`

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

> This method is deprecated. New code should use the `offset` function in the `ImageChops` module.

### paste

`paste(image, box)`

> Pastes an image into self. The box argument is either a 2-tuple giving the upper left 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).

`paste(colour, box)`

> Same as above, but fills the region with a single colour. The colour is given as a single numerical value for single-band images, and a tuple for multi-band images.

> `paste(image, box, mask)`

> Same as above, but 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 unless you use the same image as mask.

`paste(colour, box, mask)`

> Same as above, but fills the region with a single colour.

### point

`point(table) ⇒ image`

`point(function) ⇒ image`

> 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 "I" (integer) or "F" (floating point), you must use a function, and it must have the following format:

>         argument * scale + offset

> Example: Map floating point images

>         out = im.point(lambda i: i * 1.2 + 10)

> You can leave out either the `scale` or the `offset`.

`point(table, mode) ⇒ image`

`point(function, mode) ⇒ image`

> Map the image through table, and convert it on fly. In this version, this can only be used to convert "L" and "P" images to "1" in one step, e.g. to threshold an image.

### putalpha

`putalpha(band)`

> Copies the given band to the alpha layer of self. Self must be an "RGBA" image, and the band must be either "L" or "1".

### putdata

`putdata(data [[,scale [,offset]])`

> Copy pixel values from a sequence object into the image, starting at the upper left corner. The scale and offset values are used to adjust the sequence values. If the scale is omitted, it defaults to 1.0. If the offset is omitted, it defaults to 0.0.

### putpalette

`putpalette(sequence)`

> Attach a palette to a "P" or "L" image. The palette sequence should 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.

### putpixel

`putpixel(xy, colour)`

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

> For more extensive changes, use `paste` or the `ImageDraw` module instead.

### resize

`resize(size) ⇒ image`

`resize(size, filter) ⇒ image`

> Returns a resized copy of an image. The size argument gives the requested size in pixels, as a 2-tuple: (`width`, `height`).

> The filter argument can be `NEAREST`, `BILINEAR`, or `BICUBIC`. If omitted, it defaults to `NEAREST`.

### rotate

`rotate(angle) ⇒ image`

`rotate(angle, filter)`

> Returns a copy of an image rotated the given number of degrees counter clockwise around its centre.

> The filter argument can be `NEAREST`, `BILINEAR`, or `BICUBIC`. If omitted, it defaults to `NEAREST`.

### save

`save(outfile, options)`

`save(outfile, format, 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

`seek(frame)`

> Seeks to the given frame in a 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.

### show

`show()`

> Displays an 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 runs the `start` command on it to start the registered BMP display utility (usually `Paint`).

> This method returns `None`.

### split

`split() ⇒ sequence`

> 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

`tell() ⇒ integer`

> Returns the current frame number.

### thumbnail

`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`.

### tobitmap

`tobitmap() ⇒ string`

> Returns the image converted to an X11 bitmap.

### tostring

`tostring()`

> Returns a string containing pixel data, using the standard "raw" encoder.

`tostring(decoder, parameters)`

### transform

`transform(size, method, data) ⇒ image`

`transform(size, method, data, filter) ⇒ image`

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

> In this version, the method argument can be `EXTENT` (cut out a rectangular subregion), `AFFINE` (affine transform), `QUAD` (map a quadrilateral to a rectangle), or `MESH` (map a number of source quadrilaterals in one operation). The various methods are described below.

> The filter argument defines how to filter pixels from the source image. In this version, it can be `NEAREST` (use nearest neighbour), `BILINEAR` (linear interpolatation in a 2x2 environment), or `BICUBIC` (cubic spline interpolation in a 4x4 environment). If omitted, it defaults to `NEAREST`.

### transform(EXTENT)

`transform(size, EXTENT, data) ⇒ image`

`transform(size, EXTENT, data, filter) ⇒ image`

> Extracts a subregion from the image.

> Data is a 4-tuple (x0, y0, x1, y1) which specifies 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 size.

> 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(AFFINE)

`transform(size, AFFINE, data) ⇒ image`

`transform(size, AFFINE, data, filter) ⇒ image`

> Applies an affine transform to the image, and places the result in a new image with the given size.

> Data is a 6-tuple (a, b, c, d, e, f) which contain the first two rows from an affine transform matrix. For each pixel (x, y) in the output image, the new value is taken from a position (a x + b y + c, d x + e y + f) in the input image, rounded to nearest pixel.

> This function can be used to scale, translate, rotate, and shear the original image.

### transform(QUAD)

`transform(size, QUAD, data) ⇒ image`

`transform(size, QUAD, data, filter) ⇒ image`

> Maps a quadrilateral (a region defined by four corners) from the image to a rectangle with the given size.

> Data is an 8-tuple (x0, y0, x1, y1, x2, y2, y3, y3) which contain the upper left, lower left, lower right, and upper right corner of the source quadrilateral.

### transform(MESH)

`transform(size, MESH, data) ⇒ image`

`transform(size, MESH, data, filter) ⇒ image`

> Similar to `QUAD`, but data is a list of target rectangles and corresponding source quadrilaterals.

### transpose

`transpose(method) ⇒ image`

> Returns a flipped or rotated copy of an image.

> Method can be one of the following: `FLIP_LEFT_RIGHT`, `FLIP_TOP_BOTTOM`, `ROTATE_90`, `ROTATE_180`, or `ROTATE_270`.

### verify

`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.

## Attributes

Instances of the `Image` class have the following attributes:

### format

`format` (string or `None`)

> The file format that this image was read from. For images created by the library, this attribute is set to `None`.

### mode

`mode` (string)

> Image mode. This is a string specifying the pixel format used by the image, with typical values like "1", "L", "RGB", or "CMYK."

### size

`size` (tuple of integers)

> Image size, in pixels. The size is given as a 2-tuple, with the width given first.

### palette

`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`.

### info

`info` (dictionary)

> A dictionary holding data associated with the image.