mirror of
https://github.com/python-pillow/Pillow.git
synced 2025-01-12 10:16:17 +03:00
Merge pull request #374 from irskep/doc-improvements
Port and update docs for Image, ImageChops, ImageColor, and ImageDraw
This commit is contained in:
Alex Clark ☺
commit
0cc371399b
250
PIL/Image.py
250
PIL/Image.py
|
|
@ -57,7 +57,7 @@ try:
|
|||
|
||||
except ImportError as v:
|
||||
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"):
|
||||
# The _imaging C module is present, but not compiled for
|
||||
# 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. ",
|
||||
RuntimeWarning
|
||||
)
|
||||
# Fail here anyway. Don't let people run with a mostly broken Pillow.
|
||||
raise
|
||||
# Fail here anyway. Don't let people run with a mostly broken Pillow.
|
||||
raise
|
||||
|
||||
try:
|
||||
import builtins
|
||||
|
|
@ -281,10 +281,10 @@ def getmodetype(mode):
|
|||
|
||||
def getmodebandnames(mode):
|
||||
"""
|
||||
Gets a list of individual band names. Given a mode, this function
|
||||
returns a tuple containing the names of individual bands (use
|
||||
:func:`PIL.Image.getmodetype` to get the mode used to store each individual
|
||||
band.
|
||||
Gets a list of individual band names. Given a mode, this function returns
|
||||
a tuple containing the names of individual bands (use
|
||||
:py:method:`~PIL.Image.getmodetype` to get the mode used to store each
|
||||
individual band.
|
||||
|
||||
:param mode: Input mode.
|
||||
:returns: A tuple containing band names. The length of the tuple
|
||||
|
|
@ -443,13 +443,14 @@ def _getscaleoffset(expr):
|
|||
|
||||
class Image:
|
||||
"""
|
||||
This class represents an image object. To create Image objects, use
|
||||
the appropriate factory functions. There's hardly ever any reason
|
||||
to call the Image constructor directly.
|
||||
This class represents an image object. To create
|
||||
:py:class:`~PIL.Image.Image` objects, use the appropriate factory
|
||||
functions. There's hardly ever any reason to call the Image constructor
|
||||
directly.
|
||||
|
||||
* :func:`PIL.Image.open`
|
||||
* :func:`PIL.Image.new`
|
||||
* :func:`PIL.Image.frombytes`
|
||||
* :py:func:`~PIL.Image.open`
|
||||
* :py:func:`~PIL.Image.new`
|
||||
* :py:func:`~PIL.Image.frombytes`
|
||||
"""
|
||||
format = None
|
||||
format_description = None
|
||||
|
|
@ -588,8 +589,8 @@ class Image:
|
|||
"""
|
||||
Loads this image with pixel data from a bytes object.
|
||||
|
||||
This method is similar to the :func:`PIL.Image.frombytes` function, but
|
||||
loads data into this image instead of creating a new image object.
|
||||
This method is similar to the :py:func:`~PIL.Image.frombytes` function,
|
||||
but loads data into this image instead of creating a new image object.
|
||||
"""
|
||||
|
||||
# may pass tuple instead of argument list
|
||||
|
|
@ -611,7 +612,10 @@ class Image:
|
|||
raise ValueError("cannot decode image data")
|
||||
|
||||
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)
|
||||
return self.frombytes(*args, **kw)
|
||||
|
||||
|
|
@ -651,7 +655,7 @@ class Image:
|
|||
"""
|
||||
pass
|
||||
|
||||
def convert(self, mode=None, data=None, dither=None,
|
||||
def convert(self, mode=None, matrix=None, dither=None,
|
||||
palette=WEB, colors=256):
|
||||
"""
|
||||
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.
|
||||
|
||||
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"),
|
||||
the library uses the ITU-R 601-2 luma transform:
|
||||
When translating a color image to black and white (mode "L"),
|
||||
the library uses the ITU-R 601-2 luma transform::
|
||||
|
||||
L = R * 299/1000 + G * 587/1000 + B * 114/1000
|
||||
|
||||
When translating a greyscale image into a bilevel image (mode
|
||||
"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 matrix: An optional conversion matrix. If given, this
|
||||
|
|
@ -681,8 +686,8 @@ class Image:
|
|||
to "P". Available palettes are WEB or ADAPTIVE.
|
||||
:param colors: Number of colors to use for the ADAPTIVE palette.
|
||||
Defaults to 256.
|
||||
:rtype: :class:`PIL.Image.Image`
|
||||
:returns: An Image object.
|
||||
:rtype: :py:class:`~PIL.Image.Image`
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
if not mode:
|
||||
|
|
@ -698,18 +703,18 @@ class Image:
|
|||
|
||||
self.load()
|
||||
|
||||
if data:
|
||||
if matrix:
|
||||
# matrix conversion
|
||||
if mode not in ("L", "RGB"):
|
||||
raise ValueError("illegal conversion")
|
||||
im = self.im.convert_matrix(mode, data)
|
||||
im = self.im.convert_matrix(mode, matrix)
|
||||
return self._new(im)
|
||||
|
||||
if mode == "P" and palette == ADAPTIVE:
|
||||
im = self.im.quantize(colors)
|
||||
return self._new(im)
|
||||
|
||||
# colourspace conversion
|
||||
# colorspace conversion
|
||||
if dither is None:
|
||||
dither = FLOYDSTEINBERG
|
||||
|
||||
|
|
@ -767,8 +772,8 @@ class Image:
|
|||
Copies this image. Use this method if you wish to paste things
|
||||
into an image, but still retain the original.
|
||||
|
||||
:rtype: :class:`PIL.Image.Image`
|
||||
:returns: An Image object.
|
||||
:rtype: :py:class:`~PIL.Image.Image`
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
self.load()
|
||||
im = self.im.copy()
|
||||
|
|
@ -782,12 +787,12 @@ class Image:
|
|||
|
||||
This is a lazy operation. Changes to the source image may or
|
||||
may not be reflected in the cropped image. To break the
|
||||
connection, call the {@link #Image.load} method on the cropped
|
||||
copy.
|
||||
connection, call the :py:meth:`~PIL.Image.Image.load` method on
|
||||
the cropped copy.
|
||||
|
||||
:param box: The crop rectangle, as a (left, upper, right, lower)-tuple.
|
||||
:rtype: :class:`PIL.Image.Image`
|
||||
:returns: An Image object.
|
||||
:rtype: :py:class:`~PIL.Image.Image`
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
self.load()
|
||||
|
|
@ -801,12 +806,13 @@ class Image:
|
|||
"""
|
||||
Configures the image file loader so it returns a version of the
|
||||
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
|
||||
version from a PCD file.
|
||||
|
||||
Note that this method modifies the Image object in place. If
|
||||
the image has already been loaded, this method has no effect.
|
||||
Note that this method modifies the :py:class:`~PIL.Image.Image` object
|
||||
in place. If the image has already been loaded, this method has no
|
||||
effect.
|
||||
|
||||
:param mode: The requested mode.
|
||||
:param size: The requested size.
|
||||
|
|
@ -822,11 +828,10 @@ class Image:
|
|||
def filter(self, filter):
|
||||
"""
|
||||
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.
|
||||
:returns: An Image object.
|
||||
"""
|
||||
:returns: An :py:class:`~PIL.Image.Image` object. """
|
||||
|
||||
self.load()
|
||||
|
||||
|
|
@ -1014,18 +1019,18 @@ class Image:
|
|||
|
||||
def offset(self, xoffset, yoffset=None):
|
||||
"""
|
||||
(Deprecated) 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.
|
||||
.. deprecated:: 2.0
|
||||
|
||||
This method is deprecated. New code should use the
|
||||
:func:`PIL.ImageChops.offset` function in the
|
||||
:mod:`PIL.ImageChops` module.
|
||||
.. note:: New code should use :py:func:`PIL.ImageChops.offset`.
|
||||
|
||||
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 yoffset: The vertical distance. If omitted, both
|
||||
distances are set to the same value.
|
||||
:returns: An Image object.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
if warnings:
|
||||
warnings.warn(
|
||||
|
|
@ -1043,14 +1048,14 @@ class Image:
|
|||
(0, 0)). If a 4-tuple is given, the size of the pasted image
|
||||
must match the size of the region.
|
||||
|
||||
If the modes don't match, the pasted image is converted to the
|
||||
mode of this image (see the :func:`PIL.Image.Image.convert` method for
|
||||
If the modes don't match, the pasted image is converted to the mode of
|
||||
this image (see the :py:meth:`~PIL.Image.Image.convert` method for
|
||||
details).
|
||||
|
||||
Instead of an image, the source can be a integer or tuple
|
||||
containing pixel values. The method then fills the region
|
||||
with the given colour. When creating RGB images, you can
|
||||
also use colour strings as supported by the ImageColor module.
|
||||
with the given color. When creating RGB images, you can
|
||||
also use color strings as supported by the ImageColor module.
|
||||
|
||||
If a mask is given, this method updates only the regions
|
||||
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
|
||||
is interpreted as a 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:
|
||||
|
|
@ -1131,7 +1136,7 @@ class Image:
|
|||
:param mode: Output mode (default is same as input). In the
|
||||
current version, this can only be used if the source image
|
||||
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()
|
||||
|
|
@ -1260,19 +1265,19 @@ class Image:
|
|||
|
||||
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
|
||||
multi-band images.
|
||||
|
||||
Note that this method is relatively slow. For more extensive
|
||||
changes, use :func:`PIL.Image.Image.paste` or the :mod:`PIL.ImageDraw`
|
||||
Note that this method is relatively slow. For more extensive changes,
|
||||
use :py:meth:`~PIL.Image.Image.paste` or the :py:mod:`~PIL.ImageDraw`
|
||||
module instead.
|
||||
|
||||
See:
|
||||
|
||||
* :func:`PIL.Image.Image.paste`
|
||||
* :func:`PIL.Image.Image.putdata`
|
||||
* :mod:`PIL.ImageDraw`
|
||||
* :py:meth:`~PIL.Image.Image.paste`
|
||||
* :py:meth:`~PIL.Image.Image.putdata`
|
||||
* :py:mod:`~PIL.ImageDraw`
|
||||
|
||||
:param xy: The pixel coordinate, given as (x, y).
|
||||
:param value: The pixel value.
|
||||
|
|
@ -1291,14 +1296,14 @@ class Image:
|
|||
:param size: The requested size in pixels, as a 2-tuple:
|
||||
(width, height).
|
||||
:param filter: An optional resampling filter. This can be
|
||||
one of :attr:`PIL.Image.NEAREST` (use nearest neighbour),
|
||||
:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
|
||||
environment), :attr:`PIL.Image.BICUBIC` (cubic spline
|
||||
one of :py:attr:`PIL.Image.NEAREST` (use nearest neighbour),
|
||||
:py:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
|
||||
environment), :py:attr:`PIL.Image.BICUBIC` (cubic spline
|
||||
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
|
||||
set :attr:`PIL.Image.NEAREST`.
|
||||
:returns: An Image object.
|
||||
set :py:attr:`PIL.Image.NEAREST`.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
if resample not in (NEAREST, BILINEAR, BICUBIC, ANTIALIAS):
|
||||
|
|
@ -1331,17 +1336,17 @@ class Image:
|
|||
|
||||
:param angle: In degrees counter clockwise.
|
||||
:param filter: An optional resampling filter. This can be
|
||||
one of :attr:`PIL.Image.NEAREST` (use nearest neighbour),
|
||||
:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
|
||||
environment), or :attr:`PIL.Image.BICUBIC`
|
||||
one of :py:attr:`PIL.Image.NEAREST` (use nearest neighbour),
|
||||
:py:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
|
||||
environment), or :py:attr:`PIL.Image.BICUBIC`
|
||||
(cubic spline interpolation in a 4x4 environment).
|
||||
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
|
||||
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
|
||||
input image.
|
||||
:returns: An Image object.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
if expand:
|
||||
|
|
@ -1469,7 +1474,7 @@ class Image:
|
|||
Note that in the current version of the library, most sequence
|
||||
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.
|
||||
:exception EOFError: If the call attempts to seek beyond the end
|
||||
|
|
@ -1520,7 +1525,7 @@ class Image:
|
|||
|
||||
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.
|
||||
"""
|
||||
|
|
@ -1532,24 +1537,24 @@ class Image:
|
|||
image to contain a thumbnail version of itself, no larger than
|
||||
the given size. This method calculates an appropriate thumbnail
|
||||
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.
|
||||
|
||||
Note that the bilinear and bicubic filters in the current
|
||||
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.
|
||||
|
||||
Also note that this function modifies the Image object in place.
|
||||
If you need to use the full resolution image as well, apply this
|
||||
method to a :func:`PIL.Image.Image.copy` of the original image.
|
||||
Also note that this function modifies the :py:class:`~PIL.Image.Image`
|
||||
object in place. If you need to use the full resolution image as well, apply
|
||||
this method to a :py:meth:`~PIL.Image.Image.copy` of the original image.
|
||||
|
||||
:param size: Requested size.
|
||||
:param resample: Optional resampling filter. This can be one
|
||||
of :attr:`PIL.Image.NEAREST`, :attr:`PIL.Image.BILINEAR`,
|
||||
:attr:`PIL.Image.BICUBIC`, or :attr:`PIL.Image.ANTIALIAS`
|
||||
of :py:attr:`PIL.Image.NEAREST`, :py:attr:`PIL.Image.BILINEAR`,
|
||||
:py:attr:`PIL.Image.BICUBIC`, or :py:attr:`PIL.Image.ANTIALIAS`
|
||||
(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).
|
||||
:returns: None
|
||||
"""
|
||||
|
|
@ -1593,20 +1598,20 @@ class Image:
|
|||
|
||||
:param size: The output size.
|
||||
:param method: The transformation method. This is one of
|
||||
:attr:`PIL.Image.EXTENT` (cut out a rectangular subregion),
|
||||
:attr:`PIL.Image.AFFINE` (affine transform),
|
||||
:attr:`PIL.Image.PERSPECTIVE` (perspective transform),
|
||||
: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.EXTENT` (cut out a rectangular subregion),
|
||||
:py:attr:`PIL.Image.AFFINE` (affine transform),
|
||||
:py:attr:`PIL.Image.PERSPECTIVE` (perspective transform),
|
||||
:py:attr:`PIL.Image.QUAD` (map a quadrilateral to a rectangle), or
|
||||
:py:attr:`PIL.Image.MESH` (map a number of source quadrilaterals
|
||||
in one operation).
|
||||
:param data: Extra data to the transformation method.
|
||||
:param resample: Optional resampling filter. It can be one of
|
||||
:attr:`PIL.Image.NEAREST` (use nearest neighbour),
|
||||
:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
|
||||
environment), or :attr:`PIL.Image.BICUBIC` (cubic spline
|
||||
:py:attr:`PIL.Image.NEAREST` (use nearest neighbour),
|
||||
:py:attr:`PIL.Image.BILINEAR` (linear interpolation in a 2x2
|
||||
environment), or :py:attr:`PIL.Image.BICUBIC` (cubic spline
|
||||
interpolation in a 4x4 environment). If omitted, or if the image
|
||||
has mode "1" or "P", it is set to :attr:`PIL.Image.NEAREST`.
|
||||
:returns: An Image object.
|
||||
has mode "1" or "P", it is set to :py:attr:`PIL.Image.NEAREST`.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
if self.mode == 'RGBA':
|
||||
|
|
@ -1619,7 +1624,7 @@ class Image:
|
|||
method, data = method.getdata()
|
||||
if data is None:
|
||||
raise ValueError("missing method data")
|
||||
|
||||
|
||||
im = new(self.mode, size, None)
|
||||
if method == MESH:
|
||||
# list of quads
|
||||
|
|
@ -1627,7 +1632,7 @@ class Image:
|
|||
im.__transformer(box, self, QUAD, quad, resample, fill)
|
||||
else:
|
||||
im.__transformer((0, 0)+size, self, method, data, resample, fill)
|
||||
|
||||
|
||||
return im
|
||||
|
||||
def __transformer(self, box, image, method, data,
|
||||
|
|
@ -1682,9 +1687,9 @@ class Image:
|
|||
"""
|
||||
Transpose image (flip or rotate in 90 degree steps)
|
||||
|
||||
:param method: One of :attr:`PIL.Image.FLIP_LEFT_RIGHT`,
|
||||
:attr:`PIL.Image.FLIP_TOP_BOTTOM`, :attr:`PIL.Image.ROTATE_90`,
|
||||
:attr:`PIL.Image.ROTATE_180`, or :attr:`PIL.Image.ROTATE_270`.
|
||||
:param method: One of :py:attr:`PIL.Image.FLIP_LEFT_RIGHT`,
|
||||
:py:attr:`PIL.Image.FLIP_TOP_BOTTOM`, :py:attr:`PIL.Image.ROTATE_90`,
|
||||
:py:attr:`PIL.Image.ROTATE_180`, or :py:attr:`PIL.Image.ROTATE_270`.
|
||||
: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 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
|
||||
for single-band modes, and a tuple for multi-band modes (one value
|
||||
per band). When creating RGB images, you can also use colour
|
||||
strings as supported by the ImageColor module. If the colour is
|
||||
per band). When creating RGB images, you can also use color
|
||||
strings as supported by the ImageColor module. If the color is
|
||||
None, the image is not initialised.
|
||||
:returns: An Image object.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
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.
|
||||
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 size: The image size.
|
||||
:param data: A byte buffer containing raw data for the given mode.
|
||||
:param decoder_name: What decoder to use.
|
||||
: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
|
||||
|
|
@ -1813,7 +1819,10 @@ def frombytes(mode, size, data, decoder_name="raw", *args):
|
|||
return im
|
||||
|
||||
def fromstring(*args, **kw):
|
||||
" Deprecated alias to frombytes "
|
||||
"""Deprecated alias to frombytes.
|
||||
|
||||
.. deprecated:: 2.0
|
||||
"""
|
||||
warnings.warn(
|
||||
'fromstring() is deprecated. Please call frombytes() instead.',
|
||||
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.
|
||||
|
||||
This function is similar to :func:`PIL.Image.frombytes`, but uses data in
|
||||
the byte buffer, where possible. This means that changes to the
|
||||
original buffer object are reflected in this image). Not all modes
|
||||
can share memory; supported modes include "L", "RGBX", "RGBA", and
|
||||
"CMYK".
|
||||
This function is similar to :py:func:`~PIL.Image.frombytes`, but uses data
|
||||
in the byte buffer, where possible. This means that changes to the
|
||||
original buffer object are reflected in this image). Not all modes can
|
||||
share memory; supported modes include "L", "RGBX", "RGBA", and "CMYK".
|
||||
|
||||
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
|
||||
**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
|
||||
differs from that used for :func:`PIL.Image.fromstring`. This is a bug,
|
||||
and will probably be fixed in a future release. The current release issues
|
||||
a warning if you do this; to disable the warning, you should provide the
|
||||
full set of parameters. See below for details.
|
||||
differs from that used for :py:func:`~PIL.Image.fromstring`. This is a
|
||||
bug, and will probably be fixed in a future release. The current release
|
||||
issues a warning if you do this; to disable the warning, you should provide
|
||||
the full set of parameters. See below for details.
|
||||
|
||||
:param mode: The image mode.
|
||||
: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)
|
||||
|
||||
:returns: An Image object.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
|
||||
.. versionadded:: 1.1.4
|
||||
"""
|
||||
|
|
@ -1890,7 +1898,7 @@ def fromarray(obj, mode=None):
|
|||
(using the buffer protocol).
|
||||
|
||||
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 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
|
||||
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).
|
||||
See :func:`PIL.Image.new`
|
||||
the data (or call the :py:meth:`~PIL.Image.Image.load` method).
|
||||
See :py:func:`~PIL.Image.new`.
|
||||
|
||||
:param file: A filename (string) or a file object. The file object
|
||||
must implement **read**, **seek**, and **tell** methods,
|
||||
and be opened in binary mode.
|
||||
must implement :py:meth:`~file.read`, :py:meth:`~file.seek`, and
|
||||
:py:meth:`~file.tell` methods, and be opened in binary mode.
|
||||
: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
|
||||
opened and identified.
|
||||
"""
|
||||
|
|
@ -2022,7 +2030,7 @@ def alpha_composite(im1, im2):
|
|||
:param im1: The first image.
|
||||
:param im2: The second image. Must have the same mode and size as
|
||||
the first image.
|
||||
:returns: An Image object.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
im1.load()
|
||||
|
|
@ -2045,7 +2053,7 @@ def blend(im1, im2, alpha):
|
|||
the second image is returned. There are no restrictions on the
|
||||
alpha value. If necessary, the result is clipped to fit into
|
||||
the allowed output range.
|
||||
:returns: An Image object.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
im1.load()
|
||||
|
|
@ -2080,7 +2088,7 @@ def eval(image, *args):
|
|||
|
||||
:param image: The input image.
|
||||
: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])
|
||||
|
|
@ -2094,7 +2102,7 @@ def merge(mode, bands):
|
|||
:param bands: A sequence containing one single-band image for
|
||||
each band in the output image. All bands must have the
|
||||
same size.
|
||||
:returns: An Image object.
|
||||
:returns: An :py:class:`~PIL.Image.Image` object.
|
||||
"""
|
||||
|
||||
if getmodebands(mode) != len(bands) or "*" in mode:
|
||||
|
|
|
|||
|
|
@ -17,285 +17,266 @@
|
|||
|
||||
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. "L" and "RGB").
|
||||
# <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):
|
||||
"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)
|
||||
|
||||
##
|
||||
# Copy image.
|
||||
#
|
||||
# @param image Source image.
|
||||
# @return A copy of the source 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()
|
||||
|
||||
##
|
||||
# Inverts an image
|
||||
# (MAX - image).
|
||||
#
|
||||
# @param image Source image.
|
||||
# @return An image object.
|
||||
|
||||
def invert(image):
|
||||
"Invert a channel"
|
||||
"""
|
||||
Invert an image (channel).
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
out = MAX - image
|
||||
|
||||
:rtype: :py:class:`~PIL.Image.Image`
|
||||
"""
|
||||
|
||||
image.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
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):
|
||||
"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()
|
||||
image2.load()
|
||||
return image1._new(image1.im.chop_subtract_modulo(image2.im))
|
||||
|
||||
##
|
||||
# Logical AND
|
||||
# (image1 and 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()
|
||||
image2.load()
|
||||
return image1._new(image1.im.chop_and(image2.im))
|
||||
|
||||
##
|
||||
# Logical OR
|
||||
# (image1 or 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()
|
||||
image2.load()
|
||||
return image1._new(image1.im.chop_or(image2.im))
|
||||
|
||||
##
|
||||
# Logical XOR
|
||||
# (image1 xor 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()
|
||||
image2.load()
|
||||
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):
|
||||
"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)
|
||||
|
||||
##
|
||||
# Create composite using transparency mask.
|
||||
# <p>
|
||||
# Same as the <b>composite</b> function in the <b>Image</b> module.
|
||||
|
||||
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)
|
||||
|
||||
##
|
||||
# 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):
|
||||
"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:
|
||||
yoffset = xoffset
|
||||
image.load()
|
||||
|
|
|
|||
|
|
@ -30,6 +30,15 @@ import re
|
|||
# as an RGB value.
|
||||
|
||||
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:
|
||||
rgb = colormap[color]
|
||||
except KeyError:
|
||||
|
|
@ -97,6 +106,16 @@ def getrgb(color):
|
|||
raise ValueError("unknown color specifier: %r" % color)
|
||||
|
||||
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
|
||||
color = getrgb(color)
|
||||
if mode == "RGB":
|
||||
|
|
|
|||
37
docs/PIL.rst
37
docs/PIL.rst
|
|
@ -1,13 +1,8 @@
|
|||
PIL Package
|
||||
===========
|
||||
PIL Package (autodoc of remaining modules)
|
||||
==========================================
|
||||
|
||||
:mod:`Image` Module
|
||||
-------------------
|
||||
|
||||
.. automodule:: PIL.Image
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
Reference for modules whose documentation has not yet been ported or written
|
||||
can be found here.
|
||||
|
||||
:mod:`BdfFontFile` Module
|
||||
-------------------------
|
||||
|
|
@ -65,14 +60,6 @@ PIL Package
|
|||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
:mod:`ImageChops` Module
|
||||
------------------------
|
||||
|
||||
.. automodule:: PIL.ImageChops
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
:mod:`ImageCms` Module
|
||||
----------------------
|
||||
|
||||
|
|
@ -81,22 +68,6 @@ PIL Package
|
|||
:undoc-members:
|
||||
: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
|
||||
------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -35,8 +35,8 @@ source and contribute at https://github.com/python-imaging/Pillow.
|
|||
installation
|
||||
about
|
||||
guides
|
||||
reference/index.rst
|
||||
handbook/appendices
|
||||
PIL
|
||||
original-readme
|
||||
|
||||
Support Pillow!
|
||||
|
|
|
|||
189
docs/reference/Image.rst
Normal file
189
docs/reference/Image.rst
Normal 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
41
docs/reference/ImageChops.rst
Normal 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
43
docs/reference/ImageColor.rst
Normal 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
239
docs/reference/ImageDraw.rst
Normal 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
11
docs/reference/index.rst
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
Reference
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
Image
|
||||
ImageChops
|
||||
ImageColor
|
||||
ImageDraw
|
||||
../PIL
|
||||
Loading…
Reference in New Issue
Block a user