From b25e8c5d180926c34014bbd77aee745968c140db Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Fri, 11 Oct 2013 22:18:28 -0700 Subject: [PATCH 01/12] Fully document PIL.Image from handbook --- docs/PIL.rst | 8 -- docs/index.rst | 2 +- docs/reference/Image.rst | 189 +++++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 8 ++ 4 files changed, 198 insertions(+), 9 deletions(-) create mode 100644 docs/reference/Image.rst create mode 100644 docs/reference/index.rst diff --git a/docs/PIL.rst b/docs/PIL.rst index 8918fce0e..2595c22ba 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -1,14 +1,6 @@ PIL Package =========== -:mod:`Image` Module -------------------- - -.. automodule:: PIL.Image - :members: - :undoc-members: - :show-inheritance: - :mod:`BdfFontFile` Module ------------------------- diff --git a/docs/index.rst b/docs/index.rst index 9dad0ec4f..70e8871b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,7 +36,7 @@ source and contribute at https://github.com/python-imaging/Pillow. about guides handbook/appendices - PIL + reference/index.rst original-readme Support Pillow! diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst new file mode 100644 index 000000000..107c8a753 --- /dev/null +++ b/docs/reference/Image.rst @@ -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` diff --git a/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 000000000..3f6385c47 --- /dev/null +++ b/docs/reference/index.rst @@ -0,0 +1,8 @@ +Reference +========= + +.. toctree:: + :maxdepth: 2 + + Image + ../PIL From b533aa665e64a37c37ce0edeb16a598e38681735 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Fri, 11 Oct 2013 22:18:40 -0700 Subject: [PATCH 02/12] Fix many formatting mistakes in PIL.Image's docstrings --- PIL/Image.py | 250 ++++++++++++++++++++++++++------------------------- 1 file changed, 129 insertions(+), 121 deletions(-) diff --git a/PIL/Image.py b/PIL/Image.py index 58b85d5d2..6f5e37591 100644 --- a/PIL/Image.py +++ b/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: From 39d5e639f01b2518276fe1f9e220b6e11412ce2c Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Fri, 11 Oct 2013 22:45:09 -0700 Subject: [PATCH 03/12] Fully document PIL.ImageChops --- docs/reference/ImageChops.rst | 41 +++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 2 files changed, 42 insertions(+) create mode 100644 docs/reference/ImageChops.rst diff --git a/docs/reference/ImageChops.rst b/docs/reference/ImageChops.rst new file mode 100644 index 000000000..d2e921c59 --- /dev/null +++ b/docs/reference/ImageChops.rst @@ -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 diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 3f6385c47..6b8b45c9f 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -5,4 +5,5 @@ Reference :maxdepth: 2 Image + ImageChops ../PIL From 546c20491fa1a7e39609acb237ece58e032625c1 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Fri, 11 Oct 2013 22:45:23 -0700 Subject: [PATCH 04/12] Improve ImageChops docstrings --- PIL/ImageChops.py | 166 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 148 insertions(+), 18 deletions(-) diff --git a/PIL/ImageChops.py b/PIL/ImageChops.py index dfd71eeeb..4ddaf05c3 100644 --- a/PIL/ImageChops.py +++ b/PIL/ImageChops.py @@ -41,7 +41,10 @@ from PIL import Image # @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) @@ -52,7 +55,10 @@ def constant(image, value): # @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() @@ -64,7 +70,15 @@ def duplicate(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()) @@ -81,7 +95,16 @@ def invert(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() @@ -99,7 +122,16 @@ def lighter(image1, image2): # @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() @@ -116,7 +148,16 @@ def darker(image1, image2): # @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() @@ -135,7 +176,18 @@ def difference(image1, image2): # @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() @@ -152,7 +204,15 @@ def multiply(image1, image2): # @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() @@ -170,7 +230,16 @@ def screen(image1, image2): # @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() @@ -188,7 +257,16 @@ def add(image1, image2, scale=1.0, offset=0): # @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() @@ -205,7 +283,14 @@ def subtract(image1, image2, scale=1.0, offset=0): # @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() @@ -222,7 +307,14 @@ def add_modulo(image1, image2): # @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() @@ -233,7 +325,14 @@ def subtract_modulo(image1, image2): # (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() @@ -244,7 +343,14 @@ def logical_and(image1, image2): # (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() @@ -255,7 +361,14 @@ def logical_or(image1, image2): # (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() @@ -267,7 +380,11 @@ def logical_xor(image1, image2): # Same as the blend function in the Image 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) @@ -277,7 +394,11 @@ def blend(image1, image2, alpha): # Same as the composite function in the Image 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) @@ -295,7 +416,16 @@ def composite(image1, image2, mask): # @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() From a31a84f012d04602b06c91982d15bcbac5a6cf4e Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Fri, 11 Oct 2013 22:46:39 -0700 Subject: [PATCH 05/12] Remove ImageChops from PIL.rst --- docs/PIL.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/PIL.rst b/docs/PIL.rst index 2595c22ba..c191d42a3 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -57,14 +57,6 @@ PIL Package :undoc-members: :show-inheritance: -:mod:`ImageChops` Module ------------------------- - -.. automodule:: PIL.ImageChops - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageCms` Module ---------------------- From 1e726ea36a517b041a7543a8e4d2516ffd728023 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Fri, 11 Oct 2013 22:46:57 -0700 Subject: [PATCH 06/12] Remove old ImageChops comments; redundant with docstrings --- PIL/ImageChops.py | 149 ---------------------------------------------- 1 file changed, 149 deletions(-) diff --git a/PIL/ImageChops.py b/PIL/ImageChops.py index 4ddaf05c3..ba5350e02 100644 --- a/PIL/ImageChops.py +++ b/PIL/ImageChops.py @@ -17,28 +17,6 @@ from PIL import Image -## -# The 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. -#

-# At this time, channel operations are only implemented for 8-bit -# images (e.g. "L" and "RGB"). -#

-# 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. @@ -48,11 +26,6 @@ def constant(image, value): return Image.new("L", image.size, value) -## -# Copy image. -# -# @param image Source image. -# @return A copy of the source image. def duplicate(image): """Copy a channel. Alias for :py:meth:`PIL.Image.Image.copy`. @@ -62,12 +35,6 @@ def duplicate(image): return image.copy() -## -# Inverts an image -# (MAX - image). -# -# @param image Source image. -# @return An image object. def invert(image): """ @@ -83,16 +50,6 @@ def invert(image): image.load() return image._new(image.im.chop_invert()) -## -# Compare images, and return lighter pixel value -# (max(image1, image2)). -#

-# 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): """ @@ -110,16 +67,6 @@ def lighter(image1, image2): image2.load() return image1._new(image1.im.chop_lighter(image2.im)) -## -# Compare images, and return darker pixel value -# (min(image1, image2)). -#

-# 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): """ @@ -137,15 +84,6 @@ def darker(image1, image2): image2.load() return image1._new(image1.im.chop_darker(image2.im)) -## -# Calculate absolute difference -# (abs(image1 - image2)). -#

-# 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): """ @@ -163,17 +101,6 @@ def difference(image1, image2): image2.load() return image1._new(image1.im.chop_difference(image2.im)) -## -# Superimpose positive images -# (image1 * image2 / MAX). -#

-# 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): """ @@ -193,15 +120,6 @@ def multiply(image1, image2): image2.load() return image1._new(image1.im.chop_multiply(image2.im)) -## -# Superimpose negative images -# (MAX - ((MAX - image1) * (MAX - image2) / MAX)). -#

-# 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): """ @@ -218,16 +136,6 @@ def screen(image1, image2): image2.load() return image1._new(image1.im.chop_screen(image2.im)) -## -# Add images -# ((image1 + image2) / scale + offset). -#

-# 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): """ @@ -245,16 +153,6 @@ def add(image1, image2, scale=1.0, offset=0): image2.load() return image1._new(image1.im.chop_add(image2.im, scale, offset)) -## -# Subtract images -# ((image1 - image2) / scale + offset). -#

-# 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): """ @@ -272,15 +170,6 @@ def subtract(image1, image2, scale=1.0, offset=0): image2.load() return image1._new(image1.im.chop_subtract(image2.im, scale, offset)) -## -# Add images without clipping -# ((image1 + image2) % MAX). -#

-# 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 the result. @@ -296,15 +185,6 @@ def add_modulo(image1, image2): image2.load() return image1._new(image1.im.chop_add_modulo(image2.im)) -## -# Subtract images without clipping -# ((image1 - image2) % MAX). -#

-# 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 the result. @@ -320,9 +200,6 @@ def subtract_modulo(image1, image2): 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. @@ -338,9 +215,6 @@ def logical_and(image1, image2): 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. @@ -356,9 +230,6 @@ def logical_or(image1, image2): 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. @@ -374,10 +245,6 @@ def logical_xor(image1, image2): image2.load() return image1._new(image1.im.chop_xor(image2.im)) -## -# Blend images using constant transparency weight. -#

-# Same as the blend function in the Image module. def blend(image1, image2, alpha): """Blend images using constant transparency weight. Alias for @@ -388,10 +255,6 @@ def blend(image1, image2, alpha): return Image.blend(image1, image2, alpha) -## -# Create composite using transparency mask. -#

-# Same as the composite function in the Image module. def composite(image1, image2, mask): """Create composite using transparency mask. Alias for @@ -402,18 +265,6 @@ def composite(image1, image2, mask): return Image.composite(image1, image2, mask) -## -# Offset image data. -#

-# 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): """Returns a copy of the image where data has been offset by the given From 88c700f3b2811378ccc4ee86aea5140a2ed0cf65 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Fri, 11 Oct 2013 22:54:24 -0700 Subject: [PATCH 07/12] Fully document PIL.ImageColor --- PIL/ImageColor.py | 19 ++++++++++++++++ docs/PIL.rst | 8 ------- docs/reference/ImageColor.rst | 41 +++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 4 files changed, 61 insertions(+), 8 deletions(-) create mode 100644 docs/reference/ImageColor.rst diff --git a/PIL/ImageColor.py b/PIL/ImageColor.py index 86f221adc..c14257151 100644 --- a/PIL/ImageColor.py +++ b/PIL/ImageColor.py @@ -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": diff --git a/docs/PIL.rst b/docs/PIL.rst index c191d42a3..517439caa 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -65,14 +65,6 @@ PIL Package :undoc-members: :show-inheritance: -:mod:`ImageColor` Module ------------------------- - -.. automodule:: PIL.ImageColor - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageDraw` Module ----------------------- diff --git a/docs/reference/ImageColor.rst b/docs/reference/ImageColor.rst new file mode 100644 index 000000000..2d6dd0355 --- /dev/null +++ b/docs/reference/ImageColor.rst @@ -0,0 +1,41 @@ +.. 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 +----------- + +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 diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 6b8b45c9f..8604a8787 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -6,4 +6,5 @@ Reference Image ImageChops + ImageColor ../PIL From 5c9329d5ba79a6d9f24428306fdb803e14f7a68a Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 00:52:01 -0700 Subject: [PATCH 08/12] Fully document PIL.ImageDraw --- docs/reference/ImageColor.rst | 2 + docs/reference/ImageDraw.rst | 239 ++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 3 files changed, 242 insertions(+) create mode 100644 docs/reference/ImageDraw.rst diff --git a/docs/reference/ImageColor.rst b/docs/reference/ImageColor.rst index 2d6dd0355..3115b975f 100644 --- a/docs/reference/ImageColor.rst +++ b/docs/reference/ImageColor.rst @@ -9,6 +9,8 @@ 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 ----------- diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst new file mode 100644 index 000000000..cc3377c3e --- /dev/null +++ b/docs/reference/ImageDraw.rst @@ -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. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 8604a8787..34669c7a2 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -7,4 +7,5 @@ Reference Image ImageChops ImageColor + ImageDraw ../PIL From 7b9c19b29331212d8efdf2c600e23b365fbc5012 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 00:53:46 -0700 Subject: [PATCH 09/12] Tweak PIL.rst namespace and description --- docs/PIL.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/PIL.rst b/docs/PIL.rst index 517439caa..1f4863c24 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -1,5 +1,8 @@ -PIL Package -=========== +PIL Package (autodoc) +===================== + +Reference for modules whose documentation has not yet been ported or written +can be found here. :mod:`BdfFontFile` Module ------------------------- From 5cf0d35a5bc21e74ca19048020f6090988857dc2 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 00:54:25 -0700 Subject: [PATCH 10/12] Remove ImageDraw from PIL.rst --- docs/PIL.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/PIL.rst b/docs/PIL.rst index 1f4863c24..4754d739d 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -68,14 +68,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageDraw` Module ------------------------ - -.. automodule:: PIL.ImageDraw - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageDraw2` Module ------------------------ From c69c6df8b5aee303c3346a6e2ee9937e82b3cdb2 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 00:55:39 -0700 Subject: [PATCH 11/12] Clearer PIL.rst title --- docs/PIL.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/PIL.rst b/docs/PIL.rst index 4754d739d..0f4f196fd 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -1,5 +1,5 @@ -PIL Package (autodoc) -===================== +PIL Package (autodoc of remaining modules) +========================================== Reference for modules whose documentation has not yet been ported or written can be found here. From b24fbfaab648189a83e7f7d01239565fd7a78118 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 00:56:39 -0700 Subject: [PATCH 12/12] Move reference above appendices in ToC --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 70e8871b7..e560c2594 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,8 +35,8 @@ source and contribute at https://github.com/python-imaging/Pillow. installation about guides - handbook/appendices reference/index.rst + handbook/appendices original-readme Support Pillow!