<!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>Writing Your Own Image Plugin — 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="Reference" href="../reference/index.html" />
<link rel="prev" title="Image file formats" href="image-file-formats.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"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html">Concepts</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="appendices.html">Appendices</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="image-file-formats.html">Image file formats</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Writing Your Own Image Plugin</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#example">Example</a></li>
<li class="toctree-l4"><a class="reference internal" href="#the-tile-attribute">The <code class="docutils literal notranslate"><span class="pre">tile</span></code> attribute</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#decoders">Decoders</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#the-raw-decoder">The raw decoder</a></li>
<li class="toctree-l4"><a class="reference internal" href="#decoding-floating-point-data">Decoding floating point data</a></li>
<li class="toctree-l4"><a class="reference internal" href="#the-bit-decoder">The bit decoder</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#writing-your-own-file-decoder-in-c">Writing Your Own File Decoder in C</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#setup">Setup</a></li>
<li class="toctree-l4"><a class="reference internal" href="#decoding">Decoding</a></li>
<li class="toctree-l4"><a class="reference internal" href="#cleanup">Cleanup</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#writing-your-own-file-decoder-in-python">Writing Your Own File Decoder in Python</a></li>
</ul>
</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><a href="appendices.html">Appendices</a> »</li>
<li>Writing Your Own Image Plugin</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/handbook/writing-your-own-file-decoder.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="writing-your-own-image-plugin">
<span id="image-plugins"></span><h1>Writing Your Own Image Plugin<a class="headerlink" href="#writing-your-own-image-plugin" title="Permalink to this headline">¶</a></h1>
<p>The Pillow uses a plug-in model which allows you to add your own
decoders to the library, without any changes to the library
itself. Such plug-ins usually have names like
<code class="file docutils literal notranslate"><span class="pre">XxxImagePlugin.py</span></code>, where <code class="docutils literal notranslate"><span class="pre">Xxx</span></code> is a unique format name
(usually an abbreviation).</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Pillow >= 2.1.0 no longer automatically imports any file
in the Python path with a name ending in
<code class="file docutils literal notranslate"><span class="pre">ImagePlugin.py</span></code>. You will need to import your
image plugin manually.</p>
</div>
<p>Pillow decodes files in 2 stages:</p>
<ol class="arabic simple">
<li>It loops over the available image plugins in the loaded order, and
calls the plugin’s <code class="docutils literal notranslate"><span class="pre">accept</span></code> function with the first 16 bytes of
the file. If the <code class="docutils literal notranslate"><span class="pre">accept</span></code> function returns true, the plugin’s
<code class="docutils literal notranslate"><span class="pre">_open</span></code> method is called to set up the image metadata and image
tiles. The <code class="docutils literal notranslate"><span class="pre">_open</span></code> method is not for decoding the actual image
data.</li>
<li>When the image data is requested, the <code class="docutils literal notranslate"><span class="pre">ImageFile.load</span></code> method is
called, which sets up a decoder for each tile and feeds the data to
it.</li>
</ol>
<p>An image plug-in should contain a format handler derived from the
<code class="xref py py-class docutils literal notranslate"><span class="pre">PIL.ImageFile.ImageFile</span></code> base class. This class should
provide an <code class="xref py py-meth docutils literal notranslate"><span class="pre">_open()</span></code> method, which reads the file header and
sets up at least the <code class="xref py py-attr docutils literal notranslate"><span class="pre">mode</span></code> and
<code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code> attributes. To be able to load the
file, the method must also create a list of <code class="xref py py-attr docutils literal notranslate"><span class="pre">tile</span></code>
descriptors, which contain a decoder name, extents of the tile, and
any decoder-specific data. The format handler class must be explicitly
registered, via a call to 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="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For performance reasons, it is important that the
<code class="xref py py-meth docutils literal notranslate"><span class="pre">_open()</span></code> method quickly rejects files that do not have the
appropriate contents.</p>
</div>
<div class="section" id="example">
<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<p>The following plug-in supports a simple format, which has a 128-byte header
consisting of the words “SPAM” followed by the width, height, and pixel size in
bits. The header fields are separated by spaces. The image data follows
directly after the header, and can be either bi-level, greyscale, or 24-bit
true color.</p>
<p><strong>SpamImagePlugin.py</strong>:</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="p">,</span> <span class="n">ImageFile</span>
<span class="kn">import</span> <span class="nn">string</span>
<span class="k">class</span> <span class="nc">SpamImageFile</span><span class="p">(</span><span class="n">ImageFile</span><span class="o">.</span><span class="n">ImageFile</span><span class="p">):</span>
<span class="nb">format</span> <span class="o">=</span> <span class="s2">"SPAM"</span>
<span class="n">format_description</span> <span class="o">=</span> <span class="s2">"Spam raster image"</span>
<span class="k">def</span> <span class="nf">_open</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># check header</span>
<span class="n">header</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">fp</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">128</span><span class="p">)</span>
<span class="k">if</span> <span class="n">header</span><span class="p">[:</span><span class="mi">4</span><span class="p">]</span> <span class="o">!=</span> <span class="s2">"SPAM"</span><span class="p">:</span>
<span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">,</span> <span class="s2">"not a SPAM file"</span>
<span class="n">header</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">header</span><span class="p">)</span>
<span class="c1"># size in pixels (width, height)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_size</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">header</span><span class="p">[</span><span class="mi">1</span><span class="p">]),</span> <span class="nb">int</span><span class="p">(</span><span class="n">header</span><span class="p">[</span><span class="mi">2</span><span class="p">])</span>
<span class="c1"># mode setting</span>
<span class="n">bits</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">header</span><span class="p">[</span><span class="mi">3</span><span class="p">])</span>
<span class="k">if</span> <span class="n">bits</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">mode</span> <span class="o">=</span> <span class="s2">"1"</span>
<span class="k">elif</span> <span class="n">bits</span> <span class="o">==</span> <span class="mi">8</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">mode</span> <span class="o">=</span> <span class="s2">"L"</span>
<span class="k">elif</span> <span class="n">bits</span> <span class="o">==</span> <span class="mi">24</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">mode</span> <span class="o">=</span> <span class="s2">"RGB"</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">,</span> <span class="s2">"unknown number of bits"</span>
<span class="c1"># data descriptor</span>
<span class="bp">self</span><span class="o">.</span><span class="n">tile</span> <span class="o">=</span> <span class="p">[</span>
<span class="p">(</span><span class="s2">"raw"</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="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">size</span><span class="p">,</span> <span class="mi">128</span><span class="p">,</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">mode</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">))</span>
<span class="p">]</span>
<span class="n">Image</span><span class="o">.</span><span class="n">register_open</span><span class="p">(</span><span class="n">SpamImageFile</span><span class="o">.</span><span class="n">format</span><span class="p">,</span> <span class="n">SpamImageFile</span><span class="p">)</span>
<span class="n">Image</span><span class="o">.</span><span class="n">register_extension</span><span class="p">(</span><span class="n">SpamImageFile</span><span class="o">.</span><span class="n">format</span><span class="p">,</span> <span class="s2">".spam"</span><span class="p">)</span>
<span class="n">Image</span><span class="o">.</span><span class="n">register_extension</span><span class="p">(</span><span class="n">SpamImageFile</span><span class="o">.</span><span class="n">format</span><span class="p">,</span> <span class="s2">".spa"</span><span class="p">)</span> <span class="c1"># dos version</span>
</pre></div>
</div>
<p>The format handler must always set the
<code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">mode</span></code>
attributes. If these are not set, the file cannot be opened. To
simplify the plugin, the calling code considers exceptions like
<code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code>, <code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code>, <code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code>,
<code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code> and <code class="xref py py-exc docutils literal notranslate"><span class="pre">struct.error</span></code> as a failure to identify
the file.</p>
<p>Note that the image plugin must be explicitly registered using
<a class="reference internal" href="../reference/Image.html#PIL.Image.register_open" title="PIL.Image.register_open"><code class="xref py py-func docutils literal notranslate"><span class="pre">PIL.Image.register_open()</span></code></a>. Although not required, it is also a good
idea to register any extensions used by this format.</p>
</div>
<div class="section" id="the-tile-attribute">
<h2>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">tile</span></code> attribute<a class="headerlink" href="#the-tile-attribute" title="Permalink to this headline">¶</a></h2>
<p>To be able to read the file as well as just identifying it, the <code class="xref py py-attr docutils literal notranslate"><span class="pre">tile</span></code>
attribute must also be set. This attribute consists of a list of tile
descriptors, where each descriptor specifies how data should be loaded to a
given region in the image. In most cases, only a single descriptor is used,
covering the full image.</p>
<p>The tile descriptor is a 4-tuple with the following contents:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">decoder</span><span class="p">,</span> <span class="n">region</span><span class="p">,</span> <span class="n">offset</span><span class="p">,</span> <span class="n">parameters</span><span class="p">)</span>
</pre></div>
</div>
<p>The fields are used as follows:</p>
<dl class="docutils">
<dt><strong>decoder</strong></dt>
<dd>Specifies which decoder to use. The <code class="docutils literal notranslate"><span class="pre">raw</span></code> decoder used here supports
uncompressed data, in a variety of pixel formats. For more information on
this decoder, see the description below.</dd>
<dt><strong>region</strong></dt>
<dd>A 4-tuple specifying where to store data in the image.</dd>
<dt><strong>offset</strong></dt>
<dd>Byte offset from the beginning of the file to image data.</dd>
<dt><strong>parameters</strong></dt>
<dd>Parameters to the decoder. The contents of this field depends on the
decoder specified by the first field in the tile descriptor tuple. If the
decoder doesn’t need any parameters, use None for this field.</dd>
</dl>
<p>Note that the <code class="xref py py-attr docutils literal notranslate"><span class="pre">tile</span></code> attribute contains a list of tile descriptors,
not just a single descriptor.</p>
</div>
</div>
<div class="section" id="decoders">
<h1>Decoders<a class="headerlink" href="#decoders" title="Permalink to this headline">¶</a></h1>
<div class="section" id="the-raw-decoder">
<h2>The raw decoder<a class="headerlink" href="#the-raw-decoder" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">raw</span></code> decoder is used to read uncompressed data from an image file. It
can be used with most uncompressed file formats, such as PPM, BMP, uncompressed
TIFF, and many others. To use the raw decoder with the
<a class="reference internal" href="../reference/Image.html#PIL.Image.frombytes" title="PIL.Image.frombytes"><code class="xref py py-func docutils literal notranslate"><span class="pre">PIL.Image.frombytes()</span></code></a> function, use the following syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">image</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">frombytes</span><span class="p">(</span>
<span class="n">mode</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="s2">"raw"</span><span class="p">,</span>
<span class="n">raw</span> <span class="n">mode</span><span class="p">,</span> <span class="n">stride</span><span class="p">,</span> <span class="n">orientation</span>
<span class="p">)</span>
</pre></div>
</div>
<p>When used in a tile descriptor, the parameter field should look like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">raw</span> <span class="n">mode</span><span class="p">,</span> <span class="n">stride</span><span class="p">,</span> <span class="n">orientation</span><span class="p">)</span>
</pre></div>
</div>
<p>The fields are used as follows:</p>
<dl class="docutils">
<dt><strong>raw mode</strong></dt>
<dd>The pixel layout used in the file, and is used to properly convert data to
PIL’s internal layout. For a summary of the available formats, see the
table below.</dd>
<dt><strong>stride</strong></dt>
<dd>The distance in bytes between two consecutive lines in the image. If 0, the
image is assumed to be packed (no padding between lines). If omitted, the
stride defaults to 0.</dd>
<dt><strong>orientation</strong></dt>
<dd>Whether the first line in the image is the top line on the screen (1), or
the bottom line (-1). If omitted, the orientation defaults to 1.</dd>
</dl>
<p>The <strong>raw mode</strong> field is used to determine how the data should be unpacked to
match PIL’s internal pixel layout. PIL supports a large set of raw modes; for a
complete list, see the table in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">Unpack.c</span></code> module. The following
table describes some commonly used <strong>raw modes</strong>:</p>
<table border="1" class="docutils">
<colgroup>
<col width="14%" />
<col width="86%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">mode</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">1</span></code></td>
<td>1-bit bilevel, stored with the leftmost pixel in the most
significant bit. 0 means black, 1 means white.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">1;I</span></code></td>
<td>1-bit inverted bilevel, stored with the leftmost pixel in the
most significant bit. 0 means white, 1 means black.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">1;R</span></code></td>
<td>1-bit reversed bilevel, stored with the leftmost pixel in the
least significant bit. 0 means black, 1 means white.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">L</span></code></td>
<td>8-bit greyscale. 0 means black, 255 means white.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">L;I</span></code></td>
<td>8-bit inverted greyscale. 0 means white, 255 means black.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">P</span></code></td>
<td>8-bit palette-mapped image.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">RGB</span></code></td>
<td>24-bit true colour, stored as (red, green, blue).</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">BGR</span></code></td>
<td>24-bit true colour, stored as (blue, green, red).</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">RGBX</span></code></td>
<td>24-bit true colour, stored as (red, green, blue, pad).</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">RGB;L</span></code></td>
<td>24-bit true colour, line interleaved (first all red pixels, then
all green pixels, finally all blue pixels).</td>
</tr>
</tbody>
</table>
<p>Note that for the most common cases, the raw mode is simply the same as the mode.</p>
<p>The Python Imaging Library supports many other decoders, including JPEG, PNG,
and PackBits. For details, see the <code class="file docutils literal notranslate"><span class="pre">decode.c</span></code> source file, and the
standard plug-in implementations provided with the library.</p>
</div>
<div class="section" id="decoding-floating-point-data">
<h2>Decoding floating point data<a class="headerlink" href="#decoding-floating-point-data" title="Permalink to this headline">¶</a></h2>
<p>PIL provides some special mechanisms to allow you to load a wide variety of
formats into a mode <code class="docutils literal notranslate"><span class="pre">F</span></code> (floating point) image memory.</p>
<p>You can use the <code class="docutils literal notranslate"><span class="pre">raw</span></code> decoder to read images where data is packed in any
standard machine data type, using one of the following raw modes:</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="76%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">mode</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F</span></code></td>
<td>32-bit native floating point.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;8</span></code></td>
<td>8-bit unsigned integer.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;8S</span></code></td>
<td>8-bit signed integer.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;16</span></code></td>
<td>16-bit little endian unsigned integer.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;16S</span></code></td>
<td>16-bit little endian signed integer.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;16B</span></code></td>
<td>16-bit big endian unsigned integer.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;16BS</span></code></td>
<td>16-bit big endian signed integer.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;16N</span></code></td>
<td>16-bit native unsigned integer.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;16NS</span></code></td>
<td>16-bit native signed integer.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;32</span></code></td>
<td>32-bit little endian unsigned integer.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;32S</span></code></td>
<td>32-bit little endian signed integer.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;32B</span></code></td>
<td>32-bit big endian unsigned integer.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;32BS</span></code></td>
<td>32-bit big endian signed integer.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;32N</span></code></td>
<td>32-bit native unsigned integer.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;32NS</span></code></td>
<td>32-bit native signed integer.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;32F</span></code></td>
<td>32-bit little endian floating point.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;32BF</span></code></td>
<td>32-bit big endian floating point.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;32NF</span></code></td>
<td>32-bit native floating point.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;64F</span></code></td>
<td>64-bit little endian floating point.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">F;64BF</span></code></td>
<td>64-bit big endian floating point.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">F;64NF</span></code></td>
<td>64-bit native floating point.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="the-bit-decoder">
<h2>The bit decoder<a class="headerlink" href="#the-bit-decoder" title="Permalink to this headline">¶</a></h2>
<p>If the raw decoder cannot handle your format, PIL also provides a special “bit”
decoder that can be used to read various packed formats into a floating point
image memory.</p>
<p>To use the bit decoder with the frombytes function, use the following syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">image</span> <span class="o">=</span> <span class="n">frombytes</span><span class="p">(</span>
<span class="n">mode</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="s2">"bit"</span><span class="p">,</span>
<span class="n">bits</span><span class="p">,</span> <span class="n">pad</span><span class="p">,</span> <span class="n">fill</span><span class="p">,</span> <span class="n">sign</span><span class="p">,</span> <span class="n">orientation</span>
<span class="p">)</span>
</pre></div>
</div>
<p>When used in a tile descriptor, the parameter field should look like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">bits</span><span class="p">,</span> <span class="n">pad</span><span class="p">,</span> <span class="n">fill</span><span class="p">,</span> <span class="n">sign</span><span class="p">,</span> <span class="n">orientation</span><span class="p">)</span>
</pre></div>
</div>
<p>The fields are used as follows:</p>
<dl class="docutils">
<dt><strong>bits</strong></dt>
<dd>Number of bits per pixel (2-32). No default.</dd>
<dt><strong>pad</strong></dt>
<dd>Padding between lines, in bits. This is either 0 if there is no padding, or
8 if lines are padded to full bytes. If omitted, the pad value defaults to
8.</dd>
<dt><strong>fill</strong></dt>
<dd>Controls how data are added to, and stored from, the decoder bit buffer.</dd>
<dt><strong>fill=0</strong></dt>
<dd>Add bytes to the LSB end of the decoder buffer; store pixels from the MSB
end.</dd>
<dt><strong>fill=1</strong></dt>
<dd>Add bytes to the MSB end of the decoder buffer; store pixels from the MSB
end.</dd>
<dt><strong>fill=2</strong></dt>
<dd>Add bytes to the LSB end of the decoder buffer; store pixels from the LSB
end.</dd>
<dt><strong>fill=3</strong></dt>
<dd><p class="first">Add bytes to the MSB end of the decoder buffer; store pixels from the LSB
end.</p>
<p class="last">If omitted, the fill order defaults to 0.</p>
</dd>
<dt><strong>sign</strong></dt>
<dd>If non-zero, bit fields are sign extended. If zero or omitted, bit fields
are unsigned.</dd>
<dt><strong>orientation</strong></dt>
<dd>Whether the first line in the image is the top line on the screen (1), or
the bottom line (-1). If omitted, the orientation defaults to 1.</dd>
</dl>
</div>
</div>
<div class="section" id="writing-your-own-file-decoder-in-c">
<span id="file-decoders"></span><h1>Writing Your Own File Decoder in C<a class="headerlink" href="#writing-your-own-file-decoder-in-c" title="Permalink to this headline">¶</a></h1>
<p>There are 3 stages in a file decoder’s lifetime:</p>
<ol class="arabic simple">
<li>Setup: Pillow looks for a function in the decoder registry, falling
back to a function named <code class="docutils literal notranslate"><span class="pre">[decodername]_decoder</span></code> on the internal
core image object. That function is called with the <code class="docutils literal notranslate"><span class="pre">args</span></code> tuple
from the <code class="docutils literal notranslate"><span class="pre">tile</span></code> setup in the <code class="docutils literal notranslate"><span class="pre">_open</span></code> method.</li>
<li>Decoding: The decoder’s decode function is repeatedly called with
chunks of image data.</li>
<li>Cleanup: If the decoder has registered a cleanup function, it will
be called at the end of the decoding process, even if there was an
exception raised.</li>
</ol>
<div class="section" id="setup">
<h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2>
<p>The current conventions are that the decoder setup function is named
<code class="docutils literal notranslate"><span class="pre">PyImaging_[Decodername]DecoderNew</span></code> and defined in <code class="docutils literal notranslate"><span class="pre">decode.c</span></code>. The
python binding for it is named <code class="docutils literal notranslate"><span class="pre">[decodername]_decoder</span></code> and is setup
from within the <code class="docutils literal notranslate"><span class="pre">_imaging.c</span></code> file in the codecs section of the
function array.</p>
<p>The setup function needs to call <code class="docutils literal notranslate"><span class="pre">PyImaging_DecoderNew</span></code> and at the
very least, set the <code class="docutils literal notranslate"><span class="pre">decode</span></code> function pointer. The fields of
interest in this object are:</p>
<dl class="docutils">
<dt><strong>decode</strong></dt>
<dd>Function pointer to the decode function, which has access to
<code class="docutils literal notranslate"><span class="pre">im</span></code>, <code class="docutils literal notranslate"><span class="pre">state</span></code>, and the buffer of data to be added to the image.</dd>
<dt><strong>cleanup</strong></dt>
<dd>Function pointer to the cleanup function, has access to <code class="docutils literal notranslate"><span class="pre">state</span></code>.</dd>
<dt><strong>im</strong></dt>
<dd>The target image, will be set by Pillow.</dd>
<dt><strong>state</strong></dt>
<dd>An ImagingCodecStateInstance, will be set by Pillow. The <strong>context</strong>
member is an opaque struct that can be used by the decoder to store
any format specific state or options.</dd>
<dt><strong>pulls_fd</strong></dt>
<dd><p class="first"><strong>EXPERIMENTAL</strong> – <strong>WARNING</strong>, interface may change. If set to 1,
<code class="docutils literal notranslate"><span class="pre">state->fd</span></code> will be a pointer to the Python file like object. The
decoder may use the functions in <code class="docutils literal notranslate"><span class="pre">codec_fd.c</span></code> to read directly
from the file like object rather than have the data pushed through a
buffer. Note that this implementation may be refactored until this
warning is removed.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 3.3.0.</span></p>
</div>
</dd>
</dl>
</div>
<div class="section" id="decoding">
<h2>Decoding<a class="headerlink" href="#decoding" title="Permalink to this headline">¶</a></h2>
<p>The decode function is called with the target (core) image, the
decoder state structure, and a buffer of data to be decoded.</p>
<p><strong>Experimental</strong> – If <code class="docutils literal notranslate"><span class="pre">pulls_fd</span></code> is set, then the decode function
is called once, with an empty buffer. It is the decoder’s
responsibility to decode the entire tile in that one call. The rest of
this section only applies if <code class="docutils literal notranslate"><span class="pre">pulls_fd</span></code> is not set.</p>
<p>It is the decoder’s responsibility to pull as much data as possible
out of the buffer and return the number of bytes consumed. The next
call to the decoder will include the previous unconsumed tail. The
decoder function will be called multiple times as the data is read
from the file like object.</p>
<p>If an error occurs, set <code class="docutils literal notranslate"><span class="pre">state->errcode</span></code> and return -1.</p>
<p>Return -1 on success, without setting the errcode.</p>
</div>
<div class="section" id="cleanup">
<h2>Cleanup<a class="headerlink" href="#cleanup" title="Permalink to this headline">¶</a></h2>
<p>The cleanup function is called after the decoder returns a negative
value, or if there is a read error from the file. This function should
free any allocated memory and release any resources from external
libraries.</p>
</div>
</div>
<div class="section" id="writing-your-own-file-decoder-in-python">
<span id="file-decoders-py"></span><h1>Writing Your Own File Decoder in Python<a class="headerlink" href="#writing-your-own-file-decoder-in-python" title="Permalink to this headline">¶</a></h1>
<p>Python file decoders should derive from
<a class="reference internal" href="../reference/ImageFile.html#PIL.ImageFile.PyDecoder" title="PIL.ImageFile.PyDecoder"><code class="xref py py-class docutils literal notranslate"><span class="pre">PIL.ImageFile.PyDecoder</span></code></a> and should at least override the
decode method. File decoders should be registered using
<a class="reference internal" href="../reference/Image.html#PIL.Image.register_decoder" title="PIL.Image.register_decoder"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PIL.Image.register_decoder()</span></code></a>. As in the C implementation of
the file decoders, there are three stages in the lifetime of a
Python-based file decoder:</p>
<ol class="arabic simple">
<li>Setup: Pillow looks for the decoder in the registry, then
instantiates the class.</li>
<li>Decoding: The decoder instance’s <code class="docutils literal notranslate"><span class="pre">decode</span></code> method is repeatedly
called with a buffer of data to be interpreted.</li>
<li>Cleanup: The decoder instance’s <code class="docutils literal notranslate"><span class="pre">cleanup</span></code> method is called.</li>
</ol>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="../reference/index.html" class="btn btn-neutral float-right" title="Reference" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="image-file-formats.html" class="btn btn-neutral float-left" title="Image file formats" 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>
