5. Attributes

5.1 Introduction

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:

Color Index:: PGSCI.
Color Representation:: PGSCR, PGSCRN, and PGSHLS.
Line Style:: PGSLS.
Line Width:: PGSLW.
Character Height:: PGSCH.
Character Font:: PGSCF.
Text Background:: PGSTBG.
Fill-area Style:: PGSFS, PGSHS.

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.

5.2 Color Index

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), e.g..

      CALL PGSCI(2)
      CALL PGLINE(100, XP, YP)
      CALL PGSCI(3)
      CALL PGPT(15, XP, YP, 17)

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

5.3 Color Representation

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.

Table 5.1. Default Color 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.

Setting Color Representation in the RGB System

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)

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.

Setting Color Representation in the HLS System

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.

Setting Color Representation by Name

A third alternative to PGSCR and PGSHLS is routine PGSCRN, which specifies color by name. For example,

      CALL PGSCRN(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:

if environment variable (logical name) PGPLOT_RGB is defined, ts value is used as the file name;
otherwise, if environment variable PGPLOT_DIR is defined, a file rgb.txt in the directory named by this environment variable is used;
otherwise, file rgb.txt in the current directory is used.
If all of these fail to find a file, an error is reported and the routine does nothing.

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.

Setting Background and Foreground colors at run time

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 PGPOLOT_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 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 slategrey

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.

5.4 Line Style

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:

1: full line,
2: long dashes,
3: dash-dot-dash-dot,
4: dotted,
5: dash-dot-dot-dot.

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)

5.5 Line Width

Line Width affects lines, graph-markers, and text. It is specified with routinePGSLS, which takes an integer argument specifying the line-width multilpier. 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)

5.6 Character Height

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

5.7 Character Font

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:

1: normal (simple) font (default),
2: roman font,
3: italic font,
4: script font.

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')

5.8 Text Background

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

-1: to select transparent text (the default), or
0 - 255: to select opaque text, with the argument specifying the color index of the text background. Use color index 0 to erase underlying graphics before drawing text.

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 test on a blue background:

      INTEGER YELLOW, BLUE
      PARAMETER (BLUE=4, YELLOW=7)
      ...
      CALL PGSCI(YELLOW)
      CALL PGSTBG(BLUE)
      CALL PGTEXT(X, Y, 'SPQR')

5.9 Fill-Area Style

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:

1: solid (default),
2: outline,
3: hatched,
4: cross-hatched.

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)

The spacing and orientation of the hatching lines in styles 3 and 4 can be changed by calling routine PGSHS.

5.10 The Inquiry Routines

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

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

5.11 Saving and Restoring Attributes

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:

* 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

Next: Chapter 6