Python GD Module Reference

Description

GD module is an interface to the GD library written by Thomas Boutell.
'gd is a graphics library. It allows your code to quickly draw images complete with lines, arcs, text, multiple colors, cut and paste from other images, and flood fills, and write out the result as a PNG or JPEG file. This is particularly useful in World Wide Web applications, where PNG and JPEG are two of the formats accepted for inline images by most browsers.'
It has been extended in some ways from the original GD library.

This documentation is slightly out of date. In particular, the patch by Mike Romberg adds a lot of methods to the image object, which may not be fully documented here. Use the Source, Luke.

Constants

gdFontGiant, gdFontLarge, gdFontMediumBold, gdFontSmall, gdFontTiny
Fonts for use with the string() and stringUp() methods.
gdMaxColors(256)
Maximum number of colors in an image; GD will likely change this figure in a future version.
gdStyled, gdStyledBrushed, gdBrushed
Draw mode for line() and lines() method.
gdTiled
Fill mode for fill(), fillToBorder()
gdTransparent, gdStyledBrushed
Special entries for setStyle()

Image Object

image(image[,(w,h)] | file | file,type | (w,h))
create GD image from
  • file.(png|jpeg|gd|gd2|xbm|xpm),
  • file (a filename or file-like object with a read method), type (png|jpeg|gd|gd2|xbm|xpm)
  • the existing image,
    • optionally resized to width w and height h
  • or blank with width w and height h

Image Object Methods

writePng(f)
write the image to f as a PNG, where f is either an open file-like object or a file name.
writeJpeg(f, [ q ])
write the image to f as a JPEG file, where f is either an open file-like object or a file name, and q is the quality value as an integer from 0 to 100. If q is 0 or omitted, a default is used.
writeGd(f)
write the image to f as a GD file, where f is either an open file-like object or a file name.
writeGd2(f, [ c, [ fmt ] ])
write the image to f as a GD2 file, where f is either an open file-like object or a file name, c is the chunksize and fmt is the format. See the GD 1.8.3 or later documentation for an explanation. Defaults will be supplied if omitted.
writeWbmp(f, [ fg ])
write the image to f as a WBMP file, where f is either an open file-like object or a file name, and fg is the index of the color to "set" in the result image (see the GD 1.8.3 or later documentation for details). fg defaults to 0 if omitted.

All of the above write methods accept either a filename, file object or a python object with a write() method. Use a StringIO object if you want to get the image data without writing it to a file (useful for web scripts that return generated images to the client).
 
setPixel((x,y), color)
set the pixel at (x,y) to color
line((x1,y1), (x2,y2), color)
draw a line from (x1,y1) to (x2,y2) in color
lines(((x1,y1), (x2,y2), ..., (xn, yn)), color)
draw a line along the sequence of points in the list or tuple using color
polygon(((x1,y1), (x2,y2), ..., (xn, yn)), color[, fillcolor])
draw a polygon using the list or tuple of points (minimum 3) in color, optionally filled with fillcolor
rectangle((x1,y1), (x2,y2), color[, fillcolor])
draw a rectangle with upper corner (x1,y1), lower corner (x2,y2) in color, optionally filled with fillcolor
filledPolygon(((x1,y1), (x2,y2), ..., (xn, yn)), color)
draw a filled polygon using the list or tuple of points (minimum 3) in color
filledRectangle((x1,y1), (x2,y2), color)
draw a rectangle with upper corner (x1,y1), lower corner (x2,y2) in color
arc((x,y), (w,h), start, end, color)
draw an ellipse centered at (x,y) with width w, height h from start degrees to end degrees in color.
fillToBorder((x,y), border, color)
flood from point (x,y) to border color in color
fill((x,y), color)
flood from point (x,y) in color for those pixels with the same color as the starting point
setBrush(image)
set the drawing brush to image (use gdBrushed when drawing)
setTile(image)
set the fill tile to image (use gdTiled when filling)
setStyle(tuple|list)
set the line bit-style to tuple or list of colors (use gdStyled when drawing)
getPixel((x,y))
color index of image at (x,y)
boundsSafe((x,y))
returns true if (x,y) is within image
size()
return the 2-tuple size of image
string(font, (x,y), s, color)
draw string s at (x,y) using one of the pre-defined gdmodule fonts
stringUp(font, (x,y), s, color)
vertically draw string s at (x,y) using one of the pre-defined gdmodule fonts
get_bounding_rect(font, pointsize, angle, (x,y), s)
Get bounding rect of string s using the TrueType font at the given pointsize and angle. Returns the bounding box of the given text as an eight-tuple: lower left X, lower left Y, lower right X, lower right Y, upper right X, upper right Y, upper left X, upper left Y.
string_ttf(font, pointsize, angle, (x,y), s, color)
draw string s at (x,y) using the TrueType font at the given pointsize and angle. Returns the bounding box of the given text as an eight-tuple: lower left X, lower left Y, lower right X, lower right Y, upper right X, upper right Y, upper left X, upper left Y.
string_ft(font, pointsize, angle, (x,y), s, color)
Functional equivalent of string_ttf, which may be deprecated.
colorAllocate((r,g,b))
allocate a color index to (r,g,b) (returns -1 if unable to)
colorClosest((r,g,b))
return the color index closest to (r,g,b) (returns -1 if unable to)
colorExact((r,g,b))
return an exact color index match for (r,g,b) (returns -1 if unable to)
colorsTotal()
returns the number of colors currently allocated
colorComponents(color)
returns a 3-tulple of the (r,g,b) components of color
getInterlaced()
returns true if the image is interlaced
getTransparent()
returns transparent color index or -1
colorDeallocate(color)
deallocate color from the image palette
colorTransparent(color)
set the transparent color to color
copyTo(image[, (dx,dy)[, (sx,sy)[, (w,h)]]])
copy from (sx,sy), width sw and height sh to destination image (dx,dy)
copyResizedTo(image[, (dx,dy)[, (sx,sy)[, (dw,dh)[, (sw,sh)]]]])
copy from (sx,sy), width sw and height sh to destination image (dx,dy), width dw and height dh
interlace()
set the interlace bit
origin((x,y)[,xmult,ymult])
set the origin of the image to (x,y) and multiply all x, y, width and height factors by xmult and ymult (typically either 1 or -1)
getOrigin()
returns the origin parameters ((x,y),xmult,ymult)

Other Module-level functions

fontstrsize(font, string)
return a tuple containing the size in pixels of the given string in the given font
Copyright © 1995 Richard Jones, Bureau of Meteorology Australia.
richard@bofh.asn.au

With Richard's blessing, I have taken over support for this module; so, send all bug reports, etc. to chris@gonnerman.org

This module is a python wrapper for the GD library (version 1.1.1 and later)

From the GD docs:
"COPYRIGHT 1994 BY THE QUEST CENTER AT COLD SPRING HARBOR LABS.
Permission granted for unlimited use, provided that the Quest Center at Cold Spring Harbor Labs is given credit for the library in the user-visible documentation of your software. If you modify gd, we ask that you share the modifications with us so they can be added to the distribution. See gd.html for details.

Comments