From f2be739fdf8cea6478f73444483a44fb28347a3a Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 13:48:34 -0700 Subject: [PATCH 01/11] Fully document PIL.ImageEnhance --- PIL/ImageEnhance.py | 75 ++++++++++++++++----------------- docs/PIL.rst | 8 ---- docs/reference/ImageEnhance.rst | 41 ++++++++++++++++++ docs/reference/index.rst | 1 + 4 files changed, 78 insertions(+), 47 deletions(-) create mode 100644 docs/reference/ImageEnhance.rst diff --git a/PIL/ImageEnhance.py b/PIL/ImageEnhance.py index 34d69d569..10433343e 100644 --- a/PIL/ImageEnhance.py +++ b/PIL/ImageEnhance.py @@ -20,71 +20,68 @@ from PIL import Image, ImageFilter, ImageStat + class _Enhance: - ## - # Returns an enhanced image. The enhancement factor is a floating - # point value controlling the enhancement. Factor 1.0 always - # returns a copy of the original image, lower factors mean less - # colour (brightness, contrast, etc), and higher values more. - # There are no restrictions on this value. - # - # @param factor Enhancement factor. - # @return An enhanced image. - def enhance(self, factor): + """ + Returns an enhanced image. + + :param factor: A floating point value controlling the enhancement. + Factor 1.0 always returns a copy of the original image, + lower factors mean less color (brightness, contrast, + etc), and higher values more. There are no restrictions + on this value. + :rtype: :py:class:`~PIL.Image.Image` + """ return Image.blend(self.degenerate, self.image, factor) -## -# Color enhancement object. -#

-# This class can be used to adjust the colour balance of an image, in -# a manner similar to the controls on a colour TV set. An enhancement -# factor of 0.0 gives a black and white image, a factor of 1.0 gives -# the original image. class Color(_Enhance): - "Adjust image colour balance" + """Adjust image color balance. + + This class can be used to adjust the colour balance of an image, in + a manner similar to the controls on a colour TV set. An enhancement + factor of 0.0 gives a black and white image. A factor of 1.0 gives + the original image. + """ def __init__(self, image): self.image = image self.degenerate = image.convert("L").convert(image.mode) -## -# Contrast enhancement object. -#

-# This class can be used to control the contrast of an image, similar -# to the contrast control on a TV set. An enhancement factor of 0.0 -# gives a solid grey image, factor 1.0 gives the original image. class Contrast(_Enhance): - "Adjust image contrast" + """Adjust image contrast. + + This class can be used to control the contrast of an image, similar + to the contrast control on a TV set. An enhancement factor of 0.0 + gives a solid grey image. A factor of 1.0 gives the original image. + """ def __init__(self, image): self.image = image mean = int(ImageStat.Stat(image.convert("L")).mean[0] + 0.5) self.degenerate = Image.new("L", image.size, mean).convert(image.mode) -## -# Brightness enhancement object. -#

-# This class can be used to control the brighntess of an image. An -# enhancement factor of 0.0 gives a black image, factor 1.0 gives the -# original image. class Brightness(_Enhance): - "Adjust image brightness" + """Adjust image brightness. + + This class can be used to control the brighntess of an image. An + enhancement factor of 0.0 gives a black image. A factor of 1.0 gives the + original image. + """ def __init__(self, image): self.image = image self.degenerate = Image.new(image.mode, image.size, 0) -## -# Sharpness enhancement object. -#

-# This class can be used to adjust the sharpness of an image. The -# enhancement factor 0.0 gives a blurred image, 1.0 gives the original -# image, and a factor of 2.0 gives a sharpened image. class Sharpness(_Enhance): - "Adjust image sharpness" + """Adjust image sharpness. + + This class can be used to adjust the sharpness of an image. An + enhancement factor of 0.0 gives a blurred image, a factor of 1.0 gives the + original image, and a factor of 2.0 gives a sharpened image. + """ def __init__(self, image): self.image = image self.degenerate = image.filter(ImageFilter.SMOOTH) diff --git a/docs/PIL.rst b/docs/PIL.rst index 0f4f196fd..32e9fe4ea 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -76,14 +76,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageEnhance` Module --------------------------- - -.. automodule:: PIL.ImageEnhance - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageFile` Module ----------------------- diff --git a/docs/reference/ImageEnhance.rst b/docs/reference/ImageEnhance.rst new file mode 100644 index 000000000..94e1c9b2a --- /dev/null +++ b/docs/reference/ImageEnhance.rst @@ -0,0 +1,41 @@ +.. py:module:: PIL.ImageEnhance +.. py:currentmodule:: PIL.ImageEnhance + +:mod:`ImageEnhance` Module +========================== + +The :py:mod:`ImageEnhance` module contains a number of classes that can be used +for image enhancement. + +Example +------- + +Vary the Sharpness of an Image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + import ImageEnhance + + enhancer = ImageEnhance.Sharpness(image) + + for i in range(8): + factor = i / 4.0 + enhancer.enhance(factor).show("Sharpness %f" % factor) + +Also see the :file:`enhancer.py` demo program in the :file:`Scripts/` +directory. + +Classes +------- + +All enhancement classes implement a common interface, containing a single +method: + +.. autoclass:: PIL.ImageEnhance._Enhance + :members: + +.. autoclass:: PIL.ImageEnhance.Color +.. autoclass:: PIL.ImageEnhance.Contrast +.. autoclass:: PIL.ImageEnhance.Brightness +.. autoclass:: PIL.ImageEnhance.Sharpness diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 34669c7a2..8198fdcbc 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -8,4 +8,5 @@ Reference ImageChops ImageColor ImageDraw + ImageEnhance ../PIL From b98c3f05cdc2641b9060ca6bddfb76a70eb38c35 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 13:53:31 -0700 Subject: [PATCH 02/11] Fix a couple of example imports --- docs/reference/ImageDraw.rst | 2 +- docs/reference/ImageEnhance.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index cc3377c3e..c3210f6fc 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -18,7 +18,7 @@ Example: Draw a gray cross over an image .. code-block:: python - import Image, ImageDraw + from PIL import Image, ImageDraw im = Image.open("lena.pgm") diff --git a/docs/reference/ImageEnhance.rst b/docs/reference/ImageEnhance.rst index 94e1c9b2a..db068bb84 100644 --- a/docs/reference/ImageEnhance.rst +++ b/docs/reference/ImageEnhance.rst @@ -15,7 +15,7 @@ Vary the Sharpness of an Image .. code-block:: python - import ImageEnhance + from PIL import ImageEnhance enhancer = ImageEnhance.Sharpness(image) From 348daf9490cde850e7d5c5c71b7ea3010ff123c9 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 13:57:27 -0700 Subject: [PATCH 03/11] Document ImageFile.Parser --- PIL/ImageFile.py | 10 ++++++--- docs/PIL.rst | 8 ------- docs/reference/ImageFile.rst | 41 ++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 4 files changed, 49 insertions(+), 11 deletions(-) create mode 100644 docs/reference/ImageFile.rst diff --git a/PIL/ImageFile.py b/PIL/ImageFile.py index c86f0a177..70762b4b0 100644 --- a/PIL/ImageFile.py +++ b/PIL/ImageFile.py @@ -137,7 +137,7 @@ class ImageFile(Image.Image): readonly = 0 if self.filename and len(self.tile) == 1 and not hasattr(sys, 'pypy_version_info'): - # As of pypy 2.1.0, memory mapping was failing here. + # As of pypy 2.1.0, memory mapping was failing here. # try memory mapping d, e, o, a = self.tile[0] if d == "raw" and a[0] == self.mode and a[0] in Image._MAPMODES: @@ -299,6 +299,8 @@ class Parser: """ Incremental image parser. This class implements the standard feed/close consumer interface. + + In Python 2.x, this is an old-style class. """ incremental = None image = None @@ -318,7 +320,7 @@ class Parser: """ (Consumer) Feed data to the parser. - :param data" A string buffer. + :param data: A string buffer. :exception IOError: If the parser failed to parse the image file. """ # collect data @@ -404,7 +406,9 @@ class Parser: (Consumer) Close the stream. :returns: An image object. - :exception IOError: If the parser failed to parse the image file. + :exception IOError: If the parser failed to parse the image file either + because it cannot be identified or cannot be + decoded. """ # finish decoding if self.decoder: diff --git a/docs/PIL.rst b/docs/PIL.rst index 32e9fe4ea..2665ce9c4 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -76,14 +76,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageFile` Module ------------------------ - -.. automodule:: PIL.ImageFile - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageFileIO` Module ------------------------- diff --git a/docs/reference/ImageFile.rst b/docs/reference/ImageFile.rst new file mode 100644 index 000000000..57476780d --- /dev/null +++ b/docs/reference/ImageFile.rst @@ -0,0 +1,41 @@ +.. py:module:: PIL.ImageFile +.. py:currentmodule:: PIL.ImageFile + +:mod:`ImageFile` Module +======================= + +The :py:mod:`ImageFile` module provides support functions for the image open +and save functions. + +In addition, it provides a :py:class:`Parser` class which can be used to decode +an image piece by piece (e.g. while receiving it over a network connection). +This class implements the same consumer interface as the standard **sgmllib** +and **xmllib** modules. + +Example: Parse an image +----------------------- + +.. code-block:: python + + from PIL import ImageFile + + fp = open("lena.pgm", "rb") + + p = ImageFile.Parser() + + while 1: + s = fp.read(1024) + if not s: + break + p.feed(s) + + im = p.close() + + im.save("copy.jpg") + + +:py:class:`~PIL.ImageFile.Parser` +--------------------------------- + +.. autoclass:: PIL.ImageFile.Parser() + :members: diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 8198fdcbc..0ef01aa56 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -9,4 +9,5 @@ Reference ImageColor ImageDraw ImageEnhance + ImageFile ../PIL From 11cd6a9150bff1d625dfc1563b4338aa5517483f Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 13:58:53 -0700 Subject: [PATCH 04/11] Comments identifying modules to skip documenting --- docs/PIL.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/PIL.rst b/docs/PIL.rst index 2665ce9c4..2ec1e1b70 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -68,6 +68,7 @@ can be found here. :undoc-members: :show-inheritance: +.. intentionally skipped documenting this because it's not documented anywhere :mod:`ImageDraw2` Module ------------------------ @@ -76,6 +77,7 @@ can be found here. :undoc-members: :show-inheritance: +.. intentionally skipped documenting this because it's deprecated :mod:`ImageFileIO` Module ------------------------- From a2c67dc3afe9a5f63e4b4d1721217f975aa46b7d Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 16:49:32 -0700 Subject: [PATCH 05/11] Fully document PIL.ImageFilter --- PIL/ImageFilter.py | 154 ++++++++++++++------------------- docs/reference/ImageFilter.rst | 47 ++++++++++ docs/reference/index.rst | 1 + 3 files changed, 114 insertions(+), 88 deletions(-) create mode 100644 docs/reference/ImageFilter.rst diff --git a/PIL/ImageFilter.py b/PIL/ImageFilter.py index c13f75bbc..ac8fe9f19 100644 --- a/PIL/ImageFilter.py +++ b/PIL/ImageFilter.py @@ -17,31 +17,28 @@ from functools import reduce + class Filter(object): pass -## -# Convolution filter kernel. class Kernel(Filter): + """ + Create a convolution kernel. The current version only + supports 3x3 and 5x5 integer and floating point kernels. - ## - # Create a convolution kernel. The current version only - # supports 3x3 and 5x5 integer and floating point kernels. - #

- # In the current version, kernels can only be applied to - # "L" and "RGB" images. - # - # @def __init__(size, kernel, **options) - # @param size Kernel size, given as (width, height). In - # the current version, this must be (3,3) or (5,5). - # @param kernel A sequence containing kernel weights. - # @param **options Optional keyword arguments. - # @keyparam scale Scale factor. If given, the result for each - # pixel is divided by this value. The default is the sum - # of the kernel weights. - # @keyparam offset Offset. If given, this value is added to the - # result, after it has been divided by the scale factor. + In the current version, kernels can only be applied to + "L" and "RGB" images. + + :param size: Kernel size, given as (width, height). In the current + version, this must be (3,3) or (5,5). + :param kernel: A sequence containing kernel weights. + :param scale: Scale factor. If given, the result for each pixel is + divided by this value. the default is the sum of the + kernel weights. + :param offset: Offset. If given, this value is added to the result, + after it has been divided by the scale factor. + """ def __init__(self, size, kernel, scale=None, offset=0): if scale is None: @@ -56,24 +53,23 @@ class Kernel(Filter): raise ValueError("cannot filter palette images") return image.filter(*self.filterargs) + class BuiltinFilter(Kernel): def __init__(self): pass -## -# Rank filter. class RankFilter(Filter): - name = "Rank" + """ + Create a rank filter. The rank filter sorts all pixels in + a window of the given size, and returns the **rank**'th value. - ## - # Create a rank filter. The rank filter sorts all pixels in - # a window of the given size, and returns the rank'th value. - # - # @param size The kernel size, in pixels. - # @param rank What pixel value to pick. Use 0 for a min filter, - # size*size/2 for a median filter, size*size-1 for a max filter, - # etc. + :param size: The kernel size, in pixels. + :param rank: What pixel value to pick. Use 0 for a min filter, + ``size * size / 2`` for a median filter, ``size * size - 1`` + for a max filter, etc. + """ + name = "Rank" def __init__(self, size, rank): self.size = size @@ -85,99 +81,99 @@ class RankFilter(Filter): image = image.expand(self.size//2, self.size//2) return image.rankfilter(self.size, self.rank) -## -# Median filter. Picks the median pixel value in a window with the -# given size. class MedianFilter(RankFilter): - name = "Median" + """ + Create a median filter. Picks the median pixel value in a window with the + given size. - ## - # Create a median filter. - # - # @param size The kernel size, in pixels. + :param size: The kernel size, in pixels. + """ + name = "Median" def __init__(self, size=3): self.size = size self.rank = size*size//2 -## -# Min filter. Picks the lowest pixel value in a window with the given -# size. class MinFilter(RankFilter): - name = "Min" + """ + Create a min filter. Picks the lowest pixel value in a window with the + given size. - ## - # Create a min filter. - # - # @param size The kernel size, in pixels. + :param size: The kernel size, in pixels. + """ + name = "Min" def __init__(self, size=3): self.size = size self.rank = 0 -## -# Max filter. Picks the largest pixel value in a window with the -# given size. class MaxFilter(RankFilter): - name = "Max" + """ + Create a max filter. Picks the largest pixel value in a window with the + given size. - ## - # Create a max filter. - # - # @param size The kernel size, in pixels. + :param size: The kernel size, in pixels. + """ + name = "Max" def __init__(self, size=3): self.size = size self.rank = size*size-1 -## -# Mode filter. Picks the most frequent pixel value in a box with the -# given size. Pixel values that occur only once or twice are ignored; -# if no pixel value occurs more than twice, the original pixel value -# is preserved. class ModeFilter(Filter): - name = "Mode" + """ - ## - # Create a mode filter. - # - # @param size The kernel size, in pixels. + Create a mode filter. Picks the most frequent pixel value in a box with the + given size. Pixel values that occur only once or twice are ignored; if no + pixel value occurs more than twice, the original pixel value is preserved. + + :param size: The kernel size, in pixels. + """ + name = "Mode" def __init__(self, size=3): self.size = size + def filter(self, image): return image.modefilter(self.size) -## -# Gaussian blur filter. class GaussianBlur(Filter): + """Gaussian blur filter. + + :param radius: Blur radius. + """ name = "GaussianBlur" def __init__(self, radius=2): self.radius = radius + def filter(self, image): return image.gaussian_blur(self.radius) -## -# Unsharp mask filter. class UnsharpMask(Filter): + """Unsharp mask filter. + + See Wikipedia's entry on `digital unsharp masking`_ for an explanation of + the parameters. + + .. _digital unsharp masking: https://en.wikipedia.org/wiki/Unsharp_masking#Digital_unsharp_masking + """ name = "UnsharpMask" def __init__(self, radius=2, percent=150, threshold=3): self.radius = radius self.percent = percent self.threshold = threshold + def filter(self, image): return image.unsharp_mask(self.radius, self.percent, self.threshold) -## -# Simple blur filter. class BLUR(BuiltinFilter): name = "Blur" @@ -189,8 +185,6 @@ class BLUR(BuiltinFilter): 1, 1, 1, 1, 1 ) -## -# Simple contour filter. class CONTOUR(BuiltinFilter): name = "Contour" @@ -200,8 +194,6 @@ class CONTOUR(BuiltinFilter): -1, -1, -1 ) -## -# Simple detail filter. class DETAIL(BuiltinFilter): name = "Detail" @@ -211,8 +203,6 @@ class DETAIL(BuiltinFilter): 0, -1, 0 ) -## -# Simple edge enhancement filter. class EDGE_ENHANCE(BuiltinFilter): name = "Edge-enhance" @@ -222,8 +212,6 @@ class EDGE_ENHANCE(BuiltinFilter): -1, -1, -1 ) -## -# Simple stronger edge enhancement filter. class EDGE_ENHANCE_MORE(BuiltinFilter): name = "Edge-enhance More" @@ -233,8 +221,6 @@ class EDGE_ENHANCE_MORE(BuiltinFilter): -1, -1, -1 ) -## -# Simple embossing filter. class EMBOSS(BuiltinFilter): name = "Emboss" @@ -244,8 +230,6 @@ class EMBOSS(BuiltinFilter): 0, 0, 0 ) -## -# Simple edge-finding filter. class FIND_EDGES(BuiltinFilter): name = "Find Edges" @@ -255,8 +239,6 @@ class FIND_EDGES(BuiltinFilter): -1, -1, -1 ) -## -# Simple smoothing filter. class SMOOTH(BuiltinFilter): name = "Smooth" @@ -266,8 +248,6 @@ class SMOOTH(BuiltinFilter): 1, 1, 1 ) -## -# Simple stronger smoothing filter. class SMOOTH_MORE(BuiltinFilter): name = "Smooth More" @@ -279,8 +259,6 @@ class SMOOTH_MORE(BuiltinFilter): 1, 1, 1, 1, 1 ) -## -# Simple sharpening filter. class SHARPEN(BuiltinFilter): name = "Sharpen" diff --git a/docs/reference/ImageFilter.rst b/docs/reference/ImageFilter.rst new file mode 100644 index 000000000..0a4f29bfa --- /dev/null +++ b/docs/reference/ImageFilter.rst @@ -0,0 +1,47 @@ +.. py:module:: PIL.ImageFilter +.. py:currentmodule:: PIL.ImageFilter + +:mod:`ImageFilter` Module +========================= + +The :py:mod:`ImageFilter` module contains definitions for a pre-defined set of +filters, which can be be used with :py:meth:`Image.filter() +`. + +Example Filter an image +----------------------- + +.. code-block:: python + + import ImageFilter + + im1 = im.filter(ImageFilter.BLUR) + + im2 = im.filter(ImageFilter.MinFilter(3)) + im3 = im.filter(ImageFilter.MinFilter) # same as MinFilter(3) + +Filters +------- + +The current version of the library provides the following set of predefined +image enhancement filters: + +* **BLUR** +* **CONTOUR** +* **DETAIL** +* **EDGE_ENHANCE** +* **EDGE_ENHANCE_MORE** +* **EMBOSS** +* **FIND_EDGES** +* **SMOOTH** +* **SMOOTH_MORE** +* **SHARPEN** + +.. autoclass:: PIL.ImageFilter.GaussianBlur +.. autoclass:: PIL.ImageFilter.UnsharpMask +.. autoclass:: PIL.ImageFilter.Kernel +.. autoclass:: PIL.ImageFilter.RankFilter +.. autoclass:: PIL.ImageFilter.MedianFilter +.. autoclass:: PIL.ImageFilter.MinFilter +.. autoclass:: PIL.ImageFilter.MaxFilter +.. autoclass:: PIL.ImageFilter.ModeFilter diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 0ef01aa56..510970303 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -10,4 +10,5 @@ Reference ImageDraw ImageEnhance ImageFile + ImageFilter ../PIL From bc0f53aceba284c5c9b85da11228adbec394ad44 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 17:14:12 -0700 Subject: [PATCH 06/11] Fully document PIL.ImageFont --- PIL/ImageFont.py | 99 ++++++++++++++------------------- docs/reference/ImageEnhance.rst | 7 +-- docs/reference/ImageFilter.rst | 10 ++-- docs/reference/ImageFont.rst | 69 +++++++++++++++++++++++ docs/reference/index.rst | 1 + 5 files changed, 120 insertions(+), 66 deletions(-) create mode 100644 docs/reference/ImageFont.rst diff --git a/PIL/ImageFont.py b/PIL/ImageFont.py index 826b37d5c..8313ee3ba 100644 --- a/PIL/ImageFont.py +++ b/PIL/ImageFont.py @@ -61,21 +61,6 @@ except ImportError: # position according to dx, dy. # -------------------------------------------------------------------- -## -# The ImageFont module defines a class with the same name. -# Instances of this class store bitmap fonts, and are used with the -# text method of the ImageDraw class. -#

-# PIL uses it's own font file format to store bitmap fonts. You can -# use the pilfont utility to convert BDF and PCF font -# descriptors (X window font formats) to this format. -#

-# Starting with version 1.1.4, PIL can be configured to support -# TrueType and OpenType fonts. For earlier version, TrueType -# support is only available as part of the imToolkit package -# -# @see ImageDraw#ImageDraw.text -# @see pilfont class ImageFont: "PIL font wrapper" @@ -197,41 +182,42 @@ class TransposedFont: return im.transpose(self.orientation) return im -## -# Load font file. This function loads a font object from the given -# bitmap font file, and returns the corresponding font object. -# -# @param filename Name of font file. -# @return A font object. -# @exception IOError If the file could not be read. def load(filename): - "Load a font file." + """ + Load a font file. This function loads a font object from the given + bitmap font file, and returns the corresponding font object. + + :param filename: Name of font file. + :return: A font object. + :exception IOError: If the file could not be read. + """ f = ImageFont() f._load_pilfont(filename) return f -## -# Load a TrueType or OpenType font file, and create a font object. -# This function loads a font object from the given file, and creates -# a font object for a font of the given size. -#

-# This function requires the _imagingft service. -# -# @param filename A truetype font file. Under Windows, if the file -# is not found in this filename, the loader also looks in Windows -# fonts directory -# @param size The requested size, in points. -# @param index Which font face to load (default is first available face). -# @param encoding Which font encoding to use (default is Unicode). Common -# encodings are "unic" (Unicode), "symb" (Microsoft Symbol), "ADOB" -# (Adobe Standard), "ADBE" (Adobe Expert), and "armn" (Apple Roman). -# See the FreeType documentation for more information. -# @return A font object. -# @exception IOError If the file could not be read. def truetype(font=None, size=10, index=0, encoding="", filename=None): - "Load a truetype font file." + """ + Load a TrueType or OpenType font file, and create a font object. + This function loads a font object from the given file, and creates + a font object for a font of the given size. + + This function requires the _imagingft service. + + :param filename: A truetype font file. Under Windows, if the file + is not found in this filename, the loader also looks in + Windows :file:`fonts/` directory. + :param size: The requested size, in points. + :param index: Which font face to load (default is first available face). + :param encoding: Which font encoding to use (default is Unicode). Common + encodings are "unic" (Unicode), "symb" (Microsoft + Symbol), "ADOB" (Adobe Standard), "ADBE" (Adobe Expert), + and "armn" (Apple Roman). See the FreeType documentation + for more information. + :return: A font object. + :exception IOError: If the file could not be read. + """ if filename: if warnings: @@ -251,17 +237,16 @@ def truetype(font=None, size=10, index=0, encoding="", filename=None): return FreeTypeFont(filename, size, index, encoding) raise -## -# Load font file. Same as load, but searches for a bitmap font along -# the Python path. -# -# @param filename Name of font file. -# @return A font object. -# @exception IOError If the file could not be read. -# @see #load def load_path(filename): - "Load a font file, searching along the Python path." + """ + Load font file. Same as :py:func:`~PIL.ImageFont.load`, but searches for a + bitmap font along the Python path. + + :param filename: Name of font file. + :return: A font object. + :exception IOError: If the file could not be read. + """ for dir in sys.path: if isDirectory(dir): if not isinstance(filename, str): @@ -275,13 +260,14 @@ def load_path(filename): pass raise IOError("cannot find font file") -## -# Load a (probably rather ugly) default font. -# -# @return A font object. def load_default(): - "Load a default font." + """Load a "better than nothing" default font. + + .. versionadded:: 1.1.4 + + :return: A font object. + """ from io import BytesIO import base64 f = ImageFont() @@ -406,6 +392,7 @@ w7IkEbzhVQAAAABJRU5ErkJggg== ''')))) return f + if __name__ == "__main__": # create font data chunk for embedding import base64, os, sys diff --git a/docs/reference/ImageEnhance.rst b/docs/reference/ImageEnhance.rst index db068bb84..e951b8e53 100644 --- a/docs/reference/ImageEnhance.rst +++ b/docs/reference/ImageEnhance.rst @@ -7,11 +7,8 @@ The :py:mod:`ImageEnhance` module contains a number of classes that can be used for image enhancement. -Example -------- - -Vary the Sharpness of an Image -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Example: Vary the sharpness of an image +--------------------------------------- .. code-block:: python diff --git a/docs/reference/ImageFilter.rst b/docs/reference/ImageFilter.rst index 0a4f29bfa..9866792ff 100644 --- a/docs/reference/ImageFilter.rst +++ b/docs/reference/ImageFilter.rst @@ -5,15 +5,15 @@ ========================= The :py:mod:`ImageFilter` module contains definitions for a pre-defined set of -filters, which can be be used with :py:meth:`Image.filter() -`. +filters, which can be be used with the :py:meth:`Image.filter() +` method. -Example Filter an image ------------------------ +Example: Filter an image +------------------------ .. code-block:: python - import ImageFilter + from PIL import ImageFilter im1 = im.filter(ImageFilter.BLUR) diff --git a/docs/reference/ImageFont.rst b/docs/reference/ImageFont.rst new file mode 100644 index 000000000..c93df7d3b --- /dev/null +++ b/docs/reference/ImageFont.rst @@ -0,0 +1,69 @@ +.. py:module:: PIL.ImageFont +.. py:currentmodule:: PIL.ImageFont + +: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 +:py:meth:`PIL.ImageDraw.Draw.text` method. + +PIL uses its own font file format to store bitmap fonts. You can use the +:command`pilfont` utility to convert BDF and PCF font descriptors (X window +font formats) to this format. + +Starting with version 1.1.4, PIL can be configured to support TrueType and +OpenType fonts (as well as other font formats supported by the FreeType +library). For earlier versions, TrueType support is only available as part of +the imToolkit package + +Example +------- + +.. code-block:: python + + from PIL import ImageFont, ImageDraw + + draw = ImageDraw.Draw(image) + + # use a bitmap font + font = ImageFont.load("arial.pil") + + draw.text((10, 10), "hello", font=font) + + # use a truetype font + font = ImageFont.truetype("arial.ttf", 15) + + draw.text((10, 25), "world", font=font) + +Functions +--------- + +.. autofunction:: PIL.ImageFont.load +.. autofunction:: PIL.ImageFont.load_path +.. autofunction:: PIL.ImageFont.truetype +.. autofunction:: PIL.ImageFont.load_default + +Methods +------- + +.. py:method:: PIL.ImageFont.ImageFont.getsize(text) + + :return: (width, height) + +.. py:method:: PIL.ImageFont.ImageFont.getmask(text, mode='') + + Create a bitmap for the text. + + If the font uses antialiasing, the bitmap should have mode “L” and use a + maximum value of 255. Otherwise, it should have mode “1”. + + :param text: Text to render. + :param mode: Used by some graphics drivers to indicate what mode the + driver prefers; if empty, the renderer may return either + mode. Note that the mode is always a string, to simplify + C-level implementations. + + .. versionadded:: 1.1.5 + :return: An internal PIL storage memory instance as defined by the + :py:mod:`PIL.Image.core` interface module. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 510970303..5f8d6fac3 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -11,4 +11,5 @@ Reference ImageEnhance ImageFile ImageFilter + ImageFont ../PIL From cf7b72f9b9159dd919110ea662fb696d6c560331 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 17:22:02 -0700 Subject: [PATCH 07/11] Fully document PIL.ImageGrab --- PIL/ImageGrab.py | 51 ++++++++++++++++++------------------ docs/reference/ImageGrab.rst | 15 +++++++++++ docs/reference/index.rst | 1 + 3 files changed, 42 insertions(+), 25 deletions(-) create mode 100644 docs/reference/ImageGrab.rst diff --git a/PIL/ImageGrab.py b/PIL/ImageGrab.py index 59cc04706..52668ab04 100644 --- a/PIL/ImageGrab.py +++ b/PIL/ImageGrab.py @@ -17,33 +17,31 @@ from PIL import Image -## -# (New in 1.1.3) The ImageGrab module can be used to copy -# the contents of the screen to a PIL image memory. -#

-# The current version works on Windows only.

-# -# @since 1.1.3 -## try: # built-in driver (1.1.3 and later) grabber = Image.core.grabscreen except AttributeError: - # stand-alone driver (pil plus) - import _grabscreen - grabber = _grabscreen.grab + try: + # stand-alone driver (pil plus) + import _grabscreen + grabber = _grabscreen.grab + except ImportError: + # allow the module to be imported by autodoc + grabber = None -## -# (New in 1.1.3) Take a snapshot of the screen. The pixels inside the -# bounding box are returned as an "RGB" image. If the bounding box is -# omitted, the entire screen is copied. -# -# @param bbox What region to copy. Default is the entire screen. -# @return An image -# @since 1.1.3 def grab(bbox=None): + """ + Take a snapshot of the screen. The pixels inside the bounding box are + returned as an "RGB" image. If the bounding box is omitted, the entire + screen is copied. + + .. versionadded:: 1.1.3 + + :param bbox: What region to copy. Default is the entire screen. + :return: An image + """ size, data = grabber() im = Image.frombytes( "RGB", size, data, @@ -55,14 +53,17 @@ def grab(bbox=None): return im ## -# (New in 1.1.4) Take a snapshot of the clipboard image, if any. -# -# @return An image, a list of filenames, or None if the clipboard does -# not contain image data or filenames. Note that if a list is -# returned, the filenames may not represent image files. -# @since 1.1.4 def grabclipboard(): + """ + Take a snapshot of the clipboard image, if any. + + .. versionadded:: 1.1.4 + + :return: An image, a list of filenames, or None if the clipboard does + not contain image data or filenames. Note that if a list is + returned, the filenames may not represent image files. + """ debug = 0 # temporary interface data = Image.core.grabclipboard(debug) if isinstance(data, bytes): diff --git a/docs/reference/ImageGrab.rst b/docs/reference/ImageGrab.rst new file mode 100644 index 000000000..28865ccc3 --- /dev/null +++ b/docs/reference/ImageGrab.rst @@ -0,0 +1,15 @@ +.. py:module:: PIL.ImageGrab +.. py:currentmodule:: PIL.ImageGrab + +: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. + +.. note:: The current version works on Windows only. + +.. versionadded:: 1.1.3 + +.. autofunction:: PIL.ImageGrab.grab +.. autofunction:: PIL.ImageGrab.grabclipboard diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 5f8d6fac3..5bee86b49 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -12,4 +12,5 @@ Reference ImageFile ImageFilter ImageFont + ImageGrab ../PIL From e2d88b5a518393e1a8ab2b067578159595414e57 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 17:40:14 -0700 Subject: [PATCH 08/11] Fully document ImageMath --- PIL/ImageMath.py | 20 +++--- docs/reference/ImageMath.rst | 127 +++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 3 files changed, 139 insertions(+), 9 deletions(-) create mode 100644 docs/reference/ImageMath.rst diff --git a/PIL/ImageMath.py b/PIL/ImageMath.py index 395323fd3..b2355ed1d 100644 --- a/PIL/ImageMath.py +++ b/PIL/ImageMath.py @@ -199,17 +199,19 @@ for k, v in list(globals().items()): if k[:10] == "imagemath_": ops[k[10:]] = v -## -# Evaluates an image expression. -# -# @param expression A string containing a Python-style expression. -# @keyparam options Values to add to the evaluation context. You -# can either use a dictionary, or one or more keyword arguments. -# @return The evaluated expression. This is usually an image object, -# but can also be an integer, a floating point value, or a pixel -# tuple, depending on the expression. def eval(expression, _dict={}, **kw): + """ + Evaluates an image expression. + + :param expression: A string containing a Python-style expression. + :param options: Values to add to the evaluation context. You + can either use a dictionary, or one or more keyword + arguments. + :return: The evaluated expression. This is usually an image object, but can + also be an integer, a floating point value, or a pixel tuple, + depending on the expression. + """ # build execution namespace args = ops.copy() diff --git a/docs/reference/ImageMath.rst b/docs/reference/ImageMath.rst new file mode 100644 index 000000000..6327987ed --- /dev/null +++ b/docs/reference/ImageMath.rst @@ -0,0 +1,127 @@ +.. py:module:: PIL.ImageMath +.. py:currentmodule:: PIL.ImageMath + +: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 +one or more images. + +Example: Using the :py:mod:`~PIL.ImageMath` module +-------------------------------------------------- + +.. code-block:: python + + import Image, ImageMath + + im1 = Image.open("image1.jpg") + im2 = Image.open("image2.jpg") + + out = ImageMath.eval("convert(min(a, b), 'L')", a=im1, b=im2) + out.save("result.png") + +.. py:function:: eval(expression, environment) + + Evaluate expression in the given environment. + + In the current version, :py:mod:`~PIL.ImageMath` only supports + single-layer images. To process multi-band images, use the + :py:meth:`~PIL.Image.Image.split` method or :py:func:`~PIL.Image.merge` + function. + + :param expression: A string which uses the standard Python expression + syntax. In addition to the standard operators, you can + also use the functions described below. + :param environment: A dictionary that maps image names to Image instances. + You can use one or more keyword arguments instead of a + dictionary, as shown in the above example. Note that + the names must be valid Python identifiers. + :return: An image, an integer value, a floating point value, + or a pixel tuple, depending on the expression. + +Expression syntax +----------------- + +Expressions are standard Python expressions, but they’re evaluated in a +non-standard environment. You can use PIL methods as usual, plus the following +set of operators and functions: + +Standard Operators +^^^^^^^^^^^^^^^^^^ + +You can use standard arithmetical operators for addition (+), subtraction (-), +multiplication (*), and division (/). + +The module also supports unary minus (-), modulo (%), and power (**) operators. + +Note that all operations are done with 32-bit integers or 32-bit floating +point values, as necessary. For example, if you add two 8-bit images, the +result will be a 32-bit integer image. If you add a floating point constant to +an 8-bit image, the result will be a 32-bit floating point image. + +You can force conversion using the :py:func:`~PIL.ImageMath.convert`, +:py:func:`~PIL.ImageMath.float`, and :py:func:`~PIL.ImageMath.int` functions +described below. + +Bitwise Operators +^^^^^^^^^^^^^^^^^ + +The module also provides operations that operate on individual bits. This +includes and (&), or (|), and exclusive or (^). You can also invert (~) all +pixel bits. + +Note that the operands are converted to 32-bit signed integers before the +bitwise operation is applied. This means that you’ll get negative values if +you invert an ordinary greyscale image. You can use the and (&) operator to +mask off unwanted bits. + +Bitwise operators don’t work on floating point images. + +Logical Operators +^^^^^^^^^^^^^^^^^ + +Logical operators like :keyword:`and`, :keyword:`or`, and :keyword:`not` work +on entire images, rather than individual pixels. + +An empty image (all pixels zero) is treated as false. All other images are +treated as true. + +Note that :keyword:`and` and :keyword:`or` return the last evaluated operand, +while not always returns a boolean value. + +Built-in Functions +^^^^^^^^^^^^^^^^^^ + +These functions are applied to each individual pixel. + +.. py:currentmodule:: None + +.. py:function:: abs(image) + + Absolute value. + +.. py:function:: convert(image, mode) + + Convert image to the given mode. The mode must be given as a string + constant. + +.. py:function:: float(image) + + Convert image to 32-bit floating point. This is equivalent to + convert(image, “F”). + +.. py:function:: int(image) + + Convert image to 32-bit integer. This is equivalent to convert(image, “I”). + + Note that 1-bit and 8-bit images are automatically converted to 32-bit + integers if necessary to get a correct result. + +.. py:function:: max(image1, image2) + + Maximum value. + +.. py:function:: min(image1, image2) + + Minimum value. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 5bee86b49..5681d2c4e 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -13,4 +13,5 @@ Reference ImageFilter ImageFont ImageGrab + ImageMath ../PIL From 20b9d9774a2fb3f3be3a445b470905f9737ac362 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 22:17:45 -0700 Subject: [PATCH 09/11] 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 From fdc48cba6f905ecfd218d1f0cec2a1816670ca7c Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sat, 12 Oct 2013 22:20:41 -0700 Subject: [PATCH 10/11] Update PIL.rst to remove documented modules --- docs/PIL.rst | 40 ---------------------------------------- 1 file changed, 40 deletions(-) diff --git a/docs/PIL.rst b/docs/PIL.rst index 2ec1e1b70..9b2cb37b9 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -86,46 +86,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageFilter` Module -------------------------- - -.. automodule:: PIL.ImageFilter - :members: - :undoc-members: - :show-inheritance: - -:mod:`ImageFont` Module ------------------------ - -.. automodule:: PIL.ImageFont - :members: - :undoc-members: - :show-inheritance: - -:mod:`ImageMath` Module ------------------------ - -.. automodule:: PIL.ImageMath - :members: - :undoc-members: - :show-inheritance: - -:mod:`ImageMode` Module ------------------------ - -.. automodule:: PIL.ImageMode - :members: - :undoc-members: - :show-inheritance: - -:mod:`ImageOps` Module ----------------------- - -.. automodule:: PIL.ImageOps - :members: - :undoc-members: - :show-inheritance: - :mod:`ImagePalette` Module -------------------------- From 0f3f6dd1a3051832b353326dfaef130de742b417 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 09:56:33 -0700 Subject: [PATCH 11/11] Move ImageGrab docs back to ImageGrab.rst instead of autodoc --- PIL/ImageGrab.py | 30 +++--------------------------- docs/reference/ImageGrab.rst | 22 ++++++++++++++++++++-- 2 files changed, 23 insertions(+), 29 deletions(-) diff --git a/PIL/ImageGrab.py b/PIL/ImageGrab.py index 52668ab04..9bb190934 100644 --- a/PIL/ImageGrab.py +++ b/PIL/ImageGrab.py @@ -22,26 +22,12 @@ try: # built-in driver (1.1.3 and later) grabber = Image.core.grabscreen except AttributeError: - try: - # stand-alone driver (pil plus) - import _grabscreen - grabber = _grabscreen.grab - except ImportError: - # allow the module to be imported by autodoc - grabber = None + # stand-alone driver (pil plus) + import _grabscreen + grabber = _grabscreen.grab def grab(bbox=None): - """ - Take a snapshot of the screen. The pixels inside the bounding box are - returned as an "RGB" image. If the bounding box is omitted, the entire - screen is copied. - - .. versionadded:: 1.1.3 - - :param bbox: What region to copy. Default is the entire screen. - :return: An image - """ size, data = grabber() im = Image.frombytes( "RGB", size, data, @@ -52,18 +38,8 @@ def grab(bbox=None): im = im.crop(bbox) return im -## def grabclipboard(): - """ - Take a snapshot of the clipboard image, if any. - - .. versionadded:: 1.1.4 - - :return: An image, a list of filenames, or None if the clipboard does - not contain image data or filenames. Note that if a list is - returned, the filenames may not represent image files. - """ debug = 0 # temporary interface data = Image.core.grabclipboard(debug) if isinstance(data, bytes): diff --git a/docs/reference/ImageGrab.rst b/docs/reference/ImageGrab.rst index f22847b5d..117be885b 100644 --- a/docs/reference/ImageGrab.rst +++ b/docs/reference/ImageGrab.rst @@ -11,5 +11,23 @@ or the clipboard to a PIL image memory. .. versionadded:: 1.1.3 -.. autofunction:: PIL.ImageGrab.grab -.. autofunction:: PIL.ImageGrab.grabclipboard +.. py:function:: PIL.ImageGrab.grab(bbox=None) + + Take a snapshot of the screen. The pixels inside the bounding box are + returned as an "RGB" image. If the bounding box is omitted, the entire + screen is copied. + + .. versionadded:: 1.1.3 + + :param bbox: What region to copy. Default is the entire screen. + :return: An image + +.. py:function:: PIL.ImageGrab.grabclipboard() + + Take a snapshot of the clipboard image, if any. + + .. versionadded:: 1.1.4 + + :return: An image, a list of filenames, or None if the clipboard does + not contain image data or filenames. Note that if a list is + returned, the filenames may not represent image files.