                 Chapter 5: Plotting Curves

This chapter describes how to plot  curves  with  lines  and
symbols.  Several curves  can be plotted  in one axis system
and can be differentiated by colour, line style and pattern.
Curve attributes can be plotted in a legend.

5.1 Plotting Curves

                         C U R V E

CURVE  connects  data points  with lines  or plots them with
symbols.

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

XRAY, YRAY    are arrays that contain X- and Y-coordinates.
              For a polar scaling, XRAY must hold the radial
              values and YRAY the  angular values  expressed
              in radians.
N             is the number of data points.

Notes:     -  CURVE must be called after  GRAF  from level 2
              or 3.
           -  By default, data points that lie outside of an
              axis system  are  listed  on the  screen.  The
              listing  can be  suppressed  with the  routine
              NOCHEK.
           -  For a logarithmic  scaling  of an axis,  CURVE
              suppresses the plotting of curves and prints a
              warning if some corresponding data coordinates
              have non positive values.  After the statement
              CALL NEGLOG (EPS),  where EPS is a small posi-
              tive floating point number, CURVE will use the
              value EPS for non positive values.
           -  CURVE suppresses  lines outside the borders of
              an axis system.  Suppressing  can be  disabled
              with  NOCLIP or the margins of suppression can
              be changed with GRACE.
           -  INCMRK determines if CURVE plots lines or sym-
              bols.
           -  When plotting several curves,  attributes such
              as colour and line style can be changed  auto-
              matically by  DISLIN  or directly by the user.
              The routine CHNCRV  defines  which  attributes
              are changed automatically.  The routines COLOR
              or  SETCLR are used to define colours,  SOLID,
              DOT,  DASH,  CHNDOT,  CHNDSH,  DOTL, DASHM and
              DASHL to define line styles and  MARKER to de-
              fine symbols plotted  with the routine  CURVE.
           -  Different  data interpolation  methods  can be
              chosen with POLCRV.

5.2 Plotting Legends

To differentiate multiple curves in an axis system,  legends
with text can be plotted.  DISLIN can store  up to 30  curve
attributes  such as  symbols,  thicknesses,  line styles and
colours and these can be incorporated in a legend.

Legends are created with the following steps:

       (1)   define a character variable used to store the
             lines of text in the legend
       (2)   initialize the legend
       (3)   define the lines of text
       (4)   plot the legend.

The corresponding routines are:

                         L E G I N I

LEGINI initializes a legend.

The call is:  CALL LEGINI (CBUF, NLIN, NMAX)   level 1, 2, 3

CBUF          is a  character  variable  used to  store  the
              lines of text in the legend. The variable must
              be defined by the user to have at least NLIN *
              NMAX characters.
NLIN          is the  number  of text  lines  in  the legend
              (<= 80).
NMAX          is the  number of  characters  in the  longest
              line of text (<= 132).

                         L E G L I N

LEGLIN stores lines of text for the legend.

The call is:  CALL LEGLIN (CBUF, CSTR, ILIN)   level 1, 2, 3

CBUF          see LEGINI.
CSTR          is a character string  that contains a line of
              text for the legend.
ILIN          is the number of the legend line between 1 and
              NLIN.

                         L E G E N D

LEGEND plots legends.

The call is:  CALL LEGEND (CBUF, NCOR)            level 2, 3

CBUF          see LEGINI.[0.3cm]
NCOR          indicates the position of the legend:
      =  1    is the lower left corner of the page.
      =  2    is the lower right corner of the page.
      =  3    is the upper right corner of the page.
      =  4    is the upper left corner of the page.
      =  5    is the lower left corner of the axis system.
      =  6    is the lower right corner of the axis system.
      =  7    is the upper right corner of the axis system.
      =  8    is the upper left corner of the axis system.
      =  9    means the left side  centered  at the middle
              of the page.
      = 10    means the right side centered  at the middle
              of the page.

Notes:        The following routines change the position and
              appearance  of a legend.  They must  be called
              after LEGINI except for the routines FRAME and
              LINESP.

           -  LEGTIT (CTIT) sets the title of the legend.
           -  LEGPOS (NX, NY) defines a global  position for
              the legend  where NX and NY are the plot coor-
              dinates of the upper left corner. After a call
              to LEGPOS, the second parameter in LEGEND will
              be ignored.
           -  NLX = NXLEGN (CBUF)   and  NYL = NYLEGN (CBUF)
              return the length  and the height  of a legend
              in plot coordinates.
           -  FRAME (NFRA) defines the thickness  of a frame
              plotted around a legend.
           -  LINESP (XF)  changes the spacing of lines in a
              legend.
           -  LEGCLR  retains the same colour for curves and
              lines of text in the legend.
           -  The statement   CALL MIXLEG  enables  multiple
              text lines in legends. By default, the charac-
              ter '/' is used as a newline character but can
              be changed with the routine SETMIX.
           -  LEGBGD (NCLR)  sets  the background  colour of  
              legends.  The default value -1 means,  that no
              background is plotted. 
 
                         L E G P A T

The routine  LEGPAT  stores  curve attributes plotted in le-
gends. Normally, this is done automatically by routines such
as CURVE and BARS.

The call is:  CALL LEGPAT (ITYP, ITHK, ISYM,   
                           ICLR, IPAT, ILIN)   level 1, 2, 3

ITYP          is the line style  between -1 and 7  (see LIN-
              TYP).  IF ITYP = -1,  no line will  be plotted
              in the legend line.
ITHK          defines the thickness of lines (> 0).
ISYM          is the  symbol number between   -1 and 21.  If
              ISYM = -1,  no symbol  will be plotted  in the
              legend line.
ICLR          is a colour value.  If ICLR = -1,  the current
              colour will be used.
IPAT          is the shading pattern (see SHDPAT). If IPAT =
              -1,  no pattern  will be plotted in the legend
              line.
ILIN          is the legend line between 1 and NLIN.

Notes:     -  The routine LEGPAT is useful to create legends
              without calls to CURVE.
           -  LEGPAT must be called after LEGINI.

                         L E G T Y P

Legend  entries can be plotted in vertical or horizontal di-
rection or in table form depending on the option in LEGTYP.
The routine must be called before LEGINI.

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

COPT          is a character string that can have the values
              'VERT', 'HORI' and 'TABLE'.
                                            Default: 'VERT.'

                         L E G T B L

This routine defines the number of  columns in table legends
and the direction in which the legend entries are plotted.

The call is:  CALL LEGTBL (N, COPT)            level 1, 2, 3

N             is the number of columns.

COPT          is a character string that can have the values
              'VERT' and 'HORI'.
                                       Default: (3, 'VERT').


                         L E G O P T

The routine LEGOPT modifies the appearance of legends.

The call is:  CALL LEGOPT (XF1, XF2, XF3)      level 1, 2, 3

XF1           is a multiplier for the length  of the pattern
              field. The length is XF1 * NH, where NH is the
              current  character height.  If  XF1 = 0.,  the
              pattern field will be suppressed.
XF2           is a multiplier for the  distance  between le-
              gend frames and text. The distance is XF2 * NH
              * XSPC, where XSPC is  the spacing between le-
              gend lines (see LINESP).
XF3           is a multiplier for the spacing between multi-
              ple text lines.  The space is XF3 * NH * XSPC.
                                   Default: (4.0, 0.5, 1.0).

                         L E G V A L

The routine LEGVAL modifies the appearance of legends.

The call is:  CALL LEGVAL (X, COPT)            level 1, 2, 3

COPT          is a character string that can have the values

'PATTERN'     sets the length of the pattern field to  X*NH,
              where NH is the current charater size.
'MARGIN'      sets the margin between legend  frame and text
              to X * NH * XLINSP,  where XLINSP  is the cur-
              rent line space.
'LINE'        sets the spacing between  multiple  text lines
              to X * NH * XLINSP.
'SYMBOL'      defines the size of symbols with X * NH.
'HSPACE'      sets the space between  legend  columns to X *
              NH.
'DISTANCE'    sets the horizontal space between the  pattern
              and the text fields to X * NH.
                                Defaults: (4.0, 'PATTERN'),
                                          (0.5, 'MARGIN'),
                                          (1.0, 'LINE'), 
                                          (0.8, 'SYMBOL'),
                                          (2.0, 'HSPACE'),
                                          (1.0, 'DISTANCE').

Notes:      - If X has a negative value, it's positive value
              is  interpreted  as  plot units  and not  as a
              multiplier.
            - LEGVAL should be called after LEGINI.

                         L E G S E L

The routine  LEGSEL selects legend lines that are plotted by
LEGEND.

The call is:  CALL LEGSEL (IRAY, N)            level 1, 2, 3

IRAY          is an integer array that contains legend lines
              between 1 and NLIN,  where NLIN is the parame-
              ter in LEGINI.
N             is the number of elements in IRAY.  If N = -1,
              all legend lines are plotted. 
                                             Default: N = -1

5.3 Curve Fitting

                         L I N F I T

LINFIT  plots a straight line  that  has the  best  fit to a
series of data points.

The call is:  CALL LINFIT (XRAY, YRAY, N, A, B, R, COPT)      
                                                  Level 2, 3

XRAY, YRAY    are arrays that contain X- and Y-coordinates.
N             is the number of data points.
A, B          are the returned values of the calculated line
              Y = A * X + B.
R             is the returned correlation coefficient of the
              fit between -1.0 and 1.0.  A value around zero
              means no correlation, a value near -1.0 or 1.0
              means good correlation.
COPT          is a character string that can have the values
              'NONE',  'ALL' and 'LINE'. 'NONE'  means  that
              just the values A, B and R are calculated. 
              Nothing is plotted. For that case  LINFIT  can
              also be called in the levels 0 and 1. 
              'LINE' means that the straight line is plotted
              and  'ALL' that the straight line and the data 
              points are plotted.  

5.4 Plotting Shaded Areas between Curves

                         S H D C R V

SHDCRV plots a shaded area between two curves.

The call is:  CALL SHDCRV (X1RAY, Y1RAY, N1,      
                           X2RAY, Y2RAY, N2)      level 2, 3       

X1RAY, Y1RAY  are arrays  with  the X- and Y-coordinates  of
              the  first curve.  Values are not  changed  by
              SHDCRV.
N1            is the number of points in the first curve.
X2RAY, Y2RAY  are arrays with the  X- and  Y-coordinates  of
              the second  curve.  Values are not  changed by
              SHDCRV.
N2            is the number of points in the second curve.

Notes:     -  The maximum  number of  data points  cannot be
              greater than 25000 in Fortran 77 programs.
              There is no restriction for Fortran 90 and C.
           -  Different  shading  patterns  can be  selected
              with SHDPAT. The pattern number will automati-
              cally be incremented by 1 after a call to SHD-
              CRV.
           -  Legends may be plotted for shaded curves.
           -  The routine  NOARLN will suppress border lines
              around shaded areas.

5.5 Plotting Error Bars

                         E R R B A R

The routine ERRBAR plots error bars.

The call is:  CALL ERRBAR (XRAY, YRAY, E1RAY, E2RAY, N)
                                                  level 2, 3

XRAY, YRAY    are arrays  that contain the  X- and Y-coordi-
              nates.
E1RAY, E2RAY  are arrays that contain the errors. Lines will
              be drawn from YRAY - E1RAY to YRAY + E2RAY.
N             is the number of data points.

Notes:     -  Horizontal bars will be drawn after  CALL BAR-
              TYP ('HORI').
           -  A symbol can be selected with  MARKER  and the
              symbol size with HSYMBL.


5.6 Vector Fields

                         F I E L D

The routine  FIELD  plots a vector field where the start and
end points  of  the  vectors  are  already  calculated.  The
vectors are displayed as arrows.

The call is:  CALL FIELD (X1RAY, Y1RAY, X2RAY, Y2RAY, N, 
                          IVEC)                 - level 2, 3

X1RAY, Y1RAY  are arrays that contain  the  X- and Y-coordi-
              nates of the start points. 
X2RAY, Y2RAY  are arrays that contain  the  X- and Y-coordi-
              nates of the end points. 
N             is the number of vectors.
IVEC          is a four digit number that specifies the vec-
              tor (see VECTOR).

                         V E C F L D

The routine VECFLD plots a vector field of given vectors and
positions. The vectors are displayed as arrows.

The call is:  CALL VECFLD (XVRAY, YVRAY, XPRAY, YPRAY, N, 
                                           IVEC)  level 2, 3

XVRAY, YVRAY  are arrays  that contain  the X- and Y-coordi-
              nates of the vectors. 
XPRAY, YPRAY  are arrays  that contain  the X- and Y-coordi-
              nates of the start points. 
N             is the number of vectors.
IVEC          is an integer  that specifies  the form of the 
              arrows (see VECTOR).

Notes:      - The  length  of  the  arrows  is automatically 
              scaled by  DISLIN in the routine VECFLD.  This
              behaviour can be changed with the routine VEC-
              OPT,  that may  also modify  the appearance of 
              arrows.
            - The vectors can be scaled  with different col-
              ours if the routine  VECCLR  is called  before
              with the parameter -2. If VECFLD and FIELD are
              called after GRAF,  the minimum and maximum of
              the vector  lengths  are used for colour scal-
              ing.  If VECFLD  and  FIELD  are  called after 
              GRAF3,  the Z-scaling  in  GRAF3  is used  for 
              calculating colours.

                         V E C M A T

The routine VECMAT plots a vector field on a regular grid.

The call is:  CALL VECMAT (XVMAT, YVMAT, NX, NY, XPRAY, 
                           YPRAY, IVEC)           level 2, 3

XVMAT, YVMAT  are arrays of the dimension (NX, NY) that con-
              tain  the X- and Y-coordinates of the vectors. 
NX, NY        define the dimension of XVMAT and YVMAT. 
XPRAY, YPRAY  are arrays of the  dimensions  NX und NY  that
              define the grid in the X/Y plane.
IVEC          is an integer  that specifies  the form of the 
              arrows (see VECTOR).

Note:         See the notes for VECFLD.

                         S T R E A M

The routine STREAM plots streamlines of a  vector field on a
regular grid.

The call is:  CALL STREAM (XVMAT, YVMAT, NX, NY, XPRAY, 
                          YPRAY, XSRAY, YSRAY, N) level 2, 3

XVMAT, YVMAT  are arrays of the dimension (NX, NY) that con-
              tain  the X- and Y-coordinates of the vectors. 
NX, NY        define the dimension of XVMAT and YVMAT. 
XPRAY, YPRAY  are arrays  of the  dimensions NX und NY  that
              define the grid in the X/Y plane.
XSRAY, YSRAY  are arrays  of the  dimension  N that  contain 
              starting  points  of the  streamlines.  If  no 
              starting   points  are  given,   evenly-spaced 
              streamlines are  automatically plotted by DIS-
              LIN. 
N             is the number of statrting points (N >= 0).

Notes:      - The integration method in STREAM can be chang-
              ed with  the  routine  STMMOD.  By default,  a
              Runge-Kutta 2nd order method is used.
            - The behaviour of  streamlines  can be modified 
              with the routines STMOPT and STMVAL.

                         S T M P T S

The routine STMPTS returns a calculated streamline of a vec-
tor field on a regular grid.

The call is:  CALL STMPTS (XVMAT, YVMAT, NX, NY, XPRAY, 
              YPRAY, X0, Y0, XRAY, YRAY, NMAX, N) level 2, 3

XVMAT, YVMAT  are arrays of the dimension (NX, NY) that con-
              tain  the X- and Y-coordinates of the vectors. 
NX, NY        define the dimension of XVMAT and YVMAT. 
XPRAY, YPRAY  are arrays  of the  dimensions NX und NY  that
              define the grid in the X/Y plane.
X0, Y0        define the starting point.
XRAY, YRAY    are arrays  of the  dimension NMAX  that  will 
              contain the calculated streamline.
NMAX          is the dimension of XRAY and YRAY.
N             is the  returned  number of points in XRAY and
              YRAY.

Note:         See the notes for STREAM.

                         S T M T R I

The routine STMTRI plots streamlines of a  vector field on a
triangular grid.

The call is:  CALL  STMTRI (XVRAY, YVRAY, XPRAY, YPRAY, N,
                           I1RAY, I2RAY, I3RAY, NTRI, XSRAY,
                           YSRAY, NRAY)           level 2, 3

XVRAY, YVRAY  are arrays of the dimension N that contain the
              X- and Y-coordinates of the vectors. 
XPRAY, YPRAY  are arrays of the dimension N that contain the
              positions of the vectors.
N             is the number of vectors.
I1RAY, I2RAY, is a triangulation of the points in XPRAY  and
   I3RAY      YPRAY. 
NTRI          is the number of triangles in I1RAY, I2RAY and
              I3RAY.
XSRAY, YSRAY  are arrays of the dimension  NRAY that contain 
              starting  points  of the  streamlines.  If  no 
              starting   points  are  given,   evenly-spaced 
              streamlines are  automatically plotted by DIS-
              LIN. 
NRAY          is the number of starting points (NRAY >= 0).

                         L I C P T S

The routine  LICPTS  calculates a  Line Integral Convolution
(LIC) image of a vector field.

The call is:  CALL LICPTS (XVMAT, YVMAT, NX, NY, ITMAT, 
                           IWMAT, WMAT)        level 1, 2, 3

XVMAT, YVMAT  are arrays of the dimension (NX, NY) that con-
              tain  the X- and Y-coordinates of the vectors. 
NX, NY        define the dimension of  XVMAT,  YVMAT, ITMAT,
              IWMAT and WMAT. 
ITMAT         is a texture array  of the dimension  (NX, NY)
              that is used for  the LIC algorithm.  A random
              texture  can be  calculated  with the  routine
              TXTURE.
IWMAT         is a working array of the dimension  (NX, NY).
              After the call to LICPTS,  IWMAT  contains the
              number  of hits  for image  pixels  covered by
              streamlines. 
WMAT          is  an  output array of the dimension (NX, NY) 
              that contains  the calculated LIC image.  WMAT
              contains  floating point numbers between 0 and
              255.                            
Notes:      - LICPTS  uses by  default  a fast LIC algorithm
              based on an idea  by Detlev Stalling and Hans-
              Christian Hege.  Some  parameters  of the fast 
              LIC  algorithm  can be  modified with the rou-
              tines LICMOD, STMOPT and STMVAL.
            - The  calculated  LIC  image can be plotted for 
              example with the routine CRVMAT.
          
                         T X T U R E

The routine TXTURE generates a random texture array that can
be passed to the routine LICPTS.

The call is:  CALL TXTURE (ITMAT, NX, NY)      level 1, 2, 3

ITMAT         is a returned  texture array  of the dimension
              (NX, NY). ITMAT contains random numbers in the
              range 0 to 255. 
NX, NY        define the dimension of ITMAT.
Note:         DISLIN uses the MINSTD random number generator 
              of  S.K. Park  and K.W. Miller for calculating 
              random numbers.  The returned array is identi-
              cal for all DISLIN distributions.


