Figure 5.1 Default color representations of color indices 0-15 on most color and gray-scale devices.
Note: Some Web browsers may not display the colors correctly.
The appearance of the primitive elements of a graphical image (lines, graph-markers, text, and area-fill) can be changed by specifying primitive attributes. The attributes, and the corresponding routines for changing them, are:
The routines to change attributes can be freely intermixed with the PGPLOT drawing routines. Once an attribute has been changed by a call to the appropriate routine, it remains in effect for all subsequent plotting until it is changed again. In addition to the routines that set attributes (PGSxx) there are routines for determining the current value of each attribute (PGQxx). These make it possible to write subroutines which change attribute values temporarily but restore the old attributes before returning to the calling program.
This attribute affects all the primitives: lines, graph-markers, text, and area-fill, and is controlled by routine PGSCI.
Devices differ considerably in their ability to draw in more than one color. On most hardcopy devices, the default color is black on a white background, while on most CRT devices, it is white on a black background. Color is selected using an integer parameter called the color index. Color index 1 is the default color, and color index 0 is the background color. The number of different color indices available depends on the device. On most monochrome devices, only color indices 0 and 1 are available, while some color CRT devices may permit color indices from 0 to 255. On some monochrome devices, color index can be used to select different brightnesses (intensities).
Color index 0, the background color, can be used to “erase” elements from a picture by overwriting them with color index 0. Note that not all devices are capable of this: e.g., Tektronix storage-tube terminals and pen-plotters cannot erase part of a displayed picture.
To select a new color index for subsequent plotting, use routine PGSCI (Set Color Index). For example, the following code fragment draws a line using color index 2 and some markers using color index 3:
CALL PGSCI(2)
CALL PGLINE(100, XL, YL)
CALL PGSCI(3)
CALL PGPT(15, XP, YP, 17)
cpgsci(2);
cpgline(100, xl, yl);
cpgsci(3);
cpgpt(15, xp, yp, 17);
The PGPLOT Device Manual lists the capabilities of the devices for plotting in color and variable intensity. The default color index is 1; all devices accept this. Most devices also accept color index 0 (background or erase), and several accept color index up to 15 or more. The maximum color index is the number of different colors that can be displayed at once. Some devices permit the assignment of colors to color indices to be changed (by calling PGSCR, see below). The range of color indices available on the active device can be determined by calling routine PGQCOL. The lower limit is always either 0 or 1, and the upper limit can be in the range 1 to 255.
Each color index has an associated Color Representation, which defines the associated color and intensity. Color Representation may be expressed by a set of three numbers, either the Hue, Lightness, and Saturation (H,L,S) components or the Red, Green, and Blue (R,G,B) components. (R,G,B) are quantities in the range 0.0 to 1.0, with 1.0 being maximum intensity; if R=G=B the color is a shade of gray. In the (H,L,S) system, hue is a cyclic quantity expressed as an angle in the range 0 to 360, while L and S are in the range 0.0 to 1.0.
The following table and Figure 5.1 show how the color indices are defined on most devices when PGPLOT is started. Note that these assignments are device-dependent, and in particular some devices plot in black on white background (color index 0 = white, color index 1 = black), while others plot in white on black background (color index 0 = black, color index 1 = white). Color indices 0-15 have these predefined color representations, but these may be changed with by calling PGSCR, PGSCRN, or PGSHLS. Color indices 16-maximum have no predefined representations: if these indices are used, one of these routines must be called to define the representation.
Color Index Color (H, L, S) (R, G, B) 0 Black (background) 0, 0.00, 0.00 0.00, 0.00, 0.00 1 White (default) 0, 1.00, 0.00 1.00, 1.00, 1.00 2 Red 120, 0.50, 1.00 1.00, 0.00, 0.00 3 Green 240, 0.50, 1.00 0.00, 1.00, 0.00 4 Blue 0, 0.50, 1.00 0.00, 0.00, 1.00 5 Cyan (Green + Blue) 300, 0.50, 1.00 0.00, 1.00, 1.00 6 Magenta (Red + Blue) 60, 0.50, 1.00 1.00, 0.00, 1.00 7 Yellow (Red + Green) 180, 0.50, 1.00 1.00, 1.00, 0.00 8 Red + Yellow (Orange) 150, 0.50, 1.00 1.00, 0.50, 0.00 9 Green + Yellow 210, 0.50, 1.00 0.50, 1.00, 0.00 10 Green + Cyan 270, 0.50, 1.00 0.00, 1.00, 0.50 11 Blue + Cyan 330, 0.50, 1.00 0.00, 0.50, 1.00 12 Blue + Magenta 30, 0.50, 1.00 0.50, 0.00, 1.00 13 Red + Magenta 90, 0.50, 1.00 1.00, 0.00, 0.50 14 Dark Gray 0, 0.33, 0.00 0.33, 0.33, 0.33 15 Light Gray 0, 0.66, 0.00 0.66, 0.66, 0.66 16--255 Undefined
On some devices, but not all, the assignments of colors to color indices can be changed by calling routine PGSCR, to specify the color in terms of its (R,G,B) components, PGSHLS, to specify the color in terms of its (H,L,S) components, or PGSCRN, to specify the color by name. Note that color-index 0, the background color, can be redefined in this way.
The effect of changing color representation is device-dependent. Devices usually fall into one of three classes: static color (unchangeable representation), pseudo-color (color lookup table), and direct color. On static color devices (e.g., pen plotters, Printronix printer, Tektronix terminal), attempts to change the color representation are ignored. On pseudo-color devices (e.g., most X Window devices), changing the color representation of index J changes the lookup table. Pixels already drawn with index J change to the new color, as do subsequent ones. On direct color devices (e.g., PostScript color printers, some X Window devices), changing color representation only affects the color of pixels drawn with that color index later in the program.
On monochrome devices which can display a range of intensities, the displayed intensity I is calculated from the requested (R,G,B) intensities by the following formula:
I = 0.30 R + 0.59 G + 0.11 B
as in the NTSC encoding used by US color television systems.
Use routine PGSCR, which requires red, green, and blue values in the range 0.0 (dark) to 1.0 (maximum intensity). The following example changes color index 2 to dark blue:
CALL PGSCR(2, 0.0, 0.0, 0.3)
cpgscr(2, 0.0, 0.0, 0.3);
Note that most devices do not have an infinite range of colors or monochrome intensities available; the nearest available color is used. Examples: for black, set R = G = B = 0.0; for white, set R = G = B = 1.0; for medium gray, set R = G = B = 0.5; for medium yellow, set R = G = 0.5, B = 0.0.
The HLS, or Hue-Saturation-Lightness, system is an alternative to RGB for specifying color representation. Use routine PGSHLS instead of PGSCR. Hue is represented by an angle in degrees, with red at 120, green at 240, and blue at 0 (or 360). Lightness ranges from 0.0 to 1.0, with black at lightness 0.0 and white at lightness 1.0. Saturation ranges from 0.0 (gray) to 1.0 (pure color). Hue is irrelevant when saturation is 0.0.
Examples: H L S R G B
black any 0.0 0.0 0.0 0.0 0.0
white any 1.0 0.0 1.0 1.0 1.0
medium gray any 0.5 0.0 0.5 0.5 0.5
red 120 0.5 1.0 1.0 0.0 0.0
yellow 180 0.5 1.0 1.0 1.0 0.0
pink 120 0.7 0.8 0.94 0.46 0.46
Reference: SIGGRAPH Status Report of the Graphic Standards Planning Committee, Computer Graphics, Vol.13, No.3, Association for Computing Machinery, New York, NY, 1979. See also: J. D. Foley et al., “Computer Graphics: Principles and Practice”, second edition, Addison-Wesley, 1990, section 13.3.5.
A third alternative to PGSCR and PGSHLS is routine PGSCRN, which specifies color by name. For example,
CALL PGSCRN(2, 'MediumOrchid', IER)
cpgscrn(2, "MediumOrchid", &ier);
The name is converted to R, G, B intensities by consulting an external file which is read the first time that PGSCRN is called. The name of the external file is found as follows:
PGPLOT_RGB
is defined, its value is used as the file name;PGPLOT_DIR is
defined, a file rgb.txt in the directory named by this
environment variable is used;rgb.txt in the current directory
is used.Each line of the file defines one color, with four blank- or
tab-separated fields per line. The first three fields are the R, G,
B components, which are integers in the range 0 (zero intensity) to
255 (maximum intensity). The fourth field is the color name. The
color name may include embedded blanks. The file
rgb.txt distributed with PGPLOT is based on the
standard list of color names supported by the X-window system. To see
how the colors will appear on your system, print or view the PGPLOT Color Chart (a PDF file).
The color name in PGSCRN can be replaced by a hexadecimal code, e.g., '#ff0000'. The hexadecimal code consists of 7 characters; the first is '#', and the remaining 6 characters are pairs of hexadecimal digits (0-9, a-f, upper or lower case) giving R, G, B components for the color in the range 00 (black) to ff (maximum) (0-255 decimal). This convention is widely used to specify colors, e.g., in Web browsers.
The device-dependent default color representation of color indices
0 (background) and 1 (foreground) can be overridden at run time by
defining environment variables PGPLOT_BACKGROUND and
PGPLOT_FOREGROUND. The values of these variables are
color names, as used by routine PGSCRN. For example, to ensure that
all devices use a black foreground on a white background, on a
UNIX/csh system, type
setenv PGPLOT_FOREGROUND black
setenv PGPLOT_BACKGROUND white
before running the PGPLOT program. Or you can be more creative, e.g.,
setenv PGPLOT_FOREGROUND gold
setenv PGPLOT_BACKGROUND #2040C0
On direct color devices (e.g., PostScript), it is necessary to fill the view surface with the background color (by calling routine PGERAS) for a change in color representation to affect the whole view surface.
Line Style can be, e.g., solid, dashed, or dotted. The attribute affects only lines, not the other primitives. It is controlled by subroutine PGSLS. The default line style is a full, unbroken line. Line style is described by an integer code:
To change the line style, use routine PGSLS. For example, to draw a dashed line:
CALL PGSLS(2) CALL PGLINE(620, X, Y) CALL PGSLS(1)
cpgsls(2); cpgline(620, x, y); cpgsls(1);
Line Width affects lines, graph-markers, and text. It is specified with routine PGSLW, which takes an integer argument specifying the line-width multiplier. The exact appearance of thick lines is device-dependent---it depends on the resolution of the device---but on most devices PGPLOT attempts to make the line-width unit equal to 0.005 inches (0.13 mm). The default width is 1, and the maximum that may be specified is 201. Requesting a line-width of 10, say, will give lines that are approximately 1/20 inch thick. e.g.,
CALL PGSLW(5)
cpgslw(5);
Character Height affects graph-markers and text. Character height is specified as a multiple of the default character height; the default character height one-fortieth of the height or width of the view surface (whichever is less). To change the character height, use routine PGSCH. Note that the argument is a real [float] variable or constant, not an integer like the other attribute routines. The following example is part of the program used to draw Figure 4.2:
CALL PGSCH(1.5) CALL PGSLW(3) CALL PGTEXT(0.05,10.0,'Bigger (1.5)') CALL PGSCH(0.5) CALL PGSLW(1) CALL PGTEXT(0.5,10.0,'Smaller (0.5)') CALL PGSCH(1.0)
cpgsch(1.5); cpgslw(3); cpgtxt(0.05, 10.0, "Bigger (1.5)"); cpgsch(0.5); cpgslw(1); cpgtxt(0.5, 10.0, "Smaller (0.5)"); cpgsch(1.0);
Character Font affects text only. Four fonts are available. The default font (1) is simple and is the fastest to draw. The font is defined by an integer code:
To change the character font, use routine PGSCF; it is also possible to change the font temporarily by using escape sequences (see Chapter 4). For example, the following code generates text in roman font:
INTEGER ROMAN PARAMETER (ROMAN=2) ... CALL PGSCF(ROMAN) CALL PGTEXT(X, Y, 'SPQR')
#define ROMAN 2 ... cpgscf(ROMAN); cpgtext(x, y, "SPQR");
This attribute affects the appearance of text. Text may be either transparent (the default), in which case underlying graphics show between the characters of the text, or opaque, in which case the bounding box of the text is filled with a specified color before drawing the text characters. Use routine PGSTBG to specify the text background; the argument is an integer which may be
If the color index specified by PGSTBG is the same as that specified by PGSCI, then text will be written on a background of the same color and will be unreadable.
The following code draws yellow text on a blue background:
INTEGER YELLOW, BLUE PARAMETER (BLUE=4, YELLOW=7) ... CALL PGSCI(YELLOW) CALL PGSTBG(BLUE) CALL PGTEXT(X, Y, 'SPQR')
#define BLUE 4 #define YELLOW 7 ... cpgsci(YELLOW); cpgstbg(BLUE); cpgtext(x, y, "SPQR");
Fill-Area Style can be solid (fill the area with the current color), outline (only the outline of the polygon is drawn), hatched (the region is shaded with parallel lines) or cross-hatched (the region is shaded with two sets of perpendicular lines). The style is defined by an integer code:
These are illustrated in Figure 5.2.
Fill-area style applies to polygons (PGPOLY), circles (PGCIRC), and rectangles (PGRECT).
To change the fill-area style, use routine PGSFS. The following example uses both outline and solid fill: it first erases a rectangle (using color index 0 and fill-area style 1), and then draws a frame around it (using color index 1 and fill-area style 2):
CALL PGSCI(0) CALL PGSFS(1) CALL PGRECT(0.31, 0.69, 0.85, 0.97) CALL PGSCI(1) CALL PGSFS(2) CALL PGRECT(0.31, 0.69, 0.85, 0.97)
cpgsci(0); cpgsfs(1); cpgrect(0.31, 0.69, 0.85, 0.97); cpgsci(1); cpgsfs(2); cpgrect(0.31, 0.69, 0.85, 0.97);
The spacing and orientation of the hatching lines in styles 3 and 4 can be changed by calling routine PGSHS.
The current setting of each attribute can be determined with an inquiry routine, e.g., PGQCH to determine the current character height. A general-purpose subroutine that needs to change attributes temporarily should first determine the current settings and then restore them before finishing, e.g.,
INTEGER LW, CI REAL X(7), Y(7) * save the current attributes CALL PGQLW(LW) CALL PGQCI(CI) * change the attributes and draw something CALL PGSLW(2) CALL PGSCI(11) CALL PGLINE(7, X, Y) * restore the attributes CALL PGSLW(LW) CALL PGSCI(CI) RETURN
int lw, ci; float x[7], y[7]; cpgqlw(&lw); cpgqci(&ci); cpgslw(2); cpgsci(11); cpgline(7, x, y); cpgslw(lw); cpgsci(ci); return;
There are also inquiry routines for determining the current window (PGQWIN), current viewport (PGQVP), and current pen position for use with PGMOVE and PGDRAW (PGQPOS).
It is sometimes convenient to change the current attributes temporarily, to draw a small prt of a picture, for example, and then restore them to their previous settings. This can be accomplished with the routines PGSAVE and PGUNSA.
PGSAVE saves the current PGPLOT attributes in a private storage area. They can be restored by calling PGUNSA (unsave). Attributes saved are: character font, character height, color index, fill-area style, line style, line width, pen position, arrow-head style, hatching style. Color representation is not saved.
Calls to PGSAVE and PGUNSA should always be paired. Up to 20 copies of the attributes may be saved. PGUNSA always retrieves the last-saved values (last-in first-out stack).
Note that when multiple devices are in use, PGUNSA retrieves the values saved by the last PGSAVE call, even if they were for a different device.
The example in the previous section can be written more simply as:
REAL X(7), Y(7) * save the current attributes CALL PGSAVE * change the attributes and draw something CALL PGSLW(2) CALL PGSCI(11) CALL PGLINE(7, X, Y) * restore the attributes CALL PGUNSA RETURN
float x[7], y[7]; cpgsave(); cpgslw(2); cpgsci(11); cpgline(7, x, y); cpgunsa(); return;
Figure 5.1 Default color representations of color indices 0-15 on most color and gray-scale devices.
Note: Some Web browsers may not display the colors correctly.
Figure 5.2 Fill-Area Styles: illustrated with PGPOLY, PGCIRC, and PGRECT.