3. Creating objects of class Image

3. Creating objects of class `Image`

Instances of the Image class contain an image. To use the basic Python imaging library, import it using this syntax:

    import Image

These functions return an Image object:

Image.open(f)

Reads an image from a file. The parameter f can be either the name of a file, as a string, or a readable Python file object.

Image.new(mode,size,color=None)

Creates a new image of the given mode and size. If a color is given, all pixels are set to that color initially; the default color is black.

Image.blend(i₁,i₂,a)

Creates an image by blending two images i₁ and i₂. Each pixel in the output is computed from the corresponding pixels p₁ from i₁ and p₂ from i₂ using the formula (p₁ x (1 - a) + p₂ x a).

Image.composite(i₁,i₂,mask)

Creates a composite image from two equal-sized images i₁ and i₂, where mask is a mask image with mode "1", "L", or "RGBA" of the same size.

Each pixel in the output has a value given by (p₁ x (1 - m) + p₂ x m), where m is the corresponding pixel from mask.

Image.eval(f,i)

Creates a new image by applying a function f to each pixel of image i.

Function f takes one argument and returns one argument. If the image has multiple bands, f is applied to each band.

Image.merge(mode,bandList)

Creates a multi-band image from multiple single-band images of equal size. Specify the mode of the new image with the mode argument. The bandList argument is a sequence of single-band image objects to be combined.

3.1. Attributes of the `Image` object

These attributes of image objects are available:

.format: If the image was taken from a file, this attribute is set to the format code, such as "GIF". If the image was created within the PIL, its .format will be None. See supported formats for a list of the format codes.
.mode: The mode of the image, as a string.
.size: The image's size in pixels, as 2-tuple (width,height).
.palette: If the mode of the image is "P", this attribute will be the image's palette as an instance of class ImagePalette; otherwise it will be None.
.info: A dictionary holding data associated with the image. The exact information depends on the source image format; see the section on supported formats for more information.

3.2. Methods on the `Image` object

Once you have created an image object using one of the functions described above, these methods provide operations on the image:

.save(f,format=None)

Writes the image to a file. The argument f can be the name of the file to be written, or a writeable Python file object.

The format argument specifies the kind of image file to write. It must be one of the format codes shown below under supported formats, such as "JPEG" or "TIFF". This argument is required if f is a file object. If f is a file name, this argument can be omitted, in which case the format is determined by inspecting the extension of the file name. For example, if the file name is logo.jpg, the file will be written in JPEG format.

.convert(mode)

Returns a new image with a different mode. For example, if image im has mode "RGB", you can get a new image with mode "CMYK" using the expression im.convert("CMYK").

.copy()

Returns a copy of the image.

.crop(bbox)

Returns a new image containing the bounding box specified by bbox in the original. The rows and columns specified by the third and fourth values of bbox will not be included. For example, if image im has size 4x4, im.crop((0,0,3,3)) will have size 3x3.

.filter(name)

Return a copy of the image filtered through a named image enhancement filter. See image filter for a list of the predefined image enhancement filters.

.getbands()

Returns a sequence of strings, one per band, representing the mode of the image. For example, if image im has mode "RGB", im.getbands() will return ('R', 'G', 'B').

.getbbox()

Returns the smallest bounding box that encloses the nonzero parts of the image.

.getextrema()

For single-band images, returns a tuple (min,max) where min is the smallest pixel value and max the largest pixel value in the image.

For multi-band images, returns a tuple containing the (min,max) tuple for each band.

.getpixel(xy)

Returns the pixel value or values at the given coordinates. For single-band images, returns a single number; a sequence of pixel values is returned for multi-band images. For example, if the top left pixel of an image im of mode "L" has value 128, then im.getpixel((0,0)) returns 128.

.histogram(mask=None)

For single-band images, returns a list of values [c₀, c₁, ...] where c_i is the number of pixels with value i.

For multi-band images, returns a single sequence that is the concatenation of the sequences for all bands.

To get a histogram of selected pixels from the image, build a same-sized mask image of mode "1" or "L" and pass it to this method as an argument. The resulting histogram data will include only those pixels from the image that correspond to nonzero pixels in the mask argument.

.offset(dx,dy=None)

Returns a new image the same size as the original, but with all pixels rotated dx in the +x direction, and dy in the +y direction. Pixels will wrap around. If dy is omitted, it defaults to the same value as dx.

For example, if im is an image of size 4x4, then in the new image im.offset(2,1), the pixel that was at (1,1) will now be at (3,2). Wrapping around, the pixel that was at (3,3)will now be at (0,1).

.paste(i2,where,mask=None)

Pixels are replaced with the pixels from image i2.

If where is a pair of coordinates (x,y), the new pixels are pasted so that the (0,0) pixel of i2 pixel replaces the (x,y) pixel, with the other pixels of i2 pasted in corresponding positions. Pixels from i2 that fall outside the original are discarded.
If where is a bounding box, i2 must have the same size as that bbox, and replaces the pixels at that bbox's position.
If where is None, image i2 must be the same size as the original, and replaces the entire original.

If the mode of i2 is different, it is converted before pasting.

If a mask argument is supplied, it is used to control which pixels get replaced. The mask argument must be an image of the same size as the original.

If the mask has mode "1", original pixels are left alone where there are 0 pixels in the mask, but replaced where the mask has pixels of value 1.
If the mask has mode "L", original pixels are left alone where there are 0 pixels in the mask, and replaced where the mask has 255 pixels. Intermediate values interpolate between the pixel values of the original and replacement images.
If the mask has "RGBA" mode, its "A" band is used in the same way as an "L"-mode mask.

.paste(color,box=None,mask=None)

Sets multiple pixels to the same color. If the box argument is omitted, the entire image is set to that color. If present, it must be a bounding box, and the rectangle defined by that bbox is set to that color.

If a mask is supplied, it selects the pixels to be replaced as in the previous form of the .paste() method, above.

.point(function)

Returns a new image with each pixel modified. To apply a function f(x) to each pixel, call this method with f as the first argument. The function should operate on a single pixel value (0 to 255) and return the new pixel value.

.point(table)

To translate pixels using a table lookup, pass that table as a sequence to the first argument. The table should be a sequence of 256n values, where n is the number of bands in the image. Each pixel in band b of the image is replaced by the value from table[p+256*b], where p is the old pixel's value in that band.

.putalpha(band)

To add an alpha (transparency) band to an "RGBA"-mode image, call this method and pass it an image of the same size having mode "L" or "1". The pixels of the band image replace the alpha band of the original image in place.

.putpixel(xy, color)

Replaces one pixel of the image at coordinates xy. For single-band images, specify the color as a single pixel value; for multi-band images, provide a sequence containing the pixel values of each band.

For example, im.putpixel((0,0), (0,255,0)) would set the top left pixel of an RGB image im to green.

Replacing many pixels with this method may be slow. Refer to the ImageDraw module for faster techniques for pixel modification.

.resize(size,filter=None)

Returns a new image of the given size by linear stretching or shrinking of the original image. You may provide a filter to specify how the interpolation is done; the default is NEAREST.

.rotate(theta)

Returns a new image rotated around its center by theta degrees. Any pixels that are not covered by rotation of the original image are set to black.

.show()

On Unix systems, this method runs the xv image viewer to display the image. On Windows boxes, the image is saved in BMP format and can be viewed using Paint. This can be useful for debugging.

.split()

Returns a tuple containing each band of the original image as an image of mode "L". For example, applying this method to an "RGB" image produces a tuple of three images, one each for the red, green, and blue bands.

.thumbnail(size,filter=None)

Replaces the original image, in place, with a new image of the given size. The optional filter argument works in the same way as in the .resize() method.

The aspect ratio (height : width) is preserved by this operation. The resulting image will be as large as possible while still fitting within the given size. For example, if image im has size (400,150), its size after im.thumbnail((40,40)) will be (40,15).

.transform(x_s, y_s, Image.EXTENT, (x₀,y₀,x₁,y₁))

Returns a transformed copy of the image. In the transformed image, the point originally at (x₀,y₀) will appear at (0,0), and point (x₁,y₁) will appear at (x_s, y_s).

.transform(x_s, y_s, Image.AFFINE, (a,b,c,d,e,f))

Affine transformation. The values a through f are the first two rows of an affine transform matrix. Each pixel at (x,y) in the resulting image comes from position (ax+by+c,dx+ey+f) in the input image, rounded to the nearest pixel.

.transpose(method)

Return a flipped or rotated copy of the original image. The method can be any of:

Image.FLIP_RIGHT_LEFT to reflect around the vertical centerline.
Image.FLIP_TOP_BOTTOM to reflect around the horizontal centerline.
Image.ROTATE_90 to rotate the image 90 degrees clockwise.
Image.ROTATE_180 to rotate the image 180 degrees.
Image.ROTATE_270 to rotate the image clockwise by 270 degrees.

Python Imaging Library (PIL)