This section contains information about using colors in PHPlot. Functions described in Section 6.3, “Colors and Line Styles” in the Reference chapter control the use of colors in PHPlot.
This section describes Palette images. Starting with PHPlot-5.1.1, a second color model is available in PHPlot: Truecolor images. Refer to Section 4.3, “Truecolor Images” for more information.
Individual colors as arguments to PHPlot functions can take one of the following forms:
A color name, as defined by SetRGBArray or from a built-in color map if SetRGBArray was not called. Note that color names are case sensitive.
Numeric color component values, in the form
#rrggbb. 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. For example,#0000ffis full-saturation blue.A PHP array of red, green, and blue color component values, each value being in the range 0 to 255 inclusive, for example
array(0,0,255)for blue.
Additional color forms can be found in Section 4.3.4, “Color Parameter Form Extensions”. Those forms are more useful with truecolor images.
Note
You cannot use the (red, green, blue) array form as a color value in those
functions (like SetDataColors) which accept either a
single color or an array of colors. The functions are unable to distinguish
between an array of colors and a single color represented as an array.
However, you can work around this restriction by using an array containing
the array with the colors, for example:
array(array(102, 0, 192)).
There are 36 colors defined in the 'small' internal color map. This is the set of color names which are available by default, unless SetRGBArray is used to load in a different color map. The colors and their names are shown in the figure below.
Here are the color names again.
| DarkGreen | DimGrey | PeachPuff | SkyBlue | SlateBlue | YellowGreen |
| aquamarine1 | azure1 | beige | black | blue | brown |
| cyan | gold | gray | green | grey | ivory |
| lavender | magenta | maroon | navy | orange | orchid |
| peru | pink | plum | purple | red | salmon |
| snow | tan | violet | wheat | white | yellow |
The color names and values in the 'small' internal color map are selected from the X11 RGB Color Database. If you use SetRGBArray to pick the 'large' color map, PHPlot loads a much larger list of colors equivalent to the entire X11 RGB Color Database. Note that there are some duplicate colors in the maps, as they include alternate spellings (like 'gray' and 'grey').
Note
You are not limited to only using colors from the color map. The color map contains a list of color names that PHPlot can translate into color values, but you can use any color at all by specifying the color value using one of the numeric representations described above.
Each data set plotted on a graph uses the next color in the Data Colors list. By default, the Data Colors list contains the following 16 colors in order.
| Data Set: | Color Name: | Color Sample: |
|---|---|---|
| 1 | SkyBlue | |
| 2 | green | |
| 3 | orange | |
| 4 | blue | |
| 5 | red | |
| 6 | DarkGreen | |
| 7 | purple | |
| 8 | peru | |
| 9 | cyan | |
| 10 | salmon | |
| 11 | SlateBlue | |
| 12 | YellowGreen | |
| 13 | magenta | |
| 14 | aquamarine1 | |
| 15 | gold | |
| 16 | violet |
An additional color list is used with error plots. These have data type
data-data-error or data-data-yx-error
(see Section 3.3.1, “Available Data Types”).
The positive and negative error bars use a color map that is set using
SetErrorBarColors. By default, this color list contains
the same colors as the data color list, so each data set and its error bars
will be in the same color. If you change the data colors list with
SetDataColors, you probably want to change the error bar
color list too, so you get the same colors for data sets and their error bars.
Some plot types support data borders, which are outlines around filled areas.
This includes the bars and squaredarea
plot types, for example.
Use SetDrawDataBorders to enable or disable drawing of
data borders.
The colors used for data borders can be set with
SetDataBorderColors.
By default, a black data border is used for all data sets, if borders are
enabled.
Note: PHPlot through version 5.0.7 used 8 colors in the default Data Colors list: SkyBlue, green, orange, blue, orange, red, violet, and azure1. If plotting more than four data sets with PHPlot-5.0.7 or earlier, you should use SetDataColors to define your own data colors list. Otherwise you will get two data sets plotted in the same color, orange.
Instead of using sequential data colors for plotted data sets, you can control exactly which data color is used for each data value using the data color callback. For more information, see Section 4.5, “Custom Data Color Selection”.
Some plot types which only support a single data set still use multiple data colors, but in a way that is specific to that plot type. This is described for each applicable plot type in Section 3.4, “PHPlot Plot Types”. For example, the 3 OHLC financial plot types use the first 4 data colors for different parts of the marker at each data point, as well as to indicate the overall direction (up or down). You can use the same methods - SetDataColors or a data color callback - to change colors for these plot types.
You can designate one color in the color map to be transparent. This is most often used to make a plot with a transparent background. Use SetTransparentColor to designate the color, and SetBackgroundColor to use that color for the background. Use a color which is not otherwise used in the plot.
For transparency to work, the output format (see SetFileFormat) must support transparency, and the the user's viewer or browser also must support transparency. If transparency is not supported, the user will see the actual color which was designated as transparent (so don't use red, for example). Most viewers support transparency in GIF format, and newer viewers should support transparency in PNG format. JPEG format does not support transparency.
The following table shows the function(s) used to set the color of each element on a plot, and the default color if no functions are used to change it. Where multiple function names are shown, they are listed from highest to lowest priority. (That is, if the first function is not used, the color is set with the second function, etc.)
| Plot element: | Function(s) used to set color: | Default color: |
|---|---|---|
| Data borders | SetDataBorderColors | black |
| Data elements (points, lines, area fill, etc.) | SetDataColors | See Section 3.5.3, “Plotting Colors” |
| Data value labels | SetDataValueLabelColor, SetDataLabelColor, SetTextColor | black |
| Error bars | SetErrorBarColors | Same as data colors. See Section 3.5.3, “Plotting Colors” |
| Image background | SetBackgroundColor | white |
| Image border | SetImageBorderColor | #c2c2c2 gray |
| Legend background | SetLegendBgColor, SetBackgroundColor | white |
| Legend color box fill or shape marker | SetDataColors | N/A |
| Legend color box borders | SetTextColor or SetDataBorderColors (see notes) | black |
| Legend border | SetGridColor | black |
| Legend text | SetLegendTextColor, SetTextColor | black |
| Main title | SetTitleColor | black |
| Pie chart data labels | SetPieLabelColor, SetGridColor | black |
| Pie segment borders | SetPieBorderColor, SetGridColor | black |
| Pie segment fill | SetDataColors | N/A |
| Plot area background | SetPlotBgColor | white, but disabled by default |
| Plot border | SetGridColor | black |
| X axis line | SetGridColor | black |
| X axis data labels | SetDataLabelColor, SetTextColor | black |
| X data label lines | SetLightGridColor | gray |
| X grid lines | SetLightGridColor | gray |
| X tick labels | SetTickLabelColor, SetTextColor | black |
| X tick marks | SetTickColor | black |
| X title | SetXTitleColor, SetTitleColor | black |
| Y axis lines | SetGridColor | black |
| Y axis data labels | SetDataLabelColor, SetTextColor | black |
| Y data label lines | SetLightGridColor | gray |
| Y grid lines | SetLightGridColor | gray |
| Y tick labels | SetTickLabelColor, SetTextColor | black |
| Y tick marks | SetTickColor | black |
| Y title | SetYTitleColor, SetTitleColor | black |
The following notes apply to the table of plot element colors above:
Data borders refers to the borders, or outlines, around bars in a
barsorstackedbarsplot. Data borders are also available with thearea,squaredarea,stackedarea, andstackedsquaredareaplot types.SetPieBorderColor was added in PHPlot-6.0.0. In prior releases, pie segment borders (which were available only on unshaded pie charts) used the color set with SetGridColor. The new function is backwards compatible, as the borders default to the grid color if
SetPieBorderColoris not used.SetDataLabelColor, SetDataValueLabelColor, SetPieLabelColor, and SetTickLabelColor were added in PHPlot-5.7.0. Through PHPlot-5.6.0:
Tick labels and axis data labels all used the color set with SetTextColor.
Data value labels (incorrectly) used the title color set with SetTitleColor.
Pie chart labels used the grid color set with SetGridColor.
Except for data value labels, the defaults are backwards compatible. That is, if you use
SetGridColor()and do not use the newSetPieLabelColor(), your pie chart labels will display in the same color with all releases.The legend background uses the overall image background color set with SetBackgroundColor by default. Starting with PHPlot-6.0.0, you can set the legend background color separately with SetLegendBgColor.
The legend color box borders use the color set with SetTextColor by default. Starting with PHPlot-6.0.0, you can use the colors set with SetDataBorderColors instead. See SetLegendColorboxBorders.
Legend text uses the general text color set with SetTextColor by default. Starting with PHPlot-6.0.0, you can set the legend text color separately with SetLegendTextColor.