/usr/share/doc/python-imaging/html/tutorial.htm

<html><head><title>Tutorial</title><link rel="stylesheet" type="text/css" href="effbot.css" /></head><body><div id="TUTORIAL-CHAPTER" class="chapter"><h1 style="chapter">Tutorial</h1><div id="USING-THE-IMAGE-CLASS-SECTION" class="sect1"><h2 style="sect1">Using the Image Class</h2><p>The most important class in the Python Imaging Library is the <a href="image.htm#image-module"><tt>Image</tt></a> 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.</p><p>To load an image from a file, use the <tt>open</tt>
function in the <tt>Image</tt> module.</p><pre>    &gt;&gt;&gt; import Image
    &gt;&gt;&gt; im = Image.open(&quot;lena.ppm&quot;)</pre><p>If successful, this function returns an <tt>Image</tt>
object. You can now use instance attributes to see what the file
really contained.</p><pre>    &gt;&gt;&gt; print im.format, im.size, im.mode
    PPM (512, 512) RGB</pre><p>The <tt>format</tt> attribute identifies the source of an
image. If the image was not read from a file, it is set to
<tt>None</tt>. The <tt>size</tt> attribute is
a 2-tuple containing width and height (in pixels).  The
<tt>mode</tt> attribute defines the number and names of the
bands in the image, and also the pixel type and depth. Common modes
are <span>&quot;L&quot;</span> (for luminance) for greyscale images,
<span>&quot;RGB&quot;</span> for true colour images, and <span>&quot;CMYK&quot;</span> for
pre-press images.</p><p>If the file cannot be opened, an <tt>IOError</tt>
exception is raised.</p><p>Once you have an instance of the <tt>Image</tt> 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:</p><pre>    &gt;&gt;&gt; im.show()</pre><p>(The standard version of <tt>show</tt> is not very
efficient, since it saves the image to a temporary file and calls the
<tt>xv</tt> utility to display the image.  If you don't have
<tt>xv</tt> installed, it won't even work.  When it does
work, it is very handy for debugging and tests, though.)</p><p>The following sections provide an overview of the different functions
provided in this library.</p></div><div id="READING-AND-WRITING-IMAGES-SECTION" class="sect1"><h2 style="sect1">Reading and Writing Images</h2><p>The Python Imaging Library supports a wide variety of image file
formats. To read files from disk, you use the <a href="image.htm#image-open-function"><tt>open</tt></a>
function in the <tt>Image</tt> 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.</p><p>To save a file, use the <a href="image.htm#image-save-method"><tt>save</tt></a> method in
the <tt>Image</tt> class. When saving files, the name
becomes important. Unless you specify the format, the library use the
filename extension to figure out which file format to use when storing
the file.</p><div class="example"><b style="example">Example: Convert files to JPEG</b><pre>import os, sys
import Image

for infile in sys.argv[1:]:
    outfile = os.path.splitext(infile)[0] + &quot;.jpg&quot;
    if infile != outfile:
        try:
            Image.open(infile).save(outfile)
        except IOError:
            print &quot;cannot convert&quot;, infile</pre></div><p>You can use a second argument to the <tt>save</tt> method
in order to explicitly specify a file format.  If you use a
non-standard extension, you must always specify the format this way:</p><div class="example"><b style="example">Example: Create JPEG Thumbnails</b><pre>import os, sys
import Image

for infile in sys.argv[1:]:
    outfile = os.path.splitext(infile)[0] + &quot;.thumbnail&quot;
    if infile != outfile:
        try:
            im = Image.open(infile)
            im.thumbnail((128, 128))
            im.save(outfile, &quot;JPEG&quot;)
        except IOError:
            print &quot;cannot create thumbnail for&quot;, infile</pre></div><p>An important detail is 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.</p><p>This also means that opening an image file is a fast operation,
independent of the file size and compression type.  Here's a simple
script to quickly identify a set of image files:</p><div class="example"><b style="example">Example: Identify Image Files</b><pre>import sys
import Image

for infile in sys.argv[1:]:
    try:
        im = Image.open(infile)
        print infile, im.format, &quot;%dx%d&quot; % im.size, im.mode
    except IOError:
        pass</pre></div></div><div id="CUTTING-PASTING-AND-MERGING-IMAGES-SECTION" class="sect1"><h2 style="sect1">Cutting, Pasting and Merging Images</h2><p>The <tt>Image</tt> class contains methods allowing you
to manipulate regions within an image. To extract a sub-rectangle from
an image, use the <a href="image.htm#image-crop-method"><tt>crop</tt></a> method.</p><div class="example"><b style="example">Example: Copying a subrectangle from an image</b><pre>    box = (100, 100, 400, 400)
    region = im.crop(box)</pre></div><p>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 300x300 pixels and nothing else.</p><p>You can now process the region in some fashion, and possibly paste it
back.</p><div class="example"><b style="example">Example: Processing a subrectangle, and pasting it back</b><pre>    region = region.transpose(Image.ROTATE_180)
    im.paste(region, box)</pre></div><p>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 <a href="tutorial.htm#colour-transforms-section"><i>Colour
Transforms</i></a> below for details).</p><p>Here's an additional example:</p><div class="example"><b style="example">Example: &quot;Rolling&quot; an image</b><pre>def roll(image, delta):
    &quot;Roll an image sideways&quot;

    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</pre></div><p>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.</p><p>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:</p><div class="example"><b style="example">Example: Splitting and merging bands</b><pre>r, g, b = im.split()
im = Image.merge(&quot;RGB&quot;, (b, g, r))</pre></div></div><div id="GEOMETRICAL-TRANSFORMS-SECTION" class="sect1"><h2 style="sect1">Geometrical Transforms</h2><p>The <tt>Image</tt> class contains methods to
<tt>resize</tt> and <tt>rotate</tt> an image.
The former takes a tuple giving the new size, the latter the angle in
degrees counter-clockwise.</p><div class="example"><b style="example">Example: Simple geometry transforms</b><pre>out = im.resize((128, 128))
out = im.rotate(45) # degrees counter-clockwise</pre></div><p>To rotate the image in full 90 degree steps, you can either use the
<tt>rotate</tt> method or the
<tt>transpose</tt> method. The latter can also be used to
flip an image around its horizontal or vertical axis.</p><div class="example"><b style="example">Example: Transposing an image</b><pre>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)</pre></div><p>There's no difference in performance or result between
<tt>transpose(ROTATE)</tt> and corresponding
<tt>rotate</tt> operations.</p><p>A more general form of image transformations can be carried out via
the <a href="image.htm#image-transform-method"><tt>transform</tt></a>
method. See the reference section for details.</p></div><div id="COLOUR-TRANSFORMS-SECTION" class="sect1"><h2 style="sect1">Colour Transforms</h2><p>The Python Imaging Library allows you to convert images between
different pixel representations using the convert function.</p><div class="example"><b style="example">Example: Converting between modes</b><pre>    im = Image.open(&quot;lena.ppm&quot;).convert(&quot;L&quot;)</pre></div><p>The library supports transformations between each supported mode and
the <span>&quot;L&quot;</span> and <span>&quot;RGB&quot;</span> modes. To convert between
other modes, you may have to use an intermediate image (typically an
<span>&quot;RGB&quot;</span> image).</p></div><div id="IMAGE-ENHANCEMENT-SECTION" class="sect1"><h2 style="sect1">Image Enhancement</h2><p>The Python Imaging Library provides a number of methods and modules
that can be used for image enhancement.</p><div class="sect2"><h3 style="sect2">Filters</h3><p>The <a href="imagefilter.htm#imagefilter-module"><tt>ImageFilter</tt></a>
module contains a number of pre-defined enhancement filters that can
be used with the <tt>filter</tt> method.</p><div class="example"><b style="example">Example: Applying filters</b><pre>import ImageFilter
out = im.filter(ImageFilter.DETAIL)</pre></div></div><div class="sect2"><h3 style="sect2">Point Operations</h3><p>The <tt>point</tt> method can be used to translate the
pixel values of an image.  This can for example be used to manipulate
the image contrast. In most cases, you can use pass this function a
function object expecting one argument.  Each pixel is processed
according to that function:</p><div class="example"><b style="example">Example: Applying point transforms</b><pre># multiply each pixel by 1.2
out = im.point(lambda i: i * 1.2)</pre></div><p>Using the above technique, you can quickly apply any simple expression
to an image.  You can also combine the <tt>point</tt> and
<tt>paste</tt> methods to selectively modify an image:</p><div class="example"><b style="example">Example: Processing individual bands</b><pre># 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 &lt; 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 &lt; 100
source[G].paste(out, None, mask)

# build a new multiband image
im = Image.merge(im.mode, source)</pre></div><p>Note the syntax used to create the mask:</p><pre>    imout = im.point(lambda i: expression and 255)</pre><p>Python only evaluates as much 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.</p></div><div class="sect2"><h3 style="sect2">Enhancement</h3><p>For more advanced image enhancement, use the classes in the <a href="imageenhance.htm#imageenhance-module"><tt>ImageEnhance</tt></a>
module.  Once created from an image, an enhancement object can be used
to quickly try out different settings.</p><p>You can adjust contrast, brightness, colour balance and sharpness in
this way.</p><div class="example"><b style="example">Example: Enhancing images</b><pre>import ImageEnhance

enh = ImageEnhance.Contrast(im)
enh.enhance(1.3).show(&quot;30% more contrast&quot;)</pre></div></div></div><div id="IMAGE-SEQUENCES-SECTION" class="sect1"><h2 style="sect1">Image Sequences</h2><p>The Python Imaging Library contains some basic support for image
sequences (also called <i>animation</i> formats).
Supported sequence formats include FLI/FLC, GIF, and a few
experimental formats. TIFF files can also contain more than one frame.</p><p>When you open a sequence file, PIL automatically loads the first frame
in the sequence.  You can use the <a href="image.htm#image-seek-method"><tt>seek</tt></a> and <a href="image.htm#image-tell-method"><tt>tell</tt></a> methods
to change which frame to work with:</p><div class="example"><b style="example">Example: Reading sequences</b><pre>import Image

im = Image.open(&quot;animation.gif&quot;)
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</pre></div><p>As seen in this example, you'll get an <tt>EOFError</tt>
exception when the sequence ends.</p><p>Note that most drivers in the current version of the library only
allows you to seek to the <i>next</i> frame (as in the
above example).  To rewind the file, you may have to reopen it.</p><p>The following iterator class lets you to use the for-statement to loop
over the sequence:</p><div class="example"><b style="example">Example: A sequence iterator class</b><pre>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...</pre></div></div><div id="POSTSCRIPT-PRINTING-SECTION" class="sect1"><h2 style="sect1">Postscript Printing</h2><p>The Python Imaging Library includes functions to print images, text
and graphics on Postscript printers.  Here's a simple example:</p><div class="example"><b style="example">Example: Drawing Postscript</b><pre>import Image
import PSDraw

im = Image.open(&quot;lena.ppm&quot;)
title = &quot;lena&quot;
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(&quot;HelveticaNarrow-Bold&quot;, 36)
w, h, b = ps.textsize(title)
ps.text((4*72-w/2, 1*72-h), title) 

ps.end_document()</pre></div></div><div id="MORE-ON-READING-IMAGES-SECTION" class="sect1"><h2 style="sect1">More on Reading Images</h2><p>As described earlier, you use the open function in the
<tt>Image</tt> module to open an image file. In most
cases, you simply pass it the filename as argument:</p><pre>im = Image.open(&quot;lena.ppm&quot;)</pre><p>If everything goes well, the result is an <tt>Image</tt>
object.  Otherwise, an <tt>IOError</tt> exception is
raised.</p><p>You can use a file-like object instead of the filename.  The file
object must implement the <tt>read</tt>,
<tt>seek</tt> and <tt>tell</tt> methods, and
be opened in binary mode.</p><div class="example"><b style="example">Example: Reading from an open file</b><pre>fp = open(&quot;lena.ppm&quot;, &quot;rb&quot;)
im = Image.open(fp)</pre></div><p>To read an image from data that you have in a string, use the
<tt>StringIO</tt> class:</p><div class="example"><b style="example">Example: Reading from a string</b><pre>import StringIO

im = Image.open(StringIO.StringIO(buffer))</pre></div><p>Note that the library rewinds the file (using
<tt>seek(0)</tt>) 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 <tt>ContainerIO</tt> or
<tt>TarIO</tt> modules to access it.</p><div class="example"><b style="example">Example: Reading from a tar archive</b><pre>import TarIO

fp = TarIO.TarIO(&quot;Imaging.tar&quot;, &quot;Imaging/test/lena.ppm&quot;)
im = Image.open(fp)</pre></div><p>See comments in these modules for details.</p><div class="sect2"><h3 style="sect2">Controlling the Decoder</h3><p>Some decoders allow you to manipulate the image while reading it from
file.  This can often be used to speed up decoding when creating
thumbnails (when speed is usually be more important than quality) and
printing to a monochrome laser printer (when only a greyscale version
of the image is needed).</p><p>The <a href="image.htm#image-draft-method"><tt>draft</tt></a> 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.</p><div class="example"><b style="example">Example: Reading in draft mode</b><pre>im = Image.open(file)
print &quot;original =&quot;, im.mode, im.size

im.draft(&quot;L&quot;, (100, 100))
print &quot;draft =&quot;, im.mode, im.size</pre></div><pre>    original = RGB (512, 512)
    draft = L (128, 128)</pre><p>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 <tt>thumbnail</tt> method instead.</p></div></div></div></body></html>
python-imaging-doc-html 1.1.2-1.1 / usr / share / doc / python-imaging / html / tutorial.htm
