Setting Color
Prev | Chapter 3. Advanced Use of PLplot | Next

## Setting Color

Normally, color is used for all drivers and devices that support it within PLplot subject to the condition that the user has the option of globally turning off the color (and subsequently turning it on again if so desired) using `plscolor`.

The PLplot color model allows the user to set the current color from a wide range of colors using two distinct color maps. Color map0 (called cmap0 and discussed in the section called “Color Map0”) has discrete colors arranged in no particular order with regard to color index and is most suited to coloring discrete elements of the plot. Color map1 (called cmap1 and discussed in the section called “Color Map1”) has colors which are a continuous function of color index and is most suited to coloring continuous elements of the plot. The user can change the current color (as opposed to the background color which is a special case that is discussed in the section called “Color Map0”) at any point in the PLplot commands that are used to create a given plot by selecting any of the colors from either cmap0 or cmap1 using calls to `plcol0` or `plcol1`. When the current color is changed all subsequent drawing actions will utilize that new color until it is changed again.

### Color Map0

Color map0 is most suited to coloring discrete elements of the plot such as the background, axes, lines, and labels. The cmap0 palette colors are stored using RGBA (i.e., red, green, blue, and alpha transparency) components (although some drivers ignore the alpha transparency data and simply render opaque colors corresponding to the semitransparent ones). In the discussion that follows all references to cmap0 API functions with a trailing "a" in their names (e.g., `plscol0a`) refers to setting RGBA semitransparent colors while the equivalent function (e.g., `plscol0`) without the trailing "a" in the name refers to setting RGB colors with an assumed opaque alpha transparency of 1.0.

Page 1 of our standard example 02 illustrates the default 16 colors in the cmap0 palette. The background color is a special case to be discussed below, and the current color of discrete elements of the plot other than the background may be specified by cmap0 index (or cmap1 index, see the section called “Color Map1”). The cmap0 index is 1 by default (and corresponds to opaque red for the default cmap0 palette), but during the course of plotting a page, the user can change that current color as often as desired using `plcol0` to select the desired cmap0 color index from the cmap0 color palette in existence at the time.

The advanced cmap0 use case includes a number of methods for changing the cmap0 color palette. It is possible to update one index of the cmap0 palette using `plscol0a` or `plscol0`, define a complete cmap0 palette with an arbitrary number of colors using `plscmap0a` or `plscmap0`, or read in a complete cmap0 palette from a special cmap0 palette file with the command-line `cmap0` parameter or by calling `plspal0`. Our standard examples 04, 19, 26, 30, 31, and 33 illustrate how to use `plscol0a` and `plscol0`. Our standard examples 02, 24, and 30 illustrate how to use `plscmap0a` and `plscmap0`. Although the user can define and use any cmap0 palette file they like, predefined cmap0 palette files are given in `data/cmap0*.pal` within the source tree and installed in `<install-prefix>/share/plplot5.15.0/cmap0*.pal` in the install tree. By default the cmap0 palette is set using the predefined `cmap0_default.pal` file, but our standard example 16 demonstrates use of a number of our other predefined cmap0 palette files in the various pages of that example. Many of the above commands indirectly set the number of cmap0 colors, but it is also possible for the user to specify that number directly with the command-line `ncol0` parameter or by calling `plscmap0n`. For all methods of defining the cmap0 palette any number of colors are allowed in any order, but it is not guaranteed that the individual drivers will actually be able to use more than 16 colors (although most drivers do support more than 16 colors).

The background color (which always corresponds to index 0 of the cmap0 palette) is a special case that must be discussed separately. The default cmap0 palette index 0 corresponds to opaque black so by default the background is that color. However, the user may set that background color to something else by using the command-line `bg` parameter, by calling `plscolbga` or `plscolbg`, or by calling `plscol0a` or `plscol0` with a 0 index. In addition, the background color is implicitly set when the whole cmap0 color palette (including index 0) is changed with one of the methods above. However, since the background is painted at the start of each page any of these methods of changing the background color must be done before that page start. Note that although our long-term goal is for each device driver that honors semitransparent colors will also honor semitransparent background requests from users the current status is only a few drivers (e.g., the svg device driver) do that and the rest fall back to replacing the requested semitransparent background with the equivalent opaque background.

### Color Map1

Color map1 is most suited to coloring elements of plots in which continuous data values are represented by a continuous range of colors. The cmap1 palette colors are stored using RGBA (i.e., red, green, blue, and alpha transparency) components (although some drivers ignore the alpha transparency data and simply render the opaque colors corresponding to the requested semitransparent color). In the discussion that follows all references to cmap1 API functions with a trailing "a" in their names (e.g., `plscmap1la`) refers to setting RGBA semitransparent colors, while the equivalent function (e.g., `plscmap1l`) without the trailing "a" in the name refers to setting RGB colors with an assumed opaque alpha transparency of 1.0. The cmap1 index is a floating-point number whose default range is 0.0-1.0, but to set and get that range use `plscmap1_range` and `plgcmap1_range`.

Page 4 of our standard example 16 illustrates use of our default cmap1 palette to represent continuous data values as a continuous range of colors using `plshades`. For this case and also other PLplot API (e.g., `plsurf3d`) where continuous data are being plotted, the range of continuous data are scaled to the cmap1 color index range which in turn are mapped internally using `plcol1` to continuous colors using the cmap1 color palette. In addition, during the course of plotting a page, the user can change the current color used for discrete objects as often as desired by directly calling `plcol1` to select the desired cmap1 color index from the cmap1 color palette in existence at the time. However, use of `plcol0` and the cmap0 palette (see the section called “Color Map0”) to set the current color for discrete objects is more usual.

The advanced cmap1 use case includes a number of methods of changing the cmap1 palette. It is possible to define a complete cmap1 palette by using `plscmap1la` or `plscmap1l` (where linear interpolation between control points of given alpha transparency and either RGB or HLS color assures the palette is a continuous function of its index); by using `plscmap1a` or `plscmap1` (where it is the user's responsibility to makes sure that palette is a continuous function of its index); or by reading in a complete cmap1 palette from a special cmap1 palette file with the command-line `cmap1` parameter or by calling `plspal1`. Our standard examples 08, 11, 12, 15, 20, 21, and 30 illustrate how to use `plscmap1la` and `plscmap1l`. Our standard example 31 illustrates how to use `plscmap1a` and `plscmap1` (which are rarely used because of the continuity concern). Although the user can define and use any cmap1 palette file they like, predefined cmap1 palette files are given in `data/cmap1*.pal` within the source tree and installed in `<install-prefix>/share/plplot5.15.0/cmap1*.pal` in the install tree. By default the cmap1 palette is set using the predefined `cmap1_default.pal` file, but our standard example 16 demonstrates use of a number of our other predefined cmap1 palette files in the various pages of that example. The default number of cmap1 colors is 128 which supplies sufficient sampling of the continuous cmap1 palette for most purposes, but that number can be set to other values with the command-line `ncol1` parameter or by calling `plscmap1n`. (That number is also updated by calls to the rarely used `plscmap1a` or `plscmap1`.)

There is a one-to-one correspondence between RGB and HLS color spaces. Plplot provides `plrgbhls` to convert from RGB to HLS and `plhlsrgb` to convert from HLS to RGB.

RGB space is characterized by three 8-bit unsigned integers corresponding to the intensity of the red, green, and blue colors. Thus, in hexadecimal notation with the 3 bytes concatenated together the RGB values of FF0000, FFFF00, 00FF00, 00FFFF, 0000FF, FF00FF, 000000, and FFFFFF correspond to red, yellow, green, cyan, blue, magenta, black, and white.

HLS (hue, lightness, and saturation) space is often conceptually easier to use than RGB space. One useful way to visualize HLS space is as a volume made up by two cones with their bases joined at the “equator”. A given RGB point corresponds to HLS point somewhere on or inside the double cones, and vice versa. The hue corresponds to the “longitude” of the point with 0, 60, 120, 180, 240, and 300 degrees corresponding to red, yellow, green, cyan, blue, and magenta. The lightness corresponds to the distance along the axis of the figure of a perpendicular dropped from the HLS point to the axis. This values ranges from 0 at the “south pole” to 1 at the “north pole”. The saturation corresponds to the distance of the HLS point from the axis with the on-axis value being 0 and the surface value being 1. Full saturation corresponds to full color while reducing the saturation (moving toward the axis of the HLS figure) mixes more gray into the color until at zero saturation on the axis of the figure you have only shades of gray with the variation of lightness along the axis corresponding to a gray scale.

Prev | Up | Next
Setting the Area Fill Pattern | Home | Setting Character Attributes