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