Introduction

In a previous article on GD, I gave an introduction to the library and suggested some possible real-world applications. In this tutorial, I will provide some basic examples of what can be achieved with GD. I will begin by discussing how to define colors in GD, and then provide some examples of using these colors with some of GDs shape drawing functions.

In order to use the examples in this tutorial, you will need to have a PHP enabled web server with GD support included. Please refer to my detailed tutorial on Building a PHP 5 Web Server on Windows IIS, which includes a discussion on how to set up GD on such a server.

Defining colors in GD

In order to define a color in GD, we need to use the ImageCreatTrueColor() function (note that function names are not case-sensitive for GD, just like any other PHP function). We need to provide this function with a reference pointer to the image where we want to use this color (i.e. the current image we are working on). We also need to provide the function with the RGB (Red Green Blue) values for the new color: remember RGB values for each color range from 0-255, so (255,255,255) is white, and (0,0,0) is black, with millions of colors in between.

In the example below, we will create a new image, set its background color to red, and output this graphic to the browser as a PNG image:

<?php
 
// example1.php
 
// set the HTTP header type to PNG
header("Content-type: image/png"); 
 
// set the width and height of the new image in pixels
$width = 350;
$height = 360;
 
// create a pointer to a new true colour image
$im = ImageCreateTrueColor($width, $height); 
 
// sets background to red
$red = ImageColorAllocate($im, 255, 0, 0); 
ImageFillToBorder($im, 0, 0, $red, $red);
 
// send the new PNG image to the browser
ImagePNG($im); 
 
// destroy the reference pointer to the image in memory to free up resources
ImageDestroy($im); 
 
?>

View Example 1

There are a number of important points to make about this code. Firstly, the PHP header function is required to set the correct HTTP header type for the output of this script, so that the web browser will treat the output as an image file, in this case a PNG graphic. As you can see from this demonstration, even though the file is a .php file, the browser still treats it as if it were a .png!

The pointer to the image resource $im should always be destroyed using the ImageDestroy function, in order to prevent the image remaining in the memory of the web server after the script has finished, which would use up valuable resources.

Now that we know how to set up a GD image, we will explore some of the libraries more interesting functions for drawing primitive shapes and polygons.

Drawing lines

<?php
 
// example2.php
 
// set the HTTP header type to PNG
header("Content-type: image/png"); 
 
// set the width and height of the new image in pixels
$width = 350;
$height = 360;
 
// create a pointer to a new true colour image
$im = ImageCreateTrueColor($width, $height); 
 
// switch on image antializing if it is available
ImageAntiAlias($im, true);
 
// sets background to white
$white = ImageColorAllocate($im, 255, 255, 255); 
ImageFillToBorder($im, 0, 0, $white, $white);
 
// define a black color
$black = ImageColorAllocate($im, 0, 0, 0);
 
// make a new line and add it to the image
ImageLine($im, 10, 10, 250, 300, $black);
 
// add another line, this time a dashed line!
ImageDashedLine($im, 30, 10, 280, 300, $black);
 
// send the new PNG image to the browser
ImagePNG($im); 
 
// destroy the reference pointer to the image in memory to free up resources
ImageDestroy($im); 
 
?>

View Example 2

In Example 2 above, we introduce three new functions highlighted in red. The ImageAntiAlias function is used to switch on antializing in the graphic that GD produces, provided it is supported. If you come from a graphic design background, then you most-likely know what antializing is, but if not don't worry about the technical details of how it works: it simply makes your graphics look sharper and smoothens out jagged edges in geometry, therefore I would suggest using antializing if it is available on your server.

The ImageLine function is used to draw a new line in the image. Apart from requiring the image resource and colour in its parameter list, it also requires the coordinates of the start and end points of the line in the following order: start x, start y, end x, end y. The ImageDashedLine works the same way, except that as the name implies it draws a dashed line.

Drawing rectangles

<?php
 
// example3.php
 
// set the HTTP header type to PNG
header("Content-type: image/png"); 
 
// set the width and height of the new image in pixels
$width = 350;
$height = 360;
 
// create a pointer to a new true color image
$im = ImageCreateTrueColor($width, $height); 
 
// switch on image antializing if it is available
ImageAntiAlias($im, true);
 
// sets background to white
$white = ImageColorAllocate($im, 255, 255, 255); 
ImageFillToBorder($im, 0, 0, $white, $white);
 
// define black and blue colors
$black = ImageColorAllocate($im, 0, 0, 0);
$blue = ImageColorAllocate($im, 0, 0, 255);
 
// define the dimensions of our rectangle
$r_width = 150;
$r_height = 100;
$r_x = 100;
$r_y = 50;
 
ImageRectangle($im, $r_x, $r_y, $r_x+$r_width, $r_y+$r_height, $black);
 
// define the dimensions of our filled rectangle
$r_width = 150;
$r_height = 100;
$r_x = 100;
$r_y = 200;
 
ImageFilledRectangle($im, $r_x, $r_y, $r_x+$r_width, $r_y+$r_height, $blue);
 
// send the new PNG image to the browser
ImagePNG($im); 
 
// destroy the reference pointer to the image in memory to free up resources
ImageDestroy($im); 
 
?>

View Example 3

In the above example, I use two rectangle functions: ImageRectangle that draws an empty rectangle in the color specified; and ImageFilledRectangle which draws a rectangle filled with the color specified. For both functions, the parameters are identical: ImageRectangle( image, start x, start y, end x, end y, colour).

In the code above, I specified the width and the height of the rectangle in the variables:

$r_width = 150;
$r_height = 100;
$r_x = 100;
$r_y = 50;

The end x value is then the start x value plus the desired width of the rectangle, i.e. $r_x+$r_width, and the desired height is achieved in a similar manner. This allows us to think of drawing a rectangle in terms of x, y, width, height etc., in a similar way to how SVG rectangles are treated.

Circle and ellipse

<?php
 
// example4.php
 
// set the HTTP header type to PNG
header("Content-type: image/png"); 
 
// set the width and height of the new image in pixels
$width = 350;
$height = 360;
 
// create a pointer to a new true color image
$im = ImageCreateTrueColor($width, $height); 
 
// switch on image antializing if it is available
ImageAntiAlias($im, true);
 
// sets background to white
$white = ImageColorAllocate($im, 255, 255, 255); 
ImageFillToBorder($im, 0, 0, $white, $white);
 
// define black and blue colors
$black = ImageColorAllocate($im, 0, 0, 0);
$blue = ImageColorAllocate($im, 0, 0, 255);
 
// draw an empty circle
ImageEllipse($im, 180, 100, 100, 100, $black);
 
// draw a filled ellipse
ImageFilledEllipse($im, 180, 220, 150, 50, $blue);
 
// send the new PNG image to the browser
ImagePNG($im); 
 
// destroy the reference pointer to the image in memory to free up resources
ImageDestroy($im); 
 
?>

View Example 4

To draw a circle or an ellipse, we use the same ImageEllipse function. The parameters provided to this function are: image resource, center x, center y, width, height, color. As you can see from the above example, all you need to do to draw a circle rather than an ellipse is to set the width and height to the same value.

Polygon example

<?php
 
// example5.php
 
// set the HTTP header type to PNG
header("Content-type: image/png"); 
 
// set the width and height of the new image in pixels
$width = 350;
$height = 360;
 
// create a pointer to a new true color image
$im = ImageCreateTrueColor($width, $height);
 
// switch on image antializing if it is available
ImageAntiAlias($im, true);
 
// sets background to white
$white = ImageColorAllocate($im, 255, 255, 255); 
ImageFillToBorder($im, 0, 0, $white, $white);
 
// define black and blue colors
$black = ImageColorAllocate($im, 0, 0, 0);
$blue = ImageColorAllocate($im, 0, 0, 255);
 
 
function drawDiamond($x, $y, $width, $color, $filled) {
    // access the global image reference (the one outside this function)
    global $im;
 
    // here we work out the four points of the diamond
    $p1_x = $x;
    $p1_y = $y+($width/2);
 
    $p2_x = $x+($width/2);
    $p2_y = $y;
 
    $p3_x = $x+$width;
    $p3_y = $y+($width/2);
 
    $p4_x = $x+($width/2);
    $p4_y = $y+$width;
 
    // now create an array of points to store these four points
    $points = array($p1_x, $p1_y, $p2_x, $p2_y, $p3_x, $p3_y, $p4_x, $p4_y);
 
    // the number of vertices for our polygon (four as it is a diamond
    $num_of_points = 4;
 
    if ($filled) {
        // now draw out the filled polygon
        ImageFilledPolygon($im, $points, $num_of_points, $color);
    }else{
        // draw out an empty polygon
        ImagePolygon($im, $points, $num_of_points, $color);
    }
}
 
// now draw the two diamonds
drawDiamond(120, 50, 100, $black, false);
drawDiamond(120, 200, 100, $blue, true);
 
// send the new PNG image to the browser
ImagePNG($im); 
 
// destroy the reference pointer to the image in memory to free up resources
ImageDestroy($im); 
 
?>

View Example 5

I will leave you with this moderately complex polygon example to work out for yourself. As yon can see, it is quite trivial to define your own shapes to be created using GD, even complex polygon and composite shapes. The trick is to encapsulate all of the code for your custom shape inside a PHP function, like the drawDiamond function above.

Conclusion

GD provides a rich set of functions beyond those discussed in this introductory tutorial. For a complete list of these functions, I will refer you to the PHP manual. The GD library is widely used online for producing various kinds of bar and pie charts for presenting statistics, but it is not limited to this usage.

With a bit of imagination, GD can be used in far more interesting ways. I plan to continue our discussion of GD by presented such techniques in the months to come.

---

Updated 2021 : note that the above post is out-of-date, given this post was originally published in 2004, but is left here for archival purposes.