GD.pm - Manual




NAME
     GD.pm - Interface to Gd Graphics Library

DESCRIPTION
     The gd graphics library

     The gd graphics library, written by Thomas Boutell of Cold
     Spring Harbor Labs (Boutell@netcom.com), is a package of C
     routines for creating, reading, writing, and manipulating
     GIF graphics files.  It provides graphics primitives for:

     o Reading and writing GIF files.

     o Drawing lines, rectangles, arcs, ellipses and text.

     o Flood fills.

     o Using arbitrary images as tiled patterns for filling shapes.

     o Using arbitrary images as paintbrushes.

     o resizing it.
     
     o Stamping a portion of one image onto another, optionally

     o Simple text rendering.

     gd can be obtained at URL http://siva.cshl.org/gd/gd.html.
     Directions for installing it, and full documentation are
     available from that site.

     The GD.pm interface

     GD.pm is a port of the gd library by Lincoln Stein
     (lstein@genome.wi.mit.edu).  It is similar to the original C
     library, but contains some modifications to take advantage
     of perl's object-oriented features.  It defines the
     following three classes:

     GD::Image
          An image class, which holds the image data and accepts
          graphic primitive method calls.

     GD::Font
          A font class, which holds static font information and
          used for text rendering.

     GD::Polygon
          A simple polygon object, used for storing lists of
          vertices prior to rendering a polygon into an image.

     A Simple Example:


             #!/usr/local/bin/perl

             use GD;

             # create a new image
             $im = new GD::Image(100,100);

             # allocate some colors
             $white = $im->colorAllocate(255,255,255);
             $black = $im->colorAllocate(0,0,0);
             $red   = $im->colorAllocate(255,0,0);
             $blue  = $im->colorAllocate(0,0,255);

             # make the background transparent and interlaced
             $im->transparent($white);
             $im->interlaced('true');

             # Put a black frame around the picture
             $im->rectangle(0,0,99,99,$black);

             # Draw a blue oval
             $im->arc(50,50,95,75,0,360,$blue);

             # And fill it with red
             $im->fill(50,50,$red);

             # Convert the image to GIF and print it on standard output
             print $im->gif;

     Notes:

GD::Image, passing it the width and height of the image you want
to create.  An image object will be returned.  Other class
methods allow you to initialise an image from a preexisting GIF,
GD or XBM file.

     1. To create a new, empty image, send a new() message to
table. colors are added using a colorAllocate() method call.  The
three parameters in each call are the red, green and blue (rgb)
triples for the desired color.  The method returns the index of
that color in the image's color table.  You should store these
indexes for later use.

     2. Next you will ordinarily add colors to the image's color
are described below.  In this example, we do some text drawing,
create an oval, and create and draw a polygon.

     3. Now you can do some drawing!  The various graphics primitives
can add points to the returned polygon one at a time using the
addPt() method. The polygon can then be passed to an image for
rendering.

     4. Polygons are created with a new() message to GD::Polygon.  You
format by sending it a gif() message.  It will return a
(potentially large) scalar value containing the binary data for
the image.  Ordinarily you will print it out at this point or
write it to a file.

     5. When you're done drawing, you can convert the image into GIF
Method Calls
     Creating and Saving Images

     new  GD::Image::new(width,height)  [class method]

          To create a new, blank image, send a[new() message to
          the GD::Image class.  For example:

                  $myImage = new GD::Image(100,100) || die;

          This will create an image that is 100 x 100 pixels
          wide.  If you don't specify the dimensions, a default
          of 64 x 64 will be chosen. If something goes wrong
          (e.g. insufficient memory), this call will return
          undef.

     newFromGif
          GD::Image::newFromGif(FILEHANDLE)  [class method]

          This will create an image from a GIF file read in
          through the provided filehandle.  The filehandle must
          previously have been opened on a valid GIF file or
          pipe.  If successful, this call will return an
          initialized image which you can then manipulate as you
          please.  If it fails, which usually happens if the
          thing at the other end of the filehandle is not a valid
          GIF file, the call returns undef.  Notice that the call
          doesn't automatically close the filehandle for you.

          To get information about the size and color usage of
          the information, you can call the image query methods
          described below.

                  Example usage:

                  open (GIF,"barnswallow.gif") || die;
                  $myImage = newFromGif GD::Image(GIF) || die;
                  close GIF;


     newFromXbm
          GD::Image::newFromXbm(FILEHANDLE)  [class method]

          This works in exactly the same way as newFromGif, but
          reads the contents of an X Bitmap file:

                  open (XBM,"coredump.xbm") || die;
                  $myImage = newFromXbm GD::Image(XBM) || die;
                  close XBM;


     newFromGd
          GD::Image::newFromGd(FILEHANDLE)  [class method]

          This works in exactly the same way as newFromGif, but
          reads the contents of a GD file.  GD is Tom Boutell's
          disk-based storage format, intended for the rare case
          when you need to read and write the image to disk
          quickly.  It's not intended for regular use, because,
          unlike GIF or JPEG, no image compression is performed
          and these files can become BIG.

                  open (GDF,"godzilla.gd") || die;
                  $myImage = newFromGd GD::Image(GDF) || die;
                  close GDF;


     gif  GD::Image::gif  [object method]

          This returns the image data in GIF format.  You can
          then print it, pipe it to a display program, or write
          it to a file.  Example:

                  $gif_data = $myImage->gif;
                  open (DISPLAY,"| display -") || die;
                  print DISPLAY $gif_data;
                  close DISPLAY;


     gd   GD::Image::gd  [object method]

          This returns the image data in GD format.  You can then
          print it, pipe it to a display program, or write it to
          a file.  Example:

                  print MYOUTFILE $myImage->gd;


     Color Control

     colorAllocate
          GD::Image::colorAllocate(red,green,blue)  [object method]

          This allocates a color with the specified red, green
          and blue components and returns its index in the color
          table, if specified.  The first color allocated in this
          way becomes the image's background color.
          (255,255,255) is white (all pixels on).  (0,0,0) is
          black (all pixels off).  (255,0,0) is fully saturated
          red.  (127,127,127) is 50% gray.  You can find plenty
          of examples in /usr/X11/lib/X11/rgb.txt.

          If no colors are allocated, then this function returns
          -1.

          Example:

                  $white = $myImage->colorAllocate(0,0,0); #background color
                  $black = $myImage->colorAllocate(255,255,255);
                  $peachpuff = $myImage->colorAllocate(255,218,185);


     colorDeallocate
          GD::Image::colorDeallocate(colorIndex)  [object method]

          This marks the color at the specified index as being
          ripe for reallocation.  The next time colorAllocate is
          used, this entry will be replaced.  You can call this
          method several times to deallocate multiple colors.
          There's no function result from this call.

          Example:

                  $myImage->colorDeallocate($peachpuff);
                  $peachy = $myImage->colorAllocate(255,210,185);


     colorClosest
          GD::Image::colorClosest(red,green,blue)  [object method]

          This returns the index of the color closest in the
          color table to the red green and blue components
          specified.  If no colors have yet been allocated, then
          this call returns -1.

          Example:

                  $apricot = $myImage->colorClosest(255,200,180);


     colorExact
          GD::Image::colorExact(red,green,blue)  [object method]

          This returns the index of a color that exactly matches
          the specified red green and blue components.  If such a
          color is not in the color table, this call returns -1.

                  $rosey = $myImage->colorExact(255,100,80);
                  warn "Everything's coming up roses.\n" if $rosey >= 0;


     colorsTotal
          GD::Image::colorsTotal)  [object method]

          This returns the total number of colors allocated in
          the object.

                  $maxColors = $myImage->colorsTotal;


     getPixel
          GD::Image::getPixel(x,y)  [object method]

          This returns the color table index underneath the
          specified point.  It can be combined with[rgb() to
          obtain the rgb color underneath the pixel.

          Example:

                  $index = $myImage->getPixel(20,100);
                  ($r,$g,$b) = $myImage->rgb($index);


     rgb  GD::Image::rgb(colorIndex)  [object method]

          This returns a list containing the red, green and blue
          components of the specified color index.

          Example:

                  @RGB = $myImage->rgb($peachy);


     transparent
          GD::Image::transparent(colorIndex)  [object method]

          This marks the color at the specified index as being
          transparent.  Portions of the image drawn in this color
          will be invisible.  This is useful for creating
          paintbrushes of odd shapes, as well as for making GIF
          backgrounds transparent for displaying on the Web.
          Only one color can be transparent at any time. To
          disable transparency, specify -1 for the index.

          If you call this method without any parameters, it will
          return the current index of the transparent color, or
          -1 if none.

          Example:

                  open(GIF,"test.gif");
                  $im = newFromGif GD::Image(GIF);
                  $white = $im->colorClosest(255,255,255); # find white
                  $im->transparent($white);
                  print $im->gif;


     Special Colors

     GD implements a number of special colors that can be used to
     achieve special effects.  They are constants defined in the
     GD::  namespace, but automatically exported into your
     namespace when the GD module is loaded.

     setBrush

     gdBrushed
          GD::Image::setBrush( ) and GD::gdBrushed

          You can draw lines and shapes using a brush pattern.
          Brushes are just images that you can create and
          manipulate in the usual way. When you draw with them,
          their contents are used for the color and shape of the
          lines.

          To make a brushed line, you must create or load the
          brush first, then assign it to the image using
          setBrush.  You can then draw in that with that brush
          using the gdBrushed special color.  It's often useful
          to set the background of the brush to transparent so
          that the non-colored parts don't overwrite other parts
          of your image.

          Example:

                  # Create a brush at an angle
                  $diagonal_brush = new GD::Image(5,5);
                  $white = $diagonal_brush->allocateColor(255,255,255);
                  $black = $diagonal_brush->allocateColor(0,0,0);
                  $diagonal_brush->transparent($white);
                  $diagonal_brush->line(0,4,4,0,$black); # NE diagonal

                  # Set the brush
                  $myImage->setBrush($diagonal_brush);

                  # Draw a circle using the brush
                  $myImage->arc(50,50,25,25,0,360,gdBrushed);


     setStyle


     gdStyled
          GD::Image::setStyle(@colors) and GD::gdStyled

          Styled lines consist of an arbitrary series of repeated
          colors and are useful for generating dotted and dashed
          lines.  To create a styled line, use setStyle to
          specify a repeating series of colors.  It accepts an
          array consisting of one or more color indexes.  Then
          draw using the gdStyled special color.  Another special
          color, gdTransparent can be used to introduce holes in
          the line, as the example shows.

          Example:

                  # Set a style consisting of 4 pixels of yellow,
                  # 4 pixels of blue, and a 2 pixel gap
                  $myImage->setStyle($yellow,$yellow,$yellow,$yellow,
                                     $blue,$blue,$blue,$blue,
                                     gdTransparent,gdTransparent);
                  $myImage->arc(50,50,25,25,0,360,gdStyled);

          To combine the gdStyled and gdBrushed behaviors, you
          can specify gdStyledBrushed.  In this case, a pixel
          from the current brush pattern is rendered wherever the
          color specified in[setStyle() is neither gdTransparent
          nor 0.

     gdTiled
          Draw filled shapes and flood fills using a pattern.
          The pattern is just another image.  The image will be
          tiled multiple times in order to fill the required
          space, creating wallpaper effects.  You must call
          setTile in order to define the particular tile pattern
          you'll use for drawing when you specify the gdTiled
          color.  details.

     gdStyled
          The gdStyled color is used for creating dashed and
          dotted lines.  A styled line can contain any series of
          colors and is created using the setStyled command.

     Drawing Commands

     setPixel
          GD::Image::setPixel(x,y,color)  [object method]

          This sets the pixel at (x,y) to the specified color
          index.  No value is returned from this method.  The
          coordinate system starts at the upper left at (0,0) and
          gets larger as you go down and to the right.  You can
          use a real color, or one of the special colors
          gdBrushed, gdStyled and gdStyledBrushed can be
          specified.

          Example:

                  # This assumes $peach already allocated
                  $myImage->setPixel(50,50,$peach);


     line GD::Image::line(x1,y1,x2,y2,color)  [object method]

          This draws a line from (x1,y1) to (x2,y2) of the
          specified color.  You can use a real color, or one of
          the special colors gdBrushed, gdStyled and
          gdStyledBrushed.

          Example:

                  # Draw a diagonal line using the currently defind
                  # paintbrush pattern.
                  $myImage->line(0,0,150,150,gdBrushed);


     dashedLine
          GD::Image::dashedLine(x1,y1,x2,y2,color)  [object method]

          This draws a dashed line from (x1,y1) to (x2,y2) in the
          specified color.  A more powerful way to generate
          arbitrary dashed and dotted lines is to use the
         [setStyle() method described below and to draw with the
          special color gdStyled.

          Example:

                  $myImage->dashedLine(0,0,150,150,$blue);


     rectangle
          GD::Image::rectangle(x1,y1,x2,y2,color)  [object method]

          This draws a rectangle with the specified color.
          (x1,y1) and (x2,y2) are the upper left and lower right
          corners respectively.  Both real color indexes and the
          special colors gdBrushed, gdStyled and gdStyledBrushed
          are accepted.

          Example:

                  $myImage->rectangle(10,10,100,100,$rose);


     filledRectangle
          GD::Image::filledRectangle(x1,y1,x2,y2,color)  [object method]

          This draws a rectangle filed with the specified color.
          You can use a real color, or the special fill color
          gdTiled to fill the polygon with a pattern.

          Example:

                  # read in a fill pattern and set it
                  open(GIF,"happyface.gif") || die;
                  $tile = newFromGif GD::Image(GIF);
                  $myImage->setTile($tile);

                  # draw the rectangle, filling it with the pattern
                  $myImage->filledRectangle(10,10,150,200,gdTiled);


     polygon
          GD::Image::polygon(polygon,color)  [object method]

          This draws a polygon with the specified color.  The
          polygon must be created first (see below).  The polygon
          must have at least three vertices.  If the last vertex
          doesn't close the polygon, the method will close it for
          you.  Both real color indexes and the special colors
          gdBrushed, gdStyled and gdStyledBrushed can be
          specified.

          Example:

                  $poly = new GD::Polygon;
                  $poly->addPt(50,0);
                  $poly->addPt(99,99);
                  $poly->addPt(0,99);
                  $myImage->polygon($poly,$blue);


     filledPolygon
          GD::Image::filledPolygon(poly,color)  [object method]

          This draws a polygon filled with the specified color.
          You can use a real color, or the special fill color
          gdTiled to fill the polygon with a pattern.

          Example:

                  # make a polygon
                  $poly = new GD::Polygon;
                  $poly->addPt(50,0);
                  $poly->addPt(99,99);
                  $poly->addPt(0,99);

                  # draw the polygon, filling it with a color
                  $myImage->filledPolygon($poly,$peachpuff);


     arc  GD::Image::arc(cx,cy,width,height,start,end,color)
          [object method]

          This draws arcs and ellipses.  (cx,cy) are the center
          of the arc, and (width,height) specify the width and
          height, respectively.  The portion of the ellipse
          covered by the arc are controlled by start and end,
          both of which are given in degrees from 0 to 360.  Zero
          is at the top of the ellipse, and angles increase
          clockwise.  To specify a complete ellipse, use 0 and
          360 as the starting and ending angles.  To draw a
          circle, use the same value for width and height.

          You can specify a normal color or one of the special
          colors gdBrushed, gdStyled, or gdStyledBrushed.

          Example:

                  # draw a semicircle centered at 100,100
                  $myImage->arc(100,100,50,50,0,180,$blue);


     fill GD::Image::fill(x,y,color)  [object method]

          This method flood-fills regions with the specified
          color.  The color will spread through the image,
          starting at point (x,y), until it is stopped by a pixel
          of a different color from the starting pixel (this is
          similar to the "paintbucket" in many popular drawing
          toys).  You can specify a normal color, or the special
          color gdTiled, to flood-fill with patterns.

          Example:

                  # Draw a rectangle, and then make its interior blue
                  $myImage->rectangle(10,10,100,100,$black);
                  $myImage->fill(50,50,$blue);


     GD::Image::fillToBorder(x,y,bordercolor,color)  [object method]
          Like fill, this method flood-fills regions with the
          specified color, starting at position (x,y).  However,
          instead of stopping when it hits a pixel of a different
          color than the starting pixel, flooding will only stop
          when it hits the color specified by bordercolor.  You
          must specify a normal indexed color for the
          bordercolor.  However, you are free to use the gdTiled
          color for the fill.

          Example:

                  # This has the same effect as the previous example
                  $myImage->rectangle(10,10,100,100,$black);
                  $myImage->fillToBorder(50,50,$black,$blue);


     Image Copying Commands

     Two methods are provided for copying a rectangular region
     from one image to another.  One method copies a region
     without resizing it.  The other allows you to stretch the
     region during the copy operation.

     With either of these methods it is important to know that
     the routines will attempt to flesh out the destination
     image's color table to match the colors that are being
     copied from the source.  If the destination's color table is
     already full, then the routines will attempt to find the
     best match, with varying results.

     copy GD::Image::copy(sourceImage,dstX,dstY,srcX,srcY,width,height)
          [object method]

          This is the simpler of the two copy operations, copying
          the specified region from the source image to the
          destination image (the one performing the method call).
          (srcX,srcY) specify the upper left corner of a
          rectangle in the source image, and (width,height) give
          the width and height of the region to copy.
          (dstX,dstY) control where in the destination image to
          stamp the copy.  You can use the same image for both
          the source and the destination, but the source and
          destination regions must not overlap or strange things
          will happen.

          Example:

                  $myImage = new GD::Image(100,100);
                  ... various drawing stuff ...
                  $srcImage = new GD::Image(50,50);
                  ... more drawing stuff ...
                  # copy a 25x25 pixel region from $srcImage to
                  # the rectangle starting at (10,10) in $myImage
                  $myImage->copy($srcImage,10,10,0,0,25,25);


     copyResized
          GD::Image::copyResized(sourceImage,dstX,dstY,srcX,srcY,destW,destH,srcW,srcH)
           [object method]

          This method is similar to copy() but allows you to
          choose different sizes for the source and destination
          rectangles.  The source and destination rectangle's are
          specified independently by (srcW,srcH) and
          (destW,destH) respectively.  copyResized() will stretch
          or shrink the image to accomodate the size
          requirements.

          Example:

                  $myImage = new GD::Image(100,100);
                  ... various drawing stuff ...
                  $srcImage = new GD::Image(50,50);
                  ... more drawing stuff ...
                  # copy a 25x25 pixel region from $srcImage to
                  # a larger rectangle starting at (10,10) in $myImage
                  $myImage->copyResized($srcImage,10,10,0,0,50,50,25,25);


     Character and String Drawing

     Gd allows you to draw characters and strings, either in
     normal horizontal orientation or rotated 90 degrees.  These
     routines use a GD::Font object, described in more detail
     below.  There are four built-in fonts, available in global
     variables gdLargeFont, gdMediumBoldFont, gdSmallFont and
     gdTinyFont.  Currently there is no way of dynamically
     creating your own fonts.

     string
          GD::Image::string(font,x,y,string,color)  [object method]

          This method draws a string startin at position (x,y) in
          the specified font and color.  Your choices of fonts
          are gdSmallFont, gdMediumBoldFont, gdTinyFont and
          gdLargeFont.

          Example:

                  $myImage->string(gdSmallFont,2,10,"Peachy Keen",$peach);


     stringUp
          GD::Image::stringUp(font,x,y,string,color)  [object method]

          Just like the previous call, but draws the text rotated
          counterclockwise 90 degrees.

     char

     charUp
          GD::Image::char(font,x,y,char,color)  [object method]

          GD::Image::charUp(font,x,y,char,color)  [object method]

          These methods draw single characters at position (x,y)
          in the specified font and color.  They're carry-overs
          from the C interface, where there is a distinction
          between characters and strings.  Perl is insensible to
          such subtle distinctions.

     Miscellaneous Image Methods

     interlaced
          GD::Image::interlaced( ) GD::Image::interlaced(1)
          [object method]

          This method sets or queries the image's interlaced
          setting.  Interlace produces a cool venetian blinds
          effect on certain viewers.  Provide a true parameter to
          set the interlace attribute.  Provide undef to disable
          it.  Call the method without parameters to find out the
          current setting.

     getBounds
          GD::Image::getBounds( )  [object method]

          This method will return a two-member list containing
          the width and height of the image.  You query but not
          change the size of the image once it's created.

     Polygon Methods

     A few primitive polygon creation and manipulation methods
     are provided.  They aren't part of the Gd library, but I
     thought they might be handy to have around (they're borrowed
     from my qd.pl Quickdraw library).

     c
          GD::Polygon::new  [class method]

          Create an empty polygon with no vertices.

                  $poly = new GD::Polygon;


     addPt
          GD::Polygon::addPt(x,y)  [object method]

          Add point (x,y) to the polygon.

                  $poly->addPt(0,0);
                  $poly->addPt(0,50);
                  $poly->addPt(25,25);
                  $myImage->fillPoly($poly,$blue);


     getPt
          GD::Polygon::getPt(index)  [object method]

          Retrieve the point at the specified vertex.

                  ($x,$y) = $poly->getPt(2);


     setPt
          GD::Polygon::setPt(index,x,y)  [object method]

          Change the value of an already existing vertex.  It is
          an error to set a vertex that isn't already defined.

                  $poly->setPt(2,100,100);


     deletePt
          GD::Polygon:deletePt(index)  [object method]

          Delete the specified vertex, returning its value.

                  ($x,$y) = $poly->deletePt(1);


     length
          GD::Polygon::length  [object method]

          Return the number of vertices in the polygon.

                  $points = $poly->length;


     vertices
          GD::Polygon::vertices  [object method]

          Return a list of all the verticies in the polygon
          object.  Each membver of the list is a reference to an
          (x,y) array.

                  @vertices = $poly->vertices;
                  foreach $v (@vertices)
                     print join(",",@$v),"\n";
                  }


     bounds
          GD::Polygon::bounds  [object method]

          Return the smallest rectangle that completely encloses
          the polygon.  The return value is an array containing
          the (left,top,right,bottom) of the rectangle.

                  ($left,$top,$right,$bottom) = $poly->bounds;


     offset
          GD::Polygon::offset(dx,dy)  [object method]

          Offset all the vertices of the polygon by the specified
          horizontal (dh) and vertical (dy) amounts.  Positive
          numbers move the polygon down and to the right.

                  $poly->offset(10,30);


     map  GD::Polygon::map(srcL,srcT,srcR,srcB,destL,dstT,dstR,dstB)
           [object method]

          Map the polygon from a source rectangle to an
          equivalent position in a destination rectangle, moving
          it and resizing it as necessary.  See polys.pl for an
          example of how this works.  Both the source and
          destination rectangles are given in
          (left,top,right,bottom) coordinates.  For convenience,
          you can use the polygon's own bounding box as the
          source rectangle.

                  # Make the polygon really tall
                  $poly->map($poly->bounds,0,0,50,200);


     Font Utilities

     Gd's support for fonts is minimal.  Basically you have
     access to gdSmallFont and gdLargeFont for drawing, and not
     much else.  However, for future compatibility, I've made the
     fonts into perl objects of type GD::Font that you can query
     and, perhaps someday manipulate.

     gdSmallFont
          GD::Font::gdSmallFont[constant

          This is the basic small font, "borrowed" from a well
          known public domain 6x12 font.

     gdLargeFont
          GD::Font::gdLargeFont[constant

          This is the basic large font, "borrowed" from a well
          known public domain 8x16 font.

     gdMediumBoldFont
          GD::Font::gdMediumBoldFont[constant

          This is a bold font intermediate in size between the
          small and large fonts, borrowed from a public domain
          7x13 font;

     gdTinyFont
          GD::Font::gdTinyFont  [constant]

          This is a tiny, almost unreadable font, 5x8 pixels
          wide.

     nchars
          GD::Font::nchars     [object method]

          This returns the number of characters in the font.

                  print "The large font contains ",gdLargeFont->nchars," characters\n";


     offset
          GD::Font::offset     [object method]

          This returns the ASCII value of the first character in
          the font

     width

     height
          GD::Font::width  GD::Font::height    [object methods]

          These return the width and height of the font.

                  ($w,$h) = (gdLargeFont->width,gdLargeFont->height);


Copyright Information
     The GD.pm interface is copyright 1995, Lincoln D. Stein.
     You are free to use it for any purpose, commercial or
     noncommercial, provided that if you redistribute the source
     code this statement of copyright remains attached. The gd
     library is covered separately under a 1994 copyright by
     Quest Protein Database Center, Cold Spring Harbor Labs.  For
     usage information see the gd documentation at URL

             http://www.boutell.com/gd/

     The latest versions of the perl interface are available at

             http://www-genome.wi.mit.edu/ftp/pub/software/WWW/GD.html
             ftp://ftp-genome.wi.mit.edu/pub/software/WWW/GD.pm.tar.Z