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@newcenturycomputers.net

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.

  • Version 0.56
    Revised 03/10/2005 by Chris Gonnerman
    • added support for GIF files.
    • the minimum gd library version for this gdmodule version is 2.0.23.
  • Version 0.55
    Revised 03/10/2005 by Chris Gonnerman
    • corrected error in the gd.image() constructor, pointed out by Betty Li.
    • corrected yet another obvious error reported by Greg Hewgill, regarding an incorrect call to gdImagePolygon when fillcolor is not equal to 1.
    • implemented the saveAlpha and alphaBlending features as suggested by Christopher Stone.
    • fixed memory management issue regarding image deallocation reported by Matti Jagula.
    • fixed memory management issue in image_filledpolygon reported by Sadruddin Rejeb.
    • the minimum gd library version for this gdmodule version is 2.0.22.
  • Version 0.54
    Revised 03/03/2005 by Chris Gonnerman
    • this version has been withdrawn and replaced with 0.55, above.
  • Version 0.53
    Revised 06/10/2004 by Chris Gonnerman
    • corrected obvious error in image_settile(), as pointed out by Dan Mosedale.
    • applied some patches provided by John Hunter. Several are for Windows compatibility, but this should be considered a "work in progress" in this version.
    • corrected another obvious error (and an ancient one too) reported by Greg Hewgill, regarding the foreground color being used rather than the fill color in the image_polygon function.
    • the minimum gd library version for this gdmodule version is 2.0.22.
  • Version 0.52
    Revised 02/03/2004 by Chris Gonnerman
    • incorporated new functions from the matplotlib project (provided by John Hunter)
    • corrected error in PyObject_HEAD_INIT() call noted by Stefan R Kuzminski (thanks!)
  • Version 0.50
    Revised 09/13/2003 by Chris Gonnerman
    • Documentation change: version 2.0.8 or higher of GD has been required since version 0.41 of gdmodule.
    • The library search order has been changed; /usr/local/lib is now the first in the search path. This is intended to support those trying to build against newer versions of GD which might conflict with an older version installed with the Linux or BSD distibution.
  • Version 0.42
    Revised 06/10/2003 by Chris Gonnerman
    • implemented patch by Gregory P. Smith to support writing to arbitrary objects, superceding the patch in 0.41 from Andreas Rottman. gddemo.py contains Rottman's example (which works with Smith's patched version) as well as an example (by me) of reading an image from a URL. The documentation was updated to reflect these changes.
  • Version 0.41
    Revised 05/29/2003 by Chris Gonnerman
    • implemented big patch by Andreas Rottmann to support writing images to memory via StringIO/CStringIO. Currently the only documentation is an example in gddemo.py.
    • implemented patch by Bob Galloway to remove the "specialness" of negative coordinates in the string_ttf/string_ft methods.
    • implemented patch by Nathan Robertson to enable MacOSX fink builds.
    • fixed bugs in the proxy class with regard to passing of _gd.image types.
  • Version 0.40
    Revised 09/18/2002 by Chris Gonnerman
    • updated to deal with incomplete library installs
  • Version 0.30
    Revised 06/12/2002 by Chris Gonnerman
    • initial conversion to two-tier design
  • Version 0.26
    Revised 12/10/2001 by Chris Gonnerman
    • made unicode optional via define Py_UNICODEOBJECT_H
  • Version 0.25
    Revised 09/15/2001 by Chris Gonnerman
    • implemented patch by Mike Romberg:
      • adds additional image methods, available only if GD 2.0.1+ is installed.
  • Version 0.24
    Revised 08/08/2001 by Chris Gonnerman
    • implemented patch by Mike Romberg:
      • supports GCC 3.0 and GD 2.0.1
      • adds public C function makeGDImage()
        • It allows C or C++ code which uses the gd library directly to make an imageobject instance.
  • Version 0.23
    Revised 11/22/2000 by Chris Gonnerman
    • included the patch from Tanimoto Osamu
    • updated support to GD version 1.8.3
    • cleaned up code, added ANSI prototypes

Comments