From c38a858a6f9748dfdedd5d982f49dc3d2576b911 Mon Sep 17 00:00:00 2001 From: Steve Johnson Date: Sun, 6 Oct 2013 18:19:56 -0700 Subject: [PATCH] Concepts --- docs/handbook/concepts.rst | 108 +++++++++++++++++++++++++++++++++++++ docs/handbook/tutorial.rst | 6 +-- 2 files changed, 111 insertions(+), 3 deletions(-) diff --git a/docs/handbook/concepts.rst b/docs/handbook/concepts.rst index 6b799793b..03462bd89 100644 --- a/docs/handbook/concepts.rst +++ b/docs/handbook/concepts.rst @@ -1,2 +1,110 @@ Concepts ======== + +The Python Imaging Library handles *raster images*; that is, rectangles of +pixel data. + +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 +same dimensions and depth. + +To get the number and names of bands in an image, use the +:py:meth:`~PIL.Image.Image.getbands` method. + +Mode +---- + +The :term:`mode` of an image defines the type and depth of a pixel in the +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) + * ``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 doesn’t support user-defined modes; if you +to handle band combinations that are not listed above, use a sequence of Image +objects. + +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. + +Filters +------- + +For geometry operations that may map multiple input pixels to a single output +pixel, the Python Imaging Library provides four different resampling *filters*. + +``NEAREST`` + Pick the nearest pixel from the input image. Ignore all other input pixels. + +``BILINEAR`` + Use linear interpolation over a 2x2 environment in the input image. Note + that in the current version of PIL, this filter uses a fixed input + environment when downsampling. + +``BICUBIC`` + Use cubic interpolation over a 4x4 environment in the input image. Note + that in the current version of PIL, this filter uses a fixed input + environment when downsampling. + +``ANTIALIAS`` + Calculate the output pixel value using a high-quality resampling filter (a + truncated sinc) on all pixels that may contribute to the output value. In + the current version of PIL, this filter can only be used with the resize + and thumbnail methods. + + .. versionadded:: 1.1.3 + +Note that in the current version of PIL, the ``ANTIALIAS`` filter is the only +filter that behaves properly when downsampling (that is, when converting a +large image to a small one). The ``BILINEAR`` and ``BICUBIC`` filters use a +fixed input environment, and are best used for scale-preserving geometric +transforms and upsamping. + diff --git a/docs/handbook/tutorial.rst b/docs/handbook/tutorial.rst index cf04eb18d..1389910dc 100644 --- a/docs/handbook/tutorial.rst +++ b/docs/handbook/tutorial.rst @@ -26,7 +26,7 @@ image. If the image was not read from a file, it is set to None. The size attribute is a 2-tuple containing width and height (in pixels). The :py:attr:`~PIL.Image.Image.mode` attribute defines the number and names of the bands in the image, and also the pixel type and depth. Common modes are “L” -(luminance) for greyscale images, “RGB” for true colour images, and “CMYK” for +(luminance) for greyscale images, “RGB” for true color images, and “CMYK” for pre-press images. If the file cannot be opened, an :py:exc:`IOError` exception is raised. @@ -207,7 +207,7 @@ Splitting and merging bands im = Image.merge("RGB", (b, g, r)) Note that for a single-band image, :py:meth:`~PIL.Image.Image.split` returns -the image itself. To work with individual colour bands, you may want to convert +the image itself. To work with individual color bands, you may want to convert the image to “RGB” first. Geometrical transforms @@ -346,7 +346,7 @@ For more advanced image enhancement, you can use the classes in the :py:mod:`~PIL.ImageEnhance` module. Once created from an image, an enhancement object can be used to quickly try out different settings. -You can adjust contrast, brightness, colour balance and sharpness in this way. +You can adjust contrast, brightness, color balance and sharpness in this way. Enhancing images ~~~~~~~~~~~~~~~~