%N pggray %F $MIR/src/pggray.f
%D Gray-scale map of a 2D data array
%B
      SUBROUTINE PGGRAY (A, IDIM, JDIM, I1, I2, J1, J2,
     1                   FG, BG, TR)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      REAL    A(IDIM,JDIM), FG, BG, TR(6)

 Draw gray-scale map of an array in current window. The subsection
 of the array A defined by indices (I1:I2, J1:J2) is mapped onto
 the view surface world-coordinate system by the transformation
 matrix TR. The resulting quadrilateral region is clipped at the edge
 of the window and shaded with the shade at each point determined
 by the corresponding array value.  The shade is a number in the
 range 0 to 1 obtained by linear interpolation between the background
 level (BG) and the foreground level (FG), i.e.,

   shade = [A(i,j) - BG] / [FG - BG]

 The background level BG can be either less than or greater than the
 foreground level FG.  Points in the array that are outside the range
 BG to FG are assigned shade 0 or 1 as appropriate.

 PGGRAY uses two different algorithms, depending how many color
 indices are available in the color index range specified for images.
 (This range is set with routine PGSCIR, and the current or default
 range can be queried by calling routine PGQCIR).

 If 16 or more color indices are available, PGGRAY first assigns
 color representations to these color indices to give a linear ramp
 between the background color (color index 0) and the foreground color
 (color index 1), and then calls PGIMAG to draw the image using these
 color indices. In this mode, the shaded region is "opaque": every
 pixel is assigned a color.

 If less than 16 color indices are available, PGGRAY uses only
 color index 1, and uses  a "dithering" algorithm to fill in pixels,
 with the shade (computed as above) determining the faction of pixels
 that are filled. In this mode the shaded region is "transparent" and
 allows previously-drawn graphics to show through.

 The transformation matrix TR is used to calculate the world
 coordinates of the center of the "cell" that represents each
 array element. The world coordinates of the center of the cell
 corresponding to array element A(I,J) are given by:

          X = TR(1) + TR(2)*I + TR(3)*J
          Y = TR(4) + TR(5)*I + TR(6)*J

 Usually TR(3) and TR(5) are zero -- unless the coordinate
 transformation involves a rotation or shear.  The corners of the
 quadrilateral region that is shaded by PGGRAY are given by
 applying this transformation to (I1-0.5,J1-0.5), (I2+0.5, J2+0.5).

 Arguments:
  A      (input)  : the array to be plotted.
  IDIM   (input)  : the first dimension of array A.
  JDIM   (input)  : the second dimension of array A.
  I1, I2 (input)  : the inclusive range of the first index
                    (I) to be plotted.
  J1, J2 (input)  : the inclusive range of the second
                    index (J) to be plotted.
  FG     (input)  : the array value which is to appear with the
                    foreground color (corresponding to color index 1).
  BG     (input)  : the array value which is to appear with the
                    background color (corresponding to color index 0).
  TR     (input)  : transformation matrix between array grid and
                    world coordinates.
