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

                         S E T C L R

The routine  SETCLR  defines  the colour  used  for text and
lines.

The call is:  CALL SETCLR (NCOL)               level 1, 2, 3

NCOL      is a colour number in the range 0 to 255.
                                         Default: NCOL = 255

                         S E T R G B

The routine  SETRGB defines the  foreground colour specified
in RGB coordinates. SETRGB sets the nearest entry in the co-
lour table that matches the RGB coordinates. This means that
a colour will not be defined  exactly if it is not contained
in the colour table.
 
The call is:  CALL SETRGB (XR, XG, XB)         level 1, 2, 3

XR, XG, XB    are the  RGB  coordinates  of a  colour in the 
              range 0 to 1.

                         I N D R G B

The function  INDRGB returns the nearest entry in the colour 
table that matches given RGB coordinates.
 
The call is:  N = INDRGB (XR, XG, XB)          level 1, 2, 3

XR, XG, XB    are the  RGB coordinates  of a colour  in  the 
              range 0 to 1.
N             is the returned colour index.

                         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

                         S E T V L T

SETVLT selects a colour table.

The call is:  CALL SETVLT (CVLT)               level 1, 2, 3
CVLT          is a character string  that defines the colour
              table.
  = 'SMALL'   defines  a  small  colour table with the 8 co-
              lours:   1 = BLACK,    2 = RED,    3 =  GREEN, 
              4 = BLUE,  5 = YELLOW, 6 = ORANGE, 7 =  CYAN
              and 8 = MAGENTA.
  = 'VGA'     defines the  16 standard colours of a VGA gra-
              phics card.
  = 'RAIN'    defines  256  colours  arranged  in a  rainbow
              where 0 means black and 255 means white.
  = 'SPEC'    defines  256  colours  arranged  in a  rainbow
              where 0 means black and 255 means white.  This
              colour  table  uses  more  violet colours than
              'RAIN'.
  = 'GREY'    defines  256 grey scale colours  where 0 means
              black and 255 is white.
  = 'RRAIN'   is the reverse colour table of 'RAIN'.
  = 'RSPEC'   is the reverse colour table of 'SPEC'.
  = 'RGREY'   is the reverse colour table of 'GREY'.
  = 'TEMP'    defines a temperature colour table.

              The default colour table is  'RGREY' for Post-
              Script files  created with the keyword  'POST'
              in the routine METAFL, and otherwise 'RAIN'. 

                          M Y V L T

The routine MYVLT changes the current colour table.

The call is:  CALL MYVLT (XR, XG, XB, N)       level 1, 2, 3

XR, XG, XB    are arrays  containing  RGB coordinates in the
              range 0 to 1.
N             is the number of colour entries.

                         S E T I N D

The routine  SETIND  allows  the user  to change the current
colour table.

The call is:  CALL SETIND (INDEX, XR, XG, XB)  level 1, 2, 3
INDEX         is an index between  0 and 255.
XR, XG, XB    are the  RGB  coordinates  of a  colour in the
              range 0 to 1.

Sometimes,  it is easier to specify colours as HSV coordina-
tes where H is the hue, S the saturation and  V the value of
a colour.  The following routines  convert coordinates  from
the HSV to the RGB model and vice versa.

                         H S V R G B

The routine HSVRGB converts HSV coordinates to RGB coordina-
tes.

The call is:  CALL HSVRGB (XH, XS, XV, XR, XG, XB)
                                               level 1, 2, 3

XH, XS, XV    are the hue, saturation and value of a colour.
              XH  must be  in the range  0  to  360  degrees
              while  XS and XV can have values between 0 and
              1. In the HSV model, colours lie in a spectral
              order on a six-sided pyramid where red corres-
              ponds to the angle 0, green to 120 and blue to
              240 degrees.
XR, XG, XB    are the  RGB  coordinates  in the range 0 to 1
              calculated by HSVRGB.

                         R G B H S V

The routine RGBHSV converts RGB coordinates to HSV coordina-
tes.

The call is:  CALL RGBHSV (XR, XG, XB, XH, XS, XV)
                                               level 1, 2, 3

                         R E V S C R

The routine  REVSCR exchanges the colours with the indices 0
and 255.

The call is:  CALL REVSCR                      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 index in the range 0 to 255.

                          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 index in the range 0 to 255.

                         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 index between 0 and 255.

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
