4.2. Truecolor Images
Prev | Chapter 4. PHPlot Advanced Topics | Next

## 4.2. Truecolor Images

This section contains information about using Truecolor images in PHPlot. This material supplements the text in the Section 3.5, “Colors”.

Truecolor image support was added to PHPlot-5.1.1. With Truecolor image support, you can:

- Create images with a larger number of colors

- Control color transparency with alpha blending

- Perform advanced image processing operations

An example of using Truecolor with PHPlot can be found in Section 5.24, “Example - Using Truecolor To Make a Histogram”.

### 4.2.1. Using Truecolor Images in PHPlot

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.2.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.

### 4.2.2. Understanding Variable Transparency (Alpha)

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.[2] 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."[3]

### Note

Note that the PHP Manual says the resulting pixel is opaque. This means that objects drawn with alpha above 0 are partially or completely transparent only relative to other objects in that same image. This does not result in an image with transparent portions which would show through to a browser or desktop background, for example. (Read the PHP Manual page for `imagesavealpha` for more about this behavior and how to change it.) Use SetTransparentColor to make portions of an image transparent to web page or desktop backgrounds.

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.

### 4.2.3. Using Variable Transparency (Alpha) in PHPlot

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.2.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);

### 4.2.4. Color Parameter Form Extensions

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.

1. A color name, as defined by SetRGBArray or from a built-in color map if SetRGBArray was not called, followed by a colon and an alpha value as a decimal number, for example: 'red:60'. The alpha value is between 0 (opaque) and 127 (transparent). Note that colors in the color map can be defined with or without an alpha value. An alpha value appended to the color name overrides any specified in the color map. For example, if the color 'red2' is defined in the color map as array(255,0,0,80) - that is, red with 80/127 transparency - then 'red2' has alpha of 80, and 'red2:40' has alpha of 40.

2. Numeric color component values, in the form `#rrggbbaa`. Here rr is red, gg is green, and bb is blue, and each component value is represented as a 2-digit hexadecimal number between 00 and ff. Also aa is alpha, represented as a 2 digit hexadecimal number between 00 and 7f. For example, `#00ff0010` is green with 16/127 transparency.

3. A PHP array of red, green, blue, and alpha color component values. Each value of red, green, and blue are in the range 0 to 255 inclusive, and the alpha component is in the range 0 to 127 inclusive. For example, `array(0,255,0,16)` is the same green with 16/127 transparency.

### 4.2.5. Image Formats and File Formats, Palette and Truecolor

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.2.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.2.9, “Palette Images and Advanced Color Features” below.

### 4.2.6. Truecolor Images and Plot Types

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

Pie Charts

  Avoid using alpha blending with pie charts. The underlying GD routines do not fill the pie areas in a way that allows proper blending of colors. Flat pie charts (using SetShading(0)) are not too bad, showing some artifacts, but shaded or 3D-look pie charts are poorly rendered.

Bar Charts, Stacked Bar Charts

  Bars are drawn properly, but the 3D shading affects get blended, resulting in less than ideal appearance. Flat, outlined bars (using SetShading(0)) are fine with transparency, but when shading is on the 3D shadows overlap portions of the bars. With alpha blending, the overlaps take on new colors.

### 4.2.7. Background Images

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.)

### Note

The above applies only when an input file is specified to the PHPlot or PHPlot_truecolor constructor. It does not apply to an image background set with SetBgImage nor to a plot area background set with SetPlotAreaBgImage.

### 4.2.8. Additional Operations on Truecolor Images Using Callbacks

Advanced operations on truecolor PHPlot images are possible using PHPlot callbacks. See Section 4.3, “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.

### Note

Some of these functions are only available when PHP was built with the bundled version of the GD library.

#### 4.2.8.1. imageantialias()

You can turn on anti-aliasing of truecolor images. This must be done before anything is drawn, so the pre-drawing callback `draw_setup` is used. Here is a partial example:

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

Note: There are limitations with anti-aliased images. You cannot use wide lines (SetLineWidths). Patterned lines do not work, so if you are displaying X or Y grid lines you must use SetDrawDashedGrid(False) to make these solid. Also note that TrueType Font (TTF) text is always anti-aliased, even on palette images, regardless of the use of `imageantialias()`.

#### 4.2.8.2. imagealphablending() and imagelayereffect()

These functions control the combining of partially transparent colors. They can be used via a `draw_setup` callback, in the same way as `imageantialias` in the example above. Note that alpha blending is on by default with all truecolor images.

#### 4.2.8.3. imagegammacorrect()

You can have the GD library perform gamma adjustment on a truecolor image. This must be done after all drawing, so the post-drawing callback `draw_all` is used. Here is a partial example:

    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');

### 4.2.9. Palette Images and Advanced Color Features

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:

- There is no alpha blending. Drawing operations simply replace existing pixels values with the new pixel values. (These are actually index values into the color table.)

- Alpha values are ignored when the image is output to a JPEG or GIF file. All colors are output as opaque.

- Alpha values are preserved in PNG image files. These will be palette, not truecolor, PNG images, with the color table containing the alpha values. You can therefore have palette PNG files with partial transparency, however not all viewers properly support this.

Nothing described in Section 4.2.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.)

[2] PHPlot follows the GD Library convention here. Other systems use alpha=0 to mean transparent, and a maximum alpha value to mean opaque.

[3] From the PHP Reference Manual, imagealphablending

Prev | Up | Next
Chapter 4. PHPlot Advanced Topics | Home | 4.3. Callbacks