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.  The rou-
              tine  TRFMAT can be used to pass a matrix with
              a better resolution to CONTUR and CONMAT.
           -  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,  CONMAT
              and  CONPTS  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, or the data can be triangula-
              ted with the routine  TRIANG  and contours can
              be plotted  from the  triangulation  with  the 
              routine CONTRI.             

                         C O N T R I

The routine  CONTRI  plots contours  from  triangulated data 
that can be calculated by the routine  TRIANG  from a set of
irregularly distributed data points.

The call is:  CALL CONTRI (XRAY, YRAY, ZRAY, N, I1RAY, 
                      I2RAY, I3RAY, NTRI, ZLEV)   level 2, 3

XRAY          is an array containing the X-coordinates of 
              data points.
YRAY          is an array containing the Y-coordinates of
              data points.
ZRAY          is an array containing the Z-coordinates of
              data points.
N             is the number of data points.
I1RAY, I2RAY, is the Delaunay triangulation of the points
    I3RAY     (XRAY, YRAY) calculated by the routine TRIANG.
NTRI          is the number of triangles in I1RAY, I2RAY 
              and I3RAY.
ZLEV          is a function value that defines  the contour
              line to be calculated.

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.

Note:      -  CONSHD  may  give better  results for a higher
              resolution of  ZMAT.  A matrix  with  a higher 
              resolution can be calculated with the  routine
              TRFMAT.
           -  The colours of the  filled contours are calcu-
              lated from  a fictive colour bar where the mi-
              nimum and maximum  of the contour  levels  are
              used for the  lower  and  upper  limits of the 
              colour bar.  The scaling of the colour bar can
              be modified with the routine  ZSCALE  while  a
              colour bar can be displayed  with the  routine
              ZAXIS.  If the colours of the filled  contours
              should  not be calculated  from  a colour bar, 
              they can be defined directly  with the routine
              CONCLR.
           -  For a cell filling, the calculation of contour
              colours are  described  in the following.  The 
              levels are sorted first in ascending order. By
              default, the colour of the region between  two
              neighbouring  levels  is  calculated  from the 
              lower value of the two levels.  If you want to
              use the  upper value,  you can  define it with
              the routine SHDMOD ('UPPER', 'COLOUR'). In de-
              fault mode  (SHDMOD ('LOWER',  'COLOUR'),  the
              cells below the minimum of the levels are fil-
              led  with the  lowermost  colour of the colour
              bar, the cells above the maximum of the levels
              are filled with the  uppermost  colour  of the
              colour bar.  The plotting  of this regions can
              be suppressed with  the statement  CALL SHDMOD 
              ('NONE', 'CELL').  

                         C O N F L L

The routine CONTRI plots filled contours  from  triangulated
data that can be calculated by the routine TRIANG from a set
of irregularly distributed data points.

The call is:  CALL CONTRI (XRAY, YRAY, ZRAY, N, I1RAY, 
                I2RAY, I3RAY, NTRI, ZLVRAY, NLEV) level 2, 3

XRAY          is an array containing the X-coordinates of 
              data points.
YRAY          is an array containing the Y-coordinates of
              data points.
ZRAY          is an array containing the Z-coordinates of
              data points.
N             is the number of data points.
I1RAY, I2RAY, is the Delaunay triangulation of the points
    I3RAY     (XRAY, YRAY) calculated by the routine TRIANG.
NTRI          is the number of triangles in I1RAY, I2RAY 
              and I3RAY.
ZLVRAY        is an array containing the levels. 
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                                   
 
                         T R I P T S

The routine TRIPTS generates contours from triangulated data
without plotting.  Multiple curves  can be  returned for one
contour level.

The call is:  CALL TRIPTS (XRAY, YRAY, ZRAY, N, I1RAY, 
                           I2RAY, I3RAY, NTRI, ZLEV,
                           XPTRAY, YPTRAY, MAXPTS, IRAY,
                           MAXCRV, NCURVS)  level 0, 1, 2, 3

XRAY          is an array containing the X-coordinates of 
              data points.
YRAY          is an array containing the Y-coordinates of
              data points.
ZRAY          is an array containing the Z-coordinates of
              data points.
N             is the number of data points.
I1RAY, I2RAY, is the Delaunay triangulation of the points
    I3RAY     (XRAY, YRAY) calculated by the routine TRIANG.
NTRI          is the number of triangles in I1RAY, I2RAY 
              and I3RAY.
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.


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 LABDIG (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 value.  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 a 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  selects the algorithm  used for contour
filling, or modifies options for cell filling.

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

CKEY          is a  character  string  containing one of the 
              following keywords:
 = 'CONTUR'   defines  the algorithm  used for  contour fil-
              ling.  COPT  can  have  the  values 'CELL' and 
              'POLY'. The default value is COPT = 'CELL'.
 = 'CELL'     modifies the cell filling algorithm.  COPT can
              have the values  'BOTH',  'UPPER', 'LOWER' and 
              'NONE'.  If COPT = 'NONE',  the filling of the
              regions below and above  the level limits  are
              suppressed. If COPT = 'UPPER',  the filling of
              the region below the  lowermost  level is sup-
              pressed. COPT = 'LOWER' means that the filling
              of the  region  above  the uppermost  level is
              suppressed. By default, both regions described
              above are filled. 
 = 'COLOR'    modifies  the  calculation of colours  for cell
              filling.  COPT  can  have  the values  'LOWER',
              'MIDDLE' and 'UPPER'.  For COPT = 'LOWER',  the
              lower value of two neighbouring  levels is used
              for colour calculation, for COPT = 'UPPER', the
              upper value of two neighbouring levels is used,
              and for COPT = 'MIDDLE',  the mean value of the
              two levels is used for colour calculation.  The 
              default value is COPT = 'LOWER'.

                         C O N C L R

The routine CONCLR defines colours for filled contour lines.

The call is:  CALL CONCLR (NCRAY, N)           level 1, 2, 3

NCRAY         is an integer array containing colour numbers.
N             is the number of entries in NCRAY (<= 256).

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