# The ImageDraw Module

This module provide basic graphics support for `Image` objects. It can for example be used to create new images, annotate or retouch existing images, and to generate graphics on the fly for web use.

## Example

Example: Draw a Grey Cross Over an Image

    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")

## Functions

### Draw (constructor)

`Draw(image)` creates an object that can be used to draw in the given image.

Note that the image will be modified in place.

## Methods

### arc

`arc(xy, start, end, options)`. Draws an arc (a circle outline segment) between the start and end angles, inside the given bounding box.

The `outline` option gives the colour to use for the arc.

### bitmap

`bitmap(xy, bitmap, options)`. Draws a bitmap at the given position, using the current fill colour.

### chord

`chord(xy, start, end, options)`. Same as `arc`, but connects the end points with a straight line.

The `outline` option gives the colour to use for the chord outline. The `fill` option gives the colour to use for the chord interior.

### ellipse

`ellipse(xy, options)`. Draws an ellipse inside the given bounding box.

The `outline` option gives the colour to use for the ellipse outline. The `fill` option gives the colour to use for the ellipse interior.

### line

`line(xy, options)` draws a line between the coordinates in the `xy` list.

The coordinate list can be any sequence object containing either 2-tuples [ (`x, y`), ... ] or numeric values [ `x`, `y`, ... ]. It should contain at least two coordinates.

The `fill` option gives the colour to use for the line.

### pieslice

`pieslice(xy, start, end, options)`. Same as `arc`, but also draws straight lines between the end points and the center of the bounding box.

The `outline` option gives the colour to use for the pieslice outline. The `fill` option gives the colour to use for the pieslice interior.

### point

`point(xy, options)` draws points (individual pixels) at the given coordinates.

The coordinate list can be any sequence object containing either 2-tuples [ (`x, y`), ... ] or numeric values [ `x`, `y`, ... ].

The `fill` option gives the colour to use for the points.

### polygon

`polygon(xy, options)` 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.

The coordinate list can be any sequence object containing either 2-tuples [ (`x, y`), ... ] or numeric values [ `x`, `y`, ... ]. It should contain at least three coordinates.

The `outline` option gives the colour to use for the polygon outline. The `fill` option gives the colour to use for the polygon interior.

### rectangle

`rectangle(box, options)` draws a rectangle.

The box can be any sequence object containing either 2-tuples [ (`x, y`), (`x, y`) ] or numeric values [ `x`, `y`, `x`, `y` ]. It should contain exactly two coordinates.

Note that the second coordinate pair defines a point just outside the rectangle, also when the rectangle is not filled.

The `outline` option gives the colour to use for the rectangle outline. The `fill` option gives the colour to use for the rectangle interior.

### text

`text(position, string, options)` draws the string at the given position.

The `font` option is used to specify what font to use. It should be an instance of the `ImageFont` class, typically loaded from file using the `load` method in the `ImageFont` module.

The `fill` option gives the colour to use for the text.

### textsize

`textsize(string, options) ⇒ (width, height)` return the size of the given string.

The `font` option is used to specify what font to use. It should be an instance of the `ImageFont` class, typically loaded from file using the `load` method in the `ImageFont` module.

## Compatibility

The `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.

### ImageDraw (constructor)

`ImageDraw(image)`. Same as `Draw`. Don't use this name in new code.

### setink

`setink(ink)` sets the color to use for subsequent draw and fill operations.

### setfill

`setfill(mode)` 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.

### setfont

`setfont(font)` sets the default font to use for the `text` method.

The `font` argument should be an instance of the `ImageFont` class, typically loaded from file using the `load` method in the `ImageFont` module.