%N pgimag %F $MIR/src/pgimag.f
%D Color image from a 2D data array
%B
      SUBROUTINE PGIMAG (A, IDIM, JDIM, I1, I2, J1, J2,
     1                   A1, A2, TR)
      INTEGER IDIM, JDIM, I1, I2, J1, J2
      REAL    A(IDIM,JDIM), A1, A2, TR(6)

 Draw a color image 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. Each element of the array is represented in the image
 by a small quadrilateral, which is filled with a color specified by
 the corresponding array value.

 The subroutine uses color indices in the range C1 to C2, which can
 be specified by calling PGSCIR before PGIMAG. The default values
 for C1 and C2 are device-dependent; these values can be determined by
 calling PGQCIR. Note that color representations should be assigned to
 color indices C1 to C2 by calling PGSCR before calling PGIMAG. On some
 devices (but not all), the color representation can be changed after
 the call to PGIMAG by calling PGSCR again.

 Array values in the range A1 to A2 are mapped on to the range of
 color indices C1 to C2, with array values <= A1 being given color
 index C1 and values >= A2 being given color index C2. The mapping
 function for intermediate array values can be specified by
 calling routine PGSITF before PGIMAG; the default is linear.

 On devices which have no available color indices (C1 > C2),
 PGIMAG will return without doing anything. On devices with only
 one color index (C1=C2), all array values map to the same color
 which is rather uninteresting. An image is always "opaque",
 i.e., it obscures all graphical elements previously drawn in
 the region.

 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 PGIMAG 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.
  A1     (input)  : the array value which is to appear with shade C1.
  A2     (input)  : the array value which is to appear with shade C2.
  TR     (input)  : transformation matrix between array grid and
                    world coordinates.
