Image Archives¶

The Python Imaging Library is ideal for image archival and batch processing applications. You can use the library to create thumbnails, convert between file formats, print images, etc.

The current version identifies and reads a large number of formats. Write support is intentionally restricted to the most commonly used interchange and presentation formats.

Image Display¶

The current release includes Tk PhotoImage and BitmapImage interfaces, as well as a Windows DIB interface that can be used with PythonWin and other Windows-based toolkits. Many other GUI toolkits come with some kind of PIL support.

For debugging, there’s also a show() method which saves an image to disk, and calls an external display utility.

Image Processing¶

The library contains basic image processing functionality, including point operations, filtering with a set of built-in convolution kernels, and colour space conversions.

The library also supports image resizing, rotation and arbitrary affine transforms.

There’s a histogram method allowing you to pull some statistics out of an image. This can be used for automatic contrast enhancement, and for global statistical analysis.

Using the Image class¶

The most important class in the Python Imaging Library is the Image class, defined in the module with the same name. You can create instances of this class in several ways; either by loading images from files, processing other images, or creating images from scratch.

To load an image from a file, use the open() function in the Image module:

>>> from PIL import Image
>>> im = Image.open("lena.ppm")

If successful, this function returns an Image object. You can now use instance attributes to examine the file contents:

>>> from __future__ import print_function
>>> print(im.format, im.size, im.mode)
PPM (512, 512) RGB

The format attribute identifies the source of an image. If the image was not read from a file, it is set to None. The size attribute is a 2-tuple containing width and height (in pixels). The mode attribute defines the number and names of the bands in the image, and also the pixel type and depth. Common modes are “L” (luminance) for greyscale images, “RGB” for true color images, and “CMYK” for pre-press images.

If the file cannot be opened, an IOError exception is raised.

Once you have an instance of the Image class, you can use the methods defined by this class to process and manipulate the image. For example, let’s display the image we just loaded:

>>> im.show()

The following sections provide an overview of the different functions provided in this library.

Reading and writing images¶

The Python Imaging Library supports a wide variety of image file formats. To read files from disk, use the open() function in the Image module. You don’t have to know the file format to open a file. The library automatically determines the format based on the contents of the file.

To save a file, use the save() method of the Image class. When saving files, the name becomes important. Unless you specify the format, the library uses the filename extension to discover which file storage format to use.

from __future__ import print_function
import os, sys
from PIL import Image

for infile in sys.argv[1:]:
    f, e = os.path.splitext(infile)
    outfile = f + ".jpg"
    if infile != outfile:
        try:
            Image.open(infile).save(outfile)
        except IOError:
            print("cannot convert", infile)

from __future__ import print_function
import os, sys
from PIL import Image

size = (128, 128)

for infile in sys.argv[1:]:
    outfile = os.path.splitext(infile)[0] + ".thumbnail"
    if infile != outfile:
        try:
            im = Image.open(infile)
            im.thumbnail(size)
            im.save(outfile, "JPEG")
        except IOError:
            print("cannot create thumbnail for", infile)

from __future__ import print_function
import sys
from PIL import Image

for infile in sys.argv[1:]:
    try:
        with Image.open(infile) as im:
            print(infile, im.format, "%dx%d" % im.size, im.mode)
    except IOError:
        pass

Cutting, pasting, and merging images¶

The Image class contains methods allowing you to manipulate regions within an image. To extract a sub-rectangle from an image, use the crop() method.

box = (100, 100, 400, 400)
region = im.crop(box)

region = region.transpose(Image.ROTATE_180)
im.paste(region, box)

def roll(image, delta):
    "Roll an image sideways"

    xsize, ysize = image.size

    delta = delta % xsize
    if delta == 0: return image

    part1 = image.crop((0, 0, delta, ysize))
    part2 = image.crop((delta, 0, xsize, ysize))
    image.paste(part2, (0, 0, xsize-delta, ysize))
    image.paste(part1, (xsize-delta, 0, xsize, ysize))

    return image

r, g, b = im.split()
im = Image.merge("RGB", (b, g, r))

Geometrical transforms¶

The PIL.Image.Image class contains methods to resize() and rotate() an image. The former takes a tuple giving the new size, the latter the angle in degrees counter-clockwise.

out = im.resize((128, 128))
out = im.rotate(45) # degrees counter-clockwise

out = im.transpose(Image.FLIP_LEFT_RIGHT)
out = im.transpose(Image.FLIP_TOP_BOTTOM)
out = im.transpose(Image.ROTATE_90)
out = im.transpose(Image.ROTATE_180)
out = im.transpose(Image.ROTATE_270)

Color transforms¶

The Python Imaging Library allows you to convert images between different pixel representations using the convert() method.

im = Image.open("lena.ppm").convert("L")

Image enhancement¶

The Python Imaging Library provides a number of methods and modules that can be used to enhance images.

from PIL import ImageFilter
out = im.filter(ImageFilter.DETAIL)

# multiply each pixel by 1.2
out = im.point(lambda i: i * 1.2)

# split the image into individual bands
source = im.split()

R, G, B = 0, 1, 2

# select regions where red is less than 100
mask = source[R].point(lambda i: i < 100 and 255)

# process the green band
out = source[G].point(lambda i: i * 0.7)

# paste the processed band back, but only where red was < 100
source[G].paste(out, None, mask)

# build a new multiband image
im = Image.merge(im.mode, source)

imout = im.point(lambda i: expression and 255)

from PIL import ImageEnhance

enh = ImageEnhance.Contrast(im)
enh.enhance(1.3).show("30% more contrast")

Image sequences¶

The Python Imaging Library contains some basic support for image sequences (also called animation formats). Supported sequence formats include FLI/FLC, GIF, and a few experimental formats. TIFF files can also contain more than one frame.

When you open a sequence file, PIL automatically loads the first frame in the sequence. You can use the seek and tell methods to move between different frames:

from PIL import Image

im = Image.open("animation.gif")
im.seek(1) # skip to the second frame

try:
    while 1:
        im.seek(im.tell()+1)
        # do something to im
except EOFError:
    pass # end of sequence

class ImageSequence:
    def __init__(self, im):
        self.im = im
    def __getitem__(self, ix):
        try:
            if ix:
                self.im.seek(ix)
            return self.im
        except EOFError:
            raise IndexError # end of sequence

for frame in ImageSequence(im):
    # ...do something to frame...

Postscript printing¶

The Python Imaging Library includes functions to print images, text and graphics on Postscript printers. Here’s a simple example:

from PIL import Image
from PIL import PSDraw

im = Image.open("lena.ppm")
title = "lena"
box = (1*72, 2*72, 7*72, 10*72) # in points

ps = PSDraw.PSDraw() # default is sys.stdout
ps.begin_document(title)

# draw the image (75 dpi)
ps.image(box, im, 75)
ps.rectangle(box)

# draw title
ps.setfont("HelveticaNarrow-Bold", 36)
ps.text((3*72, 4*72), title)

ps.end_document()

More on reading images¶

As described earlier, the open() function of the Image module is used to open an image file. In most cases, you simply pass it the filename as an argument:

im = Image.open("lena.ppm")

If everything goes well, the result is an PIL.Image.Image object. Otherwise, an IOError exception is raised.

You can use a file-like object instead of the filename. The object must implement read(), seek() and tell() methods, and be opened in binary mode.

fp = open("lena.ppm", "rb")
im = Image.open(fp)

import StringIO

im = Image.open(StringIO.StringIO(buffer))

from PIL import TarIO

fp = TarIO.TarIO("Imaging.tar", "Imaging/test/lena.ppm")
im = Image.open(fp)

Controlling the decoder¶

Some decoders allow you to manipulate the image while reading it from a file. This can often be used to speed up decoding when creating thumbnails (when speed is usually more important than quality) and printing to a monochrome laser printer (when only a greyscale version of the image is needed).

The draft() method manipulates an opened but not yet loaded image so it as closely as possible matches the given mode and size. This is done by reconfiguring the image decoder.

from __future__ import print_function
im = Image.open(file)
print("original =", im.mode, im.size)

im.draft("L", (100, 100))
print("draft =", im.mode, im.size)

original = RGB (512, 512)
draft = L (128, 128)

Bands¶

An image can consist of one or more bands of data. The Python Imaging Library allows you to store several bands in a single image, provided they all have the same dimensions and depth. For example, a PNG image might have ‘R’, ‘G’, ‘B’, and ‘A’ bands for the red, green, blue, and alpha transparency values. Many operations act on each band separately, e.g., histograms. It is often useful to think of each pixel as having one value per band.

To get the number and names of bands in an image, use the getbands() method.

Modes¶

The mode of an image defines the type and depth of a pixel in the image. The current release supports the following standard modes:

• 1 (1-bit pixels, black and white, stored with one pixel per byte)
• L (8-bit pixels, black and white)
• P (8-bit pixels, mapped to any other mode using a color palette)
• RGB (3x8-bit pixels, true color)
• RGBA (4x8-bit pixels, true color with transparency mask)
• CMYK (4x8-bit pixels, color separation)
• YCbCr (3x8-bit pixels, color video format)
  • Note that this refers to the JPEG, and not the ITU-R BT.2020, standard
• LAB (3x8-bit pixels, the L*a*b color space)
• HSV (3x8-bit pixels, Hue, Saturation, Value color space)
• I (32-bit signed integer pixels)
• F (32-bit floating point pixels)

PIL also provides limited support for a few special modes, including LA (L with alpha), RGBX (true color with padding) and RGBa (true color with premultiplied alpha). However, PIL doesn’t support user-defined modes; if you to handle band combinations that are not listed above, use a sequence of Image objects.

You can read the mode of an image through the mode attribute. This is a string containing one of the above values.

Size¶

You can read the image size through the size attribute. This is a 2-tuple, containing the horizontal and vertical size in pixels.

Coordinate System¶

The Python Imaging Library uses a Cartesian pixel coordinate system, with (0,0) in the upper left corner. Note that the coordinates refer to the implied pixel corners; the centre of a pixel addressed as (0, 0) actually lies at (0.5, 0.5).

Coordinates are usually passed to the library as 2-tuples (x, y). Rectangles are represented as 4-tuples, with the upper left corner given first. For example, a rectangle covering all of an 800x600 pixel image is written as (0, 0, 800, 600).

Palette¶

The palette mode (P) uses a color palette to define the actual color for each pixel.

Info¶

You can attach auxiliary information to an image using the info attribute. This is a dictionary object.

How such information is handled when loading and saving image files is up to the file format handler (see the chapter on Image file formats). Most handlers add properties to the info attribute when loading an image, but ignore it when saving images.

Filters¶

For geometry operations that may map multiple input pixels to a single output pixel, the Python Imaging Library provides four different resampling filters.

NEAREST

Pick the nearest pixel from the input image. Ignore all other input pixels.

BILINEAR

For resize calculate the output pixel value using linear interpolation on all pixels that may contribute to the output value. For other transformations linear interpolation over a 2x2 environment in the input image is used.

BICUBIC

For resize calculate the output pixel value using cubic interpolation on all pixels that may contribute to the output value. For other transformations cubic interpolation over a 4x4 environment in the input image is used.

LANCZOS

Calculate the output pixel value using a high-quality Lanczos filter (a truncated sinc) on all pixels that may contribute to the output value. In the current version of PIL, this filter can only be used with the resize and thumbnail methods.

1.1.3 新版功能.

Examples¶

The following script loads an image, rotates it 45 degrees, and displays it using an external viewer (usually xv on Unix, and the paint program on Windows).

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

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

Functions¶

PIL.Image.open(fp, mode='r')[源代码]¶

Opens and identifies the given image file.

This is a lazy operation; this function identifies the file, but the file remains open and the actual image data is not read from the file until you try to process the data (or call the load() method). See new().

参数:	fp – A filename (string), pathlib.Path object or a file object. The file object must implement read(), seek(), and tell() methods, and be opened in binary mode. mode – The mode. If given, this argument must be “r”.
返回:	An Image object.
引发:	IOError – If the file cannot be found, or the image cannot be opened and identified.

警告

To protect against potential DOS attacks caused by “decompression bombs” (i.e. malicious files which decompress into a huge amount of data and are designed to crash or cause disruption by using up a lot of memory), Pillow will issue a DecompressionBombWarning if the image is over a certain limit. If desired, the warning can be turned into an error with warnings.simplefilter('error', Image.DecompressionBombWarning) or suppressed entirely with warnings.simplefilter('ignore', Image.DecompressionBombWarning). See also the logging documentation to have warnings output to the logging facility instead of stderr.

The Image Class¶

class PIL.Image.Image[源代码]¶

This class represents an image object. To create Image objects, use the appropriate factory functions. There’s hardly ever any reason to call the Image constructor directly.

• open()
• new()
• frombytes()

An instance of the Image class has the following methods. Unless otherwise stated, all methods return a new instance of the Image class, holding the resulting image.

Image.convert(mode=None, matrix=None, dither=None, palette=0, colors=256)[源代码]¶

Returns a converted copy of this image. For the “P” mode, this method 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 version supports all possible conversions between “L”, “RGB” and “CMYK.” The matrix argument only supports “L” and “RGB”.

When translating a color 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

The default method of converting a greyscale (“L”) or “RGB” image into a bilevel (mode “1”) image uses Floyd-Steinberg dither to approximate the original image luminosity levels. If dither is NONE, all non-zero values are set to 255 (white). To use other thresholds, use the point() method.

参数:	mode – The requested mode. See: Modes. matrix – An optional conversion matrix. If given, this should be 4- or 12-tuple containing floating point values. dither – Dithering method, used when converting from mode “RGB” to “P” or from “RGB” or “L” to “1”. Available methods are NONE or FLOYDSTEINBERG (default). palette – Palette to use when converting from mode “RGB” to “P”. Available palettes are WEB or ADAPTIVE. colors – Number of colors to use for the ADAPTIVE palette. Defaults to 256.
返回类型:	Image
返回:	An Image object.

The following example converts an RGB image (linearly calibrated according to ITU-R 709, using the D65 luminant) to the CIE XYZ color 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)

Image.copy()[源代码]¶

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

返回类型:	Image
返回:	An Image object.

Image.crop(box=None)[源代码]¶

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

This is a lazy operation. Changes to the source image may or may not be reflected in the cropped image. To break the connection, call the load() method on the cropped copy.

参数:	box – The crop rectangle, as a (left, upper, right, lower)-tuple.
返回类型:	Image
返回:	An Image object.

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

参数:	mode – The requested mode. size – The requested size.

Image.filter(filter)[源代码]¶

Filters this image using the given filter. For a list of available filters, see the ImageFilter module.

参数:	filter – Filter kernel.
返回:	An Image object.

Image.getbands()[源代码]¶

Returns a tuple containing the name of each band in this image. For example, getbands on an RGB image returns (“R”, “G”, “B”).

返回:	A tuple containing band names.
返回类型:	tuple

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

Image.getcolors(maxcolors=256)[源代码]¶

Returns a list of colors used in this image.

参数:	maxcolors – Maximum number of colors. If this number is exceeded, this method returns None. The default limit is 256 colors.
返回:	An unsorted list of (count, pixel) values.

Image.getdata(band=None)[源代码]¶

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

参数:	band – What band to return. The default is to return all bands. To return a single band, pass in the index value (e.g. 0 to get the “R” band from an “RGB” image).
返回:	A sequence-like object.

Image.getextrema()[源代码]¶

Gets the the minimum and maximum pixel values for each band in the image.

返回:	For a single-band image, a 2-tuple containing the minimum and maximum pixel value. For a multi-band image, a tuple containing one 2-tuple for each band.

Image.getpalette()[源代码]¶

Returns the image palette as a list.

返回:	A list of color values [r, g, b, ...], or None if the image has no palette.

Image.getpixel(xy)[源代码]¶

Returns the pixel value at a given position.

参数:	xy – The coordinate, given as (x, y).
返回:	The pixel value. If the image is a multi-layer image, this method returns a tuple.

Image.histogram(mask=None, extrema=None)[源代码]¶

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.

If a mask is provided, the method 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”).

参数:	mask – An optional mask.
返回:	A list containing pixel counts.

Image.offset(xoffset, yoffset=None)[源代码]¶

Image.paste(im, box=None, mask=None)[源代码]¶

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

Instead of an image, the source can be a integer or tuple containing pixel values. The method then fills the region with the given color. When creating RGB images, you can also use color strings as supported by the ImageColor module.

If a mask is given, this method 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 will mix the two images together, including their alpha channels if they have them.

See alpha_composite() if you want to combine images with respect to their alpha channels.

参数:

im – Source image or pixel value (integer or tuple). box – An optional 4-tuple giving the region to paste into. If a 2-tuple is used instead, it’s treated as the upper left corner. If omitted or None, the source is pasted into the upper left corner. If an image is given as the second argument and there is no third, the box defaults to (0, 0), and the second argument is interpreted as a mask image. mask – An optional mask image.

Image.point(lut, mode=None)[源代码]¶

Maps this image through a lookup table or function.

参数:

lut – A lookup table, containing 256 (or 65336 if self.mode==”I” and mode == “L”) values per band in the image. A function can be 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. mode – Output mode (default is same as input). In the current version, this can only be used if the source image has mode “L” or “P”, and the output has mode “1” or the source image mode is “I” and the output mode is “L”.

返回:

An Image object.

Image.putalpha(alpha)[源代码]¶

Adds or replaces the alpha layer in this image. If the image does not have an alpha layer, it’s converted to “LA” or “RGBA”. The new layer must be either “L” or “1”.

参数:	alpha – The new alpha layer. This can either be an “L” or “1” image having the same size as this image, or an integer or other color value.

Image.putdata(data, scale=1.0, offset=0.0)[源代码]¶

Copies pixel data to this image. This method copies data from a sequence object into the image, starting at the upper left corner (0, 0), and continuing until either the image or the sequence ends. The scale and offset values are used to adjust the sequence values: pixel = value*scale + offset.

参数:	data – A sequence object. scale – An optional scale value. The default is 1.0. offset – An optional offset value. The default is 0.0.

Image.putpalette(data, rawmode='RGB')[源代码]¶

Attaches a palette to this image. The image must be a “P” or “L” image, and the palette sequence must 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.

参数:	data – A palette sequence (either a list or a string).

Image.putpixel(xy, value)[源代码]¶

Modifies the pixel at the given position. The color 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. For more extensive changes, use paste() or the ImageDraw module instead.

See:

• paste()
• putdata()
• ImageDraw

参数:	xy – The pixel coordinate, given as (x, y). value – The pixel value.

Image.quantize(colors=256, method=None, kmeans=0, palette=None)[源代码]¶

Convert the image to ‘P’ mode with the specified number of colors.

参数:	colors – The desired number of colors, <= 256 method – 0 = median cut 1 = maximum coverage 2 = fast octree kmeans – Integer palette – Quantize to the PIL.ImagingPalette palette.
返回:	A new image

Image.resize(size, resample=0)[源代码]¶

Returns a resized copy of this image.

参数:	size – The requested size in pixels, as a 2-tuple: (width, height). resample – An optional resampling filter. This can be one of PIL.Image.NEAREST (use nearest neighbour), PIL.Image.BILINEAR (linear interpolation), PIL.Image.BICUBIC (cubic spline interpolation), or PIL.Image.LANCZOS (a high-quality downsampling filter). If omitted, or if the image has mode “1” or “P”, it is set PIL.Image.NEAREST.
返回:	An Image object.

Image.rotate(angle, resample=0, expand=0)[源代码]¶

Returns a rotated copy of this image. This method returns a copy of this image, rotated the given number of degrees counter clockwise around its centre.

参数:

angle – In degrees counter clockwise. resample – An optional resampling filter. This can be one of PIL.Image.NEAREST (use nearest neighbour), PIL.Image.BILINEAR (linear interpolation in a 2x2 environment), or PIL.Image.BICUBIC (cubic spline interpolation in a 4x4 environment). If omitted, or if the image has mode “1” or “P”, it is set PIL.Image.NEAREST. expand – Optional expansion flag. If true, expands the output image to make it large enough to hold the entire rotated image. If false or omitted, make the output image the same size as the input image.

返回:

An Image object.

Image.save(fp, format=None, **params)[源代码]¶

Saves this image under the given filename. If no format is specified, the format to use is determined from the filename extension, if possible.

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 in the image format documentation for each writer.

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.

参数:	fp – A filename (string), pathlib.Path object or file object. format – Optional format override. If omitted, the format to use is determined from the filename extension. If a file object was used instead of a filename, this parameter should always be used. options – Extra parameters to the image writer.
返回:	None
引发:	KeyError – If the output format could not be determined from the file name. Use the format option to solve this. IOError – If the file could not be written. The file may have been created, and may contain partial data.

Image.seek(frame)[源代码]¶

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

See tell().

参数:	frame – Frame number, starting at 0.
引发:	EOFError – If the call attempts to seek beyond the end of the sequence.

Image.show(title=None, command=None)[源代码]¶

Displays this 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 (usually Paint).

参数:	title – Optional title to use for the image window, where possible. command – command used to show the image

Image.split()[源代码]¶

Split this image into individual bands. This method 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).

返回:	A tuple containing bands.

Image.tell()[源代码]¶

Returns the current frame number. See seek().

返回:	Frame number, starting with 0.

Image.thumbnail(size, resample=3)[源代码]¶

Make this image into a thumbnail. This method 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.

参数:	size – Requested size. resample – Optional resampling filter. This can be one of PIL.Image.NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC, or PIL.Image.LANCZOS. If omitted, it defaults to PIL.Image.BICUBIC. (was PIL.Image.NEAREST prior to version 2.5.0)
返回:	None

Image.tobitmap(name='image')[源代码]¶

Returns the image converted to an X11 bitmap.

注解

This method only works for mode “1” images.

参数:	name – The name prefix to use for the bitmap variables.
返回:	A string containing an X11 bitmap.
引发:	ValueError – If the mode is not “1”

Image.tobytes(encoder_name='raw', *args)[源代码]¶

Return image as a bytes object.

警告

This method returns the raw image data from the internal storage. For compressed image data (e.g. PNG, JPEG) use save(), with a BytesIO parameter for in-memory data.

参数:	encoder_name – What encoder to use. The default is to use the standard “raw” encoder. args – Extra arguments to the encoder.
返回类型:	A bytes object.

Image.tostring(*args, **kw)[源代码]¶

Image.transform(size, method, data=None, resample=0, fill=1)[源代码]¶

Transforms this image. This method 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.

参数:

size – The output size. method – The transformation method. This is one of PIL.Image.EXTENT (cut out a rectangular subregion), PIL.Image.AFFINE (affine transform), PIL.Image.PERSPECTIVE (perspective transform), PIL.Image.QUAD (map a quadrilateral to a rectangle), or PIL.Image.MESH (map a number of source quadrilaterals in one operation). data – Extra data to the transformation method. resample – Optional resampling filter. It can be one of PIL.Image.NEAREST (use nearest neighbour), PIL.Image.BILINEAR (linear interpolation in a 2x2 environment), or PIL.Image.BICUBIC (cubic spline interpolation in a 4x4 environment). If omitted, or if the image has mode “1” or “P”, it is set to PIL.Image.NEAREST.

返回:

An Image object.

Image.transpose(method)[源代码]¶

Transpose image (flip or rotate in 90 degree steps)

参数:	method – One of PIL.Image.FLIP_LEFT_RIGHT, PIL.Image.FLIP_TOP_BOTTOM, PIL.Image.ROTATE_90, PIL.Image.ROTATE_180, PIL.Image.ROTATE_270 or PIL.Image.TRANSPOSE.
返回:	Returns a flipped or rotated copy of this image.

Image.verify()[源代码]¶

Verifies the contents of a file. For data read from a file, this method 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.

Image.fromstring(*args, **kw)[源代码]¶

Image.load()[源代码]¶

Allocates storage for the image and loads the pixel data. 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. This method will close the file associated with the image.

返回:	An image access object.
返回类型:	PixelAccess Class or PIL.PyAccess

Image.close()[源代码]¶

Closes the file pointer, if possible.

This operation will destroy the image core and release its memory. The image data will be unusable afterward.

This function is only required to close images that have not had their file read and closed by the load() method.

Attributes¶

Instances of the Image class have the following attributes:

PIL.Image.format¶

The file format of the source file. For images created by the library itself (via a factory function, or by running a method on an existing image), this attribute is set to None.

Type:	string or None

PIL.Image.mode¶

Image mode. This is a string specifying the pixel format used by the image. Typical values are “1”, “L”, “RGB”, or “CMYK.” See Modes for a full list.

Type:	string

PIL.Image.size¶

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

Type:	(width, height)

PIL.Image.width¶

Image width, in pixels.

Type:	int

PIL.Image.height¶

Image height, in pixels.

Type:	int

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

Type:	ImagePalette or None

PIL.Image.info¶

A dictionary holding data associated with the image. This dictionary is used by file handlers to pass on various non-image information read from the file. See documentation for the various file handlers for details.

Most methods ignore the dictionary when returning new images; since the keys are not standardized, it’s not possible for a method to know if the operation affects the dictionary. If you need the information later on, keep a reference to the info dictionary returned from the open method.

Unless noted elsewhere, this dictionary does not affect saving files.

Type:	dict

Functions¶

Most channel operations take one or two image arguments and returns a new image. Unless otherwise noted, the result of a channel operation is always clipped to the range 0 to MAX (which is 255 for all modes supported by the operations in this module).

PIL.ImageChops.add(image1, image2, scale=1.0, offset=0)[源代码]¶

Adds two images, dividing the result by scale and adding the offset. If omitted, scale defaults to 1.0, and offset to 0.0.

out = ((image1 + image2) / scale + offset)

返回类型:	Image

PIL.ImageChops.add_modulo(image1, image2)[源代码]¶

Add two images, without clipping the result.

out = ((image1 + image2) % MAX)

返回类型:	Image

PIL.ImageChops.blend(image1, image2, alpha)[源代码]¶

Blend images using constant transparency weight. Alias for PIL.Image.Image.blend().

返回类型:	Image

PIL.ImageChops.composite(image1, image2, mask)[源代码]¶

Create composite using transparency mask. Alias for PIL.Image.Image.composite().

返回类型:	Image

PIL.ImageChops.constant(image, value)[源代码]¶

Fill a channel with a given grey level.

返回类型:	Image

PIL.ImageChops.darker(image1, image2)[源代码]¶

Compares the two images, pixel by pixel, and returns a new image containing the darker values.

out = min(image1, image2)

返回类型:	Image

PIL.ImageChops.difference(image1, image2)[源代码]¶

Returns the absolute value of the pixel-by-pixel difference between the two images.

out = abs(image1 - image2)

返回类型:	Image

PIL.ImageChops.duplicate(image)[源代码]¶

Copy a channel. Alias for PIL.Image.Image.copy().

返回类型:	Image

PIL.ImageChops.invert(image)[源代码]¶

Invert an image (channel).

out = MAX - image

返回类型:	Image

PIL.ImageChops.lighter(image1, image2)[源代码]¶

Compares the two images, pixel by pixel, and returns a new image containing the lighter values.

out = max(image1, image2)

返回类型:	Image

PIL.ImageChops.logical_and(image1, image2)[源代码]¶

Logical AND between two images.

out = ((image1 and image2) % MAX)

返回类型:	Image

PIL.ImageChops.logical_or(image1, image2)[源代码]¶

Logical OR between two images.

out = ((image1 or image2) % MAX)

返回类型:	Image

PIL.ImageChops.multiply(image1, image2)[源代码]¶

Superimposes two images on top of each other.

If you multiply an image with a solid black image, the result is black. If you multiply with a solid white image, the image is unaffected.

out = image1 * image2 / MAX

返回类型:	Image

PIL.ImageChops.offset(image, xoffset, yoffset=None)[源代码]¶

Returns a copy of the image where 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.

参数:	xoffset – The horizontal distance. yoffset – The vertical distance. If omitted, both distances are set to the same value.
返回类型:	Image

PIL.ImageChops.screen(image1, image2)[源代码]¶

Superimposes two inverted images on top of each other.

out = MAX - ((MAX - image1) * (MAX - image2) / MAX)

返回类型:	Image

PIL.ImageChops.subtract(image1, image2, scale=1.0, offset=0)[源代码]¶

Subtracts two images, dividing the result by scale and adding the offset. If omitted, scale defaults to 1.0, and offset to 0.0.

out = ((image1 - image2) / scale + offset)

返回类型:	Image

PIL.ImageChops.subtract_modulo(image1, image2)[源代码]¶

Subtract two images, without clipping the result.

out = ((image1 - image2) % MAX)

返回类型:	Image

Color Names¶

The ImageColor module supports the following string formats:

• Hexadecimal color specifiers, given as #rgb or #rrggbb. For example, #ff0000 specifies pure red.
• RGB functions, given as rgb(red, green, blue) where the color values are integers in the range 0 to 255. Alternatively, the color values can be given as three percentages (0% to 100%). For example, rgb(255,0,0) and rgb(100%,0%,0%) both specify pure red.
• Hue-Saturation-Lightness (HSL) functions, given as hsl(hue, saturation%, lightness%) where hue is the color given as an angle between 0 and 360 (red=0, green=120, blue=240), saturation is a value between 0% and 100% (gray=0%, full color=100%), and lightness is a value between 0% and 100% (black=0%, normal=50%, white=100%). For example, hsl(0,100%,50%) is pure red.
• Common HTML color names. The ImageColor module provides some 140 standard color names, based on the colors supported by the X Window system and most web browsers. color names are case insensitive. For example, red and Red both specify pure red.

Functions¶

PIL.ImageColor.getrgb(color)[源代码]¶

Convert a color string to an RGB tuple. If the string cannot be parsed, this function raises a ValueError exception.

1.1.4 新版功能.

参数:	color – A color string
返回:	(red, green, blue[, alpha])

PIL.ImageColor.getcolor(color, mode)[源代码]¶

Same as getrgb(), but converts the RGB value to a greyscale value if the mode is not color or a palette image. If the string cannot be parsed, this function raises a ValueError exception.

1.1.4 新版功能.

参数:	color – A color string
返回:	(graylevel [, alpha]) or (red, green, blue[, alpha])

CmsProfile¶

The ICC color profiles are wrapped in an instance of the class CmsProfile. The specification ICC.1:2010 contains more information about the meaning of the values in ICC profiles.

For convenience, all XYZ-values are also given as xyY-values (so they can be easily displayed in a chromaticity diagram, for example).

class PIL.ImageCms.CmsProfile¶

creation_date¶

Date and time this profile was first created (see 7.2.1 of ICC.1:2010).

Type:	datetime.datetime or None

version¶

The version number of the ICC standard that this profile follows (e.g. 2.0).

Type:	float

icc_version¶

Same as version, but in encoded format (see 7.2.4 of ICC.1:2010).

device_class¶

4-character string identifying the profile class. One of scnr, mntr, prtr, link, spac, abst, nmcl (see 7.2.5 of ICC.1:2010 for details).

Type:	string

xcolor_space¶

4-character string (padded with whitespace) identifying the color space, e.g. XYZ␣, RGB␣ or CMYK (see 7.2.6 of ICC.1:2010 for details).

Note that the deprecated attribute color_space contains an interpreted (non-padded) variant of this (but can be empty on unknown input).

Type:	string

connection_space¶

4-character string (padded with whitespace) identifying the color space on the B-side of the transform (see 7.2.7 of ICC.1:2010 for details).

Note that the deprecated attribute pcs contains an interpreted (non-padded) variant of this (but can be empty on unknown input).

Type:	string

header_flags¶

The encoded header flags of the profile (see 7.2.11 of ICC.1:2010 for details).

Type:	int

header_manufacturer¶

4-character string (padded with whitespace) identifying the device manufacturer, which shall match the signature contained in the appropriate section of the ICC signature registry found at www.color.org (see 7.2.12 of ICC.1:2010).

Type:	string

header_model¶

4-character string (padded with whitespace) identifying the device model, which shall match the signature contained in the appropriate section of the ICC signature registry found at www.color.org (see 7.2.13 of ICC.1:2010).

Type:	string

attributes¶

Flags used to identify attributes unique to the particular device setup for which the profile is applicable (see 7.2.14 of ICC.1:2010 for details).

Type:	int

rendering_intent¶

The rendering intent to use when combining this profile with another profile (usually overridden at run-time, but provided here for DeviceLink and embedded source profiles, see 7.2.15 of ICC.1:2010).

One of ImageCms.INTENT_ABSOLUTE_COLORIMETRIC, ImageCms.INTENT_PERCEPTUAL, ImageCms.INTENT_RELATIVE_COLORIMETRIC and ImageCms.INTENT_SATURATION.

Type:	int

profile_id¶

A sequence of 16 bytes identifying the profile (via a specially constructed MD5 sum), or 16 binary zeroes if the profile ID has not been calculated (see 7.2.18 of ICC.1:2010).

Type:	bytes

copyright¶

The text copyright information for the profile (see 9.2.21 of ICC.1:2010).

Type:	unicode or None

manufacturer¶

The (english) display string for the device manufacturer (see 9.2.22 of ICC.1:2010).

Type:	unicode or None

model¶

The (english) display string for the device model of the device for which this profile is created (see 9.2.23 of ICC.1:2010).

Type:	unicode or None

profile_description¶

The (english) display string for the profile description (see 9.2.41 of ICC.1:2010).

Type:	unicode or None

target¶

The name of the registered characterization data set, or the measurement data for a characterization target (see 9.2.14 of ICC.1:2010).

Type:	unicode or None

red_colorant¶

The first column in the matrix used in matrix/TRC transforms (see 9.2.44 of ICC.1:2010).

Type:	((X, Y, Z), (x, y, Y)) or None

green_colorant¶

The second column in the matrix used in matrix/TRC transforms (see 9.2.30 of ICC.1:2010).

Type:	((X, Y, Z), (x, y, Y)) or None

blue_colorant¶

The third column in the matrix used in matrix/TRC transforms (see 9.2.4 of ICC.1:2010).

Type:	((X, Y, Z), (x, y, Y)) or None

luminance¶

The absolute luminance of emissive devices in candelas per square metre as described by the Y channel (see 9.2.32 of ICC.1:2010).

Type:	((X, Y, Z), (x, y, Y)) or None

chromaticity¶

The data of the phosphor/colorant chromaticity set used (red, green and blue channels, see 9.2.16 of ICC.1:2010).

Type:	((x, y, Y), (x, y, Y), (x, y, Y)) or None

chromatic_adaption¶

The chromatic adaption matrix converts a color measured using the actual illumination conditions and relative to the actual adopted white, to an color relative to the PCS adopted white, with complete adaptation from the actual adopted white chromaticity to the PCS adopted white chromaticity (see 9.2.15 of ICC.1:2010).

Two matrices are returned, one in (X, Y, Z) space and one in (x, y, Y) space.

Type:	2-tuple of 3-tuple, the first with (X, Y, Z) and the second with (x, y, Y) values

colorant_table¶

This tag identifies the colorants used in the profile by a unique name and set of PCSXYZ or PCSLAB values (see 9.2.19 of ICC.1:2010).

Type:	list of strings

colorant_table_out¶

This tag identifies the colorants used in the profile by a unique name and set of PCSLAB values (for DeviceLink profiles only, see 9.2.19 of ICC.1:2010).

Type:	list of strings

colorimetric_intent¶

4-character string (padded with whitespace) identifying the image state of PCS colorimetry produced using the colorimetric intent transforms (see 9.2.20 of ICC.1:2010 for details).

Type:	string or None

perceptual_rendering_intent_gamut¶

4-character string (padded with whitespace) identifying the (one) standard reference medium gamut (see 9.2.37 of ICC.1:2010 for details).

Type:	string or None

saturation_rendering_intent_gamut¶

4-character string (padded with whitespace) identifying the (one) standard reference medium gamut (see 9.2.37 of ICC.1:2010 for details).

Type:	string or None

technology¶

4-character string (padded with whitespace) identifying the device technology (see 9.2.47 of ICC.1:2010 for details).

Type:	string or None

media_black_point¶

This tag specifies the media black point and is used for generating absolute colorimetry.

This tag was available in ICC 3.2, but it is removed from version 4.

Type:	((X, Y, Z), (x, y, Y)) or None

media_white_point_temperature¶

Calculates the white point temperature (see the LCMS documentation for more information).

Type:	float or None

viewing_condition¶

The (english) display string for the viewing conditions (see 9.2.48 of ICC.1:2010).

Type:	unicode or None

screening_description¶

The (english) display string for the screening conditions.

This tag was available in ICC 3.2, but it is removed from version 4.

Type:	unicode or None

red_primary¶

The XYZ-transformed of the RGB primary color red (1, 0, 0).

Type:	((X, Y, Z), (x, y, Y)) or None

green_primary¶

The XYZ-transformed of the RGB primary color green (0, 1, 0).

Type:	((X, Y, Z), (x, y, Y)) or None

blue_primary¶

The XYZ-transformed of the RGB primary color blue (0, 0, 1).

Type:	((X, Y, Z), (x, y, Y)) or None

is_matrix_shaper¶

True if this profile is implemented as a matrix shaper (see documentation on LCMS).

Type:	bool

clut¶

Returns a dictionary of all supported intents and directions for the CLUT model.

The dictionary is indexed by intents (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC, ImageCms.INTENT_PERCEPTUAL, ImageCms.INTENT_RELATIVE_COLORIMETRIC and ImageCms.INTENT_SATURATION).

The values are 3-tuples indexed by directions (ImageCms.DIRECTION_INPUT, ImageCms.DIRECTION_OUTPUT, ImageCms.DIRECTION_PROOF).

The elements of the tuple are booleans. If the value is True, that intent is supported for that direction.

Type:	dict of boolean 3-tuples

intent_supported¶

Returns a dictionary of all supported intents and directions.

The dictionary is indexed by intents (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC, ImageCms.INTENT_PERCEPTUAL, ImageCms.INTENT_RELATIVE_COLORIMETRIC and ImageCms.INTENT_SATURATION).

The values are 3-tuples indexed by directions (ImageCms.DIRECTION_INPUT, ImageCms.DIRECTION_OUTPUT, ImageCms.DIRECTION_PROOF).

The elements of the tuple are booleans. If the value is True, that intent is supported for that direction.

Type:	dict of boolean 3-tuples

color_space¶

Deprecated but retained for backwards compatibility. Interpreted value of xcolor_space. May be the empty string if value could not be decoded.

Type:	string

pcs¶

Deprecated but retained for backwards compatibility. Interpreted value of connection_space. May be the empty string if value could not be decoded.

Type:	string

product_model¶

Deprecated but retained for backwards compatibility. ASCII-encoded value of model.

Type:	string

product_manufacturer¶

Deprecated but retained for backwards compatibility. ASCII-encoded value of manufacturer.

Type:	string

product_copyright¶

Deprecated but retained for backwards compatibility. ASCII-encoded value of copyright.

Type:	string

product_description¶

Deprecated but retained for backwards compatibility. ASCII-encoded value of profile_description.

Type:	string

product_desc¶

Deprecated but retained for backwards compatibility. ASCII-encoded value of profile_description.

This alias of product_description used to contain a derived informative string about the profile, depending on the value of the description, copyright, manufacturer and model fields).

Type:	string

There is one function defined on the class:

is_intent_supported(intent, direction)¶

Returns if the intent is supported for the given direction.

Note that you can also get this information for all intents and directions with intent_supported.

参数:	intent – One of ImageCms.INTENT_ABSOLUTE_COLORIMETRIC, ImageCms.INTENT_PERCEPTUAL, ImageCms.INTENT_RELATIVE_COLORIMETRIC and ImageCms.INTENT_SATURATION. direction – One of ImageCms.DIRECTION_INPUT, ImageCms.DIRECTION_OUTPUT and ImageCms.DIRECTION_PROOF
返回:	Boolean if the intent and direction is supported.