ImageDraw Module

The ImageDraw module provide simple 2D graphics for 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.

Example: Draw a gray cross over an image

from PIL 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 PIL.Image.Image.new() or 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 palecodee 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 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 lacodeer raster data.

To load a bitmap font, use the load functions in the ImageFont module.

To load a OpenType/TrueType font, use the truetype function in the ImageFont module. Note that this function depends on third-party libraries, and may not available in all PIL builds.

Functions

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

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.

参数:	xy – Four points to define the bounding box. Sequence of either [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. outline – Color to use for the outline.

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 macodee (mode “L” or “RGBA”).

This is equivalent to doing image.paste(xy, color, bitmap).

To paste pixel data into an image, use the paste() method on the image itself.

PIL.ImageDraw.Draw.chord(xy, start, end, fill=None, outline=None)

Same as arc(), but connects the end points with a straight line.

参数:	xy – Four points to define the bounding box. Sequence of either [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.ellipse(xy, fill=None, outline=None)

Draws an ellipse inside the given bounding box.

参数:	xy – Four points to define the bounding box. Sequence of either [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.line(xy, fill=None, width=0)

Draws a line between the coordinates in the xy list.

参数:	xy – Sequence of either 2-tuples like [(x, y), (x, y), ...] or numeric values like [x, y, x, y, ...]. fill – Color to use for the line. width – The line width, in pixels. Note that line joins are not handled well, so wide polylines will not look good. 1.1.5 新版功能. 注解 This option was broken until version 1.1.6.

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.

参数:	xy – Four points to define the bounding box. Sequence of either [(x0, y0), (x1, y1)] or [x0, y0, x1, y1]. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.point(xy, fill=None)

Draws points (individual pixels) at the given coordinates.

参数:	xy – Sequence of either 2-tuples like [(x, y), (x, y), ...] or numeric values like [x, y, x, y, ...]. fill – Color to use for the point.

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.

参数:	xy – Sequence of either 2-tuples like [(x, y), (x, y), ...] or numeric values like [x, y, x, y, ...]. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.rectangle(xy, fill=None, outline=None)

Draws a rectangle.

参数:	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. outline – Color to use for the outline. fill – Color to use for the fill.

PIL.ImageDraw.Draw.shape(shape, fill=None, outline=None)

警告

This method is experimental.

Draw a shape.

PIL.ImageDraw.Draw.text(xy, text, fill=None, font=None, anchor=None)

Draws the string at the given position.

参数:	xy – Top left corner of the text. text – Text to be drawn. font – An ImageFont instance. fill – Color to use for the text.

PIL.ImageDraw.Draw.textsize(text, font=None)

Return the size of the given string, in pixels.

参数:	text – Text to be measured. font – An ImageFont instance.

Legacy API

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.

PIL.ImageDraw.ImageDraw(image)

返回类型:	Draw

PIL.ImageDraw.Draw.setink(ink)

1.1.5 版后已移除.

Sets the color to use for subsequent draw and fill operations.

PIL.ImageDraw.Draw.setfill(fill)

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.

PIL.ImageDraw.Draw.setfont(font)

1.1.5 版后已移除.

Sets the default font to use for the text method.

参数:	font – An ImageFont instance.