<!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>