diff --git a/PIL/Image.py b/PIL/Image.py index d556df34c..b961ae2ce 100644 --- a/PIL/Image.py +++ b/PIL/Image.py @@ -745,6 +745,7 @@ class Image: associated with the image. :returns: An image access object. + :rtype: :ref:`PixelAccess` or :py:class:`PIL.PyAccess` """ if self.im and self.palette and self.palette.dirty: # realize palette diff --git a/PIL/PyAccess.py b/PIL/PyAccess.py index 93aeae59e..28829051d 100644 --- a/PIL/PyAccess.py +++ b/PIL/PyAccess.py @@ -78,6 +78,8 @@ class PyAccess(object): images :param xy: The pixel coordinate, given as (x, y). + :returns: a pixel value for single band images, a tuple of + pixel values for multiband images. """ (x, y) = self.check_xy(xy) diff --git a/docs/reference/PixelAccess.rst b/docs/reference/PixelAccess.rst new file mode 100644 index 000000000..55ab8c578 --- /dev/null +++ b/docs/reference/PixelAccess.rst @@ -0,0 +1,74 @@ +.. _PixelAccess: + +:py:class:`PixelAccess` Class +============================= + +The PixelAccess class provides read and write access to +:py:class:`PIL.Image` data at a pixel level. + +.. note:: Accessing individual pixels is fairly slow. If you are looping over all of the pixels in an image, there is likely a faster way using other parts of the Pillow API. + +Example +------- + +The following script loads an image, accesses one pixel from it, then +changes it. + +.. code-block:: python + + from PIL import Image + im = Image.open('hopper.jpg') + px = im.load() + print (px[4,4]) + px[4,4] = (0,0,0) + print (px[4,4]) + +Results in the following:: + + (23, 24, 68) + (0, 0, 0) + + + +:py:class:`PixelAccess` Class +----------------------------------- + +.. class:: PixelAccess + + .. method:: __setitem__(self, xy, color): + + Modifies the pixel at x,y. The color is given as a single + numerical value for single band images, and a tuple for + multi-band images + + :param xy: The pixel coordinate, given as (x, y). + :param value: The pixel value. + + .. method:: __getitem__(self, xy): + + Returns the pixel at x,y. The pixel is returned as a single + value for single band images or a tuple for multiple band + images + + :param xy: The pixel coordinate, given as (x, y). + :returns: a pixel value for single band images, a tuple of + pixel values for multiband images. + + .. method:: putpixel(self, xy, color): + + Modifies the pixel at x,y. The color is given as a single + numerical value for single band images, and a tuple for + multi-band images + + :param xy: The pixel coordinate, given as (x, y). + :param value: The pixel value. + + .. method:: getpixel(self, xy): + + Returns the pixel at x,y. The pixel is returned as a single + value for single band images or a tuple for multiple band + images + + :param xy: The pixel coordinate, given as (x, y). + :returns: a pixel value for single band images, a tuple of + pixel values for multiband images. diff --git a/docs/reference/PyAccess.rst b/docs/reference/PyAccess.rst new file mode 100644 index 000000000..cb853f89e --- /dev/null +++ b/docs/reference/PyAccess.rst @@ -0,0 +1,38 @@ +.. py:module:: PIL.PyAccess +.. py:currentmodule:: PIL.PyAccess + +:py:mod:`PyAccess` Module +========================= + +The :py:mod:`PyAccess` module provides a CFFI/Python implementation of the :ref:`PixelAccess`. This implementation is far faster on PyPy than the PixelAccess version. + +.. note:: Accessing individual pixels is fairly slow. If you are + looping over all of the pixels in an image, there is likely + a faster way using other parts of the Pillow API. + +Example +------- + +The following script loads an image, accesses one pixel from it, then changes it. + +.. code-block:: python + + from PIL import Image + im = Image.open('hopper.jpg') + px = im.load() + print (px[4,4]) + px[4,4] = (0,0,0) + print (px[4,4]) + +Results in the following:: + + (23, 24, 68) + (0, 0, 0) + + + +:py:class:`PyAccess` Class +-------------------------- + +.. autoclass:: PIL.PyAccess.PyAccess() + :members: diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 2f10b861d..73a3ecfed 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -28,4 +28,6 @@ Reference ExifTags OleFileIO PSDraw + PixelAccess + PyAccess ../PIL