Creating and Drawing Images (Programming PHP)

9.4. Creating and Drawing Images

For now, let's start with the simplest possible GD example. Example 9-1 is a script that generates a black filled square. The code works with any version of GD that supports the PNG image format.

Example 9-1. A black square on a white background (black.php)

<?php
 $im = ImageCreate(200,200);
 $white = ImageColorAllocate($im,0xFF,0xFF,0xFF);
 $black = ImageColorAllocate($im,0x00,0x00,0x00);
 ImageFilledRectangle($im,50,50,150,150,$black);
 header('Content-Type: image/png');
 ImagePNG($im);
?>

Example 9-1 illustrates the basic steps in generating any image: creating the image, allocating colors, drawing the image, and then saving or sending the image. Figure 9-1 shows the output of Example 9-1.

Figure 9-1. A black square on a white background

To see the result, simply point your browser at the black.php PHP page. To embed this image in a web page, use:

<img src="black.php">

9.4.1. The Structure of a Graphics Program

Most dynamic image-generation programs follow the same basic steps outlined in Example 9-1.

You can create a 256-color image with the ImageCreate( ) function, which returns an image handle:

$image = ImageCreate(width, height);

All colors used in an image must be allocated with the ImageColorAllocate( ) function. The first color allocated becomes the background color for the image.[4]

[4]This is true only for images with a color palette. True color images created using ImageCreateTrueColor( ) do not obey this rule.

$color = ImageColorAllocate(image, red, green, blue);

The arguments are the numeric RGB (red, green, blue) components of the color. In Example 9-1, we wrote the color values in hexadecimal, to bring the function call closer to the HTML color representation "#FFFFFF" and "#000000".

There are many drawing primitives in GD. Example 9-1 uses ImageFilledRectangle( ), in which you specify the dimensions of the rectangle by passing the coordinates of the top-left and bottom-right corners:

ImageFilledRectangle(image, tlx, tly, brx, bry, color);

The next step is to send a Content-Type header to the browser with the appropriate content type for the kind of image being created. Once that is done, we call the appropriate output function. The ImageJPEG( ) , ImagePNG( ), and ImageWBMP( ) functions create JPEG, PNG, and WBMP files from the image, respectively:

ImageJPEG(image [, filename [, quality ]]);
ImagePNG(image [, filename ]);
ImageWBMP(image [, filename ]);

If no filename is given, the image is sent to the browser. The quality argument for JPEGs is a number from 0 (worst-looking) to 10 (best-looking). The lower the quality, the smaller the JPEG file. The default setting is 7.5.

In Example 9-1, we set the HTTP header immediately before calling the output-generating function ImagePNG( ). If, instead, you set the Content-Type at the very start of the script, any errors that are generated are treated as image data and the browser displays a broken image icon. Table 9-1 lists the image formats and their Content-Type values.

Table 9-1. Content-Type values for image formats

Format	Content-Type
GIF	image/gif
JPEG	image/jpeg
PNG	image/png
WBMP	image/vnd.wap.wbmp

9.4.2. Changing the Output Format

As you may have deduced, generating an image stream of a different type requires only two changes to the script: send a different Content-Type and use a different image-generating function. Example 9-2 shows Example 9-1 modified to generate a JPEG instead of a PNG image.

Example 9-2. JPEG version of the black square

<?php
 $im = ImageCreate(200,200);
 $white = ImageColorAllocate($im,0xFF,0xFF,0xFF);
 $black = ImageColorAllocate($im,0x00,0x00,0x00);
 ImageFilledRectangle($im,50,50,150,150,$black);
 header('Content-Type: image/jpeg');
 ImageJPEG($im);
?>

9.4.3. Testing for Supported Image Formats

If you are writing code that must be portable across systems that may support different image formats, use the ImageTypes( ) function to check which image types are supported. This function returns a bitfield; you can use the bitwise AND operator (&) to check if a given bit is set. The constants IMG_GIF, IMG_JPG, IMG_PNG, and IMG_WBMP correspond to the bits for those image formats.

Example 9-3 generates PNG files if PNG is supported, JPEG files if PNG is not supported, and GIF files if neither PNG nor JPEG are supported.

Example 9-3. Checking for image format support

<?php
 $im = ImageCreate(200,200);
 $white = ImageColorAllocate($im,0xFF,0xFF,0xFF);
 $black = ImageColorAllocate($im,0x00,0x00,0x00);
 ImageFilledRectangle($im,50,50,150,150,$black);
 if (ImageTypes( ) & IMG_PNG) {
   header("Content-Type: image/png");
   ImagePNG($im);
 } elseif (ImageTypes( ) & IMG_JPG) {
   header("Content-Type: image/jpeg");
   ImageJPEG($im);
 } elseif (ImageTypes( ) & IMG_GIF) {
   header("Content-Type: image/gif");
   ImageGIF($im);
 }
?>

9.4.4. Reading an Existing File

If you want to start with an existing image and then modify it, use either ImageCreateFromJPEG( ) or ImageCreateFromPNG( ):

$image = ImageCreateFromJPEG(filename);
$image = ImageCreateFromPNG(filename);

9.4.5. Basic Drawing Functions

GD has functions for drawing basic points, lines, arcs, rectangles, and polygons. This section describes the base functions supported by GD 1.x.

The most basic function is ImageSetPixel( ) , which sets the color of a specified pixel:

ImageSetPixel(image, x, y, color);

There are two functions for drawing lines, ImageLine( ) and ImageDashedLine( ):

ImageLine(image, start_x, start_ y, end_x, end_ y, color);
ImageDashedLine(image, start_x, start_ y, end_x, end_ y, color);

There are two functions for drawing rectangles, one that simply draws the outline and one that fills the rectangle with the specified color:

ImageRectangle(image, tlx, tly, brx, bry, color);
ImageFilledRectangle(image, tlx, tly, brx, bry, color);

Specify the location and size of the rectangle by passing the coordinates of the top-left and bottom-right corners.

You can draw arbitrary polygons with the ImagePolygon( ) and ImageFilledPolygon( ) functions:

ImagePolygon(image, points, number, color);
ImageFilledPolygon(image, points, number, color);

Both functions take an array of points. This array has two integers (the x and y coordinates) for each vertex on the polygon. The number argument is the number of vertices in the array (typically count($points)/2).

The ImageArc( ) function draws an arc (a portion of an ellipse):

ImageArc(image, center_x, center_ y, width, height, start, end, color);

The ellipse is defined by its center, width, and height (height and width are the same for a circle). The start and end points of the arc are given as degrees counting counterclockwise from 3 o'clock. Draw the full ellipse with a start of 0 and an end of 360.

There are two ways to fill in already-drawn shapes. The ImageFill( ) function performs a flood fill, changing the color of the pixels starting at the given location. Any change in pixel color marks the limits of the fill. The ImageFillToBorder( ) function lets you pass the particular color of the limits of the fill:

ImageFill(image, x, y, color);
ImageFillToBorder(image, x, y, border_color, color);