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