From 20b9d9774a2fb3f3be3a445b470905f9737ac362 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 22:17:45 -0700 Subject: [PATCH] Fully document PIL.ImageOps; fix some :py:mod: markup --- PIL/ImageOps.py | 249 ++++++++++++++++---------------- docs/reference/Image.rst | 4 +- docs/reference/ImageChops.rst | 4 +- docs/reference/ImageColor.rst | 4 +- docs/reference/ImageDraw.rst | 4 +- docs/reference/ImageEnhance.rst | 4 +- docs/reference/ImageFile.rst | 4 +- docs/reference/ImageFilter.rst | 4 +- docs/reference/ImageFont.rst | 4 +- docs/reference/ImageGrab.rst | 4 +- docs/reference/ImageMath.rst | 4 +- docs/reference/ImageOps.rst | 27 ++++ docs/reference/index.rst | 1 + 13 files changed, 169 insertions(+), 148 deletions(-) create mode 100644 docs/reference/ImageOps.rst diff --git a/PIL/ImageOps.py b/PIL/ImageOps.py index 943c6cafb..0d22f8c64 100644 --- a/PIL/ImageOps.py +++ b/PIL/ImageOps.py @@ -22,14 +22,6 @@ from PIL._util import isStringType import operator from functools import reduce -## -# (New in 1.1.3) The 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. -# -# @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 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. 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 black and white -# 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 -# getmesh 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. -#

-# The fit 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, - cropped to the aspect ratio and size that you request. + Returns a sized and cropped version of the image, cropped to the + 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: diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index 107c8a753..fe13c882b 100644 --- a/docs/reference/Image.rst +++ b/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 diff --git a/docs/reference/ImageChops.rst b/docs/reference/ImageChops.rst index d2e921c59..c95363c5d 100644 --- a/docs/reference/ImageChops.rst +++ b/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 diff --git a/docs/reference/ImageColor.rst b/docs/reference/ImageColor.rst index 3115b975f..da9b406e1 100644 --- a/docs/reference/ImageColor.rst +++ b/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 diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index c3210f6fc..68855eb5b 100644 --- a/docs/reference/ImageDraw.rst +++ b/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 diff --git a/docs/reference/ImageEnhance.rst b/docs/reference/ImageEnhance.rst index e951b8e53..e6eae85f0 100644 --- a/docs/reference/ImageEnhance.rst +++ b/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. diff --git a/docs/reference/ImageFile.rst b/docs/reference/ImageFile.rst index 57476780d..9612658e9 100644 --- a/docs/reference/ImageFile.rst +++ b/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. diff --git a/docs/reference/ImageFilter.rst b/docs/reference/ImageFilter.rst index 9866792ff..e89fafbcf 100644 --- a/docs/reference/ImageFilter.rst +++ b/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() diff --git a/docs/reference/ImageFont.rst b/docs/reference/ImageFont.rst index c93df7d3b..166d977a6 100644 --- a/docs/reference/ImageFont.rst +++ b/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 diff --git a/docs/reference/ImageGrab.rst b/docs/reference/ImageGrab.rst index 28865ccc3..f22847b5d 100644 --- a/docs/reference/ImageGrab.rst +++ b/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. diff --git a/docs/reference/ImageMath.rst b/docs/reference/ImageMath.rst index 6327987ed..e3f9ed8d6 100644 --- a/docs/reference/ImageMath.rst +++ b/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 diff --git a/docs/reference/ImageOps.rst b/docs/reference/ImageOps.rst new file mode 100644 index 000000000..50cea90ca --- /dev/null +++ b/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 diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 5681d2c4e..b996c9160 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -14,4 +14,5 @@ Reference ImageFont ImageGrab ImageMath + ImageOps ../PIL