To make a Truecolor image in PHPlot, create an object of the derived class PHPlot_truecolor instead of the class PHPlot. For example, replace this:

$plot = new PHPlot(800, 600);

with this:

$plot = new PHPlot_truecolor(800, 600);

That is all you need to do in order to create truecolor images. All PHPlot methods are compatible with PHPlot_truecolor objects. An image file produced from a PHPlot_truecolor object with no other programming changes will be the same as an image file produced from a PHPlot object except as described under Section 4.3.5, “Image Formats and File Formats, Palette and Truecolor”.

One of the advantages of truecolor images is the ability to use variable transparency. This is described in the next two sections.

Colors in a truecolor image have four components: red, green, blue, and alpha. The alpha component corresponds to the transparency of a color. An alpha value of zero means the color is opaque, and an alpha value of 127 means the color is transparent, or clear.^[4] In between values, from 1 to 126, correspond to various amounts of transparency.

Transparency is only meaningful when drawing objects on top of objects, or objects on top of the image background. An object drawn with an opaque color (alpha=0) will replace whatever was in the image before the object was drawn at that position. An object drawn with an transparent color (alpha=127) is invisible and does not affect the appearance of the image. An object drawn with a color that has an alpha value between 1 and 126 will be combined with whatever was in the image before the object was drawn using alpha blending.

The PHP Manual explains alpha blending like this: "In blending mode, the alpha channel component of the color supplied to all drawing functions determines how much of the underlying color should be allowed to shine through. As a result, gd automatically blends the existing color at that point with the drawing color, and stores the result in the image. The resulting pixel is opaque."^[5]

The following figure shows the effect of alpha blending when drawing lines. The left side shows the normal overlaying of lines, and the right side shows alpha-blended overlaying of lines with alpha = 60 (that is, 60/127 transparency). The effect of alpha blending can be seen where the data lines cross. Note: These plots use wide lines (3 pixels) and the portions of the images are magnified 2x to show detail.

To use partially transparent colors (that is, colors with an alpha channel) with a PHPlot_truecolor object, you can specify an alpha value as part of a color specification, and you can specify a default alpha value for all data colors.

Use of alpha values with a color specification is described below, in Section 4.3.4, “Color Parameter Form Extensions”. Here are some examples of using colors with an alpha specification.

This sets the color used for labels to red=192, green=192, blue=33, and alpha=50 (that is, 50/127 transparency).

$plot->SetTextColor(array(192, 192, 33, 50));

This sets the color used for tick marks to the color 'blue' from the color map, with alpha value 64 (64/127 transparency).

$plot->SetTickColor('blue:64');

This sets colors for the first three data sets to red, green, and blue with different alpha values. The three colors are represented using different formats for illustration purposes.

$plot->SetDataColors(array(
      array(255, 0, 0, 60), // Red with alpha=60
      '#00ff0050',          // Green with alpha=80 (0x50)
      'blue:70'));          // Blue with alpha=70

Instead of specifying the alpha value for each data set color, you can provide a default alpha value for all data colors using the third argument to This uses the colors specified in $my_color_array with a default alpha of 50. The default is applied to any color definition which does not already have an alpha value. SetDataColors.

$plot->SetDataColors($my_color_array, NULL, 50);

This can also be used to apply an alpha value to the default data colors. This retains the default data colors, but applies alpha = 50 (50/127 transparency) to all the colors. This is a quick way to get partially transparent data colors without re-specifying all the colors.

$plot->SetDataColors(NULL, NULL, 50);

In addition to the forms specified in Section 3.5.1, “Color Parameter Forms”, colors specifications can include an alpha value. Although this works with palette images as well as truecolor images, specifying alpha values with palette images provides limited value.

PHPlot can produce JPEG, PNG, and GIF image files (and possibly others). You select the PHPlot output image file format with SetFileFormat.

PHPlot works with GD images before producing an image file. There are two types of GD images: truecolor and palette. Truecolor images represent pixels as 32 bit values, combining 8 bits each of red, green, and blue components with a 7 bit alpha (transparency) value. Palette images use a color table with at most 256 entries, and represent pixels as 8 bit indexes into the color table. The palette image color table entries have 32 bit values, with the same components as truecolor image pixel values. So palette images in GD can have at most 256 unique colors, but there is no limitation on the number of unique colors in truecolor images.

As long as you don't specify a background image when creating your plot object, truecolor images are created with the PHPlot_truecolor class, and palette images are created with the PHPlot class. If you specify a background image, the GD image created by PHPlot matches the type - truecolor or palette - of your background image file. More on background image files can be found in Section 4.3.7, “Background Images” below.

What happens when you output the GD image to an image file depends on the image file format you select.

JPEG image files are always truecolor. Whether you have a GD palette image or truecolor image, you will get a truecolor image file. Note: You are discouraged from using JPEG images with PHPlot, because they are not optimal for this type of graphical information due to use of lossy compression.

GIF image files are always palette type, limited to 256 colors. If you have a GD palette image, you will get a palette GIF image file with the colors you used in your plot. If you have a a GD truecolor image, GD will convert your image to palette format, reducing the number of colors to 256 if necessary. This may change the appearance of your plot. Note that some versions of the PHP manual for imagecreatetruecolor() incorrectly state that you cannot output a GIF file from a truecolor GD image.

PNG image files support truecolor images and palette images of various color depths. If you have a GD palette image, you will get a palette PNG image file. If you have a GD truecolor image, you will get a truecolor PNG image file. Note that by default, even though PNG truecolor image files support an alpha channel, GD eliminates the alpha channel when producing a PNG file. The visual effects of alpha blending are reproduced using opaque colors. GD apparently does this due to poor support in viewers for alpha channels. Refer to the PHP Manual page on imagesavealpha() for details.

The following figure shows the relationship between constructor, background image format, GD image type, and image file format.

In the initial release of Truecolor support in PHPlot-5.1.1, alpha channel information was ignored when using a PHPlot object, and only used with a PHPlot_truecolor object. This was changed in PHPlot-5.1.2, and alpha channel information is used for both PHPlot and PHPlot_truecolor classes. However, alpha channel information is not always useful with palette images. More on this can be found in Section 4.3.9, “Palette Images and Advanced Color Features” below.

All PHPlot plot types work with truecolor images, but not all plot types work well with alpha blending of data colors.

When creating a PHPlot or PHPlot_truecolor object, you can provide an existing image filename to the constructor as the fourth argument, $input_file.

$plot = new PHPlot(800, 600, NULL, 'myimage.png');

This image file becomes the background for your plot. (The function SetInputFile also does this, but is deprecated for use except through the constructor.)

If you provide an input file to the constructor, the image associated with your PHPlot or PHPlot_truecolor object takes on the type of the input file: palette or truecolor. It does not matter which constructor you use when specifying an input file as background. (This was changed after the initial release of truecolor support. In PHPlot-5.1.1, you must use the PHPlot_truecolor constructor in order to use some truecolor features even when you use a truecolor background image file. Starting with PHPlot-5.1.2 you can use either constructor.)

Advanced operations on truecolor PHPlot images are possible using PHPlot callbacks. See Section 4.4, “Callbacks” for more information about using callbacks. Here are some of the operations you can perform, and the corresponding GD functions. Refer to the GD section of the PHP Manual for more information on these functions.

function pre_plot($img)
{
    imageantialias($img, True);
}
...
$plot = new PHPlot_truecolor(1024, 768);
$plot->SetCallback('draw_setup', 'pre_plot');

function post_plot($img)
{
    imagegammacorrect($img, 1.0, 0.5); // Input gamma=1, output gamma=.5
}

...
$plot = new PHPlot_truecolor(1024, 768);
$plot->SetCallback('draw_all', 'post_plot');

You will have a GD palette image if you use the PHPlot constructor without a background image file, or if you use either the PHPlot or PHPlot_truecolor constructors with a background image file that is a palette image (GIF or some types of PNG). You can use alpha color specifications with palette GD images, but this is not recommended. The results are not well documented, but the following behavior has been observed:

Nothing described in Section 4.3.8, “Additional Operations on Truecolor Images Using Callbacks” works with palette images, including gamma adjust and anti-aliasing (except that TrueType Font text is always anti-aliased.)