From 7881c86bbaf6bdaaef4caab82665fe43d3f893de Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 21:22:18 -0700 Subject: [PATCH 1/8] Document PIL.ImagePalette as best I can --- PIL/ImagePalette.py | 30 +++++++++++++++++++----------- docs/PIL.rst | 8 -------- docs/reference/ImagePalette.rst | 21 +++++++++++++++++++++ docs/reference/index.rst | 1 + 4 files changed, 41 insertions(+), 19 deletions(-) create mode 100644 docs/reference/ImagePalette.rst diff --git a/PIL/ImagePalette.py b/PIL/ImagePalette.py index 2fa051407..61affdb19 100644 --- a/PIL/ImagePalette.py +++ b/PIL/ImagePalette.py @@ -19,11 +19,9 @@ import array from PIL import Image, ImageColor -## -# Colour palette wrapper for palette mapped images. class ImagePalette: - "Colour palette for palette mapped images" + "Color palette for palette mapped images" def __init__(self, mode = "RGB", palette = None): self.mode = mode @@ -35,14 +33,21 @@ class ImagePalette: raise ValueError("wrong palette size") def getdata(self): - # experimental: get palette contents in format suitable - # for the low-level im.putpalette primitive + """ + Get palette contents in format suitable # for the low-level + ``im.putpalette`` primitive. + + .. warning:: This method is experimental. + """ if self.rawmode: return self.rawmode, self.palette return self.mode + ";L", self.tobytes() def tobytes(self): - # experimental: convert palette to bytes + """Convert palette to bytes. + + .. warning:: This method is experimental. + """ if self.rawmode: raise ValueError("palette contains raw palette data") if isinstance(self.palette, bytes): @@ -57,7 +62,10 @@ class ImagePalette: tostring = tobytes def getcolor(self, color): - # experimental: given an rgb tuple, allocate palette entry + """Given an rgb tuple, allocate palette entry. + + .. warning:: This method is experimental. + """ if self.rawmode: raise ValueError("palette contains raw palette data") if isinstance(color, tuple): @@ -80,7 +88,10 @@ class ImagePalette: raise ValueError("unknown color specifier: %r" % color) def save(self, fp): - # (experimental) save palette to text file + """Save palette to text file. + + .. warning:: This method is experimental. + """ if self.rawmode: raise ValueError("palette contains raw palette data") if isinstance(fp, str): @@ -192,6 +203,3 @@ def load(filename): raise IOError("cannot load palette") return lut # data, rawmode - - -# add some psuedocolour palettes as well diff --git a/docs/PIL.rst b/docs/PIL.rst index 9b2cb37b9..431f8f3ee 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -86,14 +86,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImagePalette` Module --------------------------- - -.. automodule:: PIL.ImagePalette - :members: - :undoc-members: - :show-inheritance: - :mod:`ImagePath` Module ----------------------- diff --git a/docs/reference/ImagePalette.rst b/docs/reference/ImagePalette.rst new file mode 100644 index 000000000..15b8aed8f --- /dev/null +++ b/docs/reference/ImagePalette.rst @@ -0,0 +1,21 @@ +.. py:module:: PIL.ImagePalette +.. py:currentmodule:: PIL.ImagePalette + +:py:mod:`ImagePalette` Module +============================= + +The :py:mod:`ImagePalette` module contains a class of the same name to +represent the color palette of palette mapped images. + +.. note:: + + This module was never well-documented. It hasn't changed since 2001, + though, so it's probably safe for you to read the source code and puzzle + out the internals if you need to. + + The :py:class:`~PIL.ImagePalette.ImagePalette` class has several methods, + but they are all marked as "experimental." Read that as you will. The + ``[source]`` link is there for a reason. + +.. autoclass:: PIL.ImagePalette.ImagePalette + :members: diff --git a/docs/reference/index.rst b/docs/reference/index.rst index b996c9160..607ffe10b 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -15,4 +15,5 @@ Reference ImageGrab ImageMath ImageOps + ImagePalette ../PIL From 6566a73bcff226bdfe8dcb24c8740318fd19a770 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 21:41:21 -0700 Subject: [PATCH 2/8] Fully document PIL.ImagePath --- PIL/ImagePath.py | 11 ++---- docs/PIL.rst | 8 ----- docs/reference/ImagePath.rst | 68 ++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 4 files changed, 72 insertions(+), 16 deletions(-) create mode 100644 docs/reference/ImagePath.rst diff --git a/PIL/ImagePath.py b/PIL/ImagePath.py index 63e367063..656d5ce61 100644 --- a/PIL/ImagePath.py +++ b/PIL/ImagePath.py @@ -16,17 +16,12 @@ from PIL import Image -## -# Path wrapper. + +# the Python class below is overridden by the C implementation. + class Path: - ## - # Creates a path object. - # - # @param xy Sequence. The sequence can contain 2-tuples [(x, y), ...] - # or a flat list of numbers [x, y, ...]. - def __init__(self, xy): pass diff --git a/docs/PIL.rst b/docs/PIL.rst index 431f8f3ee..cd2252826 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -86,14 +86,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImagePath` Module ------------------------ - -.. automodule:: PIL.ImagePath - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageQt` Module --------------------- diff --git a/docs/reference/ImagePath.rst b/docs/reference/ImagePath.rst new file mode 100644 index 000000000..700464144 --- /dev/null +++ b/docs/reference/ImagePath.rst @@ -0,0 +1,68 @@ +.. py:module:: PIL.ImagePath +.. py:currentmodule:: PIL.ImagePath + +:py:mod:`ImagePath` Module +========================== + +The :py:mod:`ImagePath` module is used to store and manipulate 2-dimensional +vector data. Path objects can be passed to the methods on the +:py:mod:`~PIL.ImageDraw` module. + +.. py:class:: PIL.ImagePath.Path + + A path object. The coordinate list can be any sequence object containing + either 2-tuples [(x, y), …] or numeric values [x, y, …]. + + You can also create a path object from another path object. + + In 1.1.6 and later, you can also pass in any object that implements + Python’s buffer API. The buffer should provide read access, and contain C + floats in machine byte order. + + The path object implements most parts of the Python sequence interface, and + behaves like a list of (x, y) pairs. You can use len(), item access, and + slicing as usual. However, the current version does not support slice + assignment, or item and slice deletion. + + :param xy: A sequence. The sequence can contain 2-tuples [(x, y), ...] + or a flat list of numbers [x, y, ...]. + +.. py:method:: PIL.ImagePath.Path.compact(distance=2) + + Compacts the path, by removing points that are close to each other. This + method modifies the path in place, and returns the number of points left in + the path. + + **distance** is measured as `Manhattan distance`_ and defaults to two + pixels. + +.. _Manhattan distance: http://en.wikipedia.org/wiki/Manhattan_distance + +.. py:method:: PIL.ImagePath.Path.getbbox() + + Gets the bounding box of the path. + + :return: ``(x0, y0, x1, y1)`` + +.. py:method:: PIL.ImagePath.Path.map(function) + + Maps the path through a function. + +.. py:method:: PIL.ImagePath.Path.tolist(flat=0) + + Converts the path to a Python list [(x, y), …]. + + :param flat: By default, this function returns a list of 2-tuples + [(x, y), ...]. If this argument is :keyword:`True`, it + returns a flat list [x, y, ...] instead. + :return: A list of coordinates. See **flat**. + +.. py:method:: PIL.ImagePath.Path.transform(matrix) + + Transforms the path in place, using an affine transform. The matrix is a + 6-tuple (a, b, c, d, e, f), and each point is mapped as follows: + + .. code-block:: python + + xOut = xIn * a + yIn * b + c + yOut = xIn * d + yIn * e + f diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 607ffe10b..8d206dbb1 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -16,4 +16,5 @@ Reference ImageMath ImageOps ImagePalette + ImagePath ../PIL From 1a72ba260a46c3783423e121d061da93cae0c953 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 21:45:44 -0700 Subject: [PATCH 3/8] Fully document PIL.ImageQt --- docs/PIL.rst | 8 -------- docs/reference/ImageQt.rst | 20 ++++++++++++++++++++ docs/reference/index.rst | 1 + 3 files changed, 21 insertions(+), 8 deletions(-) create mode 100644 docs/reference/ImageQt.rst diff --git a/docs/PIL.rst b/docs/PIL.rst index cd2252826..a4c709719 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -86,14 +86,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageQt` Module ---------------------- - -.. automodule:: PIL.ImageQt - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageSequence` Module --------------------------- diff --git a/docs/reference/ImageQt.rst b/docs/reference/ImageQt.rst new file mode 100644 index 000000000..2f5cccf45 --- /dev/null +++ b/docs/reference/ImageQt.rst @@ -0,0 +1,20 @@ +.. py:module:: PIL.ImageQt +.. py:currentmodule:: PIL.ImageQt + +:py:mod:`ImageQt` Module +======================== + +The :py:mod:`ImageQt` module contains support for creating PyQt4 QImage objects +from PIL images. + +.. versionadded:: 1.1.6 + +.. py:class:: ImageQt.ImageQt(image) + + Creates an :py:class:`~PIL.ImageQt.ImageQt` object from a PIL + :py:class:`~PIL.Image.Image` object. This class is a subclass of + QtGui.QImage, which means that you can pass the resulting objects directly + to PyQt4 API functions and methods. + + This operation is currently supported for mode 1, L, P, RGB, and RGBA + images. To handle other modes, you need to convert the image first. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 8d206dbb1..925487781 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -17,4 +17,5 @@ Reference ImageOps ImagePalette ImagePath + ImageQt ../PIL From f284c194ca9073ec1fca4ebf2b71cae11d1f64a4 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 21:49:35 -0700 Subject: [PATCH 4/8] Fully document PIL.ImageSequence --- PIL/ImageSequence.py | 15 +++++++++------ docs/PIL.rst | 8 -------- docs/reference/ImageSequence.rst | 27 +++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 4 files changed, 37 insertions(+), 14 deletions(-) create mode 100644 docs/reference/ImageSequence.rst diff --git a/PIL/ImageSequence.py b/PIL/ImageSequence.py index e94ca0b1e..513c9247b 100644 --- a/PIL/ImageSequence.py +++ b/PIL/ImageSequence.py @@ -14,15 +14,18 @@ # ## -# This class implements an iterator object that can be used to loop -# over an image sequence. class Iterator: + """ + This class implements an iterator object that can be used to loop + over an image sequence. - ## - # Create an iterator. - # - # @param im An image object. + You can use the ``[]`` operator to access elements by index. This operator + will raise an :py:exc:`IndexError` if you try to access a nonexistent + frame. + + :param im: An image object. + """ def __init__(self, im): if not hasattr(im, "seek"): diff --git a/docs/PIL.rst b/docs/PIL.rst index a4c709719..10774bcc7 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -86,14 +86,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageSequence` Module ---------------------------- - -.. automodule:: PIL.ImageSequence - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageShow` Module ----------------------- diff --git a/docs/reference/ImageSequence.rst b/docs/reference/ImageSequence.rst new file mode 100644 index 000000000..85539cb9e --- /dev/null +++ b/docs/reference/ImageSequence.rst @@ -0,0 +1,27 @@ +.. py:module:: PIL.ImageSequence +.. py:currentmodule:: PIL.ImageSequence + +:py:mod:`ImageSequence` Module +============================== + +The :py:mod:`ImageSequence` module contains a wrapper class that lets you +iterate over the frames of an image sequence. + +Extracting frames from an animation +----------------------------------- + +.. code-block:: python + + from PIL import Image, ImageSequence + + im = Image.open("animation.fli") + + index = 1 + for frame in ImageSequence.Iterator(im): + frame.save("frame%d.png" % index) + index = index + 1 + +The :py:class:`~PIL.ImageSequence.Iterator` class +------------------------------------------------- + +.. autoclass:: PIL.ImageSequence.Iterator diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 925487781..929ac099e 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -18,4 +18,5 @@ Reference ImagePalette ImagePath ImageQt + ImageSequence ../PIL From 81ea5c35cba7f004881ae4fae1eafc135d6d094f Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 21:57:07 -0700 Subject: [PATCH 5/8] Fully document PIL.ImageStat --- PIL/ImageStat.py | 17 ------------ docs/PIL.rst | 8 ------ docs/reference/ImageStat.rst | 53 ++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 4 files changed, 54 insertions(+), 25 deletions(-) create mode 100644 docs/reference/ImageStat.rst diff --git a/PIL/ImageStat.py b/PIL/ImageStat.py index 508d6b46e..ef63b7857 100644 --- a/PIL/ImageStat.py +++ b/PIL/ImageStat.py @@ -25,25 +25,8 @@ from PIL import Image import operator, math from functools import reduce -## -# The ImageStat module calculates global statistics for an -# image, or a region of an image. -## - -## -# Calculate statistics for the given image. If a mask is included, -# only the regions covered by that mask are included in the -# statistics. class Stat: - "Get image or feature statistics" - - ## - # Create a statistics object. - # - # @def __init__(image, mask=None) - # @param image A PIL image, or a precalculate histogram. - # @param mask An optional mask. def __init__(self, image_or_list, mask = None): try: diff --git a/docs/PIL.rst b/docs/PIL.rst index 10774bcc7..f5ebb69a4 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -94,14 +94,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageStat` Module ------------------------ - -.. automodule:: PIL.ImageStat - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageTk` Module --------------------- diff --git a/docs/reference/ImageStat.rst b/docs/reference/ImageStat.rst new file mode 100644 index 000000000..c8dfe3062 --- /dev/null +++ b/docs/reference/ImageStat.rst @@ -0,0 +1,53 @@ +.. py:module:: PIL.ImageStat +.. py:currentmodule:: PIL.ImageStat + +:py:mod:`ImageStat` Module +========================== + +The :py:mod:`ImageStat` module calculates global statistics for an image, or +for a region of an image. + +.. py:class:: PIL.ImageStat.Stat(image_or_list, mask=None) + + Calculate statistics for the given image. If a mask is included, + only the regions covered by that mask are included in the + statistics. You can also pass in a previously calculated histogram. + + :param image: A PIL image, or a precalculated histogram. + :param mask: An optional mask. + + .. py:attribute:: extrema + + Min/max values for each band in the image. + + .. py:attribute:: count + + Total number of pixels. + + .. py:attribute:: sum + + Sum of all pixels. + + .. py:attribute:: sum2 + + Squared sum of all pixels. + + .. py:attribute:: pixel + + Average pixel level. + + .. py:attribute:: median + + Median pixel level. + + .. py:attribute:: rms + + RMS (root-mean-square). + + .. py:attribute:: var + + Variance. + + .. py:attribute:: stddev + + Standard deviation. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 929ac099e..fa0522b99 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -19,4 +19,5 @@ Reference ImagePath ImageQt ImageSequence + ImageStat ../PIL From 4b4f090258450d6853d98fb71d7775e7e5a69d20 Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 22:09:02 -0700 Subject: [PATCH 6/8] Fully document PIL.ImageTk --- PIL/ImageTk.py | 157 ++++++++++++++++------------------ docs/PIL.rst | 8 -- docs/reference/ImageChops.rst | 4 +- docs/reference/ImageTk.rst | 16 ++++ docs/reference/index.rst | 1 + 5 files changed, 94 insertions(+), 92 deletions(-) create mode 100644 docs/reference/ImageTk.rst diff --git a/PIL/ImageTk.py b/PIL/ImageTk.py index 1b75422fc..1e81d240e 100644 --- a/PIL/ImageTk.py +++ b/PIL/ImageTk.py @@ -34,13 +34,6 @@ except ImportError: from PIL import Image -## -# The ImageTk module contains support to create and modify -# Tkinter BitmapImage and PhotoImage objects. -#

-# For examples, see the demo programs in the Scripts -# directory. -## # -------------------------------------------------------------------- # Check for Tkinter interface hooks @@ -61,28 +54,25 @@ def _pilbitmap_check(): # -------------------------------------------------------------------- # PhotoImage -## -# Creates a Tkinter-compatible photo image. This can be used -# everywhere Tkinter expects an image object. If the image is an RGBA -# image, pixels having alpha 0 are treated as transparent. - class PhotoImage: + """ + A Tkinter-compatible photo image. This can be used + everywhere Tkinter expects an image object. If the image is an RGBA + image, pixels having alpha 0 are treated as transparent. - ## - # Create a photo image object. The constructor takes either - # a PIL image, or a mode and a size. Alternatively, you can - # use the file or data options to initialize - # the photo image object. - #

- # @def __init__(image=None, size=None, **options) - # @param image Either a PIL image, or a mode string. If a - # mode string is used, a size must also be given. - # @param size If the first argument is a mode string, this - # defines the size of the image. - # @keyparam file A filename to load the image from (using - # Image.open(file)). - # @keyparam data An 8-bit string containing image data (as - # loaded from an image file). + The constructor takes either a PIL image, or a mode and a size. + Alternatively, you can use the **file** or **data** options to initialize + the photo image object. + + :param image: Either a PIL image, or a mode string. If a mode string is + used, a size must also be given. + :param size: If the first argument is a mode string, this defines the size + of the image. + :keyword file: A filename to load the image from (using + ``Image.open(file)``). + :keyword data: An 8-bit string containing image data (as loaded from an + image file). + """ def __init__(self, image=None, size=None, **kw): @@ -130,44 +120,48 @@ class PhotoImage: except: pass # ignore internal errors - ## - # Get the Tkinter photo image identifier. This method is - # automatically called by Tkinter whenever a PhotoImage object is - # passed to a Tkinter method. - # - # @return A Tkinter photo image identifier (a string). def __str__(self): + """ + Get the Tkinter photo image identifier. This method is automatically + called by Tkinter whenever a PhotoImage object is passed to a Tkinter + method. + + :return: A Tkinter photo image identifier (a string). + """ return str(self.__photo) - ## - # Get the width of the image. - # - # @return The width, in pixels. def width(self): + """ + Get the width of the image. + + :return: The width, in pixels. + """ return self.__size[0] - ## - # Get the height of the image. - # - # @return The height, in pixels. def height(self): + """ + Get the height of the image. + + :return: The height, in pixels. + """ return self.__size[1] - ## - # Paste a PIL image into the photo image. Note that this can - # be very slow if the photo image is displayed. - # - # @param im A PIL image. The size must match the target region. - # If the mode does not match, the image is converted to the - # mode of the bitmap image. - # @param box A 4-tuple defining the left, upper, right, and - # lower pixel coordinate. If None is given instead of a - # tuple, all of the image is assumed. def paste(self, im, box=None): + """ + Paste a PIL image into the photo image. Note that this can + be very slow if the photo image is displayed. + + :param im: A PIL image. The size must match the target region. If the + mode does not match, the image is converted to the mode of + the bitmap image. + :param box: A 4-tuple defining the left, upper, right, and lower pixel + coordinate. If None is given instead of a tuple, all of + the image is assumed. + """ # convert to blittable im.load() @@ -197,24 +191,21 @@ class PhotoImage: # -------------------------------------------------------------------- # BitmapImage -## -# Create a Tkinter-compatible bitmap image. This can be used -# everywhere Tkinter expects an image object. class BitmapImage: + """ - ## - # Create a Tkinter-compatible bitmap image. - #

- # The given image must have mode "1". Pixels having value 0 are - # treated as transparent. Options, if any, are passed on to - # Tkinter. The most commonly used option is foreground, - # which is used to specify the colour for the non-transparent - # parts. See the Tkinter documentation for information on how to - # specify colours. - # - # @def __init__(image=None, **options) - # @param image A PIL image. + A Tkinter-compatible bitmap image. This can be used everywhere Tkinter + expects an image object. + + The given image must have mode "1". Pixels having value 0 are treated as + transparent. Options, if any, are passed on to Tkinter. The most commonly + used option is **foreground**, which is used to specify the color for the + non-transparent parts. See the Tkinter documentation for information on + how to specify colours. + + :param image: A PIL image. + """ def __init__(self, image=None, **kw): @@ -249,36 +240,38 @@ class BitmapImage: except: pass # ignore internal errors - ## - # Get the width of the image. - # - # @return The width, in pixels. def width(self): + """ + Get the width of the image. + + :return: The width, in pixels. + """ return self.__size[0] - ## - # Get the height of the image. - # - # @return The height, in pixels. def height(self): + """ + Get the height of the image. + + :return: The height, in pixels. + """ return self.__size[1] - ## - # Get the Tkinter bitmap image identifier. This method is - # automatically called by Tkinter whenever a BitmapImage object - # is passed to a Tkinter method. - # - # @return A Tkinter bitmap image identifier (a string). def __str__(self): + """ + Get the Tkinter bitmap image identifier. This method is automatically + called by Tkinter whenever a BitmapImage object is passed to a Tkinter + method. + + :return: A Tkinter bitmap image identifier (a string). + """ return str(self.__photo) -## -# Copies the contents of a PhotoImage to a PIL image memory. def getimage(photo): + """Copies the contents of a PhotoImage to a PIL image memory.""" photo.tk.call("PyImagingPhotoGet", photo) # -------------------------------------------------------------------- diff --git a/docs/PIL.rst b/docs/PIL.rst index f5ebb69a4..8c787862f 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -94,14 +94,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageTk` Module ---------------------- - -.. automodule:: PIL.ImageTk - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageTransform` Module ---------------------------- diff --git a/docs/reference/ImageChops.rst b/docs/reference/ImageChops.rst index c95363c5d..8d08315b0 100644 --- a/docs/reference/ImageChops.rst +++ b/docs/reference/ImageChops.rst @@ -1,8 +1,8 @@ .. py:module:: PIL.ImageChops .. py:currentmodule:: PIL.ImageChops -:py:mod:`ImageChops` Module -=========================== +:py:mod:`ImageChops` ("Channel Operations") 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/ImageTk.rst b/docs/reference/ImageTk.rst new file mode 100644 index 000000000..7ee4af029 --- /dev/null +++ b/docs/reference/ImageTk.rst @@ -0,0 +1,16 @@ +.. py:module:: PIL.ImageTk +.. py:currentmodule:: PIL.ImageTk + +:py:mod:`ImageTk` Module +======================== + +The :py:mod:`ImageTk` module contains support to create and modify Tkinter +BitmapImage and PhotoImage objects from PIL images. + +For examples, see the demo programs in the Scripts directory. + +.. autoclass:: PIL.ImageTk.BitmapImage + :members: + +.. autoclass:: PIL.ImageTk.PhotoImage + :members: diff --git a/docs/reference/index.rst b/docs/reference/index.rst index fa0522b99..d6460ad70 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -20,4 +20,5 @@ Reference ImageQt ImageSequence ImageStat + ImageTk ../PIL From 7030e50b36841ee1537f85de48c9c2ddf2a9ad4b Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 22:19:12 -0700 Subject: [PATCH 7/8] Fully document PIL.ImageWin --- PIL/ImageWin.py | 139 ++++++++++++++++++++---------------- docs/PIL.rst | 8 --- docs/reference/ImageWin.rst | 29 ++++++++ docs/reference/index.rst | 1 + 4 files changed, 108 insertions(+), 69 deletions(-) create mode 100644 docs/reference/ImageWin.rst diff --git a/PIL/ImageWin.py b/PIL/ImageWin.py index d83763e01..aa90b887b 100644 --- a/PIL/ImageWin.py +++ b/PIL/ImageWin.py @@ -20,44 +20,49 @@ import warnings from PIL import Image -## -# The ImageWin module contains support to create and display -# images under Windows 95/98, NT, 2000 and later. class HDC: + """ + Wraps a HDC integer. The resulting object can be passed to the + :py:meth:`~PIL.ImageWin.Dib.draw` and :py:meth:`~PIL.ImageWin.Dib.expose` + methods. + """ def __init__(self, dc): self.dc = dc def __int__(self): return self.dc class HWND: + """ + Wraps a HWND integer. The resulting object can be passed to the + :py:meth:`~PIL.ImageWin.Dib.draw` and :py:meth:`~PIL.ImageWin.Dib.expose` + methods, instead of a DC. + """ def __init__(self, wnd): self.wnd = wnd def __int__(self): return self.wnd -## -# Create a Windows bitmap with the given mode and size. The mode can -# be one of "1", "L", "P", or "RGB". -# -# If the display requires a palette, this constructor creates a -# suitable palette and associates it with the image. For an "L" image, -# 128 greylevels are allocated. For an "RGB" image, a 6x6x6 colour -# cube is used, together with 20 greylevels. -# -# To make sure that palettes work properly under Windows, you must -# call the palette method upon certain events from Windows. class Dib: + """ + A Windows bitmap with the given mode and size. The mode can be one of "1", + "L", "P", or "RGB". - ## - # Create Windows bitmap. - # - # @param image Either a PIL image, or a mode string. If a - # mode string is used, a size must also be given. The - # mode can be one of "1", "L", "P", or "RGB". - # @param size If the first argument is a mode string, this - # defines the size of the image. + If the display requires a palette, this constructor creates a suitable + palette and associates it with the image. For an "L" image, 128 greylevels + are allocated. For an "RGB" image, a 6x6x6 colour cube is used, together + with 20 greylevels. + + To make sure that palettes work properly under Windows, you must call the + **palette** method upon certain events from Windows. + + :param image: Either a PIL image, or a mode string. If a mode string is + used, a size must also be given. The mode can be one of "1", + "L", "P", or "RGB". + :param size: If the first argument is a mode string, this + defines the size of the image. + """ def __init__(self, image, size=None): if hasattr(image, "mode") and hasattr(image, "size"): @@ -74,15 +79,15 @@ class Dib: if image: self.paste(image) - ## - # Copy the bitmap contents to a device context. - # - # @param handle Device context (HDC), cast to a Python integer, - # or a HDC or HWND instance. In PythonWin, you can use the - # GetHandleAttrib method of the CDC class to get - # a suitable handle. def expose(self, handle): + """ + Copy the bitmap contents to a device context. + + :param handle: Device context (HDC), cast to a Python integer, or a HDC + or HWND instance. In PythonWin, you can use the + :py:meth:`CDC.GetHandleAttrib` to get a suitable handle. + """ if isinstance(handle, HWND): dc = self.image.getdc(handle) try: @@ -94,6 +99,15 @@ class Dib: return result def draw(self, handle, dst, src=None): + """ + Same as expose, but allows you to specify where to draw the image, and + what part of it to draw. + + The destination and source areas are given as 4-tuple rectangles. If + the source is omitted, the entire image is copied. If the source and + the destination have different sizes, the image is resized as + necessary. + """ if not src: src = (0,0) + self.size if isinstance(handle, HWND): @@ -106,22 +120,22 @@ class Dib: result = self.image.draw(handle, dst, src) return result - ## - # Installs the palette associated with the image in the - # given device context. - #

- # This method should be called upon QUERYNEWPALETTE - # and PALETTECHANGED events from Windows. If this - # method returns a non-zero value, one or more display - # palette entries were changed, and the image should be - # redrawn. - # - # @param handle Device context (HDC), cast to a Python integer, - # or an HDC or HWND instance. - # @return A true value if one or more entries were changed - # (this indicates that the image should be redrawn). def query_palette(self, handle): + """ + Installs the palette associated with the image in the given device + context. + + This method should be called upon **QUERYNEWPALETTE** and + **PALETTECHANGED** events from Windows. If this method returns a + non-zero value, one or more display palette entries were changed, and + the image should be redrawn. + + :param handle: Device context (HDC), cast to a Python integer, or an + HDC or HWND instance. + :return: A true value if one or more entries were changed (this + indicates that the image should be redrawn). + """ if isinstance(handle, HWND): handle = self.image.getdc(handle) try: @@ -132,17 +146,18 @@ class Dib: result = self.image.query_palette(handle) return result - ## - # Paste a PIL image into the bitmap image. - # - # @param im A PIL image. The size must match the target region. - # If the mode does not match, the image is converted to the - # mode of the bitmap image. - # @param box A 4-tuple defining the left, upper, right, and - # lower pixel coordinate. If None is given instead of a - # tuple, all of the image is assumed. def paste(self, im, box=None): + """ + Paste a PIL image into the bitmap image. + + :param im: A PIL image. The size must match the target region. + If the mode does not match, the image is converted to the + mode of the bitmap image. + :param box: A 4-tuple defining the left, upper, right, and + lower pixel coordinate. If None is given instead of a + tuple, all of the image is assumed. + """ im.load() if self.mode != im.mode: im = im.convert(self.mode) @@ -151,21 +166,23 @@ class Dib: else: self.image.paste(im.im) - ## - # Load display memory contents from byte data. - # - # @param buffer A buffer containing display data (usually - # data returned from tobytes) def frombytes(self, buffer): + """ + Load display memory contents from byte data. + + :param buffer: A buffer containing display data (usually + data returned from tobytes) + """ return self.image.frombytes(buffer) - ## - # Copy display memory contents to bytes object. - # - # @return A bytes object containing display data. def tobytes(self): + """ + Copy display memory contents to bytes object. + + :return: A bytes object containing display data. + """ return self.image.tobytes() ## diff --git a/docs/PIL.rst b/docs/PIL.rst index 8c787862f..99f029596 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -102,14 +102,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`ImageWin` Module ----------------------- - -.. automodule:: PIL.ImageWin - :members: - :undoc-members: - :show-inheritance: - :mod:`JpegPresets` Module ------------------------- diff --git a/docs/reference/ImageWin.rst b/docs/reference/ImageWin.rst new file mode 100644 index 000000000..2696e7e99 --- /dev/null +++ b/docs/reference/ImageWin.rst @@ -0,0 +1,29 @@ +.. py:module:: PIL.ImageWin +.. py:currentmodule:: PIL.ImageWin + +:py:mod:`ImageWin` Module (Windows-only) +======================================== + +The :py:mod:`ImageWin` module contains support to create and display images on +Windows. + +ImageWin can be used with PythonWin and other user interface toolkits that +provide access to Windows device contexts or window handles. For example, +Tkinter makes the window handle available via the winfo_id method: + +.. code-block:: python + + from PIL import ImageWin + + dib = ImageWin.Dib(...) + + hwnd = ImageWin.HWND(widget.winfo_id()) + dib.draw(hwnd, xy) + + +.. autoclass:: PIL.ImageWin.Dib + :members: + + +.. autoclass:: PIL.ImageWin.HDC +.. autoclass:: PIL.ImageWin.HWND diff --git a/docs/reference/index.rst b/docs/reference/index.rst index d6460ad70..2e148e65a 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -21,4 +21,5 @@ Reference ImageSequence ImageStat ImageTk + ImageWin ../PIL From c3de637362e309c1f78424144ca7ef668efe909b Mon Sep 17 00:00:00 2001 From: Stephen Johnson Date: Sun, 13 Oct 2013 22:30:00 -0700 Subject: [PATCH 8/8] Fully document PIL.PSDraw --- PIL/PSDraw.py | 42 ++++++++++++++++++++++++++++++++++++--- docs/PIL.rst | 8 -------- docs/reference/PSDraw.rst | 11 ++++++++++ docs/reference/index.rst | 1 + 4 files changed, 51 insertions(+), 11 deletions(-) create mode 100644 docs/reference/PSDraw.rst diff --git a/PIL/PSDraw.py b/PIL/PSDraw.py index dd4acd8af..88593bb9d 100644 --- a/PIL/PSDraw.py +++ b/PIL/PSDraw.py @@ -23,6 +23,10 @@ from PIL import EpsImagePlugin # Simple Postscript graphics interface. class PSDraw: + """ + Sets up printing to the given file. If **file** is omitted, + :py:attr:`sys.stdout` is assumed. + """ def __init__(self, fp=None): if not fp: @@ -31,7 +35,7 @@ class PSDraw: self.fp = fp def begin_document(self, id = None): - "Write Postscript DSC header" + """Set up printing of a document. (Write Postscript DSC header.)""" # FIXME: incomplete self.fp.write("%!PS-Adobe-3.0\n" "save\n" @@ -45,7 +49,7 @@ class PSDraw: self.isofont = {} def end_document(self): - "Write Postscript DSC footer" + """Ends printing. (Write Postscript DSC footer.)""" self.fp.write("%%EndDocument\n" "restore showpage\n" "%%End\n") @@ -53,6 +57,12 @@ class PSDraw: self.fp.flush() def setfont(self, font, size): + """ + Selects which font to use. + + :param font: A Postscript font name + :param size: Size in points. + """ if font not in self.isofont: # reencode font self.fp.write("/PSDraw-%s ISOLatin1Encoding /%s E\n" %\ @@ -62,23 +72,49 @@ class PSDraw: self.fp.write("/F0 %d /PSDraw-%s F\n" % (size, font)) def setink(self, ink): + """ + .. warning:: + + This has been in the PIL API for ages but was never implemented. + """ print("*** NOT YET IMPLEMENTED ***") def line(self, xy0, xy1): + """ + Draws a line between the two points. Coordinates are given in + Postscript point coordinates (72 points per inch, (0, 0) is the lower + left corner of the page). + """ xy = xy0 + xy1 self.fp.write("%d %d %d %d Vl\n" % xy) def rectangle(self, box): + """ + Draws a rectangle. + + :param box: A 4-tuple of integers whose order and function is currently + undocumented. + + Hint: the tuple is passed into this format string: + + .. code-block:: python + + %d %d M %d %d 0 Vr\n + """ self.fp.write("%d %d M %d %d 0 Vr\n" % box) def text(self, xy, text): + """ + Draws text at the given position. You must use + :py:meth:`~PIL.PSDraw.PSDraw.setfont` before calling this method. + """ text = "\\(".join(text.split("(")) text = "\\)".join(text.split(")")) xy = xy + (text,) self.fp.write("%d %d M (%s) S\n" % xy) def image(self, box, im, dpi = None): - "Write an PIL image" + """Draw a PIL image, centered in the given box.""" # default resolution depends on mode if not dpi: if im.mode == "1": diff --git a/docs/PIL.rst b/docs/PIL.rst index 99f029596..6726f661f 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -118,14 +118,6 @@ can be found here. :undoc-members: :show-inheritance: -:mod:`PSDraw` Module --------------------- - -.. automodule:: PIL.PSDraw - :members: - :undoc-members: - :show-inheritance: - :mod:`PaletteFile` Module ------------------------- diff --git a/docs/reference/PSDraw.rst b/docs/reference/PSDraw.rst new file mode 100644 index 000000000..2b5b9b340 --- /dev/null +++ b/docs/reference/PSDraw.rst @@ -0,0 +1,11 @@ +.. py:module:: PIL.PSDraw +.. py:currentmodule:: PIL.PSDraw + +:py:mod:`PSDraw` Module +======================= + +The :py:mod:`PSDraw` module provides simple print support for Postscript +printers. You can print text, graphics and images through this module. + +.. autoclass:: PIL.PSDraw.PSDraw + :members: diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 2e148e65a..2d57e37be 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -22,4 +22,5 @@ Reference ImageStat ImageTk ImageWin + PSDraw ../PIL