Name:         PGCONX

Purpose:      contour map of a 2D data array (non rectangular)

Category:     GRAPHICS

File:         pgplot.src

Author:       T.J. Pearson

Use:          see description below.

Description:

            SUBROUTINE PGCONX (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, PLOT)
            INTEGER  IDIM, JDIM, I1, J1, I2, J2, NC
            REAL     A(IDIM,JDIM), C(*)
            EXTERNAL PLOT
      
       Draw a contour map of an array using a user-supplied plotting
       routine.  This routine should be used instead of PGCONT when the
       data are defined on a non-rectangular grid.  PGCONT permits only
       a linear transformation between the (I,J) grid of the array
       and the world coordinate system (x,y), but PGCONX permits any
       transformation to be used, the transformation being defined by a
       user-supplied subroutine. The nature of the contouring algorithm,
       however, dictates that the transformation should maintain the
       rectangular topology of the grid, although grid-points may be
       allowed to coalesce.  As an example of a deformed rectangular
       grid, consider data given on the polar grid theta=0.1n(pi/2),
       for n=0,1,...,10, and r=0.25m, for m=0,1,..,4. This grid
       contains 55 points, of which 11 are coincident at the origin.
       The input array for PGCONX should be dimensioned (11,5), and
       data values should be provided for all 55 elements.  PGCONX can
       also be used for special applications in which the height of the
       contour affects its appearance, e.g., stereoscopic views.
      
       The map is truncated if necessary at the boundaries of the viewport.
       Each contour line is drawn with the current line attributes (color
       index, style, and width); except that if argument NC is positive
       (see below), the line style is set by PGCONX to 1 (solid) for
       positive contours or 2 (dashed) for negative contours. Attributes
       for the contour lines can also be set in the user-supplied
       subroutine, if desired.
      
       Arguments:
        A      (input) : data array.
        IDIM   (input) : first dimension of A.
        JDIM   (input) : second dimension of A.
        I1, I2 (input) : range of first index to be contoured (inclusive).
        J1, J2 (input) : range of second index to be contoured (inclusive).
        C      (input) : array of NC contour levels; dimension at least NC.
        NC     (input) : +/- number of contour levels (less than or equal
                         to dimension of C). If NC is positive, it is the
                         number of contour levels, and the line-style is
                         chosen automatically as described above. If NC is
                         negative, it is minus the number of contour
                         levels, and the current setting of line-style is
                         used for all the contours.
        PLOT   (input) : the address (name) of a subroutine supplied by
                         the user, which will be called by PGCONX to do
                         the actual plotting. This must be declared
                         EXTERNAL in the program unit calling PGCONX.
      
       The subroutine PLOT will be called with four arguments:
            CALL PLOT(VISBLE,X,Y,Z)
       where X,Y (input) are real variables corresponding to
       I,J indices of the array A. If  VISBLE (input, integer) is 1,
       PLOT should draw a visible line from the current pen
       position to the world coordinate point corresponding to (X,Y);
       if it is 0, it should move the pen to (X,Y). Z is the value
       of the current contour level, and may be used by PLOT if desired.
       Example:
             SUBROUTINE PLOT (VISBLE,X,Y,Z)
             REAL X, Y, Z, XWORLD, YWORLD
             INTEGER VISBLE
             XWORLD = X*COS(Y) ! this is the user-defined
             YWORLD = X*SIN(Y) ! transformation
             IF (VISBLE.EQ.0) THEN
                 CALL PGMOVE (XWORLD, YWORLD)
             ELSE
                 CALL PGDRAW (XWORLD, YWORLD)
             END IF
             END

Note:         This subroutine is only callable from Fortran, not from C.

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