4. The ImageDraw module

4. The `ImageDraw` module

When you need to draw on an image, import the ImageDraw module like this:

    import ImageDraw

Then instantiate a Draw object:

    draw  =  ImageDraw.Draw(i)

where i is the Image object you want to draw on.

Methods on a Draw object include:

.arc(bbox,start,end,fill=None)

Draws an arc, that part of the ellipse fitting inside the bounding box bbox and lying between angles start and end. Note: Angles increase clockwise, unlike angles elsewhere in the PIL. For example, draw.arc((0,0,200,200), 0, 135) would draw a circular arc centered at (100,100) and extending from the east to the southwest.

If supplied, the fill argument specifies the color of the arc. The default color is white.

.chord(bbox,start,end,fill=None,outline=None)

Same as the .arc() method, but it also draws a straight line connecting the endpoints of the arc.

For this method, the fill argument determines the color inside, that is, between the chord and the arc. The default is that this area is not filled.

To change the color of the perimeter border around the chord's area, set the outline argument to the color you want. The default color is white.

.ellipse(bbox,fill=None,outline=None)

Draws the ellipse that fits inside the bounding box bbox. To draw a circle, use a square bounding box.

Note that the ellipse will include the left and top sides of the bounding box, but they will exclude the right and bottom sides of the box. For example, a bounding box (0,0,10,10) will give you a circle of diameter 10, not diameter 11.

If you omit the fill argument, only the perimeter of the ellipse is drawn. If you pass a color to this argument, the interior of the ellipse will be filled with that color.

Use outline=c to draw the perimeter border using color c. The default color is white.

.line(L, fill=None)

Draws one or more line segments. The argument L specifies the endpoints, and can have either of these forms:

A sequence of 2-element sequences, each of which specifies one endpoint. For example, draw.line([(10,20),(100,20)] would draw a straight line from (10,20) to (100,20). You can specify any number of points to get a “polyline;” for example, draw.line(((60,60), (90,60), (90,90), (60,90), (60,60))) would draw a square 30 pixels on a side.
A sequence containing an even number of values. Each succeeding pair is taken as an (x,y) coordinate. For example, draw.line((10,20,100,20)) would give you the same result as the first example in the paragraph above.

.pieslice(bbox,start,end,fill=None,outline=None)

Similar to the .arc() method, but draws two radii connecting the endpoints of the arc to the center. The fill and outline arguments work in the same way as in the .chord() method: fill determines the interior color, and outline sets the color of the border.

.point(xy,fill=None)

Sets the pixel at coordinates xy to the color specified by the fill argument. The default color is white.

.polygon(L, fill=None, outline=None)

Works like the .line() method, but after drawing all the specified line segments, it draws one more that connects the last point back to the first. The interior displays the fill, transparent by default. The border is drawn in the outline color, defaulting to white.

For example, draw.polygon([(60,60), (90,60), (90,90), (60,90)], fill="red", outline="green") would draw a square box with a green outline, filled with red.

.text(xy,message,fill=None,font=None)

Draws the text of the string message on the image with its upper left corner at coordinates xy.

To write the text in color, pass that color to the fill argument; the default text color is white.

There is a default font, rather small (about 11 pixels tall) and in a serif style. You can also specify a font using the font argument; see the ImageFont module for more information on fonts.

.textsize(message,font=None)

For a given text string message, returns a tuple (w,h) where w is the width in pixels that text will occupy on the display, and h its the height in pixels.

If the font argument is omitted, you will get the size using the default font. Supply a font to this method's font argument to get the size of the text in that font.

Python Imaging Library (PIL)

4. The ImageDraw module

4. The `ImageDraw` module