                   Chapter 14: Contouring

This  chapter  describes  routines  for  contouring   three-
dimensional functions of the form  Z = F(X,Y).  Contours can
be generated with the routine CONPTS  or with other software
packages  and  plotted  with  the  routine  CONCRV or can be
calculated and plotted by  DISLIN  with the routines CONMAT,
CONTUR and CONSHD.

14.1 Plotting Contours

                         C O N C R V

CONCRV plots contours generated by other software packages.

The call is:  CALL CONCRV (XRAY, YRAY, N, ZLEV)   level 2, 3

XRAY, YRAY    are arrays containing the X- and Y-coordinates
              of a contour line.
N             is the number of points.
ZLEV          is a function value used for labels.

                         C O N T U R

The routine  CONTUR  calculates  and plots  contours  of the
function Z = F(X,Y).

The call is:   CALL CONTUR (XRAY, N, YRAY, M, ZMAT, ZLEV)
                                                  level 2, 3

XRAY           is an array containing X-coordinates.
N              is the dimension of XRAY.
YRAY           is an array containing Y-coordinates.
M              is the dimension of YRAY.
ZMAT           is a  matrix  of the dimension (N, M) contai-
               ning function values.
ZLEV           is a function value that defines  the contour
               line to be  calculated.  ZLEV can be used for
               labels.

                         C O N M A T

The routine  CONMAT  plots  contours  of the  function   Z = 
F(X,Y).  The function values  correspond to a linear grid in
the XY-plane.

The call is:  CALL CONMAT (ZMAT, N, M, ZLEV)      level 2, 3

ZMAT          is a  matrix of the  dimension  (N, M) contai-
              ning the function values. If XA, XE, YA and YE
              are  the axis limits in GRAF or values defined
              with  the  routine  SURSZE,  the connection of
              grid points and matrix elements can be descri-
              bed by the formula:

              ZMAT(I,J) = F(X,Y)  where
              X = XA + (I-1) * (XE - XA)/(N-1), I = 1,..,N
              Y = YA + (J-1) * (YE - YA)/(M-1), J = 1,..,M.

N, M          define the dimension of ZMAT.
ZLEV          is a function value  that defines  the contour
              line to be calculated.  The value  can be used
              for labels.

Notes:     -  CONCRV,  CONTUR  and CONMAT  use linear inter-
              polation to connect contour points.
           -  Geographical  projections  can be defined  for
              contouring.
           -  The thickness of contours can be set with THK-
              CRV.  Line styles  and colours can also be de-
              fined.  Legends are supported for  filled  and
              non-filled contours.
           -  The number of matrix points in CONTUR and CON-
              MAT is limited to N * M <= 256000  in  Fortran
              77. There is no limit for the C and Fortran 90
              libraries of DISLIN.
           -  To  plot  contours  for  randomly  distributed
              points of the form  X(N),  Y(N)  and Z(N), the
              routine  GETMAT  can be  used to  calculate  a
              function matrix.

14.2 Plotting Filled Contours

                         C O N S H D

The routine CONSHD plots filled contours of the function Z =
F(X,Y).  Two algorithms can be selected for contour filling:
a cell filling algorithm  and a polygon  filling  algorithm.
For a polygon filling,  only closed contours  can be filled.
The algorithm can be defined with the routine SHDMOD. 

The call is:  CALL CONSHD (XRAY, N, YRAY, M, ZMAT, ZLVRAY, 
                           NLEV)                  level 2, 3

XRAY          is an array containing X-coordinates.
N             is the dimension of XRAY.
YRAY          is an array containing Y-coordinates.
M             is the dimension of YRAY.
ZMAT          is a matrix of the dimension (N, M) containing
              function values.
ZLVRAY        is an array containing the levels.  The levels
              must be sorted in ascending order if cell fil-
              ling is selected. For polygon filling, the le-
              vels should be sorted in such a way that inner
              contours are plotted last.
NLEV          is the number of levels.

14.3 Generating Contours

                         C O N P T S

The routine  CONPTS  generates  contours  without  plotting.
Multiple curves can be returned for one contour level.

The call is:  CALL CONPTS (XRAY, N, YRAY, M, ZMAT, ZLEV, 
                           XPTRAY, YPTRAY, MAXPTS, IRAY,
                           MAXCRV, NCURVS)  level 0, 1, 2, 3

XRAY          is an array containing X-coordinates.
N             is the dimension of XRAY.
YRAY          is an array containing Y-coordinates.
M             is the dimension of YRAY.
ZMAT          is a matrix of the dimension (N, M) containing
              function values.
ZLEV          is a function value  that defines  the contour
              line to be calculated. 
XPTRAY,       are returned arrays  containing the calculated
   YPTRAY     contour.  The arrays can contain  several cur-
              ves.
MAXPTS        is the maximal  number  of points  that can be
              passed to XPTRAY and YPTRAY.
IRAY          is a  returned integer array that contains the
              number  of  points  for each generated contour
              curve.
MAXCRV        is the maximal  number  of entries that can be
              passed to IRAY.
NCURVS        is the returned number of generated curves.

Example: 

The following  statements  generate  from  some arrays XRAY,
YRAY and ZMAT contours and plot them with the routine CURVE.

      PARAMETER (N=100, MAXPTS=1000,MAXCRV=10)
      REAL ZMAT(N,N),XRAY(N),YRAY(N),XPTS(MAXPTS),YPTS(MAXPTS)
      INTEGER IRAY(MAXCRV)
      .....
      DO I=1,12
        ZLEV=0.1+(I-1)*0.1
        CALL CONPTS(XRAY,N,YRAY,N,ZMAT,ZLEV,XPTS,YPTS,MAXPTS,
     *              IRAY,MAXCRV,NCURVS)
        K=1
        DO J=1,NCURVS
          CALL CURVE(XPTS(K),YPTS(K),IRAY(J))
          K=K+IRAY(J)
        END do
      END DO                                   
 
14.4 Parameter Setting Routines

                         L A B E L S

The routine LABELS defines contour labels.

The call is:  CALL LABELS (COPT, 'CONTUR')     level 1, 2, 3
COPT          is a character string defining the labels.
  = 'NONE'    means that no labels will be plotted.
  = 'FLOAT'   means that  the level  value  will be used for
              labels.
  = 'CONLAB'  means  that labels  defined  with the  routine
              CONLAB will be plotted.
                                     Default: COPT = 'NONE'.

Note:         The number of decimal places in contour labels
              can be  defined with  CALL DIGITS (NDIG, 'CON-
              TUR'). The default value for NDIG is 1.

                         L A B D I S

The routine  LABDIS defines the distance between contour la-
bels.

The call is:  CALL LABDIS (NDIS, 'CONTUR')     level 1, 2, 3

NDIS          is the distance between labels in plot coordi-
              nates.
                                         Default: NDIS = 500

                         L A B C L R

The routine LABCLR defines the colour of contour labels.

The call is:  CALL LABCLR (NCLR, 'CONTUR')     level 1, 2, 3

NCLR          is a colour number between -1 and 255. If NCLR
              = -1,  the contour labels will be plotted with
              the current colour.
                                          Default: NCLR = -1

                         C O N L A B

The routine CONLAB defines a character string  which will be
used for labels  if the routine  LABELS  is called  with the
parameter 'CONLAB'.

The call is:  CALL CONLAB (CLAB)               level 1, 2, 3

CLAB          is a character string containing the label.
                                        Default: CLAB = ' '.

                         C O N M O D

The routine  CONMOD  modifies  the appearance of contour la-
bels.  By default,  DISLIN suppresses the plotting of labels
at a position where the contour  is very curved.  To measure
the  curvature of a  contour for an interval,  DISLIN calcu-
lates the ratio between the arc length and the length of the
straight line between  the interval limits.  If the quotient
is much greater than 1,  the contour line  is very curved in
that interval.

The call is:  CALL CONMOD (XFAC, XQUOT)        level 1, 2, 3

XFAC          defines the length  of intervals  (>= 0).  The
              curvature of contours will be tested in inter-
              vals of  the  length (1 + XFAC) * W where W is
              the label length.
XQUOT         defines an upper limit for the quotient of arc
              length and length of the  straight line (> 1).
              If the quotient  is greater  than  XQUOT,  the
              plotting  of labels will  be suppressed in the
              tested interval.
                                        Default: (0.5, 1.5).

                         C O N G A P

The routine  CONGAP  defines the  distance  between  contour
lines and labels.

The call is:  CALL CONGAP (XFAC)               level 1, 2, 3

XFAC          is a real number used as a scaling factor. The
              distance  between  contour lines and labels is
              set to XFAC * NH where  NH is the current cha-
              racter height.
                                        Default: XFAC = 0.5.

                         S H D M O D

The routine  SHDMOD  defines  an algorithm  used for contour 
filling.

The call is:  CALL SHDMOD (COPT, 'CONTUR')     level 1, 2, 3

COPT          is a character string defining the algorithm.
 = 'CELL'     defines cell filling.
 = 'POLY'     defines polygon filling.
                                     Default: COPT = 'CELL'.

14.5 Examples

            PROGRAM EX14_1
            PARAMETER (N=100)
            DIMENSION X(N),Y(N),Z(N,N)

            FPI=3.14159/180.
            STEP=360./(N-1)
            DO I=1,N
              X(I)=(I-1.)*STEP
              Y(I)=(I-1.)*STEP
            END DO

            DO I=1,N
              DO J=1,N
                Z(I,J)=2*SIN(X(I)*FPI)*SIN(Y(J)*FPI)
              END DO
            END DO

            CALL SETPAG('DA4P')
            CALL DISINI
            CALL PAGERA
            CALL COMPLX

            CALL TITLIN('Contour Plot',1)
            CALL TITLIN('F(X,Y) = 2 * SIN(X) * SIN(Y)',3)
            CALL NAME('X-axis','X')
            CALL NAME('Y-axis','Y')

            CALL INTAX
            CALL AXSPOS(450,2670)
            CALL GRAF(0.,360.,0.,90.,0.,360.,0.,90.)

            CALL HEIGHT(30)
            DO I=1,9
              ZLEV=-2.+(I-1)*0.5
              IF(I.EQ.5) THEN
                CALL LABELS('NONE','CONTUR')
              ELSE
                 CALL LABELS('FLOAT','CONTUR')
              END IF
             CALL CONTUR(X,N,Y,N,Z,ZLEV)
            END DO

            CALL HEIGHT(50)
            CALL TITLE
            CALL DISFIN
            END

            PROGRAM EX14_2
            PARAMETER (N=100)
            DIMENSION ZMAT(N,N)

            STEP=1.2/(N-1)
            DO I=1,N
              X=0.4+(I-1)*STEP
              DO J=1,N
                Y=0.4+(J-1)*STEP
                ZMAT(I,J)=(X**2.-1.)**2. + (Y**2.-1.)**2.
              END DO
            END DO

            CALL SETPAG('DA4P')
            CALL DISINI
            CALL PAGERA
            CALL COMPLX

            CALL MIXALF
            CALL TITLIN('Contour Plot',1)
            CALL TITLIN('F(X,Y) = (X[2$ - 1)[2$ + 
           *                             (Y[2$ - 1)[2$',3)
            CALL NAME('X-axis','X')
            CALL NAME('Y-axis','Y')

            CALL AXSPOS(450,2670)
            CALL GRAF(0.4,1.6,0.4,0.2,0.4,1.6,0.4,0.2)

            DO I=1,12
              ZLEV=0.1+(I-1)*0.1
              IF(MOD(I,3).EQ.1) THEN
                CALL SOLID
                CALL THKCRV(3)
              ELSE IF(MOD(I,3).EQ.2) THEN
                CALL DASH
                CALL THKCRV(1)
              ELSE
                CALL DOT
                CALL THKCRV(1)
              END IF

              CALL CONMAT(ZMAT,N,N,ZLEV)
            END DO

            CALL HEIGHT(50)
            CALL TITLE
            CALL DISFIN
            END

            PROGRAM EX14_3
            PARAMETER (N=100)
            DIMENSION ZMAT(N,N),XRAY(N),YRAY(N),ZLEV(12)

            STEP=1.6/(N-1)
            DO I=1,N
            XRAY(I)=0.0+(I-1)*STEP
              DO J=1,N
                YRAY(J)=0.0+(J-1)*STEP
                ZMAT(I,J)=(XRAY(I)**2.-1.)**2. + 
           *              (YRAY(J)**2.-1.)**2.
              END DO
            END DO

            CALL SETPAG('DA4P')
            CALL DISINI
            CALL PAGERA
            CALL COMPLX

            CALL MIXALF
            CALL TITLIN('Shaded Contour Plot',1)
            CALL TITLIN('F(X,Y) = (X[2$ - 1)[2$ +
           *                      (Y[2$ - 1)[2$',3)
            CALL NAME('X-axis','X')
            CALL NAME('Y-axis','Y')

            CALL SHDMOD('POLY','CONTUR')
            CALL AXSPOS(450,2670)
            CALL GRAF(0.0,1.6,0.0,0.2,0.0,1.6,0.0,0.2)

            DO I=1,12
              ZLEV(13-I)=0.1+(I-1)*0.1
            END DO

            CALL CONSHD(XRAY,N,YRAY,N,ZMAT,ZLEV,12)

            CALL HEIGHT(50)
            CALL TITLE
            CALL DISFIN
            END  

