Image 模块

Image 模块提供了同名的类用来表示PIL的图像。Image模块还提供了许多工厂（factory）函数，包块从文件加载图像的函数，以及创建新图像的函数。

例子
下面的脚本加载了一个图像，并把它旋转了45度，然后调用外部的查看器（通常在Unix下是xv，Windows下是paint）。

打开，旋转，和显示图像(使用默认的查看器)

from PIL import Image
im = Image.open("bride.jpg")
im.rotate(45).show()
下面的脚本为当前目录下所以的JPEG图像创建漂亮128x128的缩略图。

创建缩略图

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, Image.ANTIALIAS)
    im.save(file + ".thumbnail", "JPEG")


函数

new
Image.new(mode, size) => image

Image.new(mode, size, color) => image

以指定的模式和大小创建一个新图像。大小以2元元组的形式给出。给colour赋单个值，表示要创建单波段图像，元组表示创建多波段图像（每个波段一个值）。如果忽略colour参数，图像将以黑色填充。如果colour设为None，图像不会被初始化。

open
Image.open(infile) => image

Image.open(infile, mode) => image

打开并识别给定图像文件。这是一个偷懒的操作；真正的图像数据只有到处理的时候才会被读入（调用load函数强制加载）。如果给出了模式（mode）参数，它必须设为“r”。

要打开图像，即可以使用字符串（表示文件名）也可以使用文件对象。对后一种情况，文件对象必须实现了read，seek，和 tell 方法，并以二进制模式打开。

blend
Image.blend(image1, image2, alpha) => image

通过使用alpha常量，在图像进行差值操作，创建新图像。两个图像必须具有相同的大小和模式。

out = image1 * (1.0 - alpha) + image2 * alpha
（注：没有成功）
如果设置alpha为0.0，将返回第一个图像的拷贝。如果设置alpha为1.0，将返回第二个图像的拷贝。对alpha的值没有限制。必要的话，结果会被剪裁，以适合允许的输出范围。

composite
Image.composite(image1, image2, mask) => image

使用遮罩（mask）作为alpha，通过在两个图像之间进行插值来创建一个新图像。遮罩图像的模式可以是“1”，“L”，或者“RGBA”。所有的图像的大小必须有相同。

eval
Image.eval(image, function) => image

把函数（function）（应该接收一个参数）应用到所给图像的每一个像素。如果图像有多个波段，相同的函数会应用到每一个波段。注意，该函数对每一个可能的像素值只计算一次，所有不能使用随机组件（components）或者其它发生器（generators）。

frombuffer
Image.frombuffer(mode, size, data) => image

(PIL1.1.4添加)。使用标准的“raw”解码器，把来自字符串或者缓冲区（buffer）对象的图像数据创建为一个图像内存（image memory）。对于某些模式，图像内存会和原来的缓冲区共享内存（这意味着对原始缓冲区对象的修改会影响图像）。不是所有的模式都能共享内存；支持共享内存的模式包括：“L”，“RGBX”，“RGBA”和“CMYK”。对其其它模式，这个函数的作用与fromstring函数类似。

注意：1.1.6版中，默认的方向与fromstring的不同。这些可能会在未来的版本中发生变化，所以为了最大的兼容性，建议在使用“raw”解码器的时候给出所有的参数。

im = Image.frombuffer(mode, size, data, "raw", mode, 0, 1)Image.frombuffer(mode, size, data, decoder, parameters) => image

与调用fromstring 相同。

fromstring
Image.fromstring(mode, size, data) => image

使用标准的“raw”解码器从来自字符串的像素数据创建一个图像内存。

Image.fromstring(mode, size, data, decoder, parameters) => image

也一样，但是允许你使用PIL支持的任何像素解码器。关于可用解码器的更多信息，参见Writing Your Own File Decoder节

注意，这个函数只对像素数据解码，而不是整个图像。如果字符串中包含了一个完整的图像文件，可以使用StringIO对象对它进行处理，并使用open函数加载图像。

merge
Image.merge(mode, bands) => image

从几个单波段图像创建一个新图像。bands参数是包含图像的元组或列表，一个图像对应模式中描述的一个波段。所有波段的图像必须有相同的大小。

方法
一个Image类的实例具有下列方法。除非另外指出，所有的方法都返回一个新的Image类的实例，包含处理过的图像数据。

convert
im.convert(mode) => image

返回图像转换后的副本

如果原始图像是调色板图像，这个函数通过调色板转换像素。忽略mode参数，会自动选择一个模式，以保证所有的图像信息和调色板信息在没有调色板的时候也能表示出来。

从彩色图像转换到黑白图像时，图像库使用ITU-R 601-2 luma转换：

    L = R * 299/1000 + G * 587/1000 + B * 114/1000在把图像转换为二值图（bilevel image）（模式“1”）时，源图像首先被转换为黑白图。然后在结果中，值大于127的像素点被设置为白色，图像抖动（and the image is dithered）。使用point方法可以改变阈值。

im.convert(mode, matrix) => image

使用转换矩阵，把一个 "RGB" 图像转换为 "L" 或者 "RGB" 图像。其中矩阵是一个4元或16元元组。

下面的例子把一个RGB图像转换(根据ITU-R 709进行线性校正，using the D65 luminant)到CIE XYZ颜色空间：

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
im.copy() => image

Copies the image. Use this method if you wish to paste things into an image, but still retain the original.复制图像。如果你想往图像上粘贴东西，但是又保持源图像不变可以使用这个函数。

crop
im.crop(box) => image

返回当前图像的一个矩形区域。box参数是一个定义了左，上，右，下像素坐标的4元元组。

这是一个投篮操作。改变源图像可能会也可能不会影响剪裁的图像。要得到一个单独的拷贝，可以在剪裁的副本上应用load函数。

draft
im.draft(mode, size)

配置图像文件加载器，使它返回一个与给定模式和大小尽可能匹配的图像。比如，你可以在加载的时候，把一个彩色的JPEG图像转换为一个灰度图，或者从一个PCD文件中提取出一个128x192的版本。

注意这个方法在适当的时候修改图像对象。如果图像已经加载了，这个方法可能无效。

filter
im.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
im.fromstring(data)

im.fromstring(data, decoder, parameters)

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

getbands
im.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
im.getbbox() => 4-tuple or None

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.

getcolors
im.getcolors() => a list of (count, color) tuples or None

im.getcolors(maxcolors) => a list of (count, color) tuples or None

(New in 1.1.5) Returns an unsorted list of (count, color) tuples, where the count is the number of times the corresponding color occurs in the image.

If the maxcolors value is exceeded, the method stops counting and returns None. The default maxcolors value is 256. To make sure you get all colors in an image, you can pass in size[0]*size[1] (but make sure you have lots of memory before you do that on huge images).

getdata
im.getdata() => sequence

Returns the contents of an 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, including iteration and basic sequence access. To convert it to an ordinary sequence (e.g. for printing), use list(im.getdata()).

getextrema
im.getextrema() => 2-tuple

Returns a 2-tuple containing the minimum and maximum values of the image. In the current version of PIL, this is only applicable to single-band images.

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

Note that this method is rather slow; if you need to process larger parts of an image from Python, you can either use pixel access objects (see load), or the getdata method.

histogram
im.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 a greyscale ("L") image by this method.

im.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
im.load()

Allocates storage for the image and loads it from the file (or from the source, for lazy operations). 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.

(New in 1.1.6) In 1.1.6 and later, load returns a pixel access object that can be used to read and modify pixels. The access object behaves like a 2-dimensional array, so you can do:

pix = im.load()
print pix[x, y]
pix[x, y] = value
Access via this object is a lot faster than getpixel and putpixel.

offset
im.offset(xoffset, yoffset) => image

(Deprecated) 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.

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

paste
im.paste(image, box)

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

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

im.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. You can work around this by using the same image as both source image and mask.

im.paste(colour, box, mask)

Same as above, but fills the region indicated by the mask with a single colour.

point
im.point(table) => image

im.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 + offsetExample:

    out = im.point(lambda i: i * 1.2 + 10)You can leave out either the scale or the offset.

im.point(table, mode) => image

im.point(function, mode) => image

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

(New in 1.1.5) This form can also be used to convert "L" images to "I" or "F", and to convert "I" images with 16-bit data to "L". In the last case, you must use a 65536-item lookup table.

putalpha
im.putalpha(band)

Copies the given band to the alpha layer of the current image.

The image must be an "RGBA" image, and the band must be either "L" or "1".

(New in PIL 1.1.5) You can use putalpha on other modes as well; the image is converted in place, to a mode that matches the current mode but has an alpha layer (this usually means "LA" or "RGBA"). Also, the band argument can be either an image, or a colour value (an integer).

putdata
im.putdata(data)

im.putdata(data, scale, offset)

Copy pixel values from a sequence object into the image, starting at the upper left corner (0, 0). The scale and offset values are used to adjust the sequence values:

    pixel = value * scale + offsetIf the scale is omitted, it defaults to 1.0. If the offset is omitted, it defaults to 0.0.

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

Note that this method is relatively slow. If you're using 1.1.6, pixel access objects (see load) provide a faster way to modify the image. If you want to generate an entire image, it can be more efficient to create a Python list and use putdata to copy it to the image. For more extensive changes, use paste or the ImageDraw module instead.

You can speed putpixel up a bit by "inlining" the call to the internal putpixel implementation method:

    im.load()
    putpixel = im.im.putpixel
    for i in range(n):
       ...
       putpixel((x, y), value)
In 1.1.6, the above is better written as:

    pix = im.load()
    for i in range(n):
        ...
        pix[x, y] = value

resize
im.resize(size) => image

im.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 one of NEAREST (use nearest neighbour), BILINEAR (linear interpolation in a 2x2 environment), BICUBIC (cubic spline interpolation in a 4x4 environment), or ANTIALIAS (a high-quality downsampling filter). If omitted, or if the image has mode "1" or "P", it is set to NEAREST.

rotate
im.rotate(angle) => image

im.rotate(angle, filter=NEAREST, expand=0) => image

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

The filter argument can be one of NEAREST (use nearest neighbour), BILINEAR (linear interpolation in a 2x2 environment), or BICUBIC (cubic spline interpolation in a 4x4 environment). If omitted, or if the image has mode "1" or "P", it is set to NEAREST.

The expand argument, if true, indicates that the output image should be made large enough to hold the rotated image. If omitted or false, the output image has the same size as the input image.

save
im.save(outfile, options...)

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

If the save fails, for some reason, the method will raise an exception (usually an IOError exception). If this happens, the method may have created the file, and may have written data to it. It's up to your application to remove incomplete files, if necessary.

seek
im.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
im.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 uses the standard BMP display utility to show it.

This method returns None.

split
im.split() => sequence

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

tell
im.tell() => integer

Returns the current frame number.

thumbnail
im.thumbnail(size)

im.thumbnail(size, filter)

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.

The filter argument can be one of NEAREST, BILINEAR, BICUBIC, or ANTIALIAS (best quality). If omitted, it defaults to NEAREST.

Note that the bilinear and bicubic filters in the current version of PIL are not well-suited for thumbnail generation. You should use ANTIALIAS unless speed is much more important than quality.

Also 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
im.tobitmap() => string

Returns the image converted to an X11 bitmap.

tostring
im.tostring() => string

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

im.tostring(encoder, parameters) => string

Returns a string containing pixel data, using the given data encoding.

transform
im.transform(size, method, data) => image

im.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 the current version of PIL, 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 the current version, it can be NEAREST (use nearest neighbour), BILINEAR (linear interpolation in a 2x2 environment), or BICUBIC (cubic spline interpolation in a 4x4 environment). If omitted, or if the image has mode "1" or "P", it is set to NEAREST.

im.transform(size, EXTENT, data) => image

im.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, such 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.

im.transform(size, AFFINE, data) => image

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

im.transform(size, QUAD, data) => image

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

im.transform(size, MESH, data) image => image

im.transform(size, MESH, data, filter) image => image

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

transpose
im.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
im.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. This method only works on a newly opened image; if the image has already been loaded, the result is undefined. Also, 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
im.format => string or None

The file format of the source file. For images created by the library, this attribute is set to None.

mode
im.mode => string

Image mode. This is a string specifying the pixel format used by the image. Typical values are "1", "L", "RGB", or "CMYK."

size
im.size => (width, height)

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

palette
im.palette => palette or None

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
im.info => dictionary

A dictionary holding data associated with the image.