Pillow/docs/reference/Image.rst

505 lines
14 KiB
ReStructuredText
Raw Normal View History

2013-10-12 09:18:28 +04:00
.. py:module:: PIL.Image
.. py:currentmodule:: PIL.Image
:py:mod:`~PIL.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
2021-02-25 15:41:31 +03:00
with Image.open("hopper.jpg") as im:
im.rotate(45).show()
2013-10-12 09:18:28 +04:00
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)
2021-02-25 15:41:31 +03:00
with Image.open(infile) as im:
im.thumbnail(size)
im.save(file + ".thumbnail", "JPEG")
2013-10-12 09:18:28 +04:00
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
2020-07-21 13:46:50 +03:00
a lot of memory), Pillow will issue a ``DecompressionBombWarning`` if the number of pixels in an
2022-09-03 13:53:22 +03:00
image is over a certain limit, :py:data:`MAX_IMAGE_PIXELS`.
2020-07-21 16:01:51 +03:00
2022-09-03 13:53:22 +03:00
This threshold can be changed by setting :py:data:`MAX_IMAGE_PIXELS`. It can be disabled
2020-07-21 16:01:51 +03:00
by setting ``Image.MAX_IMAGE_PIXELS = None``.
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.
2022-09-03 13:53:22 +03:00
If the number of pixels is greater than twice :py:data:`MAX_IMAGE_PIXELS`, then a
``DecompressionBombError`` will be raised instead.
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:: frombuffer
Generating images
^^^^^^^^^^^^^^^^^
.. autofunction:: effect_mandelbrot
.. autofunction:: effect_noise
.. autofunction:: linear_gradient
.. autofunction:: radial_gradient
2013-10-12 09:18:28 +04:00
Registering plugins
^^^^^^^^^^^^^^^^^^^
.. note::
These functions are for use by plugin authors. Application authors can
ignore them.
.. autofunction:: register_open
.. autofunction:: register_mime
.. autofunction:: register_save
.. autofunction:: register_save_all
2013-10-12 09:18:28 +04:00
.. autofunction:: register_extension
.. autofunction:: register_extensions
.. autofunction:: registered_extensions
.. autofunction:: register_decoder
.. autofunction:: register_encoder
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
2022-06-11 15:31:07 +03:00
.. automethod:: PIL.Image.Image.apply_transparency
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
2021-02-25 15:41:31 +03:00
with Image.open("hopper.jpg") as im:
2019-04-06 23:42:22 +03:00
2021-02-25 15:41:31 +03:00
# The crop method from the Image module takes four coordinates as input.
# The right can also be represented as (left+width)
# and lower can be represented as (upper+height).
(left, upper, right, lower) = (20, 20, 100, 100)
2019-06-24 10:45:53 +03:00
2021-02-25 15:41:31 +03:00
# Here the image "im" is cropped and assigned to new variable im_crop
im_crop = im.crop((left, upper, right, lower))
2019-04-06 23:42:22 +03:00
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.draft
.. automethod:: PIL.Image.Image.effect_spread
.. automethod:: PIL.Image.Image.entropy
2013-10-12 09:18:28 +04:00
.. 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
2021-02-25 15:41:31 +03:00
with Image.open("hopper.jpg") as im:
2019-04-06 23:42:22 +03:00
2021-02-25 15:41:31 +03:00
# Blur the input image using the filter ImageFilter.BLUR
im_blurred = im.filter(filter=ImageFilter.BLUR)
2019-04-06 23:42:22 +03:00
.. automethod:: PIL.Image.Image.frombytes
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
2021-02-25 15:41:31 +03:00
with Image.open("hopper.jpg") as im:
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
2021-02-25 15:41:31 +03:00
with Image.open("hopper.jpg") as im:
print(im.getbbox())
# Returns four coordinates in the format (left, upper, right, lower)
2019-06-24 10:45:53 +03:00
.. automethod:: PIL.Image.Image.getchannel
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.getcolors
.. automethod:: PIL.Image.Image.getdata
2020-04-11 11:01:13 +03:00
.. automethod:: PIL.Image.Image.getexif
.. 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.getprojection
2013-10-12 09:18:28 +04:00
.. automethod:: PIL.Image.Image.histogram
.. 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.reduce
.. automethod:: PIL.Image.Image.remap_palette
2013-10-12 09:18:28 +04:00
.. 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
2021-02-25 15:41:31 +03:00
with Image.open("hopper.jpg") as im:
2019-04-06 23:42:22 +03:00
2021-02-25 15:41:31 +03:00
# Provide the target width and height of the image
(width, height) = (im.width // 2, im.height // 2)
im_resized = im.resize((width, height))
2019-04-06 23:42:22 +03:00
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
2021-02-25 15:41:31 +03:00
with Image.open("hopper.jpg") as im:
2019-04-06 23:42:22 +03:00
2021-02-25 15:41:31 +03:00
# Rotate the image by 60 degrees counter clockwise
theta = 60
# Angle is in degrees counter clockwise
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.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.transform
.. automethod:: PIL.Image.Image.transpose
2019-04-06 23:42:22 +03:00
2022-09-03 13:53:22 +03:00
This flips the input image by using the :data:`Transpose.FLIP_LEFT_RIGHT`
2022-01-15 01:02:31 +03:00
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
2021-02-25 15:41:31 +03:00
with Image.open("hopper.jpg") as im:
2019-04-06 23:42:22 +03:00
2021-02-25 15:41:31 +03:00
# Flip the image from left to right
2022-01-15 01:02:31 +03:00
im_flipped = im.transpose(method=Image.Transpose.FLIP_LEFT_RIGHT)
2021-02-25 15:41:31 +03:00
# To flip the image from top to bottom,
2022-01-15 01:02:31 +03:00
# use the method "Image.Transpose.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.load
2014-04-18 08:53:49 +04:00
.. automethod:: PIL.Image.Image.close
2013-10-12 09:18:28 +04:00
Image Attributes
----------------
2013-10-12 09:18:28 +04:00
Instances of the :py:class:`Image` class have the following attributes:
.. py:attribute:: Image.filename
:type: str
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
.. py:attribute:: Image.format
:type: Optional[str]
2013-10-12 09:18:28 +04:00
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
2020-07-10 00:50:57 +03:00
image), this attribute is set to :data:`None`.
2013-10-12 09:18:28 +04:00
.. py:attribute:: Image.mode
:type: str
2013-10-12 09:18:28 +04:00
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
.. py:attribute:: Image.size
:type: tuple[int]
2013-10-12 09:18:28 +04:00
Image size, in pixels. The size is given as a 2-tuple (width, height).
.. py:attribute:: Image.width
:type: int
Image width, in pixels.
.. py:attribute:: Image.height
:type: int
Image height, in pixels.
.. py:attribute:: Image.palette
:type: Optional[PIL.ImagePalette.ImagePalette]
2013-10-12 09:18:28 +04:00
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.
2020-07-10 00:50:57 +03:00
Otherwise, it should be set to :data:`None`.
2013-10-12 09:18:28 +04:00
.. py:attribute:: Image.info
:type: dict
2013-10-12 09:18:28 +04:00
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.
2020-06-27 18:24:13 +03:00
.. py:attribute:: Image.is_animated
:type: bool
2020-07-05 14:47:23 +03:00
``True`` if this image has more than one frame, or ``False`` otherwise.
2020-06-27 18:24:13 +03:00
2020-07-05 14:47:23 +03:00
This attribute is only defined by image plugins that support animated images.
2020-06-27 18:24:13 +03:00
Plugins may leave this attribute undefined if they don't support loading
2020-07-05 14:47:23 +03:00
animated images, even if the given format supports animated images.
Given that this attribute is not present for all images use
``getattr(image, "is_animated", False)`` to check if Pillow is aware of multiple
frames in an image regardless of its format.
2020-06-27 18:24:13 +03:00
.. seealso:: :attr:`~Image.n_frames`, :func:`~Image.seek` and :func:`~Image.tell`
.. py:attribute:: Image.n_frames
:type: int
The number of frames in this image.
2020-07-05 14:47:23 +03:00
This attribute is only defined by image plugins that support animated images.
2020-06-27 18:24:13 +03:00
Plugins may leave this attribute undefined if they don't support loading
2020-07-05 14:47:23 +03:00
animated images, even if the given format supports animated images.
Given that this attribute is not present for all images use
``getattr(image, "n_frames", 1)`` to check the number of frames that Pillow is
aware of in an image regardless of its format.
2020-06-27 18:24:13 +03:00
.. seealso:: :attr:`~Image.is_animated`, :func:`~Image.seek` and :func:`~Image.tell`
Classes
-------
.. autoclass:: PIL.Image.Exif
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: PIL.Image.ImagePointHandler
.. autoclass:: PIL.Image.ImageTransformHandler
Constants
---------
.. data:: NONE
2020-07-20 14:16:33 +03:00
.. data:: MAX_IMAGE_PIXELS
Set to 89,478,485, approximately 0.25GB for a 24-bit (3 bpp) image.
2020-07-20 14:16:33 +03:00
See :py:meth:`~PIL.Image.open` for more information about how this is used.
Transpose methods
^^^^^^^^^^^^^^^^^
Used to specify the :meth:`Image.transpose` method to use.
2022-01-15 01:02:31 +03:00
.. autoclass:: Transpose
:members:
:undoc-members:
Transform methods
^^^^^^^^^^^^^^^^^
Used to specify the :meth:`Image.transform` method to use.
2022-01-15 01:02:31 +03:00
.. py:class:: Transform
.. py:attribute:: AFFINE
2022-01-15 01:02:31 +03:00
Affine transform
2022-01-15 01:02:31 +03:00
.. py:attribute:: EXTENT
2022-01-15 01:02:31 +03:00
Cut out a rectangular subregion
2022-01-15 01:02:31 +03:00
.. py:attribute:: PERSPECTIVE
2022-01-15 01:02:31 +03:00
Perspective transform
2022-01-15 01:02:31 +03:00
.. py:attribute:: QUAD
2022-01-15 01:02:31 +03:00
Map a quadrilateral to a rectangle
2022-01-15 01:02:31 +03:00
.. py:attribute:: MESH
2022-01-15 01:02:31 +03:00
Map a number of source quadrilaterals in one operation
Resampling filters
^^^^^^^^^^^^^^^^^^
See :ref:`concept-filters` for details.
2022-01-15 01:02:31 +03:00
.. autoclass:: Resampling
:members:
:undoc-members:
2022-01-15 01:02:31 +03:00
Some deprecated filters are also available under the following names:
.. data:: NONE
:noindex:
2022-01-15 01:02:31 +03:00
:value: Resampling.NEAREST
.. data:: LINEAR
2022-01-15 01:02:31 +03:00
:value: Resampling.BILINEAR
.. data:: CUBIC
2022-01-15 01:02:31 +03:00
:value: Resampling.BICUBIC
.. data:: ANTIALIAS
2022-01-15 01:02:31 +03:00
:value: Resampling.LANCZOS
Dither modes
^^^^^^^^^^^^
Used to specify the dithering method to use for the
:meth:`~Image.convert` and :meth:`~Image.quantize` methods.
2022-01-15 01:02:31 +03:00
.. py:class:: Dither
.. py:attribute:: NONE
No dither
2022-01-15 01:02:31 +03:00
.. py:attribute:: ORDERED
2022-01-15 01:02:31 +03:00
Not implemented
2022-01-15 01:02:31 +03:00
.. py:attribute:: RASTERIZE
2022-01-15 01:02:31 +03:00
Not implemented
.. py:attribute:: FLOYDSTEINBERG
Floyd-Steinberg dither
Palettes
^^^^^^^^
Used to specify the pallete to use for the :meth:`~Image.convert` method.
2022-01-15 01:02:31 +03:00
.. autoclass:: Palette
:members:
:undoc-members:
Quantization methods
^^^^^^^^^^^^^^^^^^^^
Used to specify the quantization method to use for the :meth:`~Image.quantize` method.
2022-01-15 01:02:31 +03:00
.. py:class:: Quantize
.. py:attribute:: MEDIANCUT
2022-01-15 01:02:31 +03:00
Median cut. Default method, except for RGBA images. This method does not support
RGBA images.
2022-01-15 01:02:31 +03:00
.. py:attribute:: MAXCOVERAGE
2022-01-15 01:02:31 +03:00
Maximum coverage. This method does not support RGBA images.
2022-01-15 01:02:31 +03:00
.. py:attribute:: FASTOCTREE
2022-01-15 01:02:31 +03:00
Fast octree. Default method for RGBA images.
2022-01-15 01:02:31 +03:00
.. py:attribute:: LIBIMAGEQUANT
2022-01-15 01:02:31 +03:00
libimagequant
2022-01-15 01:02:31 +03:00
Check support using :py:func:`PIL.features.check_feature` with
``feature="libimagequant"``.