                  Chapter 11: 3-D Colour Graphics

11.1 Introduction

This chapter presents subroutines  that plot coloured surfa-
ces in three dimensions.  Coloured surfaces  are easy to in-
terpret and show the full range of data points. A data point
is normally  plotted  as a coloured  rectangle  where the X- 
and Y-coordinates determine  the position  of the  rectangle
and the  Z-coordinate defines the colour. Colours are calcu-
lated  from a  scaled  colour bar which is,  by default, ar-
ranged as a rainbow.

11.2 Plotting Coloured Axis Systems

                         G R A F 3

The routine  GRAF3  plots a 3-D axis system where the Z-axis
is plotted as a colour bar.

The call is:  CALL GRAF3 (XA, XE, XOR, XSTEP, YA, YE, YOR,
                                  YSTEP, ZA, ZE, ZOR, ZSTEP)

XA, XE        are the lower and upper limits of the X-axis.
XOR, XSTEP    are the first  X-axis label  and the step  be-
              tween labels.
YA, YE        are the lower and upper limits of the Y-axis.
YOR, YSTEP    are the first  Y-axis label  and the step  be-
              tween labels.
ZA, ZE        are the lower and upper limits of the Z-axis.
ZOR, ZSTEP    are the first  Z-axis label  and the step  be-
              tween labels.

Note:         GRAF3 must be called from level 1 and sets the
              level to 3. For additional notes,  the user is
              referred to the routine GRAF in chapter 4.

11.3 Secondary Colour Bars

GRAF3 plots a vertical colour bar on the right side of a 3-D
axis system  which can be shifted  with the routines  VKXBAR
and  VKYBAR  or suppressed with the routine  NOBAR.  To plot
horizontal  colour bars  at global positions,  the  routines
ZAXIS and ZAXLG can be used. ZAXIS plots a linearly and ZAX-
LG a logarithmically scaled colour bar.

The call is:  CALL ZAXIS (A, B, OR, STEP, NL, CSTR, IT, 
                          NDIR, NX, NY)        level 1, 2, 3
A, B          are the  lower  and upper limits of the colour
              bar.
OR, STEP      are the  first  label and the step between la-
              bels.
NL            is the length  of the colour bar in plot coor-
              dinates.
CSTR          is  a  character  string  containing  the axis
              name.
IT            indicates how ticks,  labels and the axis name
              are plotted. If IT = 0,  they are plotted in a
              clockwise direction. If IT = 1, they are plot-
              ted in a counter-clockwise direction.
NDIR          defines  the direction  of the colour bar.  If
              NDIR = 0,  a vertical colour bar will be plot-
              ted; if NDIR = 1, a horizontal colour bar will
              be plotted.
NX, NY        are the  plot  coordinates  of the  lower left
              corner.

Analogue:     ZAXLG  plots  a logarithmically  scaled colour
              bar.

Note:         The user is referred to the notes on secondary
              axes in chapter 4.

11.4 Plotting Data Points

The routines  CURVE3,  CURVX3,  CURVY3,  CRVMAT,  CRVTRI and
CRVQDR plot three-dimensional data points. CURVE3 plots ran-
dom  points from X-, Y- and Z-arrays, CURVY3 plots points as
columns,  CURVX3 plots data points as rows and  CRVMAT plots
a coloured surface according to a matrix. The routines  CRV-
TRI and CRVQDR plot  triangles  and quadrangles  as they are
often used in finite element methods.

The calls are:  CALL CURVE3 (XRAY, YRAY, ZRAY, N)    level 3
                CALL CURVX3 (XRAY, Y, ZRAY, N)
                CALL CURVY3 (X, YRAY, ZRAY, N)
                CALL CRVMAT (ZMAT, IXDIM, IYDIM, IXP, IYP)
                CALL CRVTRI (XRAY, YRAY, ZRAY, N,
                             I1RAY, I2RAY, I3RAY, NTRI)
                CALL CRVQDR (XRAY, YRAY, ZRAY, N)
 
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.
X               is the X-pos. of a column of data points.
Y               is the Y-position of a row of data points.
ZMAT            is a matrix of the dimension  (IXDIM, IYDIM)
                containing  Z-coordinates.  The  coordinates
                correspond  to a linear grid  that  overlays
                the axis system.  If XA,  XE,  YA and YE are
                the axis limits in  GRAF3  or values defined
                with the  routine  SURSZE,  the relationship
                between the grid points and  the matrix ele-
                ments  can be described by the formula:

                ZMAT(I,J) = F(X,Y) where

                X = XA + (I - 1) * (XE - XA) / (IXDIM - 1),
                                            I = 1,...,IXDIM
                Y = YA + (J - 1) * (YE - YA) / (IYDIM - 1),
                                            J = 1,...,IYDIM.

IXDIM, IYDIM    define the dimension of ZMAT (>= 2).
IXP, IYP        are  the  number of  interpolation steps be-
                tween grid lines (>= 1). CRVMAT can interpo-
                late points linearly.
I1RAY, I2RAY,   is a  triangulation  of  the  points  (XRAY,  
 I3RAY          YRAY).  A  Delaunay  triangulation  of  data 
                poins can for example  calculated  with  the
                routine TRIANG.
NTRI            is the number  of triangles in  I1RAY, I2RAY 
                and I3RAY.

Notes:       -  The routine above must be called after GRAF3
                from level 3.
             -  The size  of coloured  rectangles can be de-
                fined with the routine SETRES  or calculated
                automatically by  DISLIN  using  the routine
                AUTRES.
             -  The  routines  CRVTRI  and  CRVQDR  can plot 
                smooth surfaces with interpolated colours if
                the  statement CALL SHDMOD ('SMOOTH',  'SUR-
                FACE') is used before. For this case, a ras-
                ter format must be defined with METAFL.    
             -  For CRVQDR,  the data  points  describe  the
                corners of the quadrangles:  the first  four
                points the first quadrangle,  the next  four
                points the next  quadrangle, and so on.  The
                number of quadrangles is N / 4.
             -  Z-coordinates  that lie outside  of the axis
                scaling will be plotted with the colour 0 if
                they  are smaller than the lower  limit,  or
                with the colour 255 if they are greater than
                the upper  limit.  To reduce  computing time
                and the size of plot files, the plotting  of
                points with  the colour 0  can be suppressed
                with the routine NOBGD.
             -  The routines  CONMAT  and SURMAT are analogy
                to CRVMAT and  plot contours and surfaces of
                space.

11.5 Parameter Setting Routines

                         S E T R E S

SETRES  defines  the size  of rectangles plotted by  CURVE3,
CURVY3 and CRVMAT.

The call is:  CALL SETRES (NPB, NPH)           level 1, 2, 3

NPB, NPH      are the width and height of rectangles in plot
              coordinates (> 0).
                                             Default: (1,1).

                         A U T R E S

With a call to AUTRES,  the size of coloured rectangles will
be automatically calculated by GRAF3 or CRVMAT.

The call is:  CALL AUTRES (IXDIM, IYDIM)       level 1, 2, 3

IXDIM, IYDIM  are the number of data points in the X- and Y-
              direction, or (0, 0). If IXDIM = 0 and IYDIM =
              0,  CRVMAT  plots  rectangles  between  neigh-
              bouring data points.  This is useful for loga-
              rithmic axes, where the rectangles should have
              a different size. A negative value can be used
              for a logartithmic axis scaling, where the ma-
              trix in CRVMAT contains already a  logarithmic
              grid. 

                         S H D M O D

Normally,  the routines  CURVE3,  CURVX3,  CURVY3 and CRVMAT 
plot coloured rectangles,  but a symbol or pixel mode can be
enabled with the routine  SHDMOD.  The symbols  used  by the
routines above and  the size of the symbols  can be set with
the routines MARKER and HSYMBL.  Pixel mode can only be used
for screen and image output. 

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

COPT          is a character string that can have the values 
              'RECT', 'SYMB' and 'PIXE'. 
                                     Default: COPT = 'RECT'.

                         A X 3 L E N

The routine  AX3LEN  defines  the axis lengths of a coloured
axis system.

The call is:   CALL AX3LEN (NXL, NYL, NZL)     level 1, 2, 3

NXL, NYL, NZL  are the axis lengths in plot coordinates.

                         P O S B A R

The routine POSBAR sets the  position of colour bars. By de-
fault, colour bars are plotted in a vertical  direction near
the right Y-axis of an axis system.

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

COPT          is a character value defining  the position of
              colour bars.
 = 'FIXED'    means  that the  colour bar  is plotted  in  a
              vertical direction near the right Y-axis. 
 = 'RIGHT'    has  nearly  the  same meaning  as the keyword 
              'FIXED',  but the colour bar is  automatically 
              moved  if labels and  an axis title is plotted
              at the right Y-axis.
 = 'TOP'      means that the colour bar is plotted above the
              axis system in a horizontal direction.
 = 'BOTTOM'   means that the colour bar is plotted below the
              axis system in a horizontal direction.
 = 'LEFT'     means that the colour bar is  plotted  on  the 
              left side of the axis system.
                                     Default COPT = 'FIXED'.

                         J U S B A R

JUSBAR defines alignment of colour bars.

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

COPT          is a character value defining the alignment of
              colour bars.
 = 'START'    means  that the  colour bar  is plotted at the 
              beginning of the X- or Y-axis.
 = 'CENTER'   means that the colour bar is centred at the X-
              or Y-axis.
 = 'END'      means that the colour bar  is justified at the
              end of the X- or Y-axis.
                                     Default COPT = 'START'.

                         W I D B A R

The routine WIDBAR defines the width of a colour bar.

The call is:  CALL WIDBAR (NZB)                level 1, 2, 3

NZB           is the width in plot coordinates.
                                            Default NZB = 85

                         F R M B A R

The routine  FRMBAR defines the thickness  of frames  around
colour bars.

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

N             is the thickness in plot coordinates.
                                               Default N = 0

                         S P C B A R

The routine SPCBAR defines the space between colour bars and
axis systems.

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

N             is the space in plot coordinates.
                                              Default N = 85

                         V K X B A R

The routine  VKXBAR  defines  horizontal  shifting of colour
bars. The distance between the colour bar  and the axis sys-
tem is, by default, 85 plot coordinates.

The call is:  CALL VKXBAR (NVFX)               level 1, 2, 3

NVFX          is an integer  that defines  the shifting.  If
              NVFX is positive, the colour bar will be shif-
              ted right;  if NVFX is negative the colour bar
              will be shifted left.
                                           Default: NVFX = 0

                         V K Y B A R

The routine  VKYBAR  defines  a vertical  shifting of colour
bars.

The call is:  CALL VKYBAR (NVFY)               level 1, 2, 3

NVFY          is an  integer  that defines  the shifting. If
              NVFY is positive, the colour bar will be shif-
              ted up;  if  NVFY is negative,  the colour bar
              will be shifted down.
                                           Default: NVFY = 0

                         N O B A R

The routine NOBAR instructs  DISLIN to suppress the plotting
of colour bars.

The call is:  CALL NOBAR                       level 1, 2, 3

                         C O L R A N

This routine  defines  the range of  colours used for colour
bars. By default, the range is 1 to 254.

The call is:  CALL COLRAN (NCA, NCE)           level 1, 2, 3

NCA, NCE      are colour numbers in the range 1 to 254.
                                          Default: (1, 254).

                          N O B G D

With a call  to the routine  NOBGD,  the plotting  of points
with the colour 0 will be suppressed.  This reduces plotting
time and the size of plot files.

The call is:  CALL NOBGD                       level 1, 2, 3


                         E X P Z L B

The routine EXPZLB expands the numbering of a logarithmical-
ly scaled Z-axis to the next order of magnitude that lies up
or down the axis limits.  The scaling of the colour bar will
not be changed.  This routine is useful if the range of  the
Z-axis scaling is smaller than 1 order of magnitude.

The call is:  CALL EXPZLB (CSTR)               level 1, 2, 3

CSTR          is a character string  defining  the expansion
              of the Z-axis numbering.
  = 'NONE'    means that the numbering will not be expanded.
  = 'FIRST'   means  that  the numbering  will  be  expanded
              downwards.
  = 'BOTH'    means  that  the numbering  will  be  expanded
              down- and upwards.
                                     Default: CSTR = 'NONE'.

11.6 Elementary Plot Routines

The following routines plot coloured rectangles and pie sec-
tors. They use the hardware features  of a  colour  graphics
system or PostScript printer.

                         R E C F L L

The routine  RECFLL plots a coloured rectangle where the po-
sition is determined by the upper left corner.

The call is:  CALL RECFLL (NX, NY, NB, NH, NCOL) 
                                               level 1, 2, 3

NX, NY        are the  plot  coordinates  of the  upper left
              corner.
NB, NH        are the width and height in plot coordinates.
NCOL          is a colour value.

                          P O I N T

The routine  POINT  plots  a coloured  rectangle  where  the
position is determined by the centre.

The call is:  CALL POINT (NX, NY, NB, NH, NCOL)
                                               level 1, 2, 3

NX, NY        are the plot coordinates of the centre point.
NB, NH        are the width and height in plot coordinates.
NCOL          is a colour value.

                         R L P O I N

The routine  RLPOIN  plots  a  coloured rectangle  where the
position is specified in user coordinates.

The call is:  CALL RLPOIN (X, Y, NB, NH, NCOL)    level 2, 3

Note:         RLPOIN  clips rectangles  at the borders of an
              axis system.

                         S E C T O R

The routine SECTOR plots coloured pie sectors.

The call is:  CALL SECTOR (NX, NY, NR1, NR2, ALPHA, BETA,
                           NCOL)               level 1, 2, 3
NX, NY        are the plot coordinates of the centre point.
NR1           is the interior radius.
NR2           is the exterior radius.
ALPHA, BETA   are the start and  end angles measured in  de-
              grees in a counter-clockwise direction.
NCOL          is a colour value.

Example:      CALL  SECTOR (100, 100, 0, 50, 0., 360., NCOL)
              plots  a  circle  around  the centre (100,100)
              with the radius 50 and the colour NCOL.

                          R L S E C

The routine  RLSEC plots coloured pie sectors where the cen-
tre and the radii are specified in user coordinates.

The call is:  CALL RLSEC (X, Y, R1, R2, ALPHA, BETA, NCOL)
                                                  level 2, 3

Notes:     -  For the conversion  of the radii to plot coor-
              dinates, the scaling of the X-axis is used.
           -  Sectors plotted by  RLSEC  will not be cut off
              at the borders of an axis system.


11.7 Conversion of Coordinates

The function  NZPOSN and the subroutine  COLRAY convert user
coordinates to colour values.

                         N Z P O S N

The function NZPOSN converts a Z-coordinate to a colour num-
ber.

The call is:  ICLR = NZPOSN (Z)                      level 3

Note:         If Z lies outside of the axis limits  and Z is
              smaller than the lower limit,  NZPOSN  returns
              the value 0  and the routine returns the value
              255 if Z is greater than the upper limit.

                         C O L R A Y

The routine  COLRAY  converts an array  of Z-coordinates to
colour values.

The call is:  CALL COLRAY (ZRAY, NRAY, N)           level 3

ZRAY          is an array of Z-coordinates.
NRAY          is an array of  colour numbers  calculated by
              COLRAY.
N             is the number of coordinates.

11.8 Example

            PROGRAM EX11_1         ! 3-D Colour Plot
            PARAMETER (N=100)
            DIMENSION ZMAT(N,N)

            FPI=3.1415927/180.
            STEP=360./(N-1)
            DO I=1,N
              X=(I-1.)*STEP
              DO J=1,N
                Y=(J-1.)*STEP
                ZMAT(I,J)=2*SIN(X*FPI)*SIN(Y*FPI)
              END DO
            END DO

            CALL METAFL('POST')
            CALL DISINI
            CALL PAGERA
            CALL PSFONT('Times-Roman')

            CALL TITLIN('3-D Colour Plot of the Function',1)
            CALL TITLIN('F(X,Y) = 2 * SIN(X) * SIN(Y)',3)

            CALL NAME('X-axis','X')
            CALL NAME('Y-axis','Y')
            CALL NAME('Z-axis','Z')

            CALL INTAX
            CALL AUTRES(N,N)
            CALL AXSPOS(300,1850)
            CALL AX3LEN(2200,1400,1400)

            CALL GRAF3(0.,360.,0.,90.,0.,360.,0.,90.,
           *                           -2.,2.,-2.,1.)
            CALL CRVMAT(ZMAT,N,N,1,1)

            CALL HEIGHT(50)
            CALL PSFONT('Palatino-BoldItalic')
            CALL TITLE
            CALL DISFIN
            END
