mirror of
https://github.com/python-pillow/Pillow.git
synced 2024-12-24 00:46:16 +03:00
Writing your own file decoder
This commit is contained in:
Steve Johnson
parent
6115049f45
commit
b4a8e023dd
|
|
@ -1,2 +1,278 @@
|
|||
Writing your own file decoder
|
||||
=============================
|
||||
|
||||
The Python Imaging Library 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 have names like :file:`XxxImagePlugin.py`, where ``Xxx`` is a unique
|
||||
format name (usually an abbreviation).
|
||||
|
||||
A decoder plug-in should contain a decoder class, based on the
|
||||
:py:class:`PIL.ImageFile.ImageFile` base class. This class should provide an
|
||||
:py:meth:`_open` method, which reads the file header and sets up at least the
|
||||
:py:attr:`~PIL.Image.Image.mode` and :py:attr:`~PIL.Image.Image.size`
|
||||
attributes. To be able to load the file, the method must also create a list of
|
||||
:py:attr:`tile` descriptors. The class must be explicitly registered, via a
|
||||
call to the :py:mod:`~PIL.Image` module.
|
||||
|
||||
For performance reasons, it is important that the :py:meth:`_open` method
|
||||
quickly rejects files that do not have the appropriate contents.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
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.
|
||||
|
||||
**SpamImagePlugin.py**::
|
||||
|
||||
from PIL 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 = int(header[1]), int(header[2])
|
||||
|
||||
# mode setting
|
||||
bits = int(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
|
||||
|
||||
The format handler must always set the :py:attr:`~PIL.Image.Image.size` and
|
||||
:py:attr:`~PIL.Image.Image.mode` attributes. If these are not set, the file
|
||||
cannot be opened. To simplify the decoder, the calling code considers
|
||||
exceptions like :py:exc:`SyntaxError`, :py:exc:`KeyError`, and
|
||||
:py:exc:`IndexError`, as a failure to identify the file.
|
||||
|
||||
Note that the decoder must be explicitly registered using
|
||||
:py:func:`PIL.Image.register_open`. Although not required, it is also a good
|
||||
idea to register any extensions used by this format.
|
||||
|
||||
The :py:attr:`tile` attribute
|
||||
-----------------------------
|
||||
|
||||
To be able to read the file as well as just identifying it, the :py:attr:`tile`
|
||||
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.
|
||||
|
||||
The tile descriptor is a 4-tuple with the following contents::
|
||||
|
||||
(decoder, region, offset, parameters)
|
||||
|
||||
The fields are used as follows:
|
||||
|
||||
**decoder**
|
||||
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.
|
||||
|
||||
**region**
|
||||
A 4-tuple specifying where to store data in the image.
|
||||
|
||||
**offset**
|
||||
Byte offset from the beginning of the file to image data.
|
||||
|
||||
**parameters**
|
||||
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.
|
||||
|
||||
Note that the :py:attr:`tile` attribute contains a list of tile descriptors,
|
||||
not just a single descriptor.
|
||||
|
||||
The ``raw`` decoder
|
||||
|
||||
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
|
||||
:py:func:`PIL.Image.fromstring` function, use the following syntax::
|
||||
|
||||
image = Image.fromstring(
|
||||
mode, size, data, "raw",
|
||||
raw mode, stride, orientation
|
||||
)
|
||||
|
||||
When used in a tile descriptor, the parameter field should look like::
|
||||
|
||||
(raw mode, stride, orientation)
|
||||
|
||||
The fields are used as follows:
|
||||
|
||||
**raw mode**
|
||||
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.
|
||||
|
||||
**stride**
|
||||
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.
|
||||
|
||||
**orientation**
|
||||
|
||||
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.
|
||||
|
||||
The **raw mode** 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 :py:mod:`Unpack.c` module. The following
|
||||
table describes some commonly used **raw modes**:
|
||||
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| mode | description |
|
||||
+===========+=================================================================+
|
||||
| ``1`` | 1-bit bilevel, stored with the leftmost pixel in the most |
|
||||
| | significant bit. 0 means black, 1 means white. |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``1;I`` | 1-bit inverted bilevel, stored with the leftmost pixel in the |
|
||||
| | most significant bit. 0 means white, 1 means black. |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``1;R`` | 1-bit reversed bilevel, stored with the leftmost pixel in the |
|
||||
| | least significant bit. 0 means black, 1 means white. |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``L`` | 8-bit greyscale. 0 means black, 255 means white. |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``L;I`` | 8-bit inverted greyscale. 0 means white, 255 means black. |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``P`` | 8-bit palette-mapped image. |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``RGB`` | 24-bit true colour, stored as (red, green, blue). |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``BGR`` | 24-bit true colour, stored as (blue, green, red). |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``RGBX`` | 24-bit true colour, stored as (blue, green, red, pad). |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
| ``RGB;L`` | 24-bit true colour, line interleaved (first all red pixels, the |
|
||||
| | all green pixels, finally all blue pixels). |
|
||||
+-----------+-----------------------------------------------------------------+
|
||||
|
||||
Note that for the most common cases, the raw mode is simply the same as the mode.
|
||||
|
||||
The Python Imaging Library supports many other decoders, including JPEG, PNG,
|
||||
and PackBits. For details, see the :file:`decode.c` source file, and the
|
||||
standard plug-in implementations provided with the library.
|
||||
|
||||
Decoding floating point data
|
||||
----------------------------
|
||||
|
||||
PIL provides some special mechanisms to allow you to load a wide variety of
|
||||
formats into a mode ``F`` (floating point) image memory.
|
||||
|
||||
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:
|
||||
|
||||
============ =======================================
|
||||
mode description
|
||||
============ =======================================
|
||||
``F`` 32-bit native floating point.
|
||||
``F;8`` 8-bit unsigned integer.
|
||||
``F;8S`` 8-bit signed integer.
|
||||
``F;16`` 16-bit little endian unsigned integer.
|
||||
``F;16S`` 16-bit little endian signed integer.
|
||||
``F;16B`` 16-bit big endian unsigned integer.
|
||||
``F;16BS`` 16-bit big endian signed integer.
|
||||
``F;16N`` 16-bit native unsigned integer.
|
||||
``F;16NS`` 16-bit native signed integer.
|
||||
``F;32`` 32-bit little endian unsigned integer.
|
||||
``F;32S`` 32-bit little endian signed integer.
|
||||
``F;32B`` 32-bit big endian unsigned integer.
|
||||
``F;32BS`` 32-bit big endian signed integer.
|
||||
``F;32N`` 32-bit native unsigned integer.
|
||||
``F;32NS`` 32-bit native signed integer.
|
||||
``F;32F`` 32-bit little endian floating point.
|
||||
``F;32BF`` 32-bit big endian floating point.
|
||||
``F;32NF`` 32-bit native floating point.
|
||||
``F;64F`` 64-bit little endian floating point.
|
||||
``F;64BF`` 64-bit big endian floating point.
|
||||
``F;64NF`` 64-bit native floating point.
|
||||
============ =======================================
|
||||
|
||||
The bit decoder
|
||||
---------------
|
||||
|
||||
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.
|
||||
|
||||
To use the bit decoder with the fromstring function, use the following syntax::
|
||||
|
||||
image = fromstring(
|
||||
mode, size, data, "bit",
|
||||
bits, pad, fill, sign, orientation
|
||||
)
|
||||
|
||||
When used in a tile descriptor, the parameter field should look like::
|
||||
|
||||
(bits, pad, fill, sign, orientation)
|
||||
|
||||
The fields are used as follows:
|
||||
|
||||
**bits**
|
||||
Number of bits per pixel (2-32). No default.
|
||||
|
||||
**pad**
|
||||
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.
|
||||
|
||||
**fill**
|
||||
Controls how data are added to, and stored from, the decoder bit buffer.
|
||||
|
||||
**fill=0**
|
||||
Add bytes to the LSB end of the decoder buffer; store pixels from the MSB
|
||||
end.
|
||||
|
||||
**fill=1**
|
||||
Add bytes to the MSB end of the decoder buffer; store pixels from the MSB
|
||||
end.
|
||||
|
||||
**fill=2**
|
||||
Add bytes to the LSB end of the decoder buffer; store pixels from the LSB
|
||||
end.
|
||||
|
||||
**fill=3**
|
||||
Add bytes to the MSB end of the decoder buffer; store pixels from the LSB
|
||||
end.
|
||||
|
||||
If omitted, the fill order defaults to 0.
|
||||
|
||||
**sign**
|
||||
If non-zero, bit fields are sign extended. If zero or omitted, bit fields
|
||||
are unsigned.
|
||||
|
||||
**orientation**
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user