diff --git a/docs/reference/ImageColor.rst b/docs/reference/ImageColor.rst index 2d6dd0355..3115b975f 100644 --- a/docs/reference/ImageColor.rst +++ b/docs/reference/ImageColor.rst @@ -9,6 +9,8 @@ CSS3-style color specifiers to RGB tuples. This module is used by :py:meth:`PIL.Image.Image.new` and the :py:mod:`~PIL.ImageDraw` module, among others. +.. _color-names: + Color Names ----------- diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst new file mode 100644 index 000000000..cc3377c3e --- /dev/null +++ b/docs/reference/ImageDraw.rst @@ -0,0 +1,239 @@ +.. py:module:: PIL.ImageDraw +.. py:currentmodule:: PIL.ImageDraw + +: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 +images, annotate or retouch existing images, and to generate graphics on the +fly for web use. + +For a more advanced drawing library for PIL, see the `aggdraw module`_. + +.. _aggdraw module: http://effbot.org/zone/aggdraw-index.htm + +Example: Draw a gray cross over an image +---------------------------------------- + +.. code-block:: python + + import Image, ImageDraw + + im = Image.open("lena.pgm") + + draw = ImageDraw.Draw(im) + draw.line((0, 0) + im.size, fill=128) + draw.line((0, im.size[1], im.size[0], 0), fill=128) + del draw + + # write to stdout + im.save(sys.stdout, "PNG") + + +Concepts +-------- + +Coordinates +^^^^^^^^^^^ + +The graphics interface uses the same coordinate system as PIL itself, with (0, +0) in the upper left corner. + +Colors +^^^^^^ + +To specify colors, you can use numbers or tuples just as you would use with +:py:meth:`PIL.Image.Image.new` or :py:meth:`PIL.Image.Image.putpixel`. For “1”, +“L”, and “I” images, use integers. For “RGB” images, use a 3-tuple containing +integer values. For “F” images, use integer or floating point values. + +For palette images (mode “P”), use integers as color indexes. In 1.1.4 and +later, you can also use RGB 3-tuples or color names (see below). The drawing +layer will automatically assign color indexes, as long as you don’t draw with +more than 256 colors. + +Color Names +^^^^^^^^^^^ + +See :ref:`color-names` for the color names supported by Pillow. + +Fonts +^^^^^ + +PIL can use bitmap fonts or OpenType/TrueType fonts. + +Bitmap fonts are stored in PIL’s own format, where each font typically consists +of a two files, one named .pil and the other usually named .pbm. The former +contains font metrics, the latter raster data. + +To load a bitmap font, use the load functions in the :py:mod:`~PIL.ImageFont` +module. + +To load a OpenType/TrueType font, use the truetype function in the +:py:mod:`~PIL.ImageFont` module. Note that this function depends on third-party +libraries, and may not available in all PIL builds. + +Functions +--------- + +.. py:class:: PIL.ImageDraw.Draw(im, mode=None) + + Creates an object that can be used to draw in the given image. + + Note that the image will be modified in place. + +Methods +------- + +.. py:method:: PIL.ImageDraw.Draw.arc(xy, start, end, fill=None) + + Draws an arc (a portion of a circle outline) between the start and end + angles, inside the given bounding box. + + :param xy: Four points to define the bounding box. Sequence of either + ``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``. + :param outline: Color to use for the outline. + +.. py:method:: PIL.ImageDraw.Draw.bitmap(xy, bitmap, fill=None) + + Draws a bitmap (mask) at the given position, using the current fill color + for the non-zero portions. The bitmap should be a valid transparency mask + (mode “1”) or matte (mode “L” or “RGBA”). + + This is equivalent to doing ``image.paste(xy, color, bitmap)``. + + To paste pixel data into an image, use the + :py:meth:`~PIL.Image.Image.paste` method on the image itself. + +.. py:method:: PIL.ImageDraw.Draw.chord(xy, start, end, fill=None, outline=None) + + Same as :py:meth:`~PIL.ImageDraw.Draw.arc`, but connects the end points + with a straight line. + + :param xy: Four points to define the bounding box. Sequence of either + ``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``. + :param outline: Color to use for the outline. + :param fill: Color to use for the fill. + +.. py:method:: PIL.ImageDraw.Draw.ellipse(xy, fill=None, outline=None) + + Draws an ellipse inside the given bounding box. + + :param xy: Four points to define the bounding box. Sequence of either + ``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``. + :param outline: Color to use for the outline. + :param fill: Color to use for the fill. + +.. py:method:: PIL.ImageDraw.Draw.line(xy, fill=None, width=0) + + Draws a line between the coordinates in the **xy** list. + + :param xy: Sequence of either 2-tuples like ``[(x, y), (x, y), ...]`` or + numeric values like ``[x, y, x, y, ...]``. + :param fill: Color to use for the line. + :param width: The line width, in pixels. Note that line + joins are not handled well, so wide polylines will not look good. + + .. versionadded:: 1.1.5 + + .. note:: This option was broken until version 1.1.6. + +.. py:method:: PIL.ImageDraw.Draw.pieslice(xy, start, end, fill=None, outline=None) + + Same as arc, but also draws straight lines between the end points and the + center of the bounding box. + + :param xy: Four points to define the bounding box. Sequence of either + ``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``. + :param outline: Color to use for the outline. + :param fill: Color to use for the fill. + +.. py:method:: PIL.ImageDraw.Draw.point(xy, fill=None) + + Draws points (individual pixels) at the given coordinates. + + :param xy: Sequence of either 2-tuples like ``[(x, y), (x, y), ...]`` or + numeric values like ``[x, y, x, y, ...]``. + :param fill: Color to use for the point. + +.. py:method:: PIL.ImageDraw.Draw.polygon(xy, fill=None, outline=None) + + Draws a polygon. + + The polygon outline consists of straight lines between the given + coordinates, plus a straight line between the last and the first + coordinate. + + :param xy: Sequence of either 2-tuples like ``[(x, y), (x, y), ...]`` or + numeric values like ``[x, y, x, y, ...]``. + :param outline: Color to use for the outline. + :param fill: Color to use for the fill. + +.. py:method:: PIL.ImageDraw.Draw.rectangle(xy, fill=None, outline=None) + + Draws a rectangle. + + :param xy: Four points to define the bounding box. Sequence of either + ``[(x0, y0), (x1, y1)]`` or ``[x0, y0, x1, y1]``. The second point + is just outside the drawn rectangle. + :param outline: Color to use for the outline. + :param fill: Color to use for the fill. + +.. py:method:: PIL.ImageDraw.Draw.shape(shape, fill=None, outline=None) + + .. warning:: This method is experimental. + + Draw a shape. + +.. py:method:: PIL.ImageDraw.Draw.text(xy, text, fill=None, font=None, anchor=None) + + Draws the string at the given position. + + :param xy: Top left corner of the text. + :param text: Text to be drawn. + :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. + :param fill: Color to use for the text. + +.. py:method:: PIL.ImageDraw.Draw.textsize(text, font=None) + + Return the size of the given string, in pixels. + + :param text: Text to be measured. + :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. + +Legacy API +---------- + +The :py:class:`~PIL.ImageDraw.Draw` class contains a constructor and a number +of methods which are provided for backwards compatibility only. For this to +work properly, you should either use options on the drawing primitives, or +these methods. Do not mix the old and new calling conventions. + + +.. py:function:: PIL.ImageDraw.ImageDraw(image) + + :rtype: :py:class:`~PIL.ImageDraw.Draw` + +.. py:method:: PIL.ImageDraw.Draw.setink(ink) + + .. deprecated:: 1.1.5 + + Sets the color to use for subsequent draw and fill operations. + +.. py:method:: PIL.ImageDraw.Draw.setfill(fill) + + .. deprecated:: 1.1.5 + + Sets the fill mode. + + If the mode is 0, subsequently drawn shapes (like polygons and rectangles) + are outlined. If the mode is 1, they are filled. + +.. py:method:: PIL.ImageDraw.Draw.setfont(font) + + .. deprecated:: 1.1.5 + + Sets the default font to use for the text method. + + :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 8604a8787..34669c7a2 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -7,4 +7,5 @@ Reference Image ImageChops ImageColor + ImageDraw ../PIL