%N pgctab %F $MIR/src/pgctab.f
%D Install the color table to be used by PGIMAG
%B
      SUBROUTINE PGCTAB(L, R, G, B, NC, CONTRA, BRIGHT)
      INTEGER NC
      REAL    L(NC), R(NC), G(NC), B(NC), CONTRA, BRIGHT

 Use the given color table to change the color representations of
 all color indexes marked for use by PGIMAG. To change which
 color indexes are thus marked, call PGSCIR before calling PGCTAB
 or PGIMAG. On devices that can change the color representations
 of previously plotted graphics, PGCTAB will also change the colors
 of existing graphics that were plotted with the marked color
 indexes. This feature can then be combined with PGBAND to
 interactively manipulate the displayed colors of data previously
 plotted with PGIMAG.

 Limitations:
  1. Some devices do not propagate color representation changes
     to previously drawn graphics.
  2. Some devices ignore requests to change color representations.
  3. The appearance of specific color representations on grey-scale
     devices is device-dependent.

 Notes:
  To reverse the sense of a color table, change the chosen contrast
  and brightness to -CONTRA and 1-BRIGHT.

  In the following, the term 'color table' refers to the input
  L,R,G,B arrays, whereas 'color ramp' refers to the resulting
  ramp of colors that would be seen with PGWEDG.

 Arguments:
  L      (input)  : An array of NC normalized ramp-intensity levels
                    corresponding to the RGB primary color intensities
                    in R(),G(),B(). Colors on the ramp are linearly
                    interpolated from neighbouring levels.
                    Levels must be sorted in increasing order.
                     0.0 places a color at the beginning of the ramp.
                     1.0 places a color at the end of the ramp.
                    Colors outside these limits are legal, but will
                    not be visible if CONTRA=1.0 and BRIGHT=0.5.
  R      (input)  : An array of NC normalized red intensities.
  G      (input)  : An array of NC normalized green intensities.
  B      (input)  : An array of NC normalized blue intensities.
  NC     (input)  : The number of color table entries.
  CONTRA (input)  : The contrast of the color ramp (normally 1.0).
                    Negative values reverse the direction of the ramp.
  BRIGHT (input)  : The brightness of the color ramp. This is normally
                    0.5, but can sensibly hold any value between 0.0
                    and 1.0. Values at or beyond the latter two
                    extremes, saturate the color ramp with the colors
                    of the respective end of the color table.
