The aggdraw Module

An AGG-based drawing interface.

The aggdraw module implements the basic WCK 2D Drawing Interface on top of the AGG library. This library supports anti-aliasing and alpha compositing, but is otherwise fully compatible with the WCK renderer.

Examples:

# draw cross on top of PIL image
d = aggdraw.Draw(im)
p = aggdraw.Pen("black", 0.5)
d.line((0, 0, 500, 500), p)
d.line((0, 500, 500, 0), p)
d.flush()

# draw cross on internal image memory
d = aggdraw.Draw("RGB", (320, 200), "white")
p = aggdraw.Pen("black", 0.5)
d.line((0, 0, 500, 500), p)
d.line((0, 500, 500, 0), p)
s = d.tostring()

Module Contents

Brush(color, opacity=255) [#]

Creates a brush object.

color: Brush color. This can be a color tuple, a CSS-style color name, or a color integer (0xaarrggbb).
opacity=: Optional brush opacity. The default is to create a solid brush.
Returns:: A brush object.

Dib (class) [#]

(Windows only; new in 1.2) Creates a drawing interface object that can be copied to a window.

mode: A mode string. In the current release, this string must be “RGB”.
size: The image size, as a 2-tuple.
color: An optional background color specifier. If a mode string was given, this is used to initialize the image memory. If omitted, it defaults to white with full alpha.

For more information about this class, see The Dib Class.

Draw(image_or_mode, size, color=None) (class) [#]

Creates a drawing interface object.

image_or_mode: A PIL Image, or a mode string. The following modes are supported: “L”, “RGB”, “RGBA”, “BGR”, “BGRA”.
size: If a mode string was given, this argument gives the image size, as a 2-tuple.
color: An optional background color specifier. If a mode string was given, this is used to initialize the image memory. If omitted, it defaults to white with full alpha.

For more information about this class, see The Draw Class.

Font(color, file, size=12, opacity=255) [#]

Font factory. This creates a font object for use with text and textsize, from a truetype font file.

color: Font color. This can be a color tuple, a CSS-style color name, or a color integer (0xaarrggbb).
file: Font source file.
size=: Optional font size, in pixels.
opacity=: Optional font opacity.
Returns:: A font object.

Path() (class) [#]

(experimental) Path factory.

Returns:: A path object.

For more information about this class, see The Path Class.

Pen(color, width=1, opacity=255) [#]

Creates a pen object.

color: Pen color. This can be a color tuple, a CSS-style color name, or a color integer (0xaarrggbb).
width=: Optional pen width.
opacity=: Optional pen opacity. The default is to create a solid pen.
Returns:: A pen object.

Symbol(path) [#]

(experimental) Symbol factory. This creates a symbol object for use with symbol.

path: An SVG-style path descriptor. The following operators are supported: M (move), L (line), H (horizontal line), V (vertical line), C (cubic bezier), S (smooth cubic bezier), Q (quadratic bezier), T (smooth quadratic bezier), and Z (close path). Use lower-case operators for relative coordinates, upper-case for absolute coordinates.
Returns:: A symbol object.

VERSION (variable) [#]

Version number, given as a string. If this variable doesn’t exist, the version is “1.1b1” or earlier.

The Dib Class

Dib (class) [#]

(Windows only; new in 1.2) Creates a drawing interface object that can be copied to a window. This object has the same methods as Draw, plus an expose method that copies the contents to a given window.

Example:

d = aggdraw.Dib("RGB", (800, 600), "white")
...
d.expose(hwnd=window)

mode: A mode string. In the current release, this string must be “RGB”.
size: The image size, as a 2-tuple.
color: An optional background color specifier. If a mode string was given, this is used to initialize the image memory. If omitted, it defaults to white with full alpha.

expose(hwnd=0, hdc=0) [#]

Copies the contents of the drawing object to the given window or device context. You must provide either a hwnd or a hdc keyword argument.

hwnd=: A HWND handle, cast to an integer.
hdc=: A HDC handle, cast to an integer.

The Draw Class

Draw(image_or_mode, size, color=None) (class) [#]

Creates a drawing interface object. The constructor can either take a PIL Image object, or mode and size specifiers.

Examples:

d = aggdraw.Draw(im)

d = aggdraw.Draw("RGB", (800, 600), "white")

image_or_mode: A PIL Image, or a mode string. The following modes are supported: “L”, “RGB”, “RGBA”, “BGR”, “BGRA”.
size: If a mode string was given, this argument gives the image size, as a 2-tuple.
color: An optional background color specifier. If a mode string was given, this is used to initialize the image memory. If omitted, it defaults to white with full alpha.

arc(xy, start, end, pen=None) [#]

Draws an arc.

xy: A 4-element Python sequence (x, y, x, y), with the upper left corner given first.
start: Start angle.
end: End angle.
pen: Optional pen object created by the Pen factory.

chord(xy, start, end, pen=None, brush=None) [#]

Draws a chord.

If a brush is given, it is used to fill the chord. If a pen is given, it is used to draw an outline around the chord. Either one (or both) can be left out.

xy: A 4-element Python sequence (x, y, x, y), with the upper left corner given first.
start: Start angle.
end: End angle.
pen: Optional pen object created by the Pen factory.
brush: Optional brush object created by the Brush factory.

ellipse(xy, pen, brush) [#]

Draws an ellipse.

If a brush is given, it is used to fill the ellipse. If a pen is given, it is used to draw an outline around the ellipse. Either one (or both) can be left out.

xy: A bounding rectangle, given as a 4-element Python sequence (x, y, x, y), with the upper left corner given first. To draw a circle, make sure the coordinates form a square.
pen: Optional pen object created by the Pen factory.
brush: Optional brush created by the Brush factory.

flush() [#]

Updates the associated image. If the drawing area is attached to a PIL Image object, this method must be called to make sure that the image updated.

fromstring(data) [#]

Copies data from a string buffer to the drawing area.

data: A string containing packed image data, compatible with PIL’s tostring method.

line(xy, pen) [#]

Draws a line.

Examples:

# a cross
pen = aggdraw.Pen("red")
draw.line((x0, y0, x1, y1), pen)
draw.line((x0, y1, x1, y0), pen)

# a character
draw.line((0, 0, 20, 100, 30, 50, 40, 100, 60, 0), pen)

xy: A Python sequence (x, y, x, y, …). If more than two coordinate pairs are given, they are connected in order, to form a polyline.
pen: A pen object created by the Pen factory method.

path(xy, path, pen=None, brush=None) [#]

(experimental) Draws a path at the given positions. If a brush is given, it is used to fill the path. If a pen is given, it is used to draw an outline around the path. Either one (or both) can be left out.

xy: A Python sequence (x, y, x, y, …).
path: A symbol object created by the Path factory.
pen: Optional pen object created by the Pen factory.
brush: Optional brush object created by the Brush factory.

pieslice(xy, start, end, pen=None, brush=None) [#]

Draws a pieslice.

If a brush is given, it is used to fill the pieslice. If a pen is given, it is used to draw an outline around the pieslice. Either one (or both) can be left out.

xy: A 4-element Python sequence (x, y, x, y), with the upper left corner given first.
start: Start angle.
end: End angle.
pen: Optional pen object created by the Pen factory.
brush: Optional brush object created by the Brush factory.

polygon(xy, pen, brush) [#]

Draws a polygon.

If a brush is given, it is used to fill the polygon. If a pen is given, it is used to draw an outline around the polygon. Either one (or both) can be left out.

xy: A Python sequence (x, y, x, y, …).
pen: Optional pen object created by the Pen factory.
brush: Optional brush object created by the Brush factory.

rectangle(xy, pen, brush) [#]

Draws a rectangle.

If a brush is given, it is used to fill the rectangle. If a pen is given, it is used to draw an outline around the rectangle. Either one (or both) can be left out.

xy: A 4-element Python sequence (x, y, x, y), with the upper left corner given first.
pen: Optional pen object created by the Pen factory.
brush: Optional brush created by the Brush factory.

setantialias(flag) [#]

(Experimental) Controls anti-aliasing.

flag: True to enable anti-aliasing, false to disable it.

settransform(transform=None) [#]

(Experimental) Replaces the current drawing transform.

Example:

draw.settransform((dx, dy))

transform: The new transform. In the current version, this must be either a (dx, dy) translation tuple, or a PIL-style (a, b, c, d, e, f) affine transform tuple. If the transform is omitted, it is reset.

symbol(xy, symbol, pen=None, brush=None) [#]

(experimental) Draws a symbol at the given positions. If a brush is given, it is used to fill the symbol. If a pen is given, it is used to draw an outline around the symbol. Either one (or both) can be left out.

xy: A Python sequence (x, y, x, y, …).
symbol: A symbol object created by the Symbol factory.
pen: Optional pen object created by the Pen factory.
brush: Optional brush object created by the Brush factory.

text(xy, text, font) [#]

Draws a text string at the given position, using the given font.

Example:

font = aggdraw.Font(black, times)
draw.text((100, 100), "hello, world", font)

xy: A 2-element Python sequence (x, y).
text: An 8-bit string containing ASCII text, or a Unicode string.
font: A font object created by the Font factory.

textsize(text, font) [#]

Determines the size of a text string.

text: An 8-bit string containing ASCII text, or a Unicode string.
font: A font object created by the Font factory.
Returns:: A (width, height) tuple.

tostring(data) [#]

Copies data from the drawing area to a string.

Returns:: A string containing packed image data, compatible with PIL’s fromstring method.

The Path Class

Path() (class) [#]

(experimental) Path factory. This creates a path object for use with path.

Returns:: A path object.

close() [#]

Closes the current path.

coords() [#]

Returns the coordinates for this path. Curves are flattened before being returned.

Returns:: A Python sequence (x, y, x, y, …).

curveto(x1, y1, x2, y2, x, y) [#]

Adds a bezier curve segment to the path.

x1
y1
x2
y2
x
y

lineto(x, y) [#]

Adds a line segment to the path.

x
y

moveto(x, y) [#]

Moves the path pointer to the given location.

x
y

rcurveto(x1, y1, x2, y2, x, y) [#]

Adds a bezier curve segment to the path, using relative coordinates. Same as curveto, but the coordinates are relative to the current position.

x1
y1
x2
y2
x
y

rlineto(x, y) [#]

Adds a line segment to the path, using relative coordinates. Same as lineto, but the coordinates are relative to the current position.

x
y

rmoveto(x, y) [#]

Moves the path pointer to the given location, relative to the current position.

x
y