mirror of
https://github.com/python-pillow/Pillow.git
synced 2024-12-24 00:46:16 +03:00
Convert Tutorial section of PIL handbook
This commit is contained in:
Steve Johnson
parent
9ea731287d
commit
9dc6f83803
|
|
@ -25,7 +25,9 @@ sys.path.insert(0, os.path.abspath('../'))
|
|||
|
||||
# Add any Sphinx extension module names here, as strings. They can be extensions
|
||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
|
||||
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode',
|
||||
'sphinx.ext.intersphinx']
|
||||
intersphinx_mapping = {'http://docs.python.org/2/': None}
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
|
|
|||
|
|
@ -1,2 +1,46 @@
|
|||
Overview
|
||||
========
|
||||
|
||||
The **Python Imaging Library** adds image processing capabilities to your
|
||||
Python interpreter.
|
||||
|
||||
This library provides extensive file format support, an efficient internal
|
||||
representation, and fairly powerful image processing capabilities.
|
||||
|
||||
The core image library is designed for fast access to data stored in a few
|
||||
basic pixel formats. It should provide a solid foundation for a general image
|
||||
processing tool.
|
||||
|
||||
Let’s look at a few possible uses of this library.
|
||||
|
||||
Image Archives
|
||||
--------------
|
||||
|
||||
The Python Imaging Library is ideal for 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 :py:class:`~PIL.ImageTk.PhotoImage` and
|
||||
:py:class:`~PIL.ImageTk.BitmapImage` interfaces, as well as a :py:mod:`Windows
|
||||
DIB interface <PIL.ImageWin>` 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 :py:meth:`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.
|
||||
|
|
|
|||
|
|
@ -1,2 +1,534 @@
|
|||
Tutorial
|
||||
========
|
||||
|
||||
Using the Image class
|
||||
---------------------
|
||||
|
||||
The most important class in the Python Imaging Library is the
|
||||
:py:class:`~PIL.Image.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 :py:func:`~PIL.Image.open` function
|
||||
in the :py:mod:`~PIL.Image` module::
|
||||
|
||||
>>> from PIL import Image
|
||||
>>> im = Image.open("lena.ppm")
|
||||
|
||||
If successful, this function returns an :py:class:`PIL.Image.Image` object. You
|
||||
can now use instance attributes to examine the file contents::
|
||||
|
||||
>>> print im.format, im.size, im.mode
|
||||
PPM (512, 512) RGB
|
||||
|
||||
The :py:attr:`~PIL.Image.Image.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
|
||||
:py:attr:`~PIL.Image.Image.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 colour images, and “CMYK” for
|
||||
pre-press images.
|
||||
|
||||
If the file cannot be opened, an :py:exc:`IOError` exception is raised.
|
||||
|
||||
Once you have an instance of the :py:class:`~PIL.Image.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()
|
||||
|
||||
.. note::
|
||||
|
||||
The standard version of :py:meth:`~PIL.Image.Image.show` is not very
|
||||
efficient, since it saves the image to a temporary file and calls the
|
||||
:command:`xv` utility to display the image. If you don’t have :command:`xv`
|
||||
installed, it won’t even work. When it does work though, it is very handy
|
||||
for debugging and tests.
|
||||
|
||||
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 :py:func:`~PIL.Image.open` function in the
|
||||
:py:mod:`~PIL.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 :py:meth:`~PIL.Image.Image.save` method of the
|
||||
:py:class:`~PIL.Image.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.
|
||||
|
||||
Convert files to JPEG
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
|
||||
A second argument can be supplied to the :py:meth:`~PIL.Image.Image.save`
|
||||
method which explicitly specifies a file format. If you use a non-standard
|
||||
extension, you must always specify the format this way:
|
||||
|
||||
Create JPEG thumbnails
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
|
||||
|
||||
It is important to note that the library doesn’t decode or load the raster data
|
||||
unless it really has to. When you open a file, the file header is read to
|
||||
determine the file format and extract things like mode, size, and other
|
||||
properties required to decode the file, but the rest of the file is not
|
||||
processed until later.
|
||||
|
||||
This means that opening an image file is a fast operation, which is independent
|
||||
of the file size and compression type. Here’s a simple script to quickly
|
||||
identify a set of image files:
|
||||
|
||||
Identify Image Files
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
import sys
|
||||
from PIL import Image
|
||||
|
||||
for infile in sys.argv[1:]:
|
||||
try:
|
||||
im = Image.open(infile)
|
||||
print infile, im.format, "%dx%d" % im.size, im.mode
|
||||
except IOError:
|
||||
pass
|
||||
|
||||
Cutting, pasting, and merging images
|
||||
------------------------------------
|
||||
|
||||
The :py:class:`~PIL.Image.Image` class contains methods allowing you to
|
||||
manipulate regions within an image. To extract a sub-rectangle from an image,
|
||||
use the :py:meth:`~PIL.Image.Image.crop` method.
|
||||
|
||||
Copying a subrectangle from an image
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
box = (100, 100, 400, 400)
|
||||
region = im.crop(box)
|
||||
|
||||
The region is defined by a 4-tuple, where coordinates are (left, upper, right,
|
||||
lower). The Python Imaging Library uses a coordinate system with (0, 0) in the
|
||||
upper left corner. Also note that coordinates refer to positions between the
|
||||
pixels, so the region in the above example is exactly 300x300 pixels.
|
||||
|
||||
The region could now be processed in a certain manner and pasted back.
|
||||
|
||||
Processing a subrectangle, and pasting it back
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
region = region.transpose(Image.ROTATE_180)
|
||||
im.paste(region, box)
|
||||
|
||||
When pasting regions back, the size of the region must match the given region
|
||||
exactly. In addition, the region cannot extend outside the image. However, the
|
||||
modes of the original image and the region do not need to match. If they don’t,
|
||||
the region is automatically converted before being pasted (see the section on
|
||||
:ref:`color-transforms` below for details).
|
||||
|
||||
Here’s an additional example:
|
||||
|
||||
Rolling an image
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
|
||||
For more advanced tricks, the paste method can also take a transparency mask as
|
||||
an optional argument. In this mask, the value 255 indicates that the pasted
|
||||
image is opaque in that position (that is, the pasted image should be used as
|
||||
is). The value 0 means that the pasted image is completely transparent. Values
|
||||
in-between indicate different levels of transparency.
|
||||
|
||||
The Python Imaging Library also allows you to work with the individual bands of
|
||||
an multi-band image, such as an RGB image. The split method creates a set of
|
||||
new images, each containing one band from the original multi-band image. The
|
||||
merge function takes a mode and a tuple of images, and combines them into a new
|
||||
image. The following sample swaps the three bands of an RGB image:
|
||||
|
||||
Splitting and merging bands
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
r, g, b = im.split()
|
||||
im = Image.merge("RGB", (b, g, r))
|
||||
|
||||
Note that for a single-band image, :py:meth:`~PIL.Image.Image.split` returns
|
||||
the image itself. To work with individual colour bands, you may want to convert
|
||||
the image to “RGB” first.
|
||||
|
||||
Geometrical transforms
|
||||
----------------------
|
||||
|
||||
The :py:class:`PIL.Image.Image` class contains methods to
|
||||
:py:meth:`~PIL.Image.Image.resize` and :py:meth:`~PIL.Image.Image.rotate` an
|
||||
image. The former takes a tuple giving the new size, the latter the angle in
|
||||
degrees counter-clockwise.
|
||||
|
||||
Simple geometry transforms
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
out = im.resize((128, 128))
|
||||
out = im.rotate(45) # degrees counter-clockwise
|
||||
|
||||
To rotate the image in 90 degree steps, you can either use the
|
||||
:py:meth:`~PIL.Image.Image.rotate` method or the
|
||||
:py:meth:`~PIL.Image.Image.transpose` method. The latter can also be used to
|
||||
flip an image around its horizontal or vertical axis.
|
||||
|
||||
Transposing an image
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
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)
|
||||
|
||||
There’s no difference in performance or result between ``transpose(ROTATE)``
|
||||
and corresponding :py:meth:`~PIL.Image.Image.rotate` operations.
|
||||
|
||||
A more general form of image transformations can be carried out via the
|
||||
:py:meth:`~PIL.Image.Image.transform` method.
|
||||
|
||||
.. _color-transforms:
|
||||
|
||||
Color transforms
|
||||
----------------
|
||||
|
||||
The Python Imaging Library allows you to convert images between different pixel
|
||||
representations using the :py:meth:`~PIL.Image.Image.convert` method.
|
||||
|
||||
Converting between modes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
im = Image.open("lena.ppm").convert("L")
|
||||
|
||||
The library supports transformations between each supported mode and the “L”
|
||||
and “RGB” modes. To convert between other modes, you may have to use an
|
||||
intermediate image (typically an “RGB” image).
|
||||
|
||||
Image enhancement
|
||||
-----------------
|
||||
|
||||
The Python Imaging Library provides a number of methods and modules that can be
|
||||
used to enhance images.
|
||||
|
||||
Filters
|
||||
^^^^^^^
|
||||
|
||||
The :py:mod:`~PIL.ImageFilter` module contains a number of pre-defined
|
||||
enhancement filters that can be used with the
|
||||
:py:meth:`~PIL.Image.Image.filter` method.
|
||||
|
||||
Applying filters
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
from PIL import ImageFilter
|
||||
out = im.filter(ImageFilter.DETAIL)
|
||||
|
||||
Point Operations
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The :py:meth:`~PIL.Image.Image.point` method can be used to translate the pixel
|
||||
values of an image (e.g. image contrast manipulation). In most cases, a
|
||||
function object expecting one argument can be passed to the this method. Each
|
||||
pixel is processed according to that function:
|
||||
|
||||
Applying point transforms
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
# multiply each pixel by 1.2
|
||||
out = im.point(lambda i: i * 1.2)
|
||||
|
||||
Using the above technique, you can quickly apply any simple expression to an
|
||||
image. You can also combine the :py:meth:`~PIL.Image.Image.point` and
|
||||
:py:meth:`~PIL.Image.Image.paste` methods to selectively modify an image:
|
||||
|
||||
Processing individual bands
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
# 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)
|
||||
|
||||
Note the syntax used to create the mask::
|
||||
|
||||
imout = im.point(lambda i: expression and 255)
|
||||
|
||||
Python only evaluates the portion of a logical expression as is necessary to
|
||||
determine the outcome, and returns the last value examined as the result of the
|
||||
expression. So if the expression above is false (0), Python does not look at
|
||||
the second operand, and thus returns 0. Otherwise, it returns 255.
|
||||
|
||||
Enhancement
|
||||
^^^^^^^^^^^
|
||||
|
||||
For more advanced image enhancement, you can use the classes in the
|
||||
:py:mod:`~PIL.ImageEnhance` module. Once created from an image, an enhancement
|
||||
object can be used to quickly try out different settings.
|
||||
|
||||
You can adjust contrast, brightness, colour balance and sharpness in this way.
|
||||
|
||||
Enhancing images
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
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:
|
||||
|
||||
Reading sequences
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
|
||||
As seen in this example, you’ll get an :py:exc:`EOFError` exception when the
|
||||
sequence ends.
|
||||
|
||||
Note that most drivers in the current version of the library only allow you to
|
||||
seek to the next frame (as in the above example). To rewind the file, you may
|
||||
have to reopen it.
|
||||
|
||||
The following iterator class lets you to use the for-statement to loop over the
|
||||
sequence:
|
||||
|
||||
A sequence iterator class
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
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:
|
||||
|
||||
Drawing Postscript
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
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 centered title
|
||||
ps.setfont("HelveticaNarrow-Bold", 36)
|
||||
w, h, b = ps.textsize(title)
|
||||
ps.text((4*72-w/2, 1*72-h), title)
|
||||
|
||||
ps.end_document()
|
||||
|
||||
More on reading images
|
||||
----------------------
|
||||
|
||||
As described earlier, the :py:func:`~PIL.Image.open` function of the
|
||||
:py:mod:`~PIL.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 :py:class:`PIL.Image.Image` object.
|
||||
Otherwise, an :exc:`IOError` exception is raised.
|
||||
|
||||
You can use a file-like object instead of the filename. The object must
|
||||
implement :py:meth:`~file.read`, :py:meth:`~file.seek` and
|
||||
:py:meth:`~file.tell` methods, and be opened in binary mode.
|
||||
|
||||
Reading from an open file
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
fp = open("lena.ppm", "rb")
|
||||
im = Image.open(fp)
|
||||
|
||||
To read an image from string data, use the :py:class:`~StringIO.StringIO`
|
||||
class:
|
||||
|
||||
Reading from a string
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
import StringIO
|
||||
|
||||
im = Image.open(StringIO.StringIO(buffer))
|
||||
|
||||
Note that the library rewinds the file (using ``seek(0)``) before reading the
|
||||
image header. In addition, seek will also be used when the image data is read
|
||||
(by the load method). If the image file is embedded in a larger file, such as a
|
||||
tar file, you can use the :py:class:`~PIL.ContainerIO` or
|
||||
:py:class:`~PIL.TarIO` modules to access it.
|
||||
|
||||
Reading from a tar archive
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
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 :py:meth:`~PIL.Image.Image.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.
|
||||
|
||||
Reading in draft mode
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
im = Image.open(file)
|
||||
print "original =", im.mode, im.size
|
||||
|
||||
im.draft("L", (100, 100))
|
||||
print "draft =", im.mode, im.size
|
||||
|
||||
This prints something like:
|
||||
|
||||
original = RGB (512, 512)
|
||||
draft = L (128, 128)
|
||||
|
||||
Note that the resulting image may not exactly match the requested mode and
|
||||
size. To make sure that the image is not larger than the given size, use the
|
||||
thumbnail method instead.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@ Pillow: a modern fork of PIL
|
|||
============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
|
||||
handbook/index.rst
|
||||
PIL
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user