The :py~PIL.Image
module provides a class with the same name which is used to represent a PIL image. The module also provides a number of factory functions, including functions to load images from files, and to create new images.
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()
The following script creates nice thumbnails of all JPEG images in the current directory preserving aspect ratios with 128x128 max resolution.
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")
open
Warning
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 number of pixels in an image is over a certain limit, :pyPIL.Image.MAX_IMAGE_PIXELS
.
This threshold can be changed by setting :pyPIL.Image.MAX_IMAGE_PIXELS
. It can be disabled by setting Image.MAX_IMAGE_PIXELS = None
.
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.
If the number of pixels is greater than twice :pyPIL.Image.MAX_IMAGE_PIXELS
, then a DecompressionBombError
will be raised instead.
alpha_composite
blend
composite
eval
merge
new
fromarray
frombytes
frombuffer
effect_mandelbrot
effect_noise
linear_gradient
radial_gradient
Note
These functions are for use by plugin authors. Application authors can ignore them.
register_open
register_mime
register_save
register_save_all
register_extension
register_extensions
registered_extensions
register_decoder
register_encoder
PIL.Image.Image
An instance of the :py~PIL.Image.Image
class has the following methods. Unless otherwise stated, all methods return a new instance of the :py~PIL.Image.Image
class, holding the resulting image.
PIL.Image.Image.alpha_composite
PIL.Image.Image.convert
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)
PIL.Image.Image.copy
PIL.Image.Image.crop
This crops the input image with the provided coordinates:
from PIL import Image
im = Image.open("hopper.jpg")
# The crop method from the Image module takes four coordinates as input.
# The right can also be represented as (left+width)
# and lower can be represented as (upper+height).
(left, upper, right, lower) = (20, 20, 100, 100)
# Here the image "im" is cropped and assigned to new variable im_crop
im_crop = im.crop((left, upper, right, lower))
PIL.Image.Image.draft
PIL.Image.Image.effect_spread
PIL.Image.Image.entropy
PIL.Image.Image.filter
PIL.Image.Image.frombytes
This blurs the input image using a filter from the ImageFilter
module:
from PIL import Image, ImageFilter
im = Image.open("hopper.jpg")
# Blur the input image using the filter ImageFilter.BLUR
im_blurred = im.filter(filter=ImageFilter.BLUR)
PIL.Image.Image.getbands
This helps to get the bands of the input image:
from PIL import Image
im = Image.open("hopper.jpg")
print(im.getbands()) # Returns ('R', 'G', 'B')
PIL.Image.Image.getbbox
This helps to get the bounding box coordinates of the input image:
from PIL import Image
im = Image.open("hopper.jpg")
print(im.getbbox())
# Returns four coordinates in the format (left, upper, right, lower)
PIL.Image.Image.getchannel
PIL.Image.Image.getcolors
PIL.Image.Image.getdata
PIL.Image.Image.getexif
PIL.Image.Image.getextrema
PIL.Image.Image.getpalette
PIL.Image.Image.getpixel
PIL.Image.Image.getprojection
PIL.Image.Image.histogram
PIL.Image.Image.paste
PIL.Image.Image.point
PIL.Image.Image.putalpha
PIL.Image.Image.putdata
PIL.Image.Image.putpalette
PIL.Image.Image.putpixel
PIL.Image.Image.quantize
PIL.Image.Image.reduce
PIL.Image.Image.remap_palette
PIL.Image.Image.resize
This resizes the given image from (width, height)
to (width/2, height/2)
:
from PIL import Image
im = Image.open("hopper.jpg")
# Provide the target width and height of the image
(width, height) = (im.width // 2, im.height // 2)
im_resized = im.resize((width, height))
PIL.Image.Image.rotate
This rotates the input image by theta
degrees counter clockwise:
from PIL import Image
im = Image.open("hopper.jpg")
# Rotate the image by 60 degrees counter clockwise
theta = 60
# Angle is in degrees counter clockwise
im_rotated = im.rotate(angle=theta)
PIL.Image.Image.save
PIL.Image.Image.seek
PIL.Image.Image.show
PIL.Image.Image.split
PIL.Image.Image.tell
PIL.Image.Image.thumbnail
PIL.Image.Image.tobitmap
PIL.Image.Image.tobytes
PIL.Image.Image.transform
PIL.Image.Image.transpose
This flips the input image by using the FLIP_LEFT_RIGHT
method.
from PIL import Image
im = Image.open("hopper.jpg")
# Flip the image from left to right
im_flipped = im.transpose(method=Image.FLIP_LEFT_RIGHT)
# To flip the image from top to bottom,
# use the method "Image.FLIP_TOP_BOTTOM"
PIL.Image.Image.verify
PIL.Image.Image.load
PIL.Image.Image.close
Instances of the :pyImage
class have the following attributes:
PIL.Image.Exif
PIL.Image.ImagePointHandler
PIL.Image.ImageTransformHandler
NONE
MAX_IMAGE_PIXELS
Set to 89,478,485, approximately 0.25GB for a 24-bit (3 bpp) image. See :py~PIL.Image.open
for more information about how this is used.
Used to specify the Image.transpose
method to use.
FLIP_LEFT_RIGHT
FLIP_TOP_BOTTOM
ROTATE_90
ROTATE_180
ROTATE_270
TRANSPOSE
TRANSVERSE
Used to specify the Image.transform
method to use.
AFFINE
Affine transform
EXTENT
Cut out a rectangular subregion
PERSPECTIVE
Perspective transform
QUAD
Map a quadrilateral to a rectangle
MESH
Map a number of source quadrilaterals in one operation
See concept-filters
for details.
NEAREST
BOX
BILINEAR
HAMMING
BICUBIC
LANCZOS
Some filters are also available under the following names for backwards compatibility:
NONE
LINEAR
CUBIC
ANTIALIAS
Used to specify the dithering method to use for the ~Image.convert
and ~Image.quantize
methods.
NONE
No dither
FLOYDSTEINBERG
Floyd-Steinberg dither
Used to specify the pallete to use for the ~Image.convert
method.
WEB
ADAPTIVE
Used to specify the quantization method to use for the ~Image.quantize
method.
MEDIANCUT
Median cut
MAXCOVERAGE
Maximum coverage
FASTOCTREE
Fast octree
LIBIMAGEQUANT
libimagequant
Check support using :pyPIL.features.check_feature
with feature="libimagequant"
.