CGI and Perl

GD: Dynamic Images

In CPAN, you can find a module called GD. This module provides a Perl interface to the GD graphics library, which was written by Thomas Boutell. This library provides several routines for creating, reading, writing, and manipulating GIF files. The routines are implemented as graphic primitives such as line and arc drawing and fill routines. Using this library, you also can render simple fonts as well as read and utilize existing GIF files.

For the examples in this chapter, you will use the GD module to dynamically create images for a Web page. First, however, you need to go over a few of the basics concerning the GD module.

GD::Image Module

The GD::Image module provides an interface to the image data and graphics primitive aspect of the GD library. This class contains interfaces for reading and writing GIF files and dynamically creating GIF file contents. In the following sections, you examine some of the functions provided in this class.

GD::Image::new(width, height) The GD::Image::new(width, height) function creates a new empty image of width width and height height. You begin here if you want to create a dynamic image using the drawing primitives. Alternatively, you can construct a GD::Image object using newFromGif(FILEHANDLE), newFromXbm(FILEHANDLE), or newFromGd(FILEHANDLE). These constructors load the image content data from FILEHANDLE, which can point to a file of type GIF, XBM, or GD format. Storing files in GD format is not recommended because no compression is performed, causing these files to potentially become rather large.

GD::Image::gif() and GD::Image::gd() The GD::Image::gif()and GD::Image::gd() methods are used to emit a GD::Image object in
either GIF or GD format. You generally use them after you have finished creating your image content and are ready to either save the image to disk or return the image data from a CGI script.

GD::Image::colorAllocate(red, green, blue) The GD::Image::colorAllocate(red, green, blue) method allocates a color corresponding to an RGB triplet. It returns a color index value that can later be used with the drawing primitives. This color index can also be passed into the colorDeallocate(colorIndex) method. A number of special color index values are automatically allocated. These constants are contained within the GD:: namespace but are automatically exported when the GD module is loaded. I mention these special color indices as I cover their uses.

GD::Image::transparent(colorIndex) The GD::Image::transparent(colorIndex) method marks the color specified by colorIndex as transparent color. All pixels using this color are invisible, thus allowing the background to appear. This capability is useful for creating the illusion of nonrectangular images, because all images are, in fact, rectangles, regardless of how they might appear.

A few other methods are related to color control, but I don't mention them here. To get a complete reference on this module, be sure to check the latest version in CPAN.

GD::Image::setBrush(GD::Image) The GD::Image::setBrush(GD::Image) method establishes a brush or pattern that you can use when drawing lines or arcs. You first create a GD::Image object that acts as your brush, pass it as an argument to this method, and then use the gdBrushed special color index when calling one of the drawing primitives.

GD::Image::setTile(GD::Image) The GD::Image::setTile(GD::Image) method establishes a tile pattern that you can use when filling areas. You first create a GD::Image object that defines your pattern, pass it as an argument to this method, and then use the gdTiled special color index as the fill color for one of the drawing methods.

GD::Image::setPixel(x,y,colorIndex) The GD::Image::setPixel(x,y,colorIndex) method sets the color of a single pixel value at location (x,y) to the color specified by colorIndex.

GD::Image::line(x1,y1,x2,y2,colorIndex) The GD::Image::line(x1,y1,x2,y2,colorIndex) method draws a line from (x1,y1) to (x2,y2) using the color specified by colorIndex. You can also use the dashedLine() method to draw a dashed or dotted line. To obtain greater control over the appearance of your dotted line, you can also use the setStyle() method and specify the gdStyled special color index value as your colorIndex for the line() method.

GD::Image::rectangle(x1,y1,x2,y2,colorIndex) The GD::Image::rectangle(x1,y1,x2,y2,colorIndex) method draws a rectangle using the color specified in colorIndex. (x1,y1) refers to the upper-left corner of the rectangle, and (x2,y2) refers to the lower-right corner. You can draw a filled rectangle using the filledRectangle() method.

GD::Image::polygon(polygon,colorIndex) The GD::Image::polygon(polygon,colorIndex) method draws a polygon defined by a GD::Polygon object, which I describe later in this chapter. The colorIndex specifies the color in which to draw the polygon. You can also draw a filled polygon using the filledPolygon() method.

GD::Image::arc(cx,cy,width,height,start,end,colorIndex) The GD::Image::arc(cx,cy,width,height,start,end,colorIndex) method draws arcs or ellipses using the color specified in colorIndex. (cx,cy) defines the center point, and width and height specify the width and height of the ellipse. start and end specify the angles at which to begin and end the arc. These values are specified in degrees between 0 and 360. A start of 0 and end of 360 with height equal to width would produce a full circle.

GD::Image::fill(x,y,colorIndex) The GD::Image::fill(x,y,colorIndex) method fills a region with the color specified by colorIndex. It starts at location (x,y) and continues setting the color of adjacent pixels until it reaches a pixel of a different color than the starting pixel. In addition to normal RGB colors, you can also use the special color gdTiled to fill with a pattern.

GD::Image::string(font,x,y,string,colorIndex) The GD::Image::string(font,x,y,string,colorIndex) method enables you to draw text into your image using the specified font and colorIndex. (x,y) defines the pixel location at which to draw the string. The fonts from which you can choose are gdSmallFont, gdMediumBoldFont, gdTinyFont, and gdLargeFont.

GD::Image::stringUp(font,x,y,string,colorIndex) The GD::Image::stringUp(font,x,y,string,colorIndex) method is the same as string(), except that it draws the text rotated counterclockwise at 90 degrees.

GD::Image::interlaced() The GD::Image::interlaced() method enables you to set or query whether the image is interlaced. An interlaced image provides a venetian-blinds effect on some viewers while the image is first being displayed. Calling this method with no parameters returns 1 or 0, depending on whether the image is interlaced or not. Calling this method with a 1 or 0 sets or removes the interlaced attribute of the image.

GD::Image::getBounds() The GD::Image::getBounds() method returns the width and height of the image in a two-
member list. You can query the width and height of an image, but you cannot change these values after an image has been created.

GD::Image::copy(srcImage,dstX,dstY,srcX,srcY,width,height) The GD::Image::copy(srcImage,dstX,dstY,srcX,srcY,width,height) method enables you to copy one image into another. You call this method on the target image and specify the source image as srcImage. (dstX,dstY) specifies the point in the destination image at which you want to copy to. (srcX,srcY) specifies the point in the source image at which you want to copy from. width and height specify the dimensions of the area being copied.

You can also resize or scale an image while copying by using the copyResized() method. In addition to source and destination coordinates, you can specify source and destination width and height. This way, you can extend or reduce an image as well as modify the proportions of an image.