SetRGBArray

SetRGBArray
Prev	PHPlot Function Reference	Next

SetRGBArray — Select a color map

Synopsis

$plot->SetRGBArray($color_array)

Description

SetRGBArray selects a color map to use. A color map is an array of color names available for use in the plot. You can select from pre-defined color maps, or define your own. Each color in a color map has a name, and 3 or 4 color component values (red, green, blue, and optional alpha). The red, green, and blue components are in the range 0 through 255, and the optional alpha component is in the range 0 through 127.

Parameters

$color_array

An array or a string. If an array, each element defines a color in the color map. The array element key is the color name, and the array element value is an array of three or four components. (See example below).

Or, a string selecting a built-in color map. Use 'small' to select a map of 36 colors, or 'large' to select a much larger color map.

Notes

If SetRGBArray is not called, the 'small' color map is used.

More information about the color maps can be found in Section 3.5.2, “Built-in Color Maps”. More information about using the alpha component can be found in Section 4.3, “Truecolor Images”.

Color names are case sensitive.

For the large color map to be loaded with SetRGBArray('large'), the file rgb.inc.php must be found on the PHP include path or in the same directory as phplot.php. This file is included in the PHPlot distribution.

You are not limited to using only the colors in the color map. The color map defines which color names you can use, and exactly what they mean. You can also specify colors numerically.

PHPlot resolves a color name to its component values (red, green, blue) at the time the element's color is set, using whatever color map is present at that time. For PHPlot's default colors, this happens when the PHPlot object is created. This means that changes to the color map affect only future color settings. See the Color Resolution example below for more. After using SetRGBArray, you will probably want to define element and data colors with the functions listed in Section 6.3, “Colors and Line Styles”.

Examples

An example of a user-defined color map is:

array( 'black' => array(0, 0, 0),
       'white' => array(255, 255, 255),
       'gray'  => array(190, 190, 190),
       'red'   => array(255, 0, 0),
       'green' => array(0, 255, 0),
       'blue'  => array(0, 0, 255) )

The following example is provided for the note above on color resolution. The main title will be black, the X title will be blue, and the Y title will be green. This is because:

The main title color is defaulted, so it gets defined as black by the PHPlot constructor. The later redefinition of black in the color array has no effect on this title.
The X title color is set to blue, using the default ('small') color map's definition of blue at that time.
The Y title color is green, because a new color map was loaded before the Y title color was set, and that color map defines a color named blue as RGB #00ff00 which is green.

$plot = new PHPlot();
...
$plot->SetXTitleColor('blue');
$plot->SetRGBArray(array('black' => array(255,0,0), 'blue' => array(0, 255, 0)));
$plot->SetYTitleColor('blue');
...

History

Starting with PHPlot-6.0.0, specifying an invalid string for $color_array results in an error message. In older releases, a two color black/white color map would be loaded with no error reported.

Versions of this manual written for releases before PHPlot-6.0.0 incorrectly stated that your color map must include the colors that PHPlot uses as internal defaults (black, white, and gray), and incorrectly implied that you could redefine existing colors (for example, change black to (r=255,g=0,b=0) to make it red) and have that apply to the default element colors. The actual behavior is as described in the note above about color resolution.

Prev	Up	Next
SetPrintImage	Home	SetShading