                  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.  The following plotting routines  require special  gra-
phics devices that can display a wide range of colours, such
as a workstation or a PC with a VGA card. These devices will
be called  colour graphics  systems throughout this chapter.
A laserprinter with a PostScript emulation  can also be used
for 3-D colour graphics.

Notes:   - A colour graphics system can be  chosen with  the
           parameters 'CONS',  'XWIN' and 'XWIi' in the rou-
           tine METAFL where i is a  window number between 1
           and 5.  With the parameters  'POST'  and  'PSCL', 
           PostScript files can be created. 
         - The output of plot commands  to the screen may be
           buffered.  To send the buffer  to the screen, the
           statement CALL SENDBF must be used.
         - Up to  256 colours  can be displayed  at the same
           time. Colours are numbered in the range  0 to 255
           where the number is an  index in the  current co-
           lour table.  DISLIN provides  several colour tab-
           les.

11.2 X Window Terminals

X Window terminals are the usual  graphics displays on work-
stations. In DISLIN, the X Window emulation can be activated
with the keywords 'CONS',  'XWIN'  and 'XWIi' in the routine
METAFL  where i is a window number between 1 and 5.  For the
keyword 'CONS', the entire screen will be used for  graphics
output  while for the  other keywords,  smaller  windows are
created.  The keywords  'XWIN' and 'XWI1' have the same mea-
ning.  By default,  the position of windows depends upon the
window number. Window 1 is situated  in the lower right cor-
ner, window 2 in the upper right corner, window 3 in the up-
per left corner,  window 4 in the lower left corner and win-
dow 5 in the centre of the screen.  The position and size of
windows can be changed with the routines WINDOW and WINSIZ.

Notes:   - Normally,  a program using X Window emulation  is
           blocked  in the  termination  routine  DISFIN and
           waiting  for  a mouse button 2  event to continue
           program execution.  This behaviour of  DISLIN can
           be modified with the routine WINMOD.
         - To conserve  current  screen  and window colours,
           the number of  colours on  an X Window screen  is
           reduced in DISLIN from  256 to 129 colours.  This
           can be changed with the routine CLRMOD.
         - Backing store for an X graphics window can be en-
           abled with CALL X11MOD ('STORE'). Normally, back-
           ing store is done automatically by the X server. 
         - Multiple windows  can be used for graphics output
           on an X Window screen.

11.3 PostScript Files

PostScript files can be created  from within  DISLIN  if the
keywords 'POST' and  'PSCL' are used in METAFL. For the key-
word 'POST',  the greyscale table  'RGREY' will be preloaded
by  DISINI  and the graphics  will be plotted  with a  white
background. For the keyword 'PSCL',  the colour table 'RAIN'
will  be preloaded  and the graphics  will be plotted with a
black background. To create a colour PostScript file  with a
white background,  use the keyword  'POST' in METAFL and the
routine SETVLT to load a new colour table.

11.4 Clearing the Screen

                         E R A S E

The routine  ERASE  clears  the screen  of a colour graphics
system or of a graphics terminal.  In general,  this is done
by DISINI at the beginning of a plot.

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

11.5 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.6 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.7 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.
             -  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.

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

                         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.9 Elementary Image Routines

The  following routines allow  transfering of image data be-
tween windows, files and arrays.

                         I M G I N I

The  routine  IMGINI  initializes  transfering of image data
with the routines RPIXEL, RPIXLS, RPXROW, WPIXEL, WPIXLS and
WPXROW.

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

                         I M G F I N

The routine IMGFIN terminates transfering of image data with
the routines  RPIXEL,  RPIXLS,  RPXROW,  WPIXEL,  WPIXLS and
WPXROW.

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

                         R P I X E L

The routine RPIXEL reads one pixel from memory.

The call is:  CALL RPIXEL (IX, IY, ICLR)       level 1, 2, 3

IX, IY        is the position of the pixel in screen coordi-
              nates.
ICLR          is the returned colour value of the pixel.

                         W P I X E L

The routine WPIXEL writes one pixel into memory.

The call is:  CALL WPIXEL (IX, IY, ICLR)       level 1, 2, 3

IX, IY        is the position of the pixel in screen coordi-
              nates.
ICLR          is the new colour value of the pixel.

                         R P I X L S

The routine  RPIXLS copies colour values from a rectangle in
memory to an array.

The call is:  CALL RPIXLS (IRAY, IX, IY, NW, NH)
                                               level 1, 2, 3

IRAY          is a byte array containing the returned colour
              values.
IX, IY        contain the starting point in screen coordina-
              tes.
NW, NH        are the  width  and height of the rectangle in
              screen coordinates.

                         W P I X L S

The routine  WPIXLS  copies colour values from an array to a
rectangle in memory.

The call is:  CALL WPIXLS (IRAY, IX, IY, NW, NH)
                                               level 1, 2, 3

IRAY          is a byte array containing the colour values.
IX, IY        contain the starting point in screen coordina-
              tes.
NW, NH        are the  width  and height of the rectangle in
              screen coordinates.

                         R P X R O W

The routine  RPXROW  copies one line  of colour values  from
memory to an array.

The call is:  CALL RPXROW (IRAY, IX, IY, N)    level 1, 2, 3

IRAY          is a byte array containing the returned colour
              values.
IX, IY        contain the starting point in screen coordina-
              tes.
N             is the number of image data.

                         W P X R O W

The routine WPXROW copies colour values  from an  array to a
line in memory.

The call is:  CALL WPXROW (IRAY, IX, IY, N)    level 1, 2, 3

IRAY          is a byte array containing the  colour values.
IX, IY        contain the starting point in screen coordina-
              tes.
N             is the number of image data.

Note:         IMGINI  and  IMGFIN must be used with the rou-
              tines  RPIXEL,  WPIXEL, RPIXLS, WPIXLS, RPXROW
              and WPXROW.

                         R I M A G E

The routine RIMAGE copies an image from memory to a file.

The call is:  CALL RIMAGE (CFIL)               level 1, 2, 3

CFIL          is the name  of the  output file.  A new  file
              version  will be  created  for  existing files
              (see FILMOD).

Notes:     -  Images are stored with an  ASCII  header of 80
              bytes  length  followed  by the  binary  image
              data.
           -  A single image file can be displayed  with the
              routine  WIMAGE  or with  the  utility program
              DISIMG. A sequence of image files can be  dis-
              played with the utility program DISMOV.

                         W I M A G E

The routine WIMAGE copies an image from a file to memory.

The call is:  CALL WIMAGE (CFIL)               level 1, 2, 3

CFIL          is the name of the input file.

                         R T I F F

The routine  RTIFF  copies  an image  from memory to a file.
The image is stored in the device-independent TIFF format.

The call is:  CALL RTIFF (CFIL)                level 1, 2, 3

CFIL          is the  name  of the output file.  A new  file
              version  will be  created  for existing  files
              (see FILMOD).

Notes:     -  This image format can be used to export images
              created with DISLIN  into other software pack-
              ages  or to  transfer  them  to other computer
              systems.
           -  A TIFF file created by DISLIN can be displayed
              with the routine  WTIFF  or with  the  utility
              program DISTIF.

                         W T I F F

The routine WTIFF copies an TIFF file created by DISLIN from
a file to memory.

The call is:  CALL WTIFF (CFIL)                level 1, 2, 3

CFIL          is the name of the input file.
 
Note:         The position of the  TIFF  file and a clipping
              window can be defined with the routines TIFORG
              and TIFWIN.

                         T I F O R G

The routine  TIFORG  defines  the upper  left corner  of the
screen where the TIFF file is copied to.

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

NX, NY        is the upper left corner  in screen  coordina-
              tes.

                         T I F W I N

The routine  TIFWIN  defines a clipping window  of the  TIFF
file  that  can be  copied  with  the routine  WTIFF  to the
screen.

The call is:  CALL TIFWIN (NX, NY, NW, NH)     level 1, 2, 3

NX, NY        is the upper left corner  of the clipping win-
              dow in pixels.
NW, NH        are the width and height  of the clipping win-
              dow in pixels.

                         R P N G

The routine RPNG copies an image from memory to a PNG file.

The call is:  CALL RPNG (CFIL)                 level 1, 2, 3

CFIL          is  the name  of the  output file.  A new file
              version  will be  created  for existing  files 
              (see FILMOD).

                         R B F P N G

The routine  RBFPNG  copies an image  from memory  as a  PNG 
file to a buffer.

The call is:  CALL RBFPNG (CBUF, NMAX, N)      level 1, 2, 3

CBUF          is  a  character  buffer  where  the  image is 
              copied to in PNG format.
NMAX          defines how many bytes can be  copied to CBUF.
              If NMAX = 0,  the size of the  PNG file is re-
              turned  in N without copying the  PNG  file to
              CBUF. 

N             is the  returned length of the buffer. N <= 0, 
              if an error occurs.

                         R P P M

The routine RPPM copies an image from memory to a PPM file.

The call is:  CALL RPPM (CFIL)                 level 1, 2, 3

CFIL          is the name  of the  output file.  A new  file 
              version  will be  created  for existing  files 
              (see FILMOD).


11.10 Multiple Windows on X11 and Windows Terminals

The following routines allow programs to create up to 5 win-
dows for graphics output on an X Window terminal. Note, that
multiple windows can be used with X Window emulation but are
not compatible with other file formats in DISLIN.

                         O P N W I N

The routine OPNWIN creates a new window for graphics  output
on the screen.

The call is:  CALL OPNWIN (ID)                 level 1, 2, 3

ID            is the window number between 1 and 5.  Normal-
              ly,  window 1  will be  created  in the  lower
              right corner, window 2 in the upper right cor-
              ner, window 3 in the  upper left corner,  win-
              dow 4 in the  lower left  corner  and window 5
              in the center of the screen.

Notes:     -  The file format must be set to X Window emula-
              tion in the routine METAFL (i.e. with the key-
              word 'XWIN').
           -  The size and position of windows can be  chan-
              ged with the routines WINDOW and WINSIZ.
           -  Windows can be closed  and  selected  with the
              routines CLSWIN and SELWIN.
           -  A created window with OPNWIN is selected auto-
              matically for graphics output.
           -  The routine  WINMOD  affects  the handling  of
              windows in the termination routine DISFIN.

                         C L S W I N

The routine CLSWIN closes a window created with OPNWIN.

The call is:  CALL CLSWIN (ID)                 level 1, 2, 3

ID            is the window number between 1 and 5.

                         S E L W I N

The routine  SELWIN selects a window on the screen where the
following graphics output will be sent to.

The call is:  CALL SELWIN (ID)                 level 1, 2, 3

ID            is the window number between 1 and 5.

                          W I N I D

The routine  WINID  returns the ID of the currently selected
window.

The call is:  CALL WINID (ID)                  level 1, 2, 3

ID            is the returned window number.

                         W I N T I T

The routine WINTIT changes the window title of the currently
selected window.

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

CSTR  is a character string containing the new window title.

11.11 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.12 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.13 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
