<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Tutorial — Pillow (PIL Fork) 5.4.1 documentation</title>
<script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/js/script.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Concepts" href="concepts.html" />
<link rel="prev" title="Overview" href="overview.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> Pillow (PIL Fork)
</a>
<div class="version">
5.4.1
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../installation.html">Installation</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Handbook</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Tutorial</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#using-the-image-class">Using the Image class</a></li>
<li class="toctree-l3"><a class="reference internal" href="#reading-and-writing-images">Reading and writing images</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#convert-files-to-jpeg">Convert files to JPEG</a></li>
<li class="toctree-l4"><a class="reference internal" href="#create-jpeg-thumbnails">Create JPEG thumbnails</a></li>
<li class="toctree-l4"><a class="reference internal" href="#identify-image-files">Identify Image Files</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#cutting-pasting-and-merging-images">Cutting, pasting, and merging images</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#copying-a-subrectangle-from-an-image">Copying a subrectangle from an image</a></li>
<li class="toctree-l4"><a class="reference internal" href="#processing-a-subrectangle-and-pasting-it-back">Processing a subrectangle, and pasting it back</a></li>
<li class="toctree-l4"><a class="reference internal" href="#rolling-an-image">Rolling an image</a></li>
<li class="toctree-l4"><a class="reference internal" href="#splitting-and-merging-bands">Splitting and merging bands</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#geometrical-transforms">Geometrical transforms</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#simple-geometry-transforms">Simple geometry transforms</a></li>
<li class="toctree-l4"><a class="reference internal" href="#transposing-an-image">Transposing an image</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#color-transforms">Color transforms</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#converting-between-modes">Converting between modes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#image-enhancement">Image enhancement</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#filters">Filters</a></li>
<li class="toctree-l4"><a class="reference internal" href="#point-operations">Point Operations</a></li>
<li class="toctree-l4"><a class="reference internal" href="#enhancement">Enhancement</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#image-sequences">Image sequences</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#reading-sequences">Reading sequences</a></li>
<li class="toctree-l4"><a class="reference internal" href="#using-the-imagesequence-iterator-class">Using the ImageSequence Iterator class</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#postscript-printing">Postscript printing</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#drawing-postscript">Drawing Postscript</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#more-on-reading-images">More on reading images</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#reading-from-an-open-file">Reading from an open file</a></li>
<li class="toctree-l4"><a class="reference internal" href="#reading-from-a-string">Reading from a string</a></li>
<li class="toctree-l4"><a class="reference internal" href="#reading-from-a-tar-archive">Reading from a tar archive</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#controlling-the-decoder">Controlling the decoder</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#reading-in-draft-mode">Reading in draft mode</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html">Concepts</a></li>
<li class="toctree-l2"><a class="reference internal" href="appendices.html">Appendices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../porting.html">Porting</a></li>
<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/index.html">Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../deprecations.html">Deprecations and removals</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Pillow (PIL Fork)</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> »</li>
<li><a href="index.html">Handbook</a> »</li>
<li>Tutorial</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/handbook/tutorial.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="tutorial">
<h1>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline">¶</a></h1>
<div class="section" id="using-the-image-class">
<h2>Using the Image class<a class="headerlink" href="#using-the-image-class" title="Permalink to this headline">¶</a></h2>
<p>The most important class in the Python Imaging Library is the
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image" title="PIL.Image.Image"><code class="xref py py-class docutils literal notranslate"><span class="pre">Image</span></code></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 <a class="reference internal" href="../reference/Image.html#PIL.Image.open" title="PIL.Image.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function
in the <a class="reference internal" href="../reference/Image.html#module-PIL.Image" title="PIL.Image"><code class="xref py py-mod docutils literal notranslate"><span class="pre">Image</span></code></a> module:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="gp">>>> </span><span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"hopper.ppm"</span><span class="p">)</span>
</pre></div>
</div>
<p>If successful, this function returns an <a class="reference internal" href="../reference/Image.html#PIL.Image.Image" title="PIL.Image.Image"><code class="xref py py-class docutils literal notranslate"><span class="pre">Image</span></code></a> object.
You can now use instance attributes to examine the file contents:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">print_function</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">im</span><span class="o">.</span><span class="n">format</span><span class="p">,</span> <span class="n">im</span><span class="o">.</span><span class="n">size</span><span class="p">,</span> <span class="n">im</span><span class="o">.</span><span class="n">mode</span><span class="p">)</span>
<span class="go">PPM (512, 512) RGB</span>
</pre></div>
</div>
<p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">format</span></code> 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
<code class="xref py py-attr docutils literal notranslate"><span class="pre">mode</span></code> 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.</p>
<p>If the file cannot be opened, an <code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code> exception is raised.</p>
<p>Once you have an instance of the <a class="reference internal" href="../reference/Image.html#PIL.Image.Image" title="PIL.Image.Image"><code class="xref py py-class docutils literal notranslate"><span class="pre">Image</span></code></a> 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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">im</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The standard version of <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.show" title="PIL.Image.Image.show"><code class="xref py py-meth docutils literal notranslate"><span class="pre">show()</span></code></a> is not very
efficient, since it saves the image to a temporary file and calls a utility
to display the image. If you don’t have an appropriate utility installed,
it won’t even work. When it does work though, it is very handy for
debugging and tests.</p>
</div>
<p>The following sections provide an overview of the different functions provided in this library.</p>
</div>
<div class="section" id="reading-and-writing-images">
<h2>Reading and writing images<a class="headerlink" href="#reading-and-writing-images" title="Permalink to this headline">¶</a></h2>
<p>The Python Imaging Library supports a wide variety of image file formats. To
read files from disk, use the <a class="reference internal" href="../reference/Image.html#PIL.Image.open" title="PIL.Image.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function in the
<a class="reference internal" href="../reference/Image.html#module-PIL.Image" title="PIL.Image"><code class="xref py py-mod docutils literal notranslate"><span class="pre">Image</span></code></a> 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 class="reference internal" href="../reference/Image.html#PIL.Image.Image.save" title="PIL.Image.Image.save"><code class="xref py py-meth docutils literal notranslate"><span class="pre">save()</span></code></a> method of the
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image" title="PIL.Image.Image"><code class="xref py py-class docutils literal notranslate"><span class="pre">Image</span></code></a> 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.</p>
<div class="section" id="convert-files-to-jpeg">
<h3>Convert files to JPEG<a class="headerlink" href="#convert-files-to-jpeg" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">print_function</span>
<span class="kn">import</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">sys</span>
<span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="k">for</span> <span class="n">infile</span> <span class="ow">in</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">:]:</span>
<span class="n">f</span><span class="p">,</span> <span class="n">e</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">infile</span><span class="p">)</span>
<span class="n">outfile</span> <span class="o">=</span> <span class="n">f</span> <span class="o">+</span> <span class="s2">".jpg"</span>
<span class="k">if</span> <span class="n">infile</span> <span class="o">!=</span> <span class="n">outfile</span><span class="p">:</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">infile</span><span class="p">)</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">outfile</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">IOError</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"cannot convert"</span><span class="p">,</span> <span class="n">infile</span><span class="p">)</span>
</pre></div>
</div>
<p>A second argument can be supplied to the <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.save" title="PIL.Image.Image.save"><code class="xref py py-meth docutils literal notranslate"><span class="pre">save()</span></code></a>
method which explicitly specifies a file format. If you use a non-standard
extension, you must always specify the format this way:</p>
</div>
<div class="section" id="create-jpeg-thumbnails">
<h3>Create JPEG thumbnails<a class="headerlink" href="#create-jpeg-thumbnails" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">print_function</span>
<span class="kn">import</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">sys</span>
<span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="n">size</span> <span class="o">=</span> <span class="p">(</span><span class="mi">128</span><span class="p">,</span> <span class="mi">128</span><span class="p">)</span>
<span class="k">for</span> <span class="n">infile</span> <span class="ow">in</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">:]:</span>
<span class="n">outfile</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">infile</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span> <span class="o">+</span> <span class="s2">".thumbnail"</span>
<span class="k">if</span> <span class="n">infile</span> <span class="o">!=</span> <span class="n">outfile</span><span class="p">:</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">infile</span><span class="p">)</span>
<span class="n">im</span><span class="o">.</span><span class="n">thumbnail</span><span class="p">(</span><span class="n">size</span><span class="p">)</span>
<span class="n">im</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">outfile</span><span class="p">,</span> <span class="s2">"JPEG"</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">IOError</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"cannot create thumbnail for"</span><span class="p">,</span> <span class="n">infile</span><span class="p">)</span>
</pre></div>
</div>
<p>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.</p>
<p>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:</p>
</div>
<div class="section" id="identify-image-files">
<h3>Identify Image Files<a class="headerlink" href="#identify-image-files" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">print_function</span>
<span class="kn">import</span> <span class="nn">sys</span>
<span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="k">for</span> <span class="n">infile</span> <span class="ow">in</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">:]:</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">with</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">infile</span><span class="p">)</span> <span class="k">as</span> <span class="n">im</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="n">infile</span><span class="p">,</span> <span class="n">im</span><span class="o">.</span><span class="n">format</span><span class="p">,</span> <span class="s2">"</span><span class="si">%d</span><span class="s2">x</span><span class="si">%d</span><span class="s2">"</span> <span class="o">%</span> <span class="n">im</span><span class="o">.</span><span class="n">size</span><span class="p">,</span> <span class="n">im</span><span class="o">.</span><span class="n">mode</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">IOError</span><span class="p">:</span>
<span class="k">pass</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="cutting-pasting-and-merging-images">
<h2>Cutting, pasting, and merging images<a class="headerlink" href="#cutting-pasting-and-merging-images" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="../reference/Image.html#PIL.Image.Image" title="PIL.Image.Image"><code class="xref py py-class docutils literal notranslate"><span class="pre">Image</span></code></a> class contains methods allowing you to
manipulate regions within an image. To extract a sub-rectangle from an image,
use the <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.crop" title="PIL.Image.Image.crop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">crop()</span></code></a> method.</p>
<div class="section" id="copying-a-subrectangle-from-an-image">
<h3>Copying a subrectangle from an image<a class="headerlink" href="#copying-a-subrectangle-from-an-image" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">box</span> <span class="o">=</span> <span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="mi">100</span><span class="p">,</span> <span class="mi">400</span><span class="p">,</span> <span class="mi">400</span><span class="p">)</span>
<span class="n">region</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">crop</span><span class="p">(</span><span class="n">box</span><span class="p">)</span>
</pre></div>
</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 exactly 300x300 pixels.</p>
<p>The region could now be processed in a certain manner and pasted back.</p>
</div>
<div class="section" id="processing-a-subrectangle-and-pasting-it-back">
<h3>Processing a subrectangle, and pasting it back<a class="headerlink" href="#processing-a-subrectangle-and-pasting-it-back" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">region</span> <span class="o">=</span> <span class="n">region</span><span class="o">.</span><span class="n">transpose</span><span class="p">(</span><span class="n">Image</span><span class="o">.</span><span class="n">ROTATE_180</span><span class="p">)</span>
<span class="n">im</span><span class="o">.</span><span class="n">paste</span><span class="p">(</span><span class="n">region</span><span class="p">,</span> <span class="n">box</span><span class="p">)</span>
</pre></div>
</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 class="reference internal" href="#color-transforms"><span class="std std-ref">Color transforms</span></a> below for details).</p>
<p>Here’s an additional example:</p>
</div>
<div class="section" id="rolling-an-image">
<h3>Rolling an image<a class="headerlink" href="#rolling-an-image" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">roll</span><span class="p">(</span><span class="n">image</span><span class="p">,</span> <span class="n">delta</span><span class="p">):</span>
<span class="sd">"""Roll an image sideways."""</span>
<span class="n">xsize</span><span class="p">,</span> <span class="n">ysize</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="n">size</span>
<span class="n">delta</span> <span class="o">=</span> <span class="n">delta</span> <span class="o">%</span> <span class="n">xsize</span>
<span class="k">if</span> <span class="n">delta</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span> <span class="k">return</span> <span class="n">image</span>
<span class="n">part1</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="n">crop</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">delta</span><span class="p">,</span> <span class="n">ysize</span><span class="p">))</span>
<span class="n">part2</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="n">crop</span><span class="p">((</span><span class="n">delta</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">xsize</span><span class="p">,</span> <span class="n">ysize</span><span class="p">))</span>
<span class="n">image</span><span class="o">.</span><span class="n">paste</span><span class="p">(</span><span class="n">part1</span><span class="p">,</span> <span class="p">(</span><span class="n">xsize</span><span class="o">-</span><span class="n">delta</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">xsize</span><span class="p">,</span> <span class="n">ysize</span><span class="p">))</span>
<span class="n">image</span><span class="o">.</span><span class="n">paste</span><span class="p">(</span><span class="n">part2</span><span class="p">,</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">xsize</span><span class="o">-</span><span class="n">delta</span><span class="p">,</span> <span class="n">ysize</span><span class="p">))</span>
<span class="k">return</span> <span class="n">image</span>
</pre></div>
</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. For example, pasting an
RGBA image and also using it as the mask would paste the opaque portion
of the image but not its transparent background.</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>
<div class="section" id="splitting-and-merging-bands">
<h3>Splitting and merging bands<a class="headerlink" href="#splitting-and-merging-bands" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">r</span><span class="p">,</span> <span class="n">g</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="s2">"RGB"</span><span class="p">,</span> <span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">g</span><span class="p">,</span> <span class="n">r</span><span class="p">))</span>
</pre></div>
</div>
<p>Note that for a single-band image, <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.split" title="PIL.Image.Image.split"><code class="xref py py-meth docutils literal notranslate"><span class="pre">split()</span></code></a> returns
the image itself. To work with individual color bands, you may want to convert
the image to “RGB” first.</p>
</div>
</div>
<div class="section" id="geometrical-transforms">
<h2>Geometrical transforms<a class="headerlink" href="#geometrical-transforms" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="../reference/Image.html#PIL.Image.Image" title="PIL.Image.Image"><code class="xref py py-class docutils literal notranslate"><span class="pre">PIL.Image.Image</span></code></a> class contains methods to
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image.resize" title="PIL.Image.Image.resize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">resize()</span></code></a> and <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.rotate" title="PIL.Image.Image.rotate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rotate()</span></code></a> an
image. The former takes a tuple giving the new size, the latter the angle in
degrees counter-clockwise.</p>
<div class="section" id="simple-geometry-transforms">
<h3>Simple geometry transforms<a class="headerlink" href="#simple-geometry-transforms" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">resize</span><span class="p">((</span><span class="mi">128</span><span class="p">,</span> <span class="mi">128</span><span class="p">))</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">rotate</span><span class="p">(</span><span class="mi">45</span><span class="p">)</span> <span class="c1"># degrees counter-clockwise</span>
</pre></div>
</div>
<p>To rotate the image in 90 degree steps, you can either use the
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image.rotate" title="PIL.Image.Image.rotate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rotate()</span></code></a> method or the
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image.transpose" title="PIL.Image.Image.transpose"><code class="xref py py-meth docutils literal notranslate"><span class="pre">transpose()</span></code></a> method. The latter can also be used to
flip an image around its horizontal or vertical axis.</p>
</div>
<div class="section" id="transposing-an-image">
<h3>Transposing an image<a class="headerlink" href="#transposing-an-image" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">transpose</span><span class="p">(</span><span class="n">Image</span><span class="o">.</span><span class="n">FLIP_LEFT_RIGHT</span><span class="p">)</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">transpose</span><span class="p">(</span><span class="n">Image</span><span class="o">.</span><span class="n">FLIP_TOP_BOTTOM</span><span class="p">)</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">transpose</span><span class="p">(</span><span class="n">Image</span><span class="o">.</span><span class="n">ROTATE_90</span><span class="p">)</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">transpose</span><span class="p">(</span><span class="n">Image</span><span class="o">.</span><span class="n">ROTATE_180</span><span class="p">)</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">transpose</span><span class="p">(</span><span class="n">Image</span><span class="o">.</span><span class="n">ROTATE_270</span><span class="p">)</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">transpose(ROTATE)</span></code> operations can also be performed identically with
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image.rotate" title="PIL.Image.Image.rotate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rotate()</span></code></a> operations, provided the <cite>expand</cite> flag is
true, to provide for the same changes to the image’s size.</p>
<p>A more general form of image transformations can be carried out via the
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image.transform" title="PIL.Image.Image.transform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">transform()</span></code></a> method.</p>
</div>
</div>
<div class="section" id="color-transforms">
<span id="id1"></span><h2>Color transforms<a class="headerlink" href="#color-transforms" title="Permalink to this headline">¶</a></h2>
<p>The Python Imaging Library allows you to convert images between different pixel
representations using the <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.convert" title="PIL.Image.Image.convert"><code class="xref py py-meth docutils literal notranslate"><span class="pre">convert()</span></code></a> method.</p>
<div class="section" id="converting-between-modes">
<h3>Converting between modes<a class="headerlink" href="#converting-between-modes" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"hopper.ppm"</span><span class="p">)</span><span class="o">.</span><span class="n">convert</span><span class="p">(</span><span class="s2">"L"</span><span class="p">)</span>
</pre></div>
</div>
<p>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).</p>
</div>
</div>
<div class="section" id="image-enhancement">
<h2>Image enhancement<a class="headerlink" href="#image-enhancement" title="Permalink to this headline">¶</a></h2>
<p>The Python Imaging Library provides a number of methods and modules that can be
used to enhance images.</p>
<div class="section" id="filters">
<h3>Filters<a class="headerlink" href="#filters" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="../reference/ImageFilter.html#module-PIL.ImageFilter" title="PIL.ImageFilter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ImageFilter</span></code></a> module contains a number of pre-defined
enhancement filters that can be used with the
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image.filter" title="PIL.Image.Image.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filter()</span></code></a> method.</p>
<div class="section" id="applying-filters">
<h4>Applying filters<a class="headerlink" href="#applying-filters" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">ImageFilter</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">ImageFilter</span><span class="o">.</span><span class="n">DETAIL</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="point-operations">
<h3>Point Operations<a class="headerlink" href="#point-operations" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.point" title="PIL.Image.Image.point"><code class="xref py py-meth docutils literal notranslate"><span class="pre">point()</span></code></a> 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 this method. Each
pixel is processed according to that function:</p>
<div class="section" id="applying-point-transforms">
<h4>Applying point transforms<a class="headerlink" href="#applying-point-transforms" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># multiply each pixel by 1.2</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">point</span><span class="p">(</span><span class="k">lambda</span> <span class="n">i</span><span class="p">:</span> <span class="n">i</span> <span class="o">*</span> <span class="mf">1.2</span><span class="p">)</span>
</pre></div>
</div>
<p>Using the above technique, you can quickly apply any simple expression to an
image. You can also combine the <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.point" title="PIL.Image.Image.point"><code class="xref py py-meth docutils literal notranslate"><span class="pre">point()</span></code></a> and
<a class="reference internal" href="../reference/Image.html#PIL.Image.Image.paste" title="PIL.Image.Image.paste"><code class="xref py py-meth docutils literal notranslate"><span class="pre">paste()</span></code></a> methods to selectively modify an image:</p>
</div>
<div class="section" id="processing-individual-bands">
<h4>Processing individual bands<a class="headerlink" href="#processing-individual-bands" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># split the image into individual bands</span>
<span class="n">source</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
<span class="n">R</span><span class="p">,</span> <span class="n">G</span><span class="p">,</span> <span class="n">B</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span>
<span class="c1"># select regions where red is less than 100</span>
<span class="n">mask</span> <span class="o">=</span> <span class="n">source</span><span class="p">[</span><span class="n">R</span><span class="p">]</span><span class="o">.</span><span class="n">point</span><span class="p">(</span><span class="k">lambda</span> <span class="n">i</span><span class="p">:</span> <span class="n">i</span> <span class="o"><</span> <span class="mi">100</span> <span class="ow">and</span> <span class="mi">255</span><span class="p">)</span>
<span class="c1"># process the green band</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">source</span><span class="p">[</span><span class="n">G</span><span class="p">]</span><span class="o">.</span><span class="n">point</span><span class="p">(</span><span class="k">lambda</span> <span class="n">i</span><span class="p">:</span> <span class="n">i</span> <span class="o">*</span> <span class="mf">0.7</span><span class="p">)</span>
<span class="c1"># paste the processed band back, but only where red was < 100</span>
<span class="n">source</span><span class="p">[</span><span class="n">G</span><span class="p">]</span><span class="o">.</span><span class="n">paste</span><span class="p">(</span><span class="n">out</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="n">mask</span><span class="p">)</span>
<span class="c1"># build a new multiband image</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="n">im</span><span class="o">.</span><span class="n">mode</span><span class="p">,</span> <span class="n">source</span><span class="p">)</span>
</pre></div>
</div>
<p>Note the syntax used to create the mask:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">imout</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">point</span><span class="p">(</span><span class="k">lambda</span> <span class="n">i</span><span class="p">:</span> <span class="n">expression</span> <span class="ow">and</span> <span class="mi">255</span><span class="p">)</span>
</pre></div>
</div>
<p>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.</p>
</div>
</div>
<div class="section" id="enhancement">
<h3>Enhancement<a class="headerlink" href="#enhancement" title="Permalink to this headline">¶</a></h3>
<p>For more advanced image enhancement, you can use the classes in the
<a class="reference internal" href="../reference/ImageEnhance.html#module-PIL.ImageEnhance" title="PIL.ImageEnhance"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ImageEnhance</span></code></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, color balance and sharpness in this way.</p>
<div class="section" id="enhancing-images">
<h4>Enhancing images<a class="headerlink" href="#enhancing-images" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">ImageEnhance</span>
<span class="n">enh</span> <span class="o">=</span> <span class="n">ImageEnhance</span><span class="o">.</span><span class="n">Contrast</span><span class="p">(</span><span class="n">im</span><span class="p">)</span>
<span class="n">enh</span><span class="o">.</span><span class="n">enhance</span><span class="p">(</span><span class="mf">1.3</span><span class="p">)</span><span class="o">.</span><span class="n">show</span><span class="p">(</span><span class="s2">"30% more contrast"</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="image-sequences">
<h2>Image sequences<a class="headerlink" href="#image-sequences" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>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:</p>
<div class="section" id="reading-sequences">
<h3>Reading sequences<a class="headerlink" href="#reading-sequences" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"animation.gif"</span><span class="p">)</span>
<span class="n">im</span><span class="o">.</span><span class="n">seek</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="c1"># skip to the second frame</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">while</span> <span class="mi">1</span><span class="p">:</span>
<span class="n">im</span><span class="o">.</span><span class="n">seek</span><span class="p">(</span><span class="n">im</span><span class="o">.</span><span class="n">tell</span><span class="p">()</span><span class="o">+</span><span class="mi">1</span><span class="p">)</span>
<span class="c1"># do something to im</span>
<span class="k">except</span> <span class="ne">EOFError</span><span class="p">:</span>
<span class="k">pass</span> <span class="c1"># end of sequence</span>
</pre></div>
</div>
<p>As seen in this example, you’ll get an <code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code> exception when the
sequence ends.</p>
<p>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.</p>
<p>The following class lets you use the for-statement to loop over the sequence:</p>
</div>
<div class="section" id="using-the-imagesequence-iterator-class">
<h3>Using the ImageSequence Iterator class<a class="headerlink" href="#using-the-imagesequence-iterator-class" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">ImageSequence</span>
<span class="k">for</span> <span class="n">frame</span> <span class="ow">in</span> <span class="n">ImageSequence</span><span class="o">.</span><span class="n">Iterator</span><span class="p">(</span><span class="n">im</span><span class="p">):</span>
<span class="c1"># ...do something to frame...</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="postscript-printing">
<h2>Postscript printing<a class="headerlink" href="#postscript-printing" title="Permalink to this headline">¶</a></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="section" id="drawing-postscript">
<h3>Drawing Postscript<a class="headerlink" href="#drawing-postscript" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">PSDraw</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"hopper.ppm"</span><span class="p">)</span>
<span class="n">title</span> <span class="o">=</span> <span class="s2">"hopper"</span>
<span class="n">box</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="o">*</span><span class="mi">72</span><span class="p">,</span> <span class="mi">2</span><span class="o">*</span><span class="mi">72</span><span class="p">,</span> <span class="mi">7</span><span class="o">*</span><span class="mi">72</span><span class="p">,</span> <span class="mi">10</span><span class="o">*</span><span class="mi">72</span><span class="p">)</span> <span class="c1"># in points</span>
<span class="n">ps</span> <span class="o">=</span> <span class="n">PSDraw</span><span class="o">.</span><span class="n">PSDraw</span><span class="p">()</span> <span class="c1"># default is sys.stdout</span>
<span class="n">ps</span><span class="o">.</span><span class="n">begin_document</span><span class="p">(</span><span class="n">title</span><span class="p">)</span>
<span class="c1"># draw the image (75 dpi)</span>
<span class="n">ps</span><span class="o">.</span><span class="n">image</span><span class="p">(</span><span class="n">box</span><span class="p">,</span> <span class="n">im</span><span class="p">,</span> <span class="mi">75</span><span class="p">)</span>
<span class="n">ps</span><span class="o">.</span><span class="n">rectangle</span><span class="p">(</span><span class="n">box</span><span class="p">)</span>
<span class="c1"># draw title</span>
<span class="n">ps</span><span class="o">.</span><span class="n">setfont</span><span class="p">(</span><span class="s2">"HelveticaNarrow-Bold"</span><span class="p">,</span> <span class="mi">36</span><span class="p">)</span>
<span class="n">ps</span><span class="o">.</span><span class="n">text</span><span class="p">((</span><span class="mi">3</span><span class="o">*</span><span class="mi">72</span><span class="p">,</span> <span class="mi">4</span><span class="o">*</span><span class="mi">72</span><span class="p">),</span> <span class="n">title</span><span class="p">)</span>
<span class="n">ps</span><span class="o">.</span><span class="n">end_document</span><span class="p">()</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="more-on-reading-images">
<h2>More on reading images<a class="headerlink" href="#more-on-reading-images" title="Permalink to this headline">¶</a></h2>
<p>As described earlier, the <a class="reference internal" href="../reference/Image.html#PIL.Image.open" title="PIL.Image.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function of the
<a class="reference internal" href="../reference/Image.html#module-PIL.Image" title="PIL.Image"><code class="xref py py-mod docutils literal notranslate"><span class="pre">Image</span></code></a> module is used to open an image file. In most cases, you
simply pass it the filename as an argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"hopper.ppm"</span><span class="p">)</span>
</pre></div>
</div>
<p>If everything goes well, the result is an <a class="reference internal" href="../reference/Image.html#PIL.Image.Image" title="PIL.Image.Image"><code class="xref py py-class docutils literal notranslate"><span class="pre">PIL.Image.Image</span></code></a> object.
Otherwise, an <code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code> exception is raised.</p>
<p>You can use a file-like object instead of the filename. The object must
implement <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">seek()</span></code> and
<code class="xref py py-meth docutils literal notranslate"><span class="pre">tell()</span></code> methods, and be opened in binary mode.</p>
<div class="section" id="reading-from-an-open-file">
<h3>Reading from an open file<a class="headerlink" href="#reading-from-an-open-file" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"hopper.ppm"</span><span class="p">,</span> <span class="s2">"rb"</span><span class="p">)</span> <span class="k">as</span> <span class="n">fp</span><span class="p">:</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">fp</span><span class="p">)</span>
</pre></div>
</div>
<p>To read an image from string data, use the <code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code>
class:</p>
</div>
<div class="section" id="reading-from-a-string">
<h3>Reading from a string<a class="headerlink" href="#reading-from-a-string" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">StringIO</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">StringIO</span><span class="o">.</span><span class="n">StringIO</span><span class="p">(</span><span class="n">buffer</span><span class="p">))</span>
</pre></div>
</div>
<p>Note that the library rewinds the file (using <code class="docutils literal notranslate"><span class="pre">seek(0)</span></code>) 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 <a class="reference internal" href="../PIL.html#module-PIL.ContainerIO" title="PIL.ContainerIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContainerIO</span></code></a> or
<a class="reference internal" href="../PIL.html#module-PIL.TarIO" title="PIL.TarIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarIO</span></code></a> modules to access it.</p>
</div>
<div class="section" id="reading-from-a-tar-archive">
<h3>Reading from a tar archive<a class="headerlink" href="#reading-from-a-tar-archive" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span><span class="p">,</span> <span class="n">TarIO</span>
<span class="n">fp</span> <span class="o">=</span> <span class="n">TarIO</span><span class="o">.</span><span class="n">TarIO</span><span class="p">(</span><span class="s2">"Tests/images/hopper.tar"</span><span class="p">,</span> <span class="s2">"hopper.jpg"</span><span class="p">)</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">fp</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="controlling-the-decoder">
<h2>Controlling the decoder<a class="headerlink" href="#controlling-the-decoder" title="Permalink to this headline">¶</a></h2>
<p>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).</p>
<p>The <a class="reference internal" href="../reference/Image.html#PIL.Image.Image.draft" title="PIL.Image.Image.draft"><code class="xref py py-meth docutils literal notranslate"><span class="pre">draft()</span></code></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="section" id="reading-in-draft-mode">
<h3>Reading in draft mode<a class="headerlink" href="#reading-in-draft-mode" title="Permalink to this headline">¶</a></h3>
<p>This is only available for JPEG and MPO files.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PIL</span> <span class="k">import</span> <span class="n">Image</span>
<span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">print_function</span>
<span class="n">im</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">file</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"original ="</span><span class="p">,</span> <span class="n">im</span><span class="o">.</span><span class="n">mode</span><span class="p">,</span> <span class="n">im</span><span class="o">.</span><span class="n">size</span><span class="p">)</span>
<span class="n">im</span><span class="o">.</span><span class="n">draft</span><span class="p">(</span><span class="s2">"L"</span><span class="p">,</span> <span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="mi">100</span><span class="p">))</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"draft ="</span><span class="p">,</span> <span class="n">im</span><span class="o">.</span><span class="n">mode</span><span class="p">,</span> <span class="n">im</span><span class="o">.</span><span class="n">size</span><span class="p">)</span>
</pre></div>
</div>
<p>This prints something like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">original</span> <span class="o">=</span> <span class="n">RGB</span> <span class="p">(</span><span class="mi">512</span><span class="p">,</span> <span class="mi">512</span><span class="p">)</span>
<span class="n">draft</span> <span class="o">=</span> <span class="n">L</span> <span class="p">(</span><span class="mi">128</span><span class="p">,</span> <span class="mi">128</span><span class="p">)</span>
</pre></div>
</div>
<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
thumbnail method instead.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="concepts.html" class="btn btn-neutral float-right" title="Concepts" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="overview.html" class="btn btn-neutral float-left" title="Overview" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 1995-2011 Fredrik Lundh, 2010-2018 Alex Clark and Contributors
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
