                  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 plotted as a coloured rectangle  where the X- and Y-coor-
dinates determine  the position of the rectangle and the  Z-
coordinate defines the colour. Colours are calculated from a
scaled colour bar which is, by default,  arranged as a rain-
bow.

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.

Analog:       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 and CRVTRI plot
three-dimensional data points.  CURVE3 plots  random  points
from X-, Y- and Z-arrays, CURVY3  plots  points  as columns,
CURVX3 plots data points as rows,  CRVMAT plots  a  coloured 
surface according to a matrix while CRVTRI plots the surface
of the Delaunay triangulation of the points.

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)

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 the Delaunay triangulation of the  points
    I3RAY       (XRAY, YRAY) calculated  by the routine TRI-
                ANG.
NTRI            is the number  of triangles in  I1RAY, I2RAY 
                and I3RAY.

Notes:       -  CURVE3,  CURVY3  and  CRVMAT  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 routine CRVTRI can plot a smooth surface
                with interpolated colours  if the  statement
                CALL SHDMOD ('SMOOTH',  'SURFACE')  is  used
                before. For this case,  a raster format must
                be defined with METAFL.    
             -  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 plotfiles,  the plotting  of
                points with  the colour 0  can be suppressed
                with the routine NOBGD.
             -  The routines  CONMAT  and SURMAT are analogs
                to CRVMAT and  plot contours and surfaces of
                space.
             -  If  SHDMOD ('SMOOTH',  'SURFACE')  is called 
                before CRVTRI, the triangles will be plotted
                with interpolated colours.  For that case, a
                raster format is needed as output format.

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

IXDIM, IYDIM  are the  number  of data points  in the X- and
              Y-direction.

                         S H D M O D

Normally,  the routines  CURVE3,  CURVX3,  CURVY3 and CRVMAT 
plot coloured rectangles,  but a symbol 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 rou-
tines MARKER and HSYMBL.

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

COPT          is a character string that can have the values 
              'RECT' and 'SYMB'. 
                                     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.

                         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

                         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 plotfiles.

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
