Pillow/docs/reference/Image.rst

233 lines
7.1 KiB
ReStructuredText
Raw Normal View History

2013-10-12 09:18:28 +04:00
.. py:module:: PIL.Image
.. py:currentmodule:: PIL.Image
:py:mod:`Image` Module
======================
2013-10-12 09:18:28 +04:00
The :py:mod:`~PIL.Image` module provides a class with the same name which is
used to represent a PIL image. The module also provides a number of factory
functions, including functions to load images from files, and to create new
images.
Examples
--------
Open, rotate, and display an image (using the default viewer)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2013-10-12 09:18:28 +04:00
The following script loads an image, rotates it 45 degrees, and displays it
using an external viewer (usually xv on Unix, and the paint program on
Windows).
.. code-block:: python
from PIL import Image
im = Image.open("bride.jpg")
im.rotate(45).show()
Create thumbnails
^^^^^^^^^^^^^^^^^
The following script creates nice thumbnails of all JPEG images in the
current directory preserving aspect ratios with 128x128 max resolution.
2013-10-12 09:18:28 +04:00
.. code-block:: python
from PIL import Image
import glob, os
size = 128, 128
for infile in glob.glob("*.jpg"):
file, ext = os.path.splitext(infile)
im = Image.open(infile)
im.thumbnail(size)
2013-10-12 09:18:28 +04:00
im.save(file + ".thumbnail", "JPEG")
Functions
---------
.. autofunction:: open
.. warning::
To protect against potential DOS attacks caused by "`decompression bombs`_" (i.e. malicious files
which decompress into a huge amount of data and are designed to crash or cause disruption by using up
a lot of memory), Pillow will issue a `DecompressionBombWarning` if the image is over a certain
limit. If desired, the warning can be turned into an error with
``warnings.simplefilter('error', Image.DecompressionBombWarning)`` or suppressed entirely with
``warnings.simplefilter('ignore', Image.DecompressionBombWarning)``. See also `the logging
documentation`_ to have warnings output to the logging facility instead of stderr.
2014-07-15 09:25:02 +04:00
.. _decompression bombs: https://en.wikipedia.org/wiki/Zip_bomb
.. _the logging documentation: https://docs.python.org/3/library/logging.html#integration-with-the-warnings-module
2014-06-27 22:30:08 +04:00
2013-10-12 09:18:28 +04:00
Image processing
^^^^^^^^^^^^^^^^
.. autofunction:: alpha_composite
.. autofunction:: blend
.. autofunction:: composite
.. autofunction:: eval
.. autofunction:: merge
Constructing images
^^^^^^^^^^^^^^^^^^^
.. autofunction:: new
.. autofunction:: fromarray
.. autofunction:: frombytes
.. autofunction:: fromstring
.. autofunction:: frombuffer
Registering plugins
^^^^^^^^^^^^^^^^^^^
.. note::
These functions are for use by plugin authors. Application authors can
ignore them.
.. autofunction:: register_open
2017-04-03 23:21:50 +03:00
.. autofunction:: register_decoder
2013-10-12 09:18:28 +04:00
.. autofunction:: register_mime
.. autofunction:: register_save
2017-04-03 23:21:50 +03:00
.. autofunction:: register_encoder
2013-10-12 09:18:28 +04:00
.. autofunction:: register_extension
2017-04-03 23:21:50 +03:00
2013-10-12 09:18:28 +04:00
The Image Class
---------------
.. autoclass:: PIL.Image.Image
An instance of the :py:class:`~PIL.Image.Image` class has the following
methods. Unless otherwise stated, all methods return a new instance of the
:py:class:`~PIL.Image.Image` class, holding the resulting image.
2017-06-29 15:14:43 +03:00
.. automethod:: PIL.Image.Image.alpha_composite
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.convert
The following example converts an RGB image (linearly calibrated according to
ITU-R 709, using the D65 luminant) to the CIE XYZ color space:
.. code-block:: python
rgb2xyz = (
0.412453, 0.357580, 0.180423, 0,
0.212671, 0.715160, 0.072169, 0,
0.019334, 0.119193, 0.950227, 0 )
out = im.convert("RGB", rgb2xyz)
.. automethod:: PIL.Image.Image.copy
.. automethod:: PIL.Image.Image.crop
.. automethod:: PIL.Image.Image.draft
.. automethod:: PIL.Image.Image.filter
.. automethod:: PIL.Image.Image.getbands
.. automethod:: PIL.Image.Image.getbbox
.. automethod:: PIL.Image.Image.getcolors
.. automethod:: PIL.Image.Image.getdata
.. automethod:: PIL.Image.Image.getextrema
2014-11-10 07:51:20 +03:00
.. automethod:: PIL.Image.Image.getpalette
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.getpixel
.. automethod:: PIL.Image.Image.histogram
.. automethod:: PIL.Image.Image.offset
.. automethod:: PIL.Image.Image.paste
.. automethod:: PIL.Image.Image.point
.. automethod:: PIL.Image.Image.putalpha
.. automethod:: PIL.Image.Image.putdata
.. automethod:: PIL.Image.Image.putpalette
.. automethod:: PIL.Image.Image.putpixel
.. automethod:: PIL.Image.Image.quantize
.. automethod:: PIL.Image.Image.resize
2017-04-03 23:21:50 +03:00
.. automethod:: PIL.Image.Image.remap_palette
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.rotate
.. automethod:: PIL.Image.Image.save
.. automethod:: PIL.Image.Image.seek
.. automethod:: PIL.Image.Image.show
.. automethod:: PIL.Image.Image.split
.. automethod:: PIL.Image.Image.getchannel
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.tell
.. automethod:: PIL.Image.Image.thumbnail
.. automethod:: PIL.Image.Image.tobitmap
.. automethod:: PIL.Image.Image.tobytes
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.tostring
.. automethod:: PIL.Image.Image.transform
.. automethod:: PIL.Image.Image.transpose
.. automethod:: PIL.Image.Image.verify
.. automethod:: PIL.Image.Image.fromstring
.. automethod:: PIL.Image.Image.load
2014-04-18 08:53:49 +04:00
.. automethod:: PIL.Image.Image.close
2013-10-12 09:18:28 +04:00
Attributes
----------
Instances of the :py:class:`Image` class have the following attributes:
.. py:attribute:: filename
2018-01-27 09:04:46 +03:00
The filename or path of the source file. Only images created with the
factory function `open` have a filename attribute. If the input is a
file like object, the filename attribute is set to an empty string.
2018-01-27 09:04:46 +03:00
:type: :py:class: `string`
2013-10-12 09:18:28 +04:00
.. py:attribute:: format
The file format of the source file. For images created by the library
itself (via a factory function, or by running a method on an existing
image), this attribute is set to ``None``.
:type: :py:class:`string` or ``None``
.. py:attribute:: mode
Image mode. This is a string specifying the pixel format used by the image.
Typical values are “1”, “L”, “RGB”, or “CMYK.” See
:ref:`concept-modes` for a full list.
2013-10-12 09:18:28 +04:00
:type: :py:class:`string`
.. py:attribute:: size
Image size, in pixels. The size is given as a 2-tuple (width, height).
:type: ``(width, height)``
.. py:attribute:: width
Image width, in pixels.
:type: :py:class:`int`
.. py:attribute:: height
Image height, in pixels.
:type: :py:class:`int`
2013-10-12 09:18:28 +04:00
.. py:attribute:: palette
Colour palette table, if any. If mode is “P”, this should be an instance of
the :py:class:`~PIL.ImagePalette.ImagePalette` class. Otherwise, it should
be set to ``None``.
:type: :py:class:`~PIL.ImagePalette.ImagePalette` or ``None``
.. py:attribute:: info
A dictionary holding data associated with the image. This dictionary is
used by file handlers to pass on various non-image information read from
the file. See documentation for the various file handlers for details.
Most methods ignore the dictionary when returning new images; since the
keys are not standardized, its not possible for a method to know if the
operation affects the dictionary. If you need the information later on,
keep a reference to the info dictionary returned from the open method.
Unless noted elsewhere, this dictionary does not affect saving files.
2013-10-12 09:18:28 +04:00
:type: :py:class:`dict`