Fully document PIL.ImageOps; fix some :py:mod: markup

PIL/ImageOps.py

@@ -22,14 +22,6 @@ from PIL._util import isStringType
 import operator
 from functools import reduce
 
-##
-# (New in 1.1.3) The <b>ImageOps</b> module contains a number of
-# 'ready-made' image processing operations.  This module is somewhat
-# experimental, and most operators only work on L and RGB images.
-#
-# @since 1.1.3
-##
-
 #
 # helpers
 
@@ -63,20 +55,20 @@ def _lut(image, lut):
 #
 # actions
 
-##
-# Maximize (normalize) image contrast.  This function calculates a
-# histogram of the input image, removes <i>cutoff</i> percent of the
-# lightest and darkest pixels from the histogram, and remaps the image
-# so that the darkest pixel becomes black (0), and the lightest
-# becomes white (255).
-#
-# @param image The image to process.
-# @param cutoff How many percent to cut off from the histogram.
-# @param ignore The background pixel value (use None for no background).
-# @return An image.
 
 def autocontrast(image, cutoff=0, ignore=None):
-    "Maximize image contrast, based on histogram"
+    """
+    Maximize (normalize) image contrast. This function calculates a
+    histogram of the input image, removes **cutoff** percent of the
+    lightest and darkest pixels from the histogram, and remaps the image
+    so that the darkest pixel becomes black (0), and the lightest
+    becomes white (255).
+
+    :param image: The image to process.
+    :param cutoff: How many percent to cut off from the histogram.
+    :param ignore: The background pixel value (use None for no background).
+    :return: An image.
+    """
     histogram = image.histogram()
     lut = []
     for layer in range(0, len(histogram), 256):
@@ -139,19 +131,19 @@ def autocontrast(image, cutoff=0, ignore=None):
                 lut.append(ix)
     return _lut(image, lut)
 
-##
-# Colorize grayscale image.  The <i>black</i> and <i>white</i>
-# arguments should be RGB tuples; this function calculates a colour
-# wedge mapping all black pixels in the source image to the first
-# colour, and all white pixels to the second colour.
-#
-# @param image The image to colourize.
-# @param black The colour to use for black input pixels.
-# @param white The colour to use for white input pixels.
-# @return An image.
 
 def colorize(image, black, white):
-    "Colorize a grayscale image"
+    """
+    Colorize grayscale image.  The **black** and **white**
+    arguments should be RGB tuples; this function calculates a color
+    wedge mapping all black pixels in the source image to the first
+    color, and all white pixels to the second color.
+
+    :param image: The image to colorize.
+    :param black: The color to use for black input pixels.
+    :param white: The color to use for white input pixels.
+    :return: An image.
+    """
     assert image.mode == "L"
     black = _color(black, "RGB")
     white = _color(white, "RGB")
@@ -163,49 +155,50 @@ def colorize(image, black, white):
     image = image.convert("RGB")
     return _lut(image, red + green + blue)
 
-##
-# Remove border from image.  The same amount of pixels are removed
-# from all four sides.  This function works on all image modes.
-#
-# @param image The image to crop.
-# @param border The number of pixels to remove.
-# @return An image.
-# @see Image#Image.crop
 
 def crop(image, border=0):
-    "Crop border off image"
+    """
+    Remove border from image.  The same amount of pixels are removed
+    from all four sides.  This function works on all image modes.
+
+    .. seealso:: :py:meth:`~PIL.Image.Image.crop`
+
+    :param image: The image to crop.
+    :param border: The number of pixels to remove.
+    :return: An image.
+    """
     left, top, right, bottom = _border(border)
     return image.crop(
         (left, top, image.size[0]-right, image.size[1]-bottom)
         )
 
-##
-# Deform the image.
-#
-# @param image The image to deform.
-# @param deformer A deformer object.  Any object that implements a
-#     <b>getmesh</b> method can be used.
-# @param resample What resampling filter to use.
-# @return An image.
 
 def deform(image, deformer, resample=Image.BILINEAR):
-    "Deform image using the given deformer"
+    """
+    Deform the image.
+
+    :param image: The image to deform.
+    :param deformer: A deformer object.  Any object that implements a
+                    **getmesh** method can be used.
+    :param resample: What resampling filter to use.
+    :return: An image.
+    """
     return image.transform(
         image.size, Image.MESH, deformer.getmesh(image), resample
         )
 
-##
-# Equalize the image histogram.  This function applies a non-linear
-# mapping to the input image, in order to create a uniform
-# distribution of grayscale values in the output image.
-#
-# @param image The image to equalize.
-# @param mask An optional mask.  If given, only the pixels selected by
-#     the mask are included in the analysis.
-# @return An image.
 
 def equalize(image, mask=None):
-    "Equalize image histogram"
+    """
+    Equalize the image histogram. This function applies a non-linear
+    mapping to the input image, in order to create a uniform
+    distribution of grayscale values in the output image.
+
+    :param image: The image to equalize.
+    :param mask: An optional mask.  If given, only the pixels selected by
+                 the mask are included in the analysis.
+    :return: An image.
+    """
     if image.mode == "P":
         image = image.convert("RGB")
     h = image.histogram(mask)
@@ -225,15 +218,16 @@ def equalize(image, mask=None):
                     n = n + h[i+b]
     return _lut(image, lut)
 
-##
-# Add border to the image
-#
-# @param image The image to expand.
-# @param border Border width, in pixels.
-# @param fill Pixel fill value (a colour value).  Default is 0 (black).
-# @return An image.
 
 def expand(image, border=0, fill=0):
+    """
+    Add border to the image
+
+    :param image: The image to expand.
+    :param border: Border width, in pixels.
+    :param fill: Pixel fill value (a color value).  Default is 0 (black).
+    :return: An image.
+    """
     "Add border to image"
     left, top, right, bottom = _border(border)
     width = left + image.size[0] + right
@@ -242,33 +236,32 @@ def expand(image, border=0, fill=0):
     out.paste(image, (left, top))
     return out
 
-##
-# Returns a sized and cropped version of the image, cropped to the
-# requested aspect ratio and size.
-# <p>
-# The <b>fit</b> function was contributed by Kevin Cazabon.
-#
-# @param size The requested output size in pixels, given as a
-#     (width, height) tuple.
-# @param method What resampling method to use.  Default is Image.NEAREST.
-# @param bleed Remove a border around the outside of the image (from all
-#     four edges.  The value is a decimal percentage (use 0.01 for one
-#     percent).  The default value is 0 (no border).
-# @param centering Control the cropping position.  Use (0.5, 0.5) for
-#     center cropping (e.g. if cropping the width, take 50% off of the
-#     left side, and therefore 50% off the right side).  (0.0, 0.0)
-#     will crop from the top left corner (i.e. if cropping the width,
-#     take all of the crop off of the right side, and if cropping the
-#     height, take all of it off the bottom).  (1.0, 0.0) will crop
-#     from the bottom left corner, etc. (i.e. if cropping the width,
-#     take all of the crop off the left side, and if cropping the height
-#     take none from the top, and therefore all off the bottom).
-# @return An image.
 
 def fit(image, size, method=Image.NEAREST, bleed=0.0, centering=(0.5, 0.5)):
     """
-    This method returns a sized and cropped version of the image,
+    Returns a sized and cropped version of the image, cropped to the
-    cropped to the aspect ratio and size that you request.
+    requested aspect ratio and size.
+
+    This function was contributed by Kevin Cazabon.
+
+    :param size: The requested output size in pixels, given as a
+                 (width, height) tuple.
+    :param method: What resampling method to use. Default is
+                   :py:attr:`PIL.Image.NEAREST`.
+    :param bleed: Remove a border around the outside of the image (from all
+                  four edges. The value is a decimal percentage (use 0.01 for
+                  one percent). The default value is 0 (no border).
+    :param centering: Control the cropping position.  Use (0.5, 0.5) for
+                      center cropping (e.g. if cropping the width, take 50% off
+                      of the left side, and therefore 50% off the right side).
+                      (0.0, 0.0) will crop from the top left corner (i.e. if
+                      cropping the width, take all of the crop off of the right
+                      side, and if cropping the height, take all of it off the
+                      bottom).  (1.0, 0.0) will crop from the bottom left
+                      corner, etc. (i.e. if cropping the width, take all of the
+                      crop off the left side, and if cropping the height take
+                      none from the top, and therefore all off the bottom).
+    :return: An image.
     """
 
     # by Kevin Cazabon, Feb 17/2000
@@ -336,73 +329,73 @@ def fit(image, size, method=Image.NEAREST, bleed=0.0, centering=(0.5, 0.5)):
     # resize the image and return it
     return out.resize(size, method)
 
-##
-# Flip the image vertically (top to bottom).
-#
-# @param image The image to flip.
-# @return An image.
 
 def flip(image):
-    "Flip image vertically"
+    """
+    Flip the image vertically (top to bottom).
+
+    :param image: The image to flip.
+    :return: An image.
+    """
     return image.transpose(Image.FLIP_TOP_BOTTOM)
 
-##
-# Convert the image to grayscale.
-#
-# @param image The image to convert.
-# @return An image.
 
 def grayscale(image):
-    "Convert to grayscale"
+    """
+    Convert the image to grayscale.
+
+    :param image: The image to convert.
+    :return: An image.
+    """
     return image.convert("L")
 
-##
-# Invert (negate) the image.
-#
-# @param image The image to invert.
-# @return An image.
 
 def invert(image):
-    "Invert image (negate)"
+    """
+    Invert (negate) the image.
+
+    :param image: The image to invert.
+    :return: An image.
+    """
     lut = []
     for i in range(256):
         lut.append(255-i)
     return _lut(image, lut)
 
-##
-# Flip image horizontally (left to right).
-#
-# @param image The image to mirror.
-# @return An image.
 
 def mirror(image):
-    "Flip image horizontally"
+    """
+    Flip image horizontally (left to right).
+
+    :param image: The image to mirror.
+    :return: An image.
+    """
     return image.transpose(Image.FLIP_LEFT_RIGHT)
 
-##
-# Reduce the number of bits for each colour channel.
-#
-# @param image The image to posterize.
-# @param bits The number of bits to keep for each channel (1-8).
-# @return An image.
 
 def posterize(image, bits):
-    "Reduce the number of bits per color channel"
+    """
+    Reduce the number of bits for each color channel.
+
+    :param image: The image to posterize.
+    :param bits: The number of bits to keep for each channel (1-8).
+    :return: An image.
+    """
     lut = []
     mask = ~(2**(8-bits)-1)
     for i in range(256):
         lut.append(i & mask)
     return _lut(image, lut)
 
-##
-# Invert all pixel values above a threshold.
-#
-# @param image The image to posterize.
-# @param threshold All pixels above this greyscale level are inverted.
-# @return An image.
 
 def solarize(image, threshold=128):
-    "Invert all values above threshold"
+    """
+    Invert all pixel values above a threshold.
+
+    :param image: The image to posterize.
+    :param threshold: All pixels above this greyscale level are inverted.
+    :return: An image.
+    """
     lut = []
     for i in range(256):
         if i < threshold:

docs/reference/Image.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.Image
 .. py:currentmodule:: PIL.Image
 
-:mod:`Image` Module
+:py: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

docs/reference/ImageChops.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageChops
 .. py:currentmodule:: PIL.ImageChops
 
-:mod:`ImageChops` Module
+:py: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

docs/reference/ImageColor.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageColor
 .. py:currentmodule:: PIL.ImageColor
 
-:mod:`ImageColor` Module
+:py: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

docs/reference/ImageDraw.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageDraw
 .. py:currentmodule:: PIL.ImageDraw
 
-:mod:`ImageDraw` Module
+:py: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

docs/reference/ImageEnhance.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageEnhance
 .. py:currentmodule:: PIL.ImageEnhance
 
-:mod:`ImageEnhance` Module
+:py:mod:`ImageEnhance` Module
-==========================
+=============================
 
 The :py:mod:`ImageEnhance` module contains a number of classes that can be used
 for image enhancement.

docs/reference/ImageFile.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageFile
 .. py:currentmodule:: PIL.ImageFile
 
-:mod:`ImageFile` Module
+:py:mod:`ImageFile` Module
-=======================
+==========================
 
 The :py:mod:`ImageFile` module provides support functions for the image open
 and save functions.

docs/reference/ImageFilter.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageFilter
 .. py:currentmodule:: PIL.ImageFilter
 
-:mod:`ImageFilter` Module
+:py:mod:`ImageFilter` Module
-=========================
+============================
 
 The :py:mod:`ImageFilter` module contains definitions for a pre-defined set of
 filters, which can be be used with the :py:meth:`Image.filter()

docs/reference/ImageFont.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageFont
 .. py:currentmodule:: PIL.ImageFont
 
-:mod:`ImageFont` Module
+:py:mod:`ImageFont` Module
-=======================
+==========================
 
 The :py:mod:`ImageFont` module defines a class with the same name. Instances of
 this class store bitmap fonts, and are used with the

docs/reference/ImageGrab.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageGrab
 .. py:currentmodule:: PIL.ImageGrab
 
-:mod:`ImageGrab` Module (Windows-only)
+:py:mod:`ImageGrab` Module (Windows-only)
-======================================
+=========================================
 
 The :py:mod:`ImageGrab` module can be used to copy the contents of the screen
 or the clipboard to a PIL image memory.

docs/reference/ImageMath.rst

@@ -1,8 +1,8 @@
 .. py:module:: PIL.ImageMath
 .. py:currentmodule:: PIL.ImageMath
 
-:mod:`ImageMath` Module
+:py:mod:`ImageMath` Module
-=======================
+==========================
 
 The :py:mod:`ImageMath` module can be used to evaluate “image expressions”. The
 module provides a single eval function, which takes an expression string and

docs/reference/ImageOps.rst

@@ -0,0 +1,27 @@
+.. py:module:: PIL.ImageOps
+.. py:currentmodule:: PIL.ImageOps
+
+:py:mod:`ImageOps` Module
+==========================
+
+The :py:mod:`ImageOps` module contains a number of ‘ready-made’ image
+processing operations. This module is somewhat experimental, and most operators
+only work on L and RGB images.
+
+Only bug fixes have been added since the Pillow fork.
+
+.. versionadded:: 1.1.3
+
+.. autofunction:: autocontrast
+.. autofunction:: colorize
+.. autofunction:: crop
+.. autofunction:: deform
+.. autofunction:: equalize
+.. autofunction:: expand
+.. autofunction:: fit
+.. autofunction:: flip
+.. autofunction:: grayscale
+.. autofunction:: invert
+.. autofunction:: mirror
+.. autofunction:: posterize
+.. autofunction:: solarize

docs/reference/index.rst

@@ -14,4 +14,5 @@ Reference
    ImageFont
    ImageGrab
    ImageMath
+   ImageOps
    ../PIL