Pillow/docs/reference/Image.rst

326 lines
9.3 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
2019-06-24 11:04:13 +03:00
using an external viewer (usually xv on Unix, and the Paint program on
2013-10-12 09:18:28 +04:00
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,
2019-06-24 11:04:13 +03:00
0.019334, 0.119193, 0.950227, 0)
2013-10-12 09:18:28 +04:00
out = im.convert("RGB", rgb2xyz)
.. automethod:: PIL.Image.Image.copy
.. automethod:: PIL.Image.Image.crop
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
This crops the input image with the provided coordinates:
2019-04-06 23:42:22 +03:00
.. code-block:: python
2019-06-24 10:45:53 +03:00
from PIL import Image
2019-06-24 11:04:13 +03:00
2019-06-24 10:48:33 +03:00
im = Image.open("hopper.jpg")
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
# The crop method from the Image module takes four coordinates as input.
2019-04-06 23:42:22 +03:00
# The right can also be represented as (left+width)
2019-06-24 11:04:13 +03:00
# and lower can be represented as (upper+height).
(left, upper, right, lower) = (20, 20, 100, 100)
2019-06-24 10:45:53 +03:00
2019-06-24 11:04:13 +03:00
# Here the image "im" is cropped and assigned to new variable im_crop
2019-04-06 23:42:22 +03:00
im_crop = im.crop((left, upper, right, lower))
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.draft
.. automethod:: PIL.Image.Image.filter
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
This blurs the input image using a filter from the ``ImageFilter`` module:
2019-04-06 23:42:22 +03:00
.. code-block:: python
2019-06-24 11:04:13 +03:00
from PIL import Image, ImageFilter
2019-06-24 10:48:33 +03:00
im = Image.open("hopper.jpg")
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
# Blur the input image using the filter ImageFilter.BLUR
2019-04-06 23:42:22 +03:00
im_blurred = im.filter(filter=ImageFilter.BLUR)
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.getbands
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
This helps to get the bands of the input image:
2019-04-06 23:42:22 +03:00
.. code-block:: python
2019-06-24 10:45:53 +03:00
from PIL import Image
2019-06-24 11:04:13 +03:00
2019-06-24 10:48:33 +03:00
im = Image.open("hopper.jpg")
2019-06-24 11:04:13 +03:00
print(im.getbands()) # Returns ('R', 'G', 'B')
2019-04-06 23:42:22 +03:00
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.getbbox
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
This helps to get the bounding box coordinates of the input image:
2019-04-06 23:42:22 +03:00
.. code-block:: python
2019-06-24 10:45:53 +03:00
from PIL import Image
2019-06-24 11:04:13 +03:00
2019-06-24 10:48:33 +03:00
im = Image.open("hopper.jpg")
2019-06-28 18:47:17 +03:00
print(im.getbbox())
2019-04-06 23:42:22 +03:00
# Returns four coordinates in the format (left, upper, right, lower)
2019-06-24 10:45:53 +03:00
2013-10-12 09:18:28 +04:00
.. 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
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
This resizes the given image from ``(width, height)`` to ``(width/2, height/2)``:
2019-04-06 23:42:22 +03:00
.. code-block:: python
2019-06-24 10:45:53 +03:00
from PIL import Image
2019-06-24 11:04:13 +03:00
2019-06-24 10:48:33 +03:00
im = Image.open("hopper.jpg")
2019-04-06 23:42:22 +03:00
# Provide the target width and height of the image
2019-06-24 11:04:13 +03:00
(width, height) = (im.width // 2, im.height // 2)
2019-04-06 23:42:22 +03:00
im_resized = im.resize((width, height))
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
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
This rotates the input image by ``theta`` degrees counter clockwise:
2019-04-06 23:42:22 +03:00
.. code-block:: python
2019-06-24 10:45:53 +03:00
from PIL import Image
2019-06-24 11:04:13 +03:00
2019-06-24 10:48:33 +03:00
im = Image.open("hopper.jpg")
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
# Rotate the image by 60 degrees counter clockwise
2019-04-06 23:42:22 +03:00
theta = 60
2019-06-24 11:04:13 +03:00
# Angle is in degrees counter clockwise
2019-06-24 10:45:53 +03:00
im_rotated = im.rotate(angle=theta)
2019-04-06 23:42:22 +03:00
2013-10-12 09:18:28 +04:00
.. 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
2019-04-06 23:42:22 +03:00
2019-06-24 11:04:13 +03:00
This flips the input image by using the ``Image.FLIP_LEFT_RIGHT`` method.
2019-04-06 23:42:22 +03:00
.. code-block:: python
2019-06-24 10:45:53 +03:00
from PIL import Image
2019-06-24 11:04:13 +03:00
2019-06-24 10:48:33 +03:00
im = Image.open("hopper.jpg")
2019-04-06 23:42:22 +03:00
# Flip the image from left to right
2019-06-24 10:45:53 +03:00
im_flipped = im.transpose(method=Image.FLIP_LEFT_RIGHT)
2019-04-06 23:42:22 +03:00
# To flip the image from top to bottom,
# use the method "Image.FLIP_TOP_BOTTOM"
2019-06-24 10:45:53 +03:00
2019-04-06 23:42:22 +03:00
2013-10-12 09:18:28 +04:00
.. 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
2019-05-18 13:36:22 +03:00
Colour palette table, if any. If mode is "P" or "PA", this should be an
instance of the :py:class:`~PIL.ImagePalette.ImagePalette` class.
Otherwise, it should be set to ``None``.
2013-10-12 09:18:28 +04:00
: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`