/usr/share/doc/python-imaging/html/writing-your-own-file-decoder.htm is in python-imaging-doc-html 1.1.2-1.1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | <html><head><title>D. Writing Your Own File Decoder</title><link rel="stylesheet" type="text/css" href="effbot.css" /></head><body><div id="WRITING-YOUR-OWN-FILE-DECODER-APPENDIX" class="appendix"><h1 style="appendix">D. Writing Your Own File Decoder</h1><p>The Python Imaging Library uses a <i>plug-in</i> model which allows you to add your own decoders to the library, without any changes to the library itself. Such plug-ins have names like <i>XxxImagePlugin.py</i>, where <i>Xxx</i> is a unique format name (usually an abbreviation).</p><p>A decoder plug-in should contain a decoder class, based on the <i>ImageFile </i>base class defined in the module with the same name. This class should provide an <i>_open</i> method, which reads the file header and sets up at least the <i>mode</i> and <i>size</i> attributes. To be able to load the file, the method must also create a list of <i>tile</i> descriptors. The class must be explicitly registered, via a call to the <i>Image </i>module.</p><p>For performance reasons, it is important that the <i>_open</i> method quickly rejects files that do not have the appropriate contents.</p><div class="sect1"><h2 style="sect1">Example</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 colour.</p><div class="example"><b style="example">Example: File: SpamImagePlugin.py</b><pre>import Image, ImageFile
import string
class SpamImageFile(ImageFile.ImageFile):
format = "SPAM"
format_description = "Spam raster image"
def _open(self):
# check header
header = self.fp.read(128)
if header[:4] != "SPAM":
raise SyntaxError, "not a SPAM file"
header = string.split(header)
# size in pixels (width, height)
self.size = string.atoi(header[1]), string.atoi(header[2])
# mode setting
bits = string.atoi(header[3])
if bits == 1:
self.mode = "1"
elif bits == 8:
self.mode = "L"
elif bits == 24:
self.mode = "RGB"
else:
raise SyntaxError, "unknown number of bits"
# data descriptor
self.tile = [("raw", (0, 0) + self.size, 128,
(self.mode, 0, 1))]
Image.register_open("SPAM", SpamImageFile)
Image.register_extension("SPAM", ".spam")
Image.register_extension("SPAM", ".spa") # dos version</pre></div><p>The format handler must always set the <i>size</i> and <i>mode</i> attributes. If these are not set, the file cannot be opened. To simplify the decoder, the calling code considers exceptions like <i>SyntaxError, KeyError, </i>and <i>IndexError,</i> as a failure to identify the file.</p><p>Note that the decoder must be explicitly registered using the <i>register_open</i> function in the <i>Image</i> module. Although not required, it is also a good idea to register any extensions used by this format.</p></div><div class="sect1"><h2 style="sect1">The Tile Attribute</h2><p>To be able to read the file as well as just identifying it, the <i>tile</i> 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><pre> (decoder, region, offset, parameters)</pre><p>The fields are used as follows: </p><p><i>decoder</i>. Specifies which decoder to use. The "raw" decoder used here supports uncompressed data, in a variety of pixel formats. For more information on this decoder, see the description below.</p><p><i>region</i>. A 4-tuple specifying where to store data in the image.</p><p><i>offset</i>. Byte offset from the beginning of the file to image data.</p><p><i>parameters</i>. 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 <tt>None</tt> for this field.</p><p>Note that the <i>tile</i> attribute contains a <i>list</i> of tile descriptors, not just a single descriptor. </p></div><div class="sect1"><h2 style="sect1">The Raw Decoder</h2><p>The raw 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 <i>fromstring</i> function, use the following syntax:</p><pre> image = fromstring(
mode, size, data, "raw",
raw mode, stride, orientation
)</pre><p>When used in a tile descriptor, the parameter field should look like:</p><pre> (raw mode, stride, orientation)</pre><p>The fields are used as follows:</p><p><i>raw mode</i>. 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.</p><p><i>stride</i>. 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.</p><p><i>orientation</i>. 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.</p><p>The <i>raw mode</i> 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 <i>Unpack.c</i> module. The following table describes some commonly used <i>raw modes</i>:</p><p><span>"1"</span>. 1-bit bilevel, stored with the leftmost pixel in the most significant bit. 0 means black, 1 means white.</p><p><span>"1;I"</span>. 1-bit inverted bilevel, stored with the leftmost pixel in the most significant bit. 0 means white, 1 means black.</p><p><span>"1;R"</span>. 1-bit reversed bilevel, stored with the leftmost pixel in the least significant bit. 0 means black, 1 means white.</p><p><span>"L"</span>. 8-bit greyscale. 0 means black, 255 means white.</p><p><span>"L;I"</span>. 8-bit inverted greyscale. 0 means white, 255 means black.</p><p><span>"P"</span>. 8-bit palette-mapped image.</p><p><span>"RGB"</span>. 24-bit true colour, stored as (red, green, blue).</p><p><span>"BGR"</span>. 24-bit true colour, stored as (blue, green, red).</p><p><span>"RGBX"</span>. 24-bit true colour, stored as (blue, green, red, pad).</p><p><span>"RGB;L"</span>. 24-bit true colour, line interleaved (first all red pixels, the all green pixels, finally all blue pixels).</p><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 <i>decode.c</i> source file, and the standard plug-in implementations provided with the library.</p></div><div class="sect1"><h2 style="sect1">Decoding Floating Point Data</h2><p>PIL provides some special mechanisms to allow you to load a wide variety of formats into a mode "F" (floating point) image memory.</p><p>You can use the "raw" decoder to read images where data is packed in any standard machine data type, using one of the following raw modes:</p><p><span>"F"</span>. 32-bit native floating point.</p><p><span>"F;8"</span>. 8-bit unsigned integer.</p><p><span>"F;8S"</span>. 8-bit signed integer.</p><p><span>"F;16"</span>. 16-bit little endian unsigned integer.</p><p><span>"F;16S"</span>. 16-bit little endian signed integer.</p><p><span>"F;16B"</span>. 16-bit big endian unsigned integer.</p><p><span>"F;16BS"</span>. 16-bit big endian signed integer.</p><p><span>"F;16N"</span>. 16-bit native unsigned integer.</p><p><span>"F;16NS"</span>. 16-bit native signed integer.</p><p><span>"F;32"</span>. 32-bit little endian unsigned integer.</p><p><span>"F;32S"</span>. 32-bit little endian signed integer.</p><p><span>"F;32B"</span>. 32-bit big endian unsigned integer.</p><p><span>"F;32BS"</span>. 32-bit big endian signed integer.</p><p><span>"F;32N"</span>. 32-bit native unsigned integer.</p><p><span>"F;32NS"</span>. 32-bit native signed integer.</p><p><span>"F;32F"</span>. 32-bit little endian floating point.</p><p><span>"F;32BF"</span>. 32-bit big endian floating point.</p><p><span>"F;32NF"</span>. 32-bit native floating point.</p><p><span>"F;64F"</span>. 64-bit little endian floating point.</p><p><span>"F;64BF"</span>. 64-bit big endian floating point.</p><p><span>"F;64NF"</span>. 64-bit native floating point.</p></div><div class="sect1"><h2 style="sect1">The Bit Decoder</h2><p>If the raw decoder cannot handle your format, PIL also provides a special "bit" decoder which can be used to read various packed formats into a floating point image memory.</p><p>To use the bit decoder with the <i>fromstring</i> function, use the following syntax:</p><pre> image = fromstring(
mode, size, data, "bit",
bits, pad, fill, sign, orientation
)</pre><p>When used in a tile descriptor, the parameter field should look like:</p><pre> (bits, pad, fill, sign, orientation)</pre><p>The fields are used as follows: </p><p><i>bits</i>. Number of bits per pixel (2-32). No default.</p><p><i>pad</i>. 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.</p><p><i>fill</i>. Controls how data are added to, and stored from, the decoder bit buffer.</p><p><i>fill=0</i>. Add bytes to the msb end of the decoder buffer; store pixels from the msb end.</p><p><i>fill=1</i>. Add bytes to the lsb end of the decoder buffer; store pixels from the msb end.</p><p><i>fill=2</i>. Add bytes to the msb end of the decoder buffer; store pixels from the lsb end.</p><p><i>fill=3</i>. Add bytes to the lsb end of the decoder buffer; store pixels from the lsb end.</p><p>If omitted, the fill order defaults to 0. </p><p><i>sign</i>. If non-zero, bit fields are sign extended. If zero or omitted, bit fields are unsigned.</p><p><i>orientation</i>. 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.</p></div></div></body></html>
|