Pillow/docs/handbook/concepts.rst

158 lines
5.9 KiB
ReStructuredText
Raw Normal View History

2013-10-07 04:30:20 +04:00
Concepts
========
2013-10-07 05:19:56 +04:00
The Python Imaging Library handles *raster images*; that is, rectangles of
pixel data.
2015-09-03 23:26:04 +03:00
.. _concept-bands:
2013-10-07 05:19:56 +04:00
Bands
-----
An image can consist of one or more bands of data. The Python Imaging Library
allows you to store several bands in a single image, provided they all have the
2015-09-03 23:26:04 +03:00
same dimensions and depth. For example, a PNG image might have 'R', 'G', 'B',
2015-10-11 13:24:35 +03:00
and 'A' bands for the red, green, blue, and alpha transparency values. Many
2015-09-03 23:26:04 +03:00
operations act on each band separately, e.g., histograms. It is often useful to
think of each pixel as having one value per band.
2013-10-07 05:19:56 +04:00
To get the number and names of bands in an image, use the
2015-10-11 13:24:35 +03:00
:py:meth:`~PIL.Image.Image.getbands` method.
2013-10-07 05:19:56 +04:00
2014-11-19 23:49:06 +03:00
.. _concept-modes:
Modes
-----
2013-10-07 05:19:56 +04:00
The ``mode`` of an image defines the type and depth of a pixel in the
2013-10-07 05:19:56 +04:00
image. The current release supports the following standard modes:
* ``1`` (1-bit pixels, black and white, stored with one pixel per byte)
* ``L`` (8-bit pixels, black and white)
* ``P`` (8-bit pixels, mapped to any other mode using a color palette)
* ``RGB`` (3x8-bit pixels, true color)
* ``RGBA`` (4x8-bit pixels, true color with transparency mask)
* ``CMYK`` (4x8-bit pixels, color separation)
* ``YCbCr`` (3x8-bit pixels, color video format)
2016-01-23 04:40:38 +03:00
* Note that this refers to the JPEG, and not the ITU-R BT.2020, standard
2014-07-26 20:59:33 +04:00
* ``LAB`` (3x8-bit pixels, the L*a*b color space)
* ``HSV`` (3x8-bit pixels, Hue, Saturation, Value color space)
2013-10-07 05:19:56 +04:00
* ``I`` (32-bit signed integer pixels)
* ``F`` (32-bit floating point pixels)
PIL also provides limited support for a few special modes, including ``LA`` (L
with alpha), ``RGBX`` (true color with padding) and ``RGBa`` (true color with
premultiplied alpha). However, PIL doesnt support user-defined modes; if you
2017-05-29 12:42:06 +03:00
need to handle band combinations that are not listed above, use a sequence of
Image objects.
2013-10-07 05:19:56 +04:00
You can read the mode of an image through the :py:attr:`~PIL.Image.Image.mode`
attribute. This is a string containing one of the above values.
Size
----
You can read the image size through the :py:attr:`~PIL.Image.Image.size`
attribute. This is a 2-tuple, containing the horizontal and vertical size in
pixels.
Coordinate System
-----------------
The Python Imaging Library uses a Cartesian pixel coordinate system, with (0,0)
in the upper left corner. Note that the coordinates refer to the implied pixel
corners; the centre of a pixel addressed as (0, 0) actually lies at (0.5, 0.5).
Coordinates are usually passed to the library as 2-tuples (x, y). Rectangles
are represented as 4-tuples, with the upper left corner given first. For
example, a rectangle covering all of an 800x600 pixel image is written as (0,
0, 800, 600).
Palette
-------
The palette mode (``P``) uses a color palette to define the actual color for
each pixel.
Info
----
You can attach auxiliary information to an image using the
:py:attr:`~PIL.Image.Image.info` attribute. This is a dictionary object.
How such information is handled when loading and saving image files is up to
the file format handler (see the chapter on :ref:`image-file-formats`). Most
handlers add properties to the :py:attr:`~PIL.Image.Image.info` attribute when
loading an image, but ignore it when saving images.
2016-06-30 15:21:45 +03:00
.. _concept-filters:
2013-10-07 05:19:56 +04:00
Filters
-------
For geometry operations that may map multiple input pixels to a single output
2017-01-08 22:32:57 +03:00
pixel, the Python Imaging Library provides different resampling *filters*.
2013-10-07 05:19:56 +04:00
``NEAREST``
2016-06-17 00:03:25 +03:00
Pick one nearest pixel from the input image. Ignore all other input pixels.
``BOX``
Each pixel of source image contributes to one pixel of the
destination image with identical weights.
For upscaling is equivalent of ``NEAREST``.
This filter can only be used with the :py:meth:`~PIL.Image.Image.resize`
and :py:meth:`~PIL.Image.Image.thumbnail` methods.
.. versionadded:: 3.4.0
2013-10-07 05:19:56 +04:00
``BILINEAR``
2014-11-09 04:26:53 +03:00
For resize calculate the output pixel value using linear interpolation
on all pixels that may contribute to the output value.
For other transformations linear interpolation over a 2x2 environment
in the input image is used.
2013-10-07 05:19:56 +04:00
2016-06-17 00:03:25 +03:00
``HAMMING``
2017-05-29 12:42:06 +03:00
Produces a sharper image than ``BILINEAR``, doesn't have dislocations
2016-06-17 00:03:25 +03:00
on local level like with ``BOX``.
This filter can only be used with the :py:meth:`~PIL.Image.Image.resize`
and :py:meth:`~PIL.Image.Image.thumbnail` methods.
.. versionadded:: 3.4.0
2013-10-07 05:19:56 +04:00
``BICUBIC``
2014-11-09 04:26:53 +03:00
For resize calculate the output pixel value using cubic interpolation
on all pixels that may contribute to the output value.
For other transformations cubic interpolation over a 4x4 environment
in the input image is used.
2013-10-07 05:19:56 +04:00
``LANCZOS``
2014-11-09 04:26:53 +03:00
Calculate the output pixel value using a high-quality Lanczos filter (a
2016-06-30 15:21:45 +03:00
truncated sinc) on all pixels that may contribute to the output value.
This filter can only be used with the :py:meth:`~PIL.Image.Image.resize`
and :py:meth:`~PIL.Image.Image.thumbnail` methods.
2013-10-07 05:19:56 +04:00
.. versionadded:: 1.1.3
2016-06-30 15:21:45 +03:00
Filters comparison table
~~~~~~~~~~~~~~~~~~~~~~~~
+------------+-------------+-----------+-------------+
| Filter | Downscaling | Upscaling | Performance |
| | quality | quality | |
+============+=============+===========+=============+
|``NEAREST`` | | | ⭐⭐⭐⭐⭐ |
+------------+-------------+-----------+-------------+
2016-06-17 00:03:25 +03:00
|``BOX`` | ⭐ | | ⭐⭐⭐⭐ |
+------------+-------------+-----------+-------------+
2016-06-30 15:21:45 +03:00
|``BILINEAR``| ⭐ | ⭐ | ⭐⭐⭐ |
+------------+-------------+-----------+-------------+
2016-06-17 00:03:25 +03:00
|``HAMMING`` | ⭐⭐ | | ⭐⭐⭐ |
+------------+-------------+-----------+-------------+
2016-06-30 15:21:45 +03:00
|``BICUBIC`` | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
+------------+-------------+-----------+-------------+
|``LANCZOS`` | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐ |
+------------+-------------+-----------+-------------+