Name:         PGGRAY

Purpose:      gray-scale map of a 2D data array

Category:     GRAPHICS

File:         pgplot.src

Author:       T.J. Pearson

Use:          see description below.

Description:

            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.

Updates:      Oct 16, 1998: JPT automatically extracted from source.