python-pillow/Pillow
1
1
Fork 0
mirror of https://github.com/python-pillow/Pillow.git synced 2025-03-14 15:22:13 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge b24fbfaab6 into 7be6e26e7b

Browse Source
This commit is contained in:
Steve Johnson 2013-10-12 00:59:22 -07:00
commit 961595e0c0
10 changed files with 824 additions and 322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
PIL/Image.py
View File

@ -57,7 +57,7 @@ try:
except ImportError as v: except ImportError as v:
core = _imaging_not_installed() core = _imaging_not_installed()
# Explanations for ways that we know we might have an import error # Explanations for ways that we know we might have an import error
if str(v).startswith("Module use of python"): if str(v).startswith("Module use of python"):
# The _imaging C module is present, but not compiled for # The _imaging C module is present, but not compiled for
# the right version (windows only). Print a warning, if # the right version (windows only). Print a warning, if
@ -81,8 +81,8 @@ except ImportError as v:
"recompile PIL or build Python --with-wide-unicode. ", "recompile PIL or build Python --with-wide-unicode. ",
RuntimeWarning RuntimeWarning
) )
# Fail here anyway. Don't let people run with a mostly broken Pillow. # Fail here anyway. Don't let people run with a mostly broken Pillow.
raise raise
try: try:
import builtins import builtins
@ -281,10 +281,10 @@ def getmodetype(mode):
def getmodebandnames(mode): def getmodebandnames(mode):
""" """
Gets a list of individual band names. Given a mode, this function Gets a list of individual band names. Given a mode, this function returns
returns a tuple containing the names of individual bands (use a tuple containing the names of individual bands (use
:func:`PIL.Image.getmodetype` to get the mode used to store each individual :py:method:`~PIL.Image.getmodetype` to get the mode used to store each
band. individual band.
:param mode: Input mode. :param mode: Input mode.
:returns: A tuple containing band names. The length of the tuple :returns: A tuple containing band names. The length of the tuple
@ -443,13 +443,14 @@ def _getscaleoffset(expr):
class Image: class Image:
""" """
This class represents an image object. To create Image objects, use This class represents an image object. To create
the appropriate factory functions. There's hardly ever any reason :py:class:`~PIL.Image.Image` objects, use the appropriate factory
to call the Image constructor directly. functions. There's hardly ever any reason to call the Image constructor
directly.
* :func:`PIL.Image.open` * :py:func:`~PIL.Image.open`
* :func:`PIL.Image.new` * :py:func:`~PIL.Image.new`
* :func:`PIL.Image.frombytes` * :py:func:`~PIL.Image.frombytes`
""" """
format = None format = None
format_description = None format_description = None
@ -588,8 +589,8 @@ class Image:
""" """
Loads this image with pixel data from a bytes object. Loads this image with pixel data from a bytes object.
This method is similar to the :func:`PIL.Image.frombytes` function, but This method is similar to the :py:func:`~PIL.Image.frombytes` function,
loads data into this image instead of creating a new image object. but loads data into this image instead of creating a new image object.
""" """
# may pass tuple instead of argument list # may pass tuple instead of argument list
@ -611,7 +612,10 @@ class Image:
raise ValueError("cannot decode image data") raise ValueError("cannot decode image data")
def fromstring(self, *args, **kw): def fromstring(self, *args, **kw):
""" Deprecated alias to frombytes """ """Deprecated alias to frombytes.
.. deprecated:: 2.0
"""
warnings.warn('fromstring() is deprecated. Please call frombytes() instead.', DeprecationWarning) warnings.warn('fromstring() is deprecated. Please call frombytes() instead.', DeprecationWarning)
return self.frombytes(*args, **kw) return self.frombytes(*args, **kw)
@ -651,7 +655,7 @@ class Image:
""" """
pass pass
def convert(self, mode=None, data=None, dither=None, def convert(self, mode=None, matrix=None, dither=None,
palette=WEB, colors=256): palette=WEB, colors=256):
""" """
Returns a converted copy of this image. For the "P" mode, this Returns a converted copy of this image. For the "P" mode, this
@ -660,16 +664,17 @@ class Image:
and the palette can be represented without a palette. and the palette can be represented without a palette.
The current version supports all possible conversions between The current version supports all possible conversions between
"L", "RGB" and "CMYK." "L", "RGB" and "CMYK." The **matrix** argument only supports "L"
and "RGB".
When translating a colour image to black and white (mode "L"), When translating a color image to black and white (mode "L"),
the library uses the ITU-R 601-2 luma transform: the library uses the ITU-R 601-2 luma transform::
L = R * 299/1000 + G * 587/1000 + B * 114/1000 L = R * 299/1000 + G * 587/1000 + B * 114/1000
When translating a greyscale image into a bilevel image (mode When translating a greyscale image into a bilevel image (mode
"1"), all non-zero values are set to 255 (white). To use other "1"), all non-zero values are set to 255 (white). To use other
thresholds, use the :func:`PIL.Image.Image.point` method. thresholds, use the :py:meth:`~PIL.Image.Image.point` method.
:param mode: The requested mode. :param mode: The requested mode.
:param matrix: An optional conversion matrix. If given, this :param matrix: An optional conversion matrix. If given, this
@ -681,8 +686,8 @@ class Image:
to "P". Available palettes are WEB or ADAPTIVE. to "P". Available palettes are WEB or ADAPTIVE.
:param colors: Number of colors to use for the ADAPTIVE palette. :param colors: Number of colors to use for the ADAPTIVE palette.
Defaults to 256. Defaults to 256.
:rtype: :class:`PIL.Image.Image` :rtype: :py:class:`~PIL.Image.Image`
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
if not mode: if not mode:
@ -698,18 +703,18 @@ class Image:
self.load() self.load()
if data: if matrix:
# matrix conversion # matrix conversion
if mode not in ("L", "RGB"): if mode not in ("L", "RGB"):
raise ValueError("illegal conversion") raise ValueError("illegal conversion")
im = self.im.convert_matrix(mode, data) im = self.im.convert_matrix(mode, matrix)
return self._new(im) return self._new(im)
if mode == "P" and palette == ADAPTIVE: if mode == "P" and palette == ADAPTIVE:
im = self.im.quantize(colors) im = self.im.quantize(colors)
return self._new(im) return self._new(im)
# colourspace conversion # colorspace conversion
if dither is None: if dither is None:
dither = FLOYDSTEINBERG dither = FLOYDSTEINBERG
@ -767,8 +772,8 @@ class Image:
Copies this image. Use this method if you wish to paste things Copies this image. Use this method if you wish to paste things
into an image, but still retain the original. into an image, but still retain the original.
:rtype: :class:`PIL.Image.Image` :rtype: :py:class:`~PIL.Image.Image`
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
self.load() self.load()
im = self.im.copy() im = self.im.copy()
@ -782,12 +787,12 @@ class Image:
This is a lazy operation. Changes to the source image may or This is a lazy operation. Changes to the source image may or
may not be reflected in the cropped image. To break the may not be reflected in the cropped image. To break the
connection, call the {@link #Image.load} method on the cropped connection, call the :py:meth:`~PIL.Image.Image.load` method on
copy. the cropped copy.
:param box: The crop rectangle, as a (left, upper, right, lower)-tuple. :param box: The crop rectangle, as a (left, upper, right, lower)-tuple.
:rtype: :class:`PIL.Image.Image` :rtype: :py:class:`~PIL.Image.Image`
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
self.load() self.load()
@ -801,12 +806,13 @@ class Image:
""" """
Configures the image file loader so it returns a version of the Configures the image file loader so it returns a version of the
image that as closely as possible matches the given mode and image that as closely as possible matches the given mode and
size. For example, you can use this method to convert a colour size. For example, you can use this method to convert a color
JPEG to greyscale while loading it, or to extract a 128x192 JPEG to greyscale while loading it, or to extract a 128x192
version from a PCD file. version from a PCD file.
Note that this method modifies the Image object in place. If Note that this method modifies the :py:class:`~PIL.Image.Image` object
the image has already been loaded, this method has no effect. in place. If the image has already been loaded, this method has no
effect.
:param mode: The requested mode. :param mode: The requested mode.
:param size: The requested size. :param size: The requested size.
@ -822,11 +828,10 @@ class Image:
def filter(self, filter): def filter(self, filter):
""" """
Filters this image using the given filter. For a list of Filters this image using the given filter. For a list of
available filters, see the :mod:`PIL.ImageFilter` module. available filters, see the :py:mod:`~PIL.ImageFilter` module.
:param filter: Filter kernel. :param filter: Filter kernel.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object. """
"""
self.load() self.load()
@ -1014,18 +1019,18 @@ class Image:
def offset(self, xoffset, yoffset=None): def offset(self, xoffset, yoffset=None):
""" """
(Deprecated) Returns a copy of the image where the data has been .. deprecated:: 2.0
offset by the given distances. Data wraps around the edges. If
yoffset is omitted, it is assumed to be equal to xoffset.
This method is deprecated. New code should use the .. note:: New code should use :py:func:`PIL.ImageChops.offset`.
:func:`PIL.ImageChops.offset` function in the
:mod:`PIL.ImageChops` module. Returns a copy of the image where the data has been offset by the given
distances. Data wraps around the edges. If **yoffset** is omitted, it
is assumed to be equal to **xoffset**.
:param xoffset: The horizontal distance. :param xoffset: The horizontal distance.
:param yoffset: The vertical distance. If omitted, both :param yoffset: The vertical distance. If omitted, both
distances are set to the same value. distances are set to the same value.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
if warnings: if warnings:
warnings.warn( warnings.warn(
@ -1043,14 +1048,14 @@ class Image:
(0, 0)). If a 4-tuple is given, the size of the pasted image (0, 0)). If a 4-tuple is given, the size of the pasted image
must match the size of the region. must match the size of the region.
If the modes don't match, the pasted image is converted to the If the modes don't match, the pasted image is converted to the mode of
mode of this image (see the :func:`PIL.Image.Image.convert` method for this image (see the :py:meth:`~PIL.Image.Image.convert` method for
details). details).
Instead of an image, the source can be a integer or tuple Instead of an image, the source can be a integer or tuple
containing pixel values. The method then fills the region containing pixel values. The method then fills the region
with the given colour. When creating RGB images, you can with the given color. When creating RGB images, you can
also use colour strings as supported by the ImageColor module. also use color strings as supported by the ImageColor module.
If a mask is given, this method updates only the regions If a mask is given, this method updates only the regions
indicated by the mask. You can use either "1", "L" or "RGBA" indicated by the mask. You can use either "1", "L" or "RGBA"
@ -1073,7 +1078,7 @@ class Image:
third, the box defaults to (0, 0), and the second argument third, the box defaults to (0, 0), and the second argument
is interpreted as a mask image. is interpreted as a mask image.
:param mask: An optional mask image. :param mask: An optional mask image.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
if isImageType(box) and mask is None: if isImageType(box) and mask is None:
@ -1131,7 +1136,7 @@ class Image:
:param mode: Output mode (default is same as input). In the :param mode: Output mode (default is same as input). In the
current version, this can only be used if the source image current version, this can only be used if the source image
has mode "L" or "P", and the output has mode "1". has mode "L" or "P", and the output has mode "1".
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
self.load() self.load()
@ -1260,19 +1265,19 @@ class Image:
def putpixel(self, xy, value): def putpixel(self, xy, value):
""" """
Modifies the pixel at the given position. The colour is given as Modifies the pixel at the given position. The color is given as
a single numerical value for single-band images, and a tuple for a single numerical value for single-band images, and a tuple for
multi-band images. multi-band images.
Note that this method is relatively slow. For more extensive Note that this method is relatively slow. For more extensive changes,
changes, use :func:`PIL.Image.Image.paste` or the :mod:`PIL.ImageDraw` use :py:meth:`~PIL.Image.Image.paste` or the :py:mod:`~PIL.ImageDraw`
module instead. module instead.
See: See:
* :func:`PIL.Image.Image.paste` * :py:meth:`~PIL.Image.Image.paste`
* :func:`PIL.Image.Image.putdata` * :py:meth:`~PIL.Image.Image.putdata`
* :mod:`PIL.ImageDraw` * :py:mod:`~PIL.ImageDraw`
:param xy: The pixel coordinate, given as (x, y). :param xy: The pixel coordinate, given as (x, y).
:param value: The pixel value. :param value: The pixel value.
@ -1291,14 +1296,14 @@ class Image:
:param size: The requested size in pixels, as a 2-tuple: :param size: The requested size in pixels, as a 2-tuple:
(width, height). (width, height).
:param filter: An optional resampling filter. This can be :param filter: An optional resampling filter. This can be
one of :attr:`PIL.Image.NEAREST` (use nearest neighbour), one of :py:attr:`PIL.Image.NEAREST` (use nearest neighbour),
:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2 :py:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
environment), :attr:`PIL.Image.BICUBIC` (cubic spline environment), :py:attr:`PIL.Image.BICUBIC` (cubic spline
interpolation in a 4x4 environment), or interpolation in a 4x4 environment), or
:attr:`PIL.Image.ANTIALIAS` (a high-quality downsampling filter). :py:attr:`PIL.Image.ANTIALIAS` (a high-quality downsampling filter).
If omitted, or if the image has mode "1" or "P", it is If omitted, or if the image has mode "1" or "P", it is
set :attr:`PIL.Image.NEAREST`. set :py:attr:`PIL.Image.NEAREST`.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
if resample not in (NEAREST, BILINEAR, BICUBIC, ANTIALIAS): if resample not in (NEAREST, BILINEAR, BICUBIC, ANTIALIAS):
@ -1331,17 +1336,17 @@ class Image:
:param angle: In degrees counter clockwise. :param angle: In degrees counter clockwise.
:param filter: An optional resampling filter. This can be :param filter: An optional resampling filter. This can be
one of :attr:`PIL.Image.NEAREST` (use nearest neighbour), one of :py:attr:`PIL.Image.NEAREST` (use nearest neighbour),
:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2 :py:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
environment), or :attr:`PIL.Image.BICUBIC` environment), or :py:attr:`PIL.Image.BICUBIC`
(cubic spline interpolation in a 4x4 environment). (cubic spline interpolation in a 4x4 environment).
If omitted, or if the image has mode "1" or "P", it is If omitted, or if the image has mode "1" or "P", it is
set :attr:`PIL.Image.NEAREST`. set :py:attr:`PIL.Image.NEAREST`.
:param expand: Optional expansion flag. If true, expands the output :param expand: Optional expansion flag. If true, expands the output
image to make it large enough to hold the entire rotated image. image to make it large enough to hold the entire rotated image.
If false or omitted, make the output image the same size as the If false or omitted, make the output image the same size as the
input image. input image.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
if expand: if expand:
@ -1469,7 +1474,7 @@ class Image:
Note that in the current version of the library, most sequence Note that in the current version of the library, most sequence
formats only allows you to seek to the next frame. formats only allows you to seek to the next frame.
See :func:`PIL.Image.Image.tell`. See :py:meth:`~PIL.Image.Image.tell`.
:param frame: Frame number, starting at 0. :param frame: Frame number, starting at 0.
:exception EOFError: If the call attempts to seek beyond the end :exception EOFError: If the call attempts to seek beyond the end
@ -1520,7 +1525,7 @@ class Image:
def tell(self): def tell(self):
""" """
Returns the current frame number. See :func:`PIL.Image.Image.seek`. Returns the current frame number. See :py:meth:`~PIL.Image.Image.seek`.
:returns: Frame number, starting with 0. :returns: Frame number, starting with 0.
""" """
@ -1532,24 +1537,24 @@ class Image:
image to contain a thumbnail version of itself, no larger than image to contain a thumbnail version of itself, no larger than
the given size. This method calculates an appropriate thumbnail the given size. This method calculates an appropriate thumbnail
size to preserve the aspect of the image, calls the size to preserve the aspect of the image, calls the
:func:`PIL.Image.Image.draft` method to configure the file reader :py:meth:`~PIL.Image.Image.draft` method to configure the file reader
(where applicable), and finally resizes the image. (where applicable), and finally resizes the image.
Note that the bilinear and bicubic filters in the current Note that the bilinear and bicubic filters in the current
version of PIL are not well-suited for thumbnail generation. version of PIL are not well-suited for thumbnail generation.
You should use :attr:`PIL.Image.ANTIALIAS` unless speed is much more You should use :py:attr:`PIL.Image.ANTIALIAS` unless speed is much more
important than quality. important than quality.
Also note that this function modifies the Image object in place. Also note that this function modifies the :py:class:`~PIL.Image.Image`
If you need to use the full resolution image as well, apply this object in place. If you need to use the full resolution image as well, apply
method to a :func:`PIL.Image.Image.copy` of the original image. this method to a :py:meth:`~PIL.Image.Image.copy` of the original image.
:param size: Requested size. :param size: Requested size.
:param resample: Optional resampling filter. This can be one :param resample: Optional resampling filter. This can be one
of :attr:`PIL.Image.NEAREST`, :attr:`PIL.Image.BILINEAR`, of :py:attr:`PIL.Image.NEAREST`, :py:attr:`PIL.Image.BILINEAR`,
:attr:`PIL.Image.BICUBIC`, or :attr:`PIL.Image.ANTIALIAS` :py:attr:`PIL.Image.BICUBIC`, or :py:attr:`PIL.Image.ANTIALIAS`
(best quality). If omitted, it defaults to (best quality). If omitted, it defaults to
:attr:`PIL.Image.NEAREST` (this will be changed to ANTIALIAS in a :py:attr:`PIL.Image.NEAREST` (this will be changed to ANTIALIAS in a
future version). future version).
:returns: None :returns: None
""" """
@ -1593,20 +1598,20 @@ class Image:
:param size: The output size. :param size: The output size.
:param method: The transformation method. This is one of :param method: The transformation method. This is one of
:attr:`PIL.Image.EXTENT` (cut out a rectangular subregion), :py:attr:`PIL.Image.EXTENT` (cut out a rectangular subregion),
:attr:`PIL.Image.AFFINE` (affine transform), :py:attr:`PIL.Image.AFFINE` (affine transform),
:attr:`PIL.Image.PERSPECTIVE` (perspective transform), :py:attr:`PIL.Image.PERSPECTIVE` (perspective transform),
:attr:`PIL.Image.QUAD` (map a quadrilateral to a rectangle), or :py:attr:`PIL.Image.QUAD` (map a quadrilateral to a rectangle), or
:attr:`PIL.Image.MESH` (map a number of source quadrilaterals :py:attr:`PIL.Image.MESH` (map a number of source quadrilaterals
in one operation). in one operation).
:param data: Extra data to the transformation method. :param data: Extra data to the transformation method.
:param resample: Optional resampling filter. It can be one of :param resample: Optional resampling filter. It can be one of
:attr:`PIL.Image.NEAREST` (use nearest neighbour), :py:attr:`PIL.Image.NEAREST` (use nearest neighbour),
:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2 :py:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
environment), or :attr:`PIL.Image.BICUBIC` (cubic spline environment), or :py:attr:`PIL.Image.BICUBIC` (cubic spline
interpolation in a 4x4 environment). If omitted, or if the image interpolation in a 4x4 environment). If omitted, or if the image
has mode "1" or "P", it is set to :attr:`PIL.Image.NEAREST`. has mode "1" or "P", it is set to :py:attr:`PIL.Image.NEAREST`.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
if self.mode == 'RGBA': if self.mode == 'RGBA':
@ -1619,7 +1624,7 @@ class Image:
method, data = method.getdata() method, data = method.getdata()
if data is None: if data is None:
raise ValueError("missing method data") raise ValueError("missing method data")
im = new(self.mode, size, None) im = new(self.mode, size, None)
if method == MESH: if method == MESH:
# list of quads # list of quads
@ -1627,7 +1632,7 @@ class Image:
im.__transformer(box, self, QUAD, quad, resample, fill) im.__transformer(box, self, QUAD, quad, resample, fill)
else: else:
im.__transformer((0, 0)+size, self, method, data, resample, fill) im.__transformer((0, 0)+size, self, method, data, resample, fill)
return im return im
def __transformer(self, box, image, method, data, def __transformer(self, box, image, method, data,
@ -1682,9 +1687,9 @@ class Image:
""" """
Transpose image (flip or rotate in 90 degree steps) Transpose image (flip or rotate in 90 degree steps)
:param method: One of :attr:`PIL.Image.FLIP_LEFT_RIGHT`, :param method: One of :py:attr:`PIL.Image.FLIP_LEFT_RIGHT`,
:attr:`PIL.Image.FLIP_TOP_BOTTOM`, :attr:`PIL.Image.ROTATE_90`, :py:attr:`PIL.Image.FLIP_TOP_BOTTOM`, :py:attr:`PIL.Image.ROTATE_90`,
:attr:`PIL.Image.ROTATE_180`, or :attr:`PIL.Image.ROTATE_270`. :py:attr:`PIL.Image.ROTATE_180`, or :py:attr:`PIL.Image.ROTATE_270`.
:returns: Returns a flipped or rotated copy of this image. :returns: Returns a flipped or rotated copy of this image.
""" """
@ -1756,13 +1761,13 @@ def new(mode, size, color=0):
:param mode: The mode to use for the new image. :param mode: The mode to use for the new image.
:param size: A 2-tuple, containing (width, height) in pixels. :param size: A 2-tuple, containing (width, height) in pixels.
:param color: What colour to use for the image. Default is black. :param color: What color to use for the image. Default is black.
If given, this should be a single integer or floating point value If given, this should be a single integer or floating point value
for single-band modes, and a tuple for multi-band modes (one value for single-band modes, and a tuple for multi-band modes (one value
per band). When creating RGB images, you can also use colour per band). When creating RGB images, you can also use color
strings as supported by the ImageColor module. If the colour is strings as supported by the ImageColor module. If the color is
None, the image is not initialised. None, the image is not initialised.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
if color is None: if color is None:
@ -1791,14 +1796,15 @@ def frombytes(mode, size, data, decoder_name="raw", *args):
Note that this function decodes pixel data only, not entire images. Note that this function decodes pixel data only, not entire images.
If you have an entire image in a string, wrap it in a If you have an entire image in a string, wrap it in a
**BytesIO** object, and use :func:`PIL.Image.open` to load it. :py:class:`~io.BytesIO` object, and use :py:func:`~PIL.Image.open` to load
it.
:param mode: The image mode. :param mode: The image mode.
:param size: The image size. :param size: The image size.
:param data: A byte buffer containing raw data for the given mode. :param data: A byte buffer containing raw data for the given mode.
:param decoder_name: What decoder to use. :param decoder_name: What decoder to use.
:param args: Additional parameters for the given decoder. :param args: Additional parameters for the given decoder.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
# may pass tuple instead of argument list # may pass tuple instead of argument list
@ -1813,7 +1819,10 @@ def frombytes(mode, size, data, decoder_name="raw", *args):
return im return im
def fromstring(*args, **kw): def fromstring(*args, **kw):
" Deprecated alias to frombytes " """Deprecated alias to frombytes.
.. deprecated:: 2.0
"""
warnings.warn( warnings.warn(
'fromstring() is deprecated. Please call frombytes() instead.', 'fromstring() is deprecated. Please call frombytes() instead.',
DeprecationWarning, DeprecationWarning,
@ -1826,21 +1835,20 @@ def frombuffer(mode, size, data, decoder_name="raw", *args):
""" """
Creates an image memory referencing pixel data in a byte buffer. Creates an image memory referencing pixel data in a byte buffer.
This function is similar to :func:`PIL.Image.frombytes`, but uses data in This function is similar to :py:func:`~PIL.Image.frombytes`, but uses data
the byte buffer, where possible. This means that changes to the in the byte buffer, where possible. This means that changes to the
original buffer object are reflected in this image). Not all modes original buffer object are reflected in this image). Not all modes can
can share memory; supported modes include "L", "RGBX", "RGBA", and share memory; supported modes include "L", "RGBX", "RGBA", and "CMYK".
"CMYK".
Note that this function decodes pixel data only, not entire images. Note that this function decodes pixel data only, not entire images.
If you have an entire image file in a string, wrap it in a If you have an entire image file in a string, wrap it in a
**BytesIO** object, and use :func:`PIL.Image.open` to load it. **BytesIO** object, and use :py:func:`~PIL.Image.open` to load it.
In the current version, the default parameters used for the "raw" decoder In the current version, the default parameters used for the "raw" decoder
differs from that used for :func:`PIL.Image.fromstring`. This is a bug, differs from that used for :py:func:`~PIL.Image.fromstring`. This is a
and will probably be fixed in a future release. The current release issues bug, and will probably be fixed in a future release. The current release
a warning if you do this; to disable the warning, you should provide the issues a warning if you do this; to disable the warning, you should provide
full set of parameters. See below for details. the full set of parameters. See below for details.
:param mode: The image mode. :param mode: The image mode.
:param size: The image size. :param size: The image size.
@ -1853,7 +1861,7 @@ def frombuffer(mode, size, data, decoder_name="raw", *args):
frombuffer(mode, size, data, "raw", mode, 0, 1) frombuffer(mode, size, data, "raw", mode, 0, 1)
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
.. versionadded:: 1.1.4 .. versionadded:: 1.1.4
""" """
@ -1890,7 +1898,7 @@ def fromarray(obj, mode=None):
(using the buffer protocol). (using the buffer protocol).
If obj is not contiguous, then the tobytes method is called If obj is not contiguous, then the tobytes method is called
and :func:`PIL.Image.frombuffer` is used. and :py:func:`~PIL.Image.frombuffer` is used.
:param obj: Object with array interface :param obj: Object with array interface
:param mode: Mode to use (will be determined from type if None) :param mode: Mode to use (will be determined from type if None)
@ -1961,14 +1969,14 @@ def open(fp, mode="r"):
This is a lazy operation; this function identifies the file, but the This is a lazy operation; this function identifies the file, but the
actual image data is not read from the file until you try to process actual image data is not read from the file until you try to process
the data (or call the :func:`PIL.Image.Image.load` method). the data (or call the :py:meth:`~PIL.Image.Image.load` method).
See :func:`PIL.Image.new` See :py:func:`~PIL.Image.new`.
:param file: A filename (string) or a file object. The file object :param file: A filename (string) or a file object. The file object
must implement **read**, **seek**, and **tell** methods, must implement :py:meth:`~file.read`, :py:meth:`~file.seek`, and
and be opened in binary mode. :py:meth:`~file.tell` methods, and be opened in binary mode.
:param mode: The mode. If given, this argument must be "r". :param mode: The mode. If given, this argument must be "r".
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
:exception IOError: If the file cannot be found, or the image cannot be :exception IOError: If the file cannot be found, or the image cannot be
opened and identified. opened and identified.
""" """
@ -2022,7 +2030,7 @@ def alpha_composite(im1, im2):
:param im1: The first image. :param im1: The first image.
:param im2: The second image. Must have the same mode and size as :param im2: The second image. Must have the same mode and size as
the first image. the first image.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
im1.load() im1.load()
@ -2045,7 +2053,7 @@ def blend(im1, im2, alpha):
the second image is returned. There are no restrictions on the the second image is returned. There are no restrictions on the
alpha value. If necessary, the result is clipped to fit into alpha value. If necessary, the result is clipped to fit into
the allowed output range. the allowed output range.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
im1.load() im1.load()
@ -2080,7 +2088,7 @@ def eval(image, *args):
:param image: The input image. :param image: The input image.
:param function: A function object, taking one integer argument. :param function: A function object, taking one integer argument.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
return image.point(args[0]) return image.point(args[0])
@ -2094,7 +2102,7 @@ def merge(mode, bands):
:param bands: A sequence containing one single-band image for :param bands: A sequence containing one single-band image for
each band in the output image. All bands must have the each band in the output image. All bands must have the
same size. same size.
:returns: An Image object. :returns: An :py:class:`~PIL.Image.Image` object.
""" """
if getmodebands(mode) != len(bands) or "*" in mode: if getmodebands(mode) != len(bands) or "*" in mode:

315
PIL/ImageChops.py
View File

@ -17,285 +17,266 @@
from PIL import Image from PIL import Image
##
# The <b>ImageChops</b> module contains a number of arithmetical image
# operations, called <i>channel operations</i> ("chops"). These can be
# used for various purposes, including special effects, image
# compositions, algorithmic painting, and more.
# <p>
# At this time, channel operations are only implemented for 8-bit
# images (e.g. &quot;L&quot; and &quot;RGB&quot;).
# <p>
# Most channel operations take one or two image arguments and returns
# a new image. Unless otherwise noted, the result of a channel
# operation is always clipped to the range 0 to MAX (which is 255 for
# all modes supported by the operations in this module).
##
##
# Return an image with the same size as the given image, but filled
# with the given pixel value.
#
# @param image Reference image.
# @param value Pixel value.
# @return An image object.
def constant(image, value): def constant(image, value):
"Fill a channel with a given grey level" """Fill a channel with a given grey level.
:rtype: :py:class:`~PIL.Image.Image`
"""
return Image.new("L", image.size, value) return Image.new("L", image.size, value)
##
# Copy image.
#
# @param image Source image.
# @return A copy of the source image.
def duplicate(image): def duplicate(image):
"Create a copy of a channel" """Copy a channel. Alias for :py:meth:`PIL.Image.Image.copy`.
:rtype: :py:class:`~PIL.Image.Image`
"""
return image.copy() return image.copy()
##
# Inverts an image
# (MAX - image).
#
# @param image Source image.
# @return An image object.
def invert(image): def invert(image):
"Invert a channel" """
Invert an image (channel).
.. code-block:: python
out = MAX - image
:rtype: :py:class:`~PIL.Image.Image`
"""
image.load() image.load()
return image._new(image.im.chop_invert()) return image._new(image.im.chop_invert())
##
# Compare images, and return lighter pixel value
# (max(image1, image2)).
# <p>
# Compares the two images, pixel by pixel, and returns a new image
# containing the lighter values.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def lighter(image1, image2): def lighter(image1, image2):
"Select the lighter pixels from each image" """
Compares the two images, pixel by pixel, and returns a new image containing
the lighter values.
.. code-block:: python
out = max(image1, image2)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_lighter(image2.im)) return image1._new(image1.im.chop_lighter(image2.im))
##
# Compare images, and return darker pixel value
# (min(image1, image2)).
# <p>
# Compares the two images, pixel by pixel, and returns a new image
# containing the darker values.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def darker(image1, image2): def darker(image1, image2):
"Select the darker pixels from each image" """
Compares the two images, pixel by pixel, and returns a new image
containing the darker values.
.. code-block:: python
out = min(image1, image2)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_darker(image2.im)) return image1._new(image1.im.chop_darker(image2.im))
##
# Calculate absolute difference
# (abs(image1 - image2)).
# <p>
# Returns the absolute value of the difference between the two images.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def difference(image1, image2): def difference(image1, image2):
"Subtract one image from another" """
Returns the absolute value of the pixel-by-pixel difference between the two
images.
.. code-block:: python
out = abs(image1 - image2)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_difference(image2.im)) return image1._new(image1.im.chop_difference(image2.im))
##
# Superimpose positive images
# (image1 * image2 / MAX).
# <p>
# Superimposes two images on top of each other. If you multiply an
# image with a solid black image, the result is black. If you multiply
# with a solid white image, the image is unaffected.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def multiply(image1, image2): def multiply(image1, image2):
"Superimpose two positive images" """
Superimposes two images on top of each other.
If you multiply an image with a solid black image, the result is black. If
you multiply with a solid white image, the image is unaffected.
.. code-block:: python
out = image1 * image2 / MAX
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_multiply(image2.im)) return image1._new(image1.im.chop_multiply(image2.im))
##
# Superimpose negative images
# (MAX - ((MAX - image1) * (MAX - image2) / MAX)).
# <p>
# Superimposes two inverted images on top of each other.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def screen(image1, image2): def screen(image1, image2):
"Superimpose two negative images" """
Superimposes two inverted images on top of each other.
.. code-block:: python
out = MAX - ((MAX - image1) * (MAX - image2) / MAX)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_screen(image2.im)) return image1._new(image1.im.chop_screen(image2.im))
##
# Add images
# ((image1 + image2) / scale + offset).
# <p>
# Adds two images, dividing the result by scale and adding the
# offset. If omitted, scale defaults to 1.0, and offset to 0.0.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def add(image1, image2, scale=1.0, offset=0): def add(image1, image2, scale=1.0, offset=0):
"Add two images" """
Adds two images, dividing the result by scale and adding the
offset. If omitted, scale defaults to 1.0, and offset to 0.0.
.. code-block:: python
out = ((image1 + image2) / scale + offset)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_add(image2.im, scale, offset)) return image1._new(image1.im.chop_add(image2.im, scale, offset))
##
# Subtract images
# ((image1 - image2) / scale + offset).
# <p>
# Subtracts two images, dividing the result by scale and adding the
# offset. If omitted, scale defaults to 1.0, and offset to 0.0.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def subtract(image1, image2, scale=1.0, offset=0): def subtract(image1, image2, scale=1.0, offset=0):
"Subtract two images" """
Subtracts two images, dividing the result by scale and adding the
offset. If omitted, scale defaults to 1.0, and offset to 0.0.
.. code-block:: python
out = ((image1 - image2) / scale + offset)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_subtract(image2.im, scale, offset)) return image1._new(image1.im.chop_subtract(image2.im, scale, offset))
##
# Add images without clipping
# ((image1 + image2) % MAX).
# <p>
# Adds two images, without clipping the result.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def add_modulo(image1, image2): def add_modulo(image1, image2):
"Add two images without clipping" """Add two images, without clipping the result.
.. code-block:: python
out = ((image1 + image2) % MAX)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_add_modulo(image2.im)) return image1._new(image1.im.chop_add_modulo(image2.im))
##
# Subtract images without clipping
# ((image1 - image2) % MAX).
# <p>
# Subtracts two images, without clipping the result.
#
# @param image1 First image.
# @param image1 Second image.
# @return An image object.
def subtract_modulo(image1, image2): def subtract_modulo(image1, image2):
"Subtract two images without clipping" """Subtract two images, without clipping the result.
.. code-block:: python
out = ((image1 - image2) % MAX)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_subtract_modulo(image2.im)) return image1._new(image1.im.chop_subtract_modulo(image2.im))
##
# Logical AND
# (image1 and image2).
def logical_and(image1, image2): def logical_and(image1, image2):
"Logical and between two images" """Logical AND between two images.
.. code-block:: python
out = ((image1 and image2) % MAX)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_and(image2.im)) return image1._new(image1.im.chop_and(image2.im))
##
# Logical OR
# (image1 or image2).
def logical_or(image1, image2): def logical_or(image1, image2):
"Logical or between two images" """Logical OR between two images.
.. code-block:: python
out = ((image1 or image2) % MAX)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_or(image2.im)) return image1._new(image1.im.chop_or(image2.im))
##
# Logical XOR
# (image1 xor image2).
def logical_xor(image1, image2): def logical_xor(image1, image2):
"Logical xor between two images" """Logical XOR between two images.
.. code-block:: python
out = ((bool(image1) != bool(image2)) % MAX)
:rtype: :py:class:`~PIL.Image.Image`
"""
image1.load() image1.load()
image2.load() image2.load()
return image1._new(image1.im.chop_xor(image2.im)) return image1._new(image1.im.chop_xor(image2.im))
##
# Blend images using constant transparency weight.
# <p>
# Same as the <b>blend</b> function in the <b>Image</b> module.
def blend(image1, image2, alpha): def blend(image1, image2, alpha):
"Blend two images using a constant transparency weight" """Blend images using constant transparency weight. Alias for
:py:meth:`PIL.Image.Image.blend`.
:rtype: :py:class:`~PIL.Image.Image`
"""
return Image.blend(image1, image2, alpha) return Image.blend(image1, image2, alpha)
##
# Create composite using transparency mask.
# <p>
# Same as the <b>composite</b> function in the <b>Image</b> module.
def composite(image1, image2, mask): def composite(image1, image2, mask):
"Create composite image by blending images using a transparency mask" """Create composite using transparency mask. Alias for
:py:meth:`PIL.Image.Image.composite`.
:rtype: :py:class:`~PIL.Image.Image`
"""
return Image.composite(image1, image2, mask) return Image.composite(image1, image2, mask)
##
# Offset image data.
# <p>
# Returns a copy of the image where data has been offset by the given
# distances. Data wraps around the edges. If yoffset is omitted, it
# is assumed to be equal to xoffset.
#
# @param image Source image.
# @param xoffset The horizontal distance.
# @param yoffset The vertical distance. If omitted, both
# distances are set to the same value.
# @return An Image object.
def offset(image, xoffset, yoffset=None): def offset(image, xoffset, yoffset=None):
"Offset image in horizontal and/or vertical direction" """Returns a copy of the image where data has been offset by the given
distances. Data wraps around the edges. If **yoffset** is omitted, it
is assumed to be equal to **xoffset**.
:param xoffset: The horizontal distance.
:param yoffset: The vertical distance. If omitted, both
distances are set to the same value.
:rtype: :py:class:`~PIL.Image.Image`
"""
if yoffset is None: if yoffset is None:
yoffset = xoffset yoffset = xoffset
image.load() image.load()

19
PIL/ImageColor.py
View File

@ -30,6 +30,15 @@ import re
# as an RGB value. # as an RGB value.
def getrgb(color): def getrgb(color):
"""
Convert a color string to an RGB tuple. If the string cannot be parsed,
this function raises a :py:exc:`ValueError` exception.
.. versionadded:: 1.1.4
:param color: A color string
:return: ``(red, green, blue)``
"""
try: try:
rgb = colormap[color] rgb = colormap[color]
except KeyError: except KeyError:
@ -97,6 +106,16 @@ def getrgb(color):
raise ValueError("unknown color specifier: %r" % color) raise ValueError("unknown color specifier: %r" % color)
def getcolor(color, mode): def getcolor(color, mode):
"""
Same as :py:func:`~PIL.ImageColor.getrgb`, but converts the RGB value to a
greyscale value if the mode is not color or a palette image. If the string
cannot be parsed, this function raises a :py:exc:`ValueError` exception.
.. versionadded:: 1.1.4
:param color: A color string
:return: ``(red, green, blue)``
"""
# same as getrgb, but converts the result to the given mode # same as getrgb, but converts the result to the given mode
color = getrgb(color) color = getrgb(color)
if mode == "RGB": if mode == "RGB":

37
docs/PIL.rst
View File

@ -1,13 +1,8 @@
PIL Package PIL Package (autodoc of remaining modules)
=========== ==========================================
:mod:`Image` Module Reference for modules whose documentation has not yet been ported or written
------------------- can be found here.
.. automodule:: PIL.Image
:members:
:undoc-members:
:show-inheritance:
:mod:`BdfFontFile` Module :mod:`BdfFontFile` Module
------------------------- -------------------------
@ -65,14 +60,6 @@ PIL Package
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
:mod:`ImageChops` Module
------------------------
.. automodule:: PIL.ImageChops
:members:
:undoc-members:
:show-inheritance:
:mod:`ImageCms` Module :mod:`ImageCms` Module
---------------------- ----------------------
@ -81,22 +68,6 @@ PIL Package
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
:mod:`ImageColor` Module
------------------------
.. automodule:: PIL.ImageColor
:members:
:undoc-members:
:show-inheritance:
:mod:`ImageDraw` Module
-----------------------
.. automodule:: PIL.ImageDraw
:members:
:undoc-members:
:show-inheritance:
:mod:`ImageDraw2` Module :mod:`ImageDraw2` Module
------------------------ ------------------------

2
docs/index.rst
View File

@ -35,8 +35,8 @@ source and contribute at https://github.com/python-imaging/Pillow.
installation installation
about about
guides guides
reference/index.rst
handbook/appendices handbook/appendices
PIL
original-readme original-readme
Support Pillow! Support Pillow!

189
docs/reference/Image.rst Normal file
View File

@ -0,0 +1,189 @@
.. py:module:: PIL.Image
.. py:currentmodule:: PIL.Image
:mod:`Image` Module
===================
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
--------
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).
Open, rotate, and display an image (using the default viewer)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python
from PIL import Image
im = Image.open("bride.jpg")
im.rotate(45).show()
The following script creates nice 128x128 thumbnails of all JPEG images in the
current directory.
Create thumbnails
^^^^^^^^^^^^^^^^^
.. 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, Image.ANTIALIAS)
im.save(file + ".thumbnail", "JPEG")
Functions
---------
.. autofunction:: open
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
.. autofunction:: register_mime
.. autofunction:: register_save
.. autofunction:: register_extension
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.
.. 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
.. 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
.. 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.tell
.. automethod:: PIL.Image.Image.thumbnail
.. automethod:: PIL.Image.Image.tobitmap
.. 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
.. deprecated:: 2.0
.. automethod:: PIL.Image.Image.load
Attributes
----------
Instances of the :py:class:`Image` class have the following attributes:
.. 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
:doc:`../handbook/concepts` for a full list.
: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:: 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, it’s 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.
:type: :py:class:`dict`

41
docs/reference/ImageChops.rst Normal file
View File

@ -0,0 +1,41 @@
.. py:module:: PIL.ImageChops
.. py:currentmodule:: PIL.ImageChops
:mod:`ImageChops` Module
========================
The :py:mod:`ImageChops` module contains a number of arithmetical image
operations, called channel operations (“chops”). These can be used for various
purposes, including special effects, image compositions, algorithmic painting,
and more.
For more pre-made operations, see :py:mod:`ImageOps`.
At this time, most channel operations are only implemented for 8-bit images
(e.g. “L” and “RGB”).
Functions
---------
Most channel operations take one or two image arguments and returns a new
image. Unless otherwise noted, the result of a channel operation is always
clipped to the range 0 to MAX (which is 255 for all modes supported by the
operations in this module).
.. autofunction:: PIL.ImageChops.add
.. autofunction:: PIL.ImageChops.add_modulo
.. autofunction:: PIL.ImageChops.blend
.. autofunction:: PIL.ImageChops.composite
.. autofunction:: PIL.ImageChops.constant
.. autofunction:: PIL.ImageChops.darker
.. autofunction:: PIL.ImageChops.difference
.. autofunction:: PIL.ImageChops.duplicate
.. autofunction:: PIL.ImageChops.invert
.. autofunction:: PIL.ImageChops.lighter
.. autofunction:: PIL.ImageChops.logical_and
.. autofunction:: PIL.ImageChops.logical_or
.. autofunction:: PIL.ImageChops.multiply
.. autofunction:: PIL.ImageChops.offset
.. autofunction:: PIL.ImageChops.screen
.. autofunction:: PIL.ImageChops.subtract
.. autofunction:: PIL.ImageChops.subtract_modulo

43
docs/reference/ImageColor.rst Normal file
View File

@ -0,0 +1,43 @@
.. py:module:: PIL.ImageColor
.. py:currentmodule:: PIL.ImageColor
:mod:`ImageColor` Module
========================
The :py:mod:`ImageColor` module contains color tables and converters from
CSS3-style color specifiers to RGB tuples. This module is used by
:py:meth:`PIL.Image.Image.new` and the :py:mod:`~PIL.ImageDraw` module, among
others.
.. _color-names:
Color Names
-----------
The ImageColor module supports the following string formats:
* Hexadecimal color specifiers, given as ``#rgb`` or ``#rrggbb``. For example,
``#ff0000`` specifies pure red.
* RGB functions, given as ``rgb(red, green, blue)`` where the color values are
integers in the range 0 to 255. Alternatively, the color values can be given
as three percentages (0% to 100%). For example, ``rgb(255,0,0)`` and
``rgb(100%,0%,0%)`` both specify pure red.
* Hue-Saturation-Lightness (HSL) functions, given as ``hsl(hue, saturation%,
lightness%)`` where hue is the color given as an angle between 0 and 360
(red=0, green=120, blue=240), saturation is a value between 0% and 100%
(gray=0%, full color=100%), and lightness is a value between 0% and 100%
(black=0%, normal=50%, white=100%). For example, ``hsl(0,100%,50%)`` is pure
red.
* Common HTML color names. The :py:mod:`~PIL.ImageColor` module provides some
140 standard color names, based on the colors supported by the X Window
system and most web browsers. color names are case insensitive. For example,
``red`` and ``Red`` both specify pure red.
Functions
---------
.. autofunction:: getrgb
.. autofunction:: getcolor

239
docs/reference/ImageDraw.rst Normal file
View File

@ -0,0 +1,239 @@
.. py:module:: PIL.ImageDraw
.. py:currentmodule:: PIL.ImageDraw
:mod:`ImageDraw` Module
=======================
The :py:mod:`ImageDraw` module provide simple 2D graphics for
:py:class:`~PIL.Image.Image` objects. You can use this module to create new
images, annotate or retouch existing images, and to generate graphics on the
fly for web use.
For a more advanced drawing library for PIL, see the `aggdraw module`_.
.. _aggdraw module: http://effbot.org/zone/aggdraw-index.htm
Example: Draw a gray cross over an image
----------------------------------------
.. code-block:: python
import Image, ImageDraw
im = Image.open("lena.pgm")
draw = ImageDraw.Draw(im)
draw.line((0, 0) + im.size, fill=128)
draw.line((0, im.size[1], im.size[0], 0), fill=128)
del draw
# write to stdout
im.save(sys.stdout, "PNG")
Concepts
--------
Coordinates
^^^^^^^^^^^
The graphics interface uses the same coordinate system as PIL itself, with (0,
0) in the upper left corner.
Colors
^^^^^^
To specify colors, you can use numbers or tuples just as you would use with
:py:meth:`PIL.Image.Image.new` or :py:meth:`PIL.Image.Image.putpixel`. For “1”,
“L”, and “I” images, use integers. For “RGB” images, use a 3-tuple containing
integer values. For “F” images, use integer or floating point values.
For palette images (mode “P”), use integers as color indexes. In 1.1.4 and
later, you can also use RGB 3-tuples or color names (see below). The drawing
layer will automatically assign color indexes, as long as you don’t draw with
more than 256 colors.
Color Names
^^^^^^^^^^^
See :ref:`color-names` for the color names supported by Pillow.
Fonts
^^^^^
PIL can use bitmap fonts or OpenType/TrueType fonts.
Bitmap fonts are stored in PIL’s own format, where each font typically consists
of a two files, one named .pil and the other usually named .pbm. The former
contains font metrics, the latter raster data.
To load a bitmap font, use the load functions in the :py:mod:`~PIL.ImageFont`
module.
To load a OpenType/TrueType font, use the truetype function in the
:py:mod:`~PIL.ImageFont` module. Note that this function depends on third-party
libraries, and may not available in all PIL builds.
Functions
---------
.. py:class:: PIL.ImageDraw.Draw(im, mode=None)
Creates an object that can be used to draw in the given image.
Note that the image will be modified in place.
Methods
-------
.. py:method:: PIL.ImageDraw.Draw.arc(xy, start, end, fill=None)
Draws an arc (a portion of a circle outline) between the start and end
angles, inside the given bounding box.
:param xy: Four points to define the bounding box. Sequence of either
``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``.
:param outline: Color to use for the outline.
.. py:method:: PIL.ImageDraw.Draw.bitmap(xy, bitmap, fill=None)
Draws a bitmap (mask) at the given position, using the current fill color
for the non-zero portions. The bitmap should be a valid transparency mask
(mode “1”) or matte (mode “L” or “RGBA”).
This is equivalent to doing ``image.paste(xy, color, bitmap)``.
To paste pixel data into an image, use the
:py:meth:`~PIL.Image.Image.paste` method on the image itself.
.. py:method:: PIL.ImageDraw.Draw.chord(xy, start, end, fill=None, outline=None)
Same as :py:meth:`~PIL.ImageDraw.Draw.arc`, but connects the end points
with a straight line.
:param xy: Four points to define the bounding box. Sequence of either
``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``.
:param outline: Color to use for the outline.
:param fill: Color to use for the fill.
.. py:method:: PIL.ImageDraw.Draw.ellipse(xy, fill=None, outline=None)
Draws an ellipse inside the given bounding box.
:param xy: Four points to define the bounding box. Sequence of either
``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``.
:param outline: Color to use for the outline.
:param fill: Color to use for the fill.
.. py:method:: PIL.ImageDraw.Draw.line(xy, fill=None, width=0)
Draws a line between the coordinates in the **xy** list.
:param xy: Sequence of either 2-tuples like ``[(x, y), (x, y), ...]`` or
numeric values like ``[x, y, x, y, ...]``.
:param fill: Color to use for the line.
:param width: The line width, in pixels. Note that line
joins are not handled well, so wide polylines will not look good.
.. versionadded:: 1.1.5
.. note:: This option was broken until version 1.1.6.
.. py:method:: PIL.ImageDraw.Draw.pieslice(xy, start, end, fill=None, outline=None)
Same as arc, but also draws straight lines between the end points and the
center of the bounding box.
:param xy: Four points to define the bounding box. Sequence of either
``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``.
:param outline: Color to use for the outline.
:param fill: Color to use for the fill.
.. py:method:: PIL.ImageDraw.Draw.point(xy, fill=None)
Draws points (individual pixels) at the given coordinates.
:param xy: Sequence of either 2-tuples like ``[(x, y), (x, y), ...]`` or
numeric values like ``[x, y, x, y, ...]``.
:param fill: Color to use for the point.
.. py:method:: PIL.ImageDraw.Draw.polygon(xy, fill=None, outline=None)
Draws a polygon.
The polygon outline consists of straight lines between the given
coordinates, plus a straight line between the last and the first
coordinate.
:param xy: Sequence of either 2-tuples like ``[(x, y), (x, y), ...]`` or
numeric values like ``[x, y, x, y, ...]``.
:param outline: Color to use for the outline.
:param fill: Color to use for the fill.
.. py:method:: PIL.ImageDraw.Draw.rectangle(xy, fill=None, outline=None)
Draws a rectangle.
:param xy: Four points to define the bounding box. Sequence of either
``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``. The second point
is just outside the drawn rectangle.
:param outline: Color to use for the outline.
:param fill: Color to use for the fill.
.. py:method:: PIL.ImageDraw.Draw.shape(shape, fill=None, outline=None)
.. warning:: This method is experimental.
Draw a shape.
.. py:method:: PIL.ImageDraw.Draw.text(xy, text, fill=None, font=None, anchor=None)
Draws the string at the given position.
:param xy: Top left corner of the text.
:param text: Text to be drawn.
:param font: An :py:class:`~PIL.ImageFont.ImageFont` instance.
:param fill: Color to use for the text.
.. py:method:: PIL.ImageDraw.Draw.textsize(text, font=None)
Return the size of the given string, in pixels.
:param text: Text to be measured.
:param font: An :py:class:`~PIL.ImageFont.ImageFont` instance.
Legacy API
----------
The :py:class:`~PIL.ImageDraw.Draw` class contains a constructor and a number
of methods which are provided for backwards compatibility only. For this to
work properly, you should either use options on the drawing primitives, or
these methods. Do not mix the old and new calling conventions.
.. py:function:: PIL.ImageDraw.ImageDraw(image)
:rtype: :py:class:`~PIL.ImageDraw.Draw`
.. py:method:: PIL.ImageDraw.Draw.setink(ink)
.. deprecated:: 1.1.5
Sets the color to use for subsequent draw and fill operations.
.. py:method:: PIL.ImageDraw.Draw.setfill(fill)
.. deprecated:: 1.1.5
Sets the fill mode.
If the mode is 0, subsequently drawn shapes (like polygons and rectangles)
are outlined. If the mode is 1, they are filled.
.. py:method:: PIL.ImageDraw.Draw.setfont(font)
.. deprecated:: 1.1.5
Sets the default font to use for the text method.
:param font: An :py:class:`~PIL.ImageFont.ImageFont` instance.

11
docs/reference/index.rst Normal file
View File

@ -0,0 +1,11 @@
Reference
=========
.. toctree::
:maxdepth: 2
Image
ImageChops
ImageColor
ImageDraw
../PIL