                   Chapter 12: 3-D Graphics

This chapter describes routines for  3-D coordinate systems.
Axis systems, curves and surfaces  can be drawn from various
angular perspectives.  All 2-D plotting routines can be used
in a 3-D axis system.

12.1 Introduction

Three-dimensional objects must be plotted in a 3-D box which
is projected onto a two-dimensional region on the page.  The
3-D box contains an X-,  Y- and Z-axis with the Z-axis lying
in the vertical direction.  The units of the axes are called
absolute 3-D coordinates. They are abstract and have  no re-
lation  to any  physical units.  An axis system  is used  to
scale the  3-D box  with user coordinates  and to plot  axis
ticks, labels and names.

The position  and size of a  projected 3-D box  depends upon
the position  and size  of the region onto which  the box is
projected,  and for a  perspective  projection  on the point 
from which  the box is viewed.  The region  is determined by 
the routines  AXSPOS and  AXSLEN where the centre of the 3-D 
box will be projected onto the centre of the region.

                         A X I S 3 D

The routine  AXIS3D defines the lengths of the 3-D box.  For
the lengths,  any positive values  can be specified;  DISLIN
uses only  the ratio  of the  values  to calculate  the axis
lengths.

The call is:  CALL AXIS3D (X3AXIS, Y3AXIS, Z3AXIS)
                                               level 1, 2, 3

X3AXIS        is the length  of the  X-axis  in absolute 3-D
              coordinates (> 0).
Y3AXIS        is the length  of the  Y-axis  in absolute 3-D
              coordinates (> 0).
Z3AXIS        is the length  of the  Z-axis  in absolute 3-D
              coordinates (> 0).
                                       Default: (2., 2., 2.)

Note:         The lower  left corner  of the  3-D box is the
              point   (-X3AXIS/2, -Y3AXIS/2, -Z3AXIS/2);
              the upper right corner is the point
                      (X3AXIS/2 ,  Y3AXIS/2,  Z3AXIS/2).
              The centre point is (0., 0., 0.).

12.2 Defining View Properties

The following routines  define view properties such as view-
point, projection type,  target point,  view angle  and view 
orientation.

                         P R O J 3 D

The routine  PROJ3D defines perspective or orthographic pro-
jection.

The call is:  CALL PROJ3D (COPT)                     level 1

COPT          is a character string that can have the values
              'PERSPECTIVE' and 'ORTHO'.
                              Default: COPT = 'PERSPECTIVE'. 

                         V I E W 3 D

The routine VIEW3D defines the viewpoint. The viewpoint is a
point in space from which the 3-D box is observed and deter-
mines  how objects  are projected  onto a 2-D plane. Objects
will appear small if the viewpoint is far away. As the view-
point is moved closer  to the 3-D box,  the objects will ap-
pear larger.

The call is:  CALL VIEW3D (XVU, YVU, ZVU, CVU) level 1, 2, 3

XVU, YVU, ZVU define the position of the viewpoint. If CVU =
              'ABS',  the parameters  must contain  absolute
              3-D coordinates,  if  CVU = 'USER',  they must
              contain user coordinates and if CVU = 'ANGLE',
              the viewpoint  must be specified by two angles
              and a radius. In the latter case, XVU is a ro-
              tation angle,  YVU  is the angle  between  the
              line from  the viewpoint to the  centre of the
              3-D box  and the horizontal direction  and ZVU
              is the distance of the viewpoint from the cen-
              tre of the 3-D box. XVU and YVU must be speci-
              fied in degrees  and ZVU in absolute 3-D coor-
              dinates.
CVU           is a character string  defining the meaning of
              XVU, YVU and ZVU.
              Def: (2*X3AXIS, -2.5*Y3AXIS, 2*Z3AXIS, 'ABS').

Note:         The viewpoint must be placed  outside the  3-D
              box.  If the point  lies inside,  DISLIN  will
              print a warning and use the default viewpoint.

                         V F O C 3 D

The routine VFOC3D defines the focus point. It specifies the
location in the 3-D box that the camera points to.

The call is:  CALL VFOC3D (XFC, YFC, ZFC, CVU) level 1, 2, 3

XFC, YFC, ZFC define the position of the focus point. If CVU
              = 'ABS', the parameters must contain  absolute
              3-D coordinates,  if CVU = 'USER',  they  must
              contain user coordinates.
CVU           is a character string  defining the meaning of
              XFC, YFC and ZFC.
                               Default: (0., 0., 0., 'ABS').

                          V U P 3 D

The rotation  of the camera  around the  viewing axis is de-
fined by an angle.

The call is:  CALL VUP3D (ANG)                 level 1, 2, 3

ANG           defines the rotation angle in degrees. The ca-
              mera is rotated in a clockwise direction.
                                           Default: ANG = 0.

                           V A N G 3 D

VANG3D  defines  the  view angle for a perspective view.  It
specifies the field of view of the lens.

The call is:  CALL VANG3D (ANG)                level 1, 2, 3

ANG           defines the view angle in degrees.
                                          Default: ANG = 28.

                           V S C L 3 D

For an orthographic  view the size  of the projected 3-D box 
can be scaled by a factor defined with VSCL3D.

The call is:  CALL VSCL3D (XFAC)               level 1, 2, 3

XFAC          defines the scaling factor.
                                         Default: XFAC = 1.0


12.3 Plotting Axis Systems

                         G R A F 3 D

The routine  GRAF3D  plots a three-dimensional  axis system.
This routine  must be called before any objects can be plot-
ted in the 3-D box.

The call is:  CALL GRAF3D (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  Z-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.

Notes:     -  GRAF3D  must be called  from level 1  and sets
              the level to 3.
           -  By default,  the labels and axis titles on the
              3-D box  are also  plotted  with a perspective 
              projection.  This default mode does not  allow
              the plotting  of hardware  fonts  and switches
              automatically to the DISLIN vector font COMPLX
              if a hardware font is enabled. Other modes for
              plotting  labels  and axis titles  that  allow
              using of hardware  fonts  can be defined  with
              the routine LABL3D. 
           -  In default mode,  GRAF3D  suppresses the plot-
              ting  of certain  start labels  to avoid over-
              plotting of labels.  This  option  can be dis-
              abled with the statement CALL FLAB3D.
           -  The user is referred  to the notes on  GRAF in
              chapter 4.

12.4 Plotting a Border around the 3-D Box

                          B O X 3 D

The routine BOX3D plots a border around the 3-D box.

The call is:  CALL BOX3D                             level 3

12.5 Plotting Grids

                         G R I D 3 D

The routine GRID3D plots a grid in the 3-D box.

The call is:  CALL GRID3D (IGRID, JGRID, COPT)       level 3

IGRID         is the number of grid lines between  labels in
              the X-direction  (or  Y-direction  for the YZ-
              plane).
JGRID         is the number of grid lines between  labels in
              the Z-direction  (or  Y-direction  for the XY-
              plane).
COPT          is a character string which defines  where the
              grid will be plotted.
  = 'ALL'     will plot a grid in the XY-, XZ- and YZ-plane.
  = 'BACK'    will plot a grid in the XZ- and YZ-plane.
  = 'BOTTOM'  will plot a grid in the XY-plane.


12.6 Plotting Curves

                         C U R V 3 D

The routine  CURV3D  is similar to  CURVE  and connects data
points with lines or marks them with symbols.

The call is:  CALL CURV3D (XRAY, YRAY, ZRAY, N)      level 3

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.

Notes:      - Data points will be interpolated linearly. The
              user  is referred  to the  notes  on  CURVE in
              chapter 5.
            - CURV3D  can  plot  2-D or  3-D symbols. By de-
              fault,  CURV3D plots 2-D symbols.  3-D symbols
              are plotted after CALL SHDMOD ('3D', 'SYMBOL')
              or if the Z-buffer is enabled before.  
            - CURV3D  can  plot true 3-D  curves  (tube seg-
              ments instead of line segments), if the option
              CALL SHDMOD ('3D', 'CURVE') is enabled before.  
              The thickness of 3-D curves and the resolution
              of the used mesh can be modified with the rou-
              tines THKC3D and MSHCRV.

                         C R V T 3 D

CRVT3D is a similar routine to CURV3D, but can show more at-
tributes.

The call is:  CALL CRVT3D (XRAY, YRAY, ZRAY, RRAY, ICRAY, N)
                                                     level 3

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.
RRAY          is an  array  describing  the thickness of the
              curve at each data point. The elements of RRAY
              must contain absolute 3-D coordinates.
ICRAY         is an integer  array  with colour values  that
              define the colour of each curve segment. 
N             is the dimension of the arrays above.

                         C U R V 4 D

The routine CURV4D plots coloured 3-D symbols.

The call is:  CALL CURV4D (XRAY, YRAY, ZRAY, WRAY, N) 
                                                     level 3

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.
WRAY          is an array of dimension N containing intensi-
              ties. The minimum and maximum of WRAY are used
              for the colour scaling.
N             is the number of data points.

Notes:      - The statement CALL ZSCALE (ZMIN, ZMAX) defines
              an alternate  range for calculating colours.
            - The used  3-D symbol  can be selected with the
              routine MARKER. The symbol numbers corresponds
              to the numbers in SYMB3D. 
                  
12.7 Vector Fields

                         F I E L D 3 D

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

The call is:  CALL FIELD3D (X1RAY, Y1RAY, Z1RAY, 
                       X2RAY, Y2RAY, Z2RAY, N, IVEC) level 3

X1RAY, Y1RAY, are  arrays  that contain  the X-,  Y-  and Z-
   Z1RAY      coordinates of the start points. 
X2RAY, Y2RAY, are  arrays  that contain  the X-,  Y-  and Z-
   Z2RAY      coordinates of the end points. 
N             is the number of vectors.
IVEC          is an integer  that specifies  the form of the 
              arrows (see VECTR3).

                         V E C F 3 D

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

The call is:  CALL VECF3D (XVRAY, YVRAY, ZVRAY, 
                       XPRAY, YPRAY, ZPRAY, N, IVEC) level 3

XVRAY, YVRAY, are  arrays  that  contain  the  X-, Y- and Z-
    ZVRAY     coordinates of the vectors. 
XPRAY, YPRAY, are  arrays  that  contain  the  X-, Y- and Z-
    ZPRAY     coordinates  of the start points. 
N             is the number of vectors.
IVEC          is an integer  that  specifies the form of the 
              arrows (see VECTR3).

Notes:      - The  length  of  the  arrows  is automatically 
              scaled by  DISLIN  in the routine VECF3D. 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.  Colour  values  are
              scaled between the minimum  and maximum of the
              vector lengths,  or scaled between  the values
              specified with the routine ZSCALE. 

                       V E C M A T 3 D

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

The call is:  CALL VECMAT3D (XV, YV, ZV, NX, NY, NZ, XP, YP, 
                             ZP, IVEC)            level 2, 3

XV, YV, ZV    are arrays of the dimension  (NX, NY, NZ) that
              contain  the X-,  Y- and Z-coordinates  of the
              vectors. 
NX, NY, NZ    define the dimension of XV, YV and ZV.
XP, YP, ZP    are  arrays  of the dimensions  NX,  NY and NZ 
              that define the grid in space.
IVEC          is an integer  that specifies  the form of the 
              arrows (see VECTR3).

Note:         See the notes for VECF3D.

                       S T R E A M 3 D

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

The call is:  CALL STREAM3D (XV, YV, ZV, NX, NY, NZ, XP, YP, 
                             ZP, XS, YS, ZS, N)   level 2, 3

XV, YV, ZV    are arrays of the dimension  (NX, NY, NZ) that
              contain  the X-,  Y- and Z-coordinates  of the
              vectors. 
NX, NY, NZ    define the dimension of XV, YV and ZV.
XP, YP, ZP    are  arrays  of the dimensions  NX,  NY and NZ 
              that define the grid in space.
XS, YS, ZS    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).

Note:         See the notes for STREAM.

                       S T M P T S 3 D

The routine  STMPTS3D returns a calculated  streamline  of a
vector field on a regular grid.

The call is:  CALL STMPTS3D (XV, YV, ZV, NX, NY, NZ, XP, YP, 
                             ZP, X0, Y0, Z0, XRAY, YRAY, 
                             ZRAY, NMAX, N)       level 2, 3

XV, YV, ZV    are arrays of the dimension  (NX, NY, NZ) that
              contain  the X-,  Y- and Z-coordinates  of the
              vectors. 
NX, NY, NZ    define the dimension of XV, YV and ZV.
XP, YP, ZP    are  arrays  of the dimensions  NX,  NY and NZ 
              that define the grid in space.
X0, Y0, Z0    define the starting point.
XRAY, YRAY,   are arrays  of the  dimension NMAX  that  will 
    ZRAY      contain the calculated streamline.
NMAX          is the dimension of XRAY, YRAY and ZRAY.
N             is the returned number of points in XRAY, YRAY
              and ZRAY.

Note:         See the notes for STREAM.

12.8 Plotting a Surface Grid from a Function

                         S U R F U N

The routine  SURFUN  plots  a  surface grid  of  the  three-
dimensional function Z = F(X,Y).

The calls is:  CALL SURFUN (ZFUN, IXP, XDEL, IYP, YDEL) 
                                                     level 3

ZFUN            is the name  of a  FUNCTION  subroutine that
                returns the function  value  for a given  X-
                and Y-coordinate.  ZFUN must be declared EX-
                TERNAL in the calling program.
XDEL, YDEL      are the distances between grid lines in user
                coordinates.  XDEL  and YDEL  determine  the
                density of  the surface plotted by SURFUN.
IXP, IYP        are the number  of points between grid lines
                interpolated by  SURFUN (>= 0).  If IXP = 0,
                surface  lines  in the  X-direction  will be
                suppressed; if IYP = 0, surface lines in the
                Y-direction will be suppressed.

12.9 Plotting a Surface Grid from a Matrix

The routines  SURMAT  and SURFCE  plot surface grids  of the
three-dimensional function Z = F(X,Y) where the function va-
lues are given in the form of a matrix.  SURMAT assumes that
the function values  correspond to a linear grid in the  XY-
plane while SURFCE can be used with non linear grids. 

The calls are:  CALL SURMAT (ZMAT, IXDIM, IYDIM, IXP, IYP)
                CALL SURFCE (XRAY, IXDIM, YRAY, IYDIM, ZMAT)
                                                     level 3

XRAY, YRAY      are arrays containing the  X- and Y-user co-
                ordinates.
ZMAT            is a matrix with the dimension (IXDIM,IYDIM)
                containing the function values.
IXDIM, IYDIM    are the  dimensions of  ZMAT,  XRAY and YRAY
                (>= 2).
IXP, IYP        are  the number  of points  interpolated be-
                tween grid lines in the X- and  Y-direction.
                These  parameters  determine  the density of
                surfaces plotted by SURMAT. For positive va-
                lues, the surface will be interpolated line-
                arly. For a negative value, the absolute va-
                lue will be used as a step for  plotted sur-
                face lines. If IXP = 0, surface lines in the
                Y-direction will be suppressed;  if IYP = 0,
                surface  lines  in the  X-direction  will be
                suppressed.

Notes:       -  The routines  SURMAT and SURFCE suppress au-
                tomatically  hidden lines.  The  suppression
                can be disabled with the statement  CALL NO-
                HIDE.
             -  SURMAT  and SURFCE  use a horizon line algo-
                rithm for suppressing hidden lines. This al-
                gorithm is efficient but  may fail for  some
                complex data structures. An alternate method
                for  suppressing  hidden  lines  can be used 
                with the routine  SURSHD  if only mesh lines
                are enabled with the statement  CALL  SURMSH
                ('ONLY'). 
             -  Surfaces can be protected  from  overwriting
                with  CALL SHLSUR  if the  hidden-line algo-
                rithm is not disabled.
             -  The limits  of the base grid  are determined
                by the parameters in  GRAF3D or can be alte-
                red with SURSZE (XA, XE, YA, YE). If XA, XE,
                YA and YE are the axis limits in  GRAF3D  or
                defined with SURSZE,  the connection of grid
                points and matrix elements  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

             -  SURVIS (CVIS) determines the visible part of
                a surface  where  CVIS  can have  the values
                'TOP', 'BOTTOM' and 'BOTH'.  The default va-
                lue is 'BOTH'.
             -  The  statement  CALL SURCLR  (ICTOP,  ICBOT)
                defines the colours  of the upper and  lower
                side of a surface where ICTOP and ICBOT con-
                tain colour values.

12.10 Plotting a Shaded Surface from a Matrix

                          S U R S H D

The routine  SURSHD  plots a  shaded surface  from a  matrix
where colour values are calculated from the Z-scaling in the
routine GRAF3D or from the parameters of the routine ZSCALE.

The call is:    CALL SURSHD (XRAY, IXDIM, YRAY, IYDIM, ZMAT)
                                                     level 3

XRAY, YRAY      are arrays containing the  X- and Y-user co-
                ordinates.
ZMAT            is a matrix with the dimension (IXDIM,IYDIM)
                containing the function values.
IXDIM, IYDIM    are the  dimensions of  ZMAT,  XRAY and YRAY
                (>= 2).

Notes:        - The statement  CALL ZSCALE  (ZMIN, ZMAX) de-
                fines an alternate  Z-scaling  that  will be
                used to calculate  colour values in  SURSHD.
                Normally, the Z-scaling in GRAF3D is used.
                For logarithmic scaling of the Z-axis,  ZMIN
                and ZMAX must be exponents of base 10. 
                If  SHDMOD ('OFF', 'ZSCALE') is  used before
                SURSHD,  the calculating of colour values is
                disabled and the current colour and material
                settings are applied to the surface.   
              - A flat shading  or a smooth  shading  can be
                selected  with  the routine  SHDMOD. The de-
                fault is flat shading. SURSHD uses automati-
                cally a  depth sort  for flat shading  and a 
                Z-buffer  for  smooth  shading  to eliminate 
                hidden surfaces  if these algorithms are not
                already enabled with the routines DBFINI and
                ZBFINI.  If  smooth  shading  is selected, a 
                raster  format  is  needed  for the graphics 
                output format  (for example  METAFL ('XWIN')
                or METAFL ('TIFF')). 
              - By  default,  SURSHD  plots first the bottom 
                and then the top of the surface  where back-
                face culling  is enabled.  Backface  culling
                means  that  single  polygons  that  are not 
                facing  the  viewpoint  are removed. This is
                done by comparing  the polygons surface nor-
                mal with the position of the viewpoint. This
                behaviour can be  modified with the routines
                SURVIS and SHDMOD.
              - Additional  grid lines  can be  enabled with 
                the routine SURMSH. SURSHD can generate only
                mesh lines if the keyword  'ONLY' is used in
                SURMSH.
              - Lighting can be enabled for  SURSHD with the
                routine LIGHT.  If lighting is enabled,  the
                function values are used for setting diffuse
                material parameters of the surface.

                          S U R S H C

The routine  SURSHC  is a similar routine to  SURSHD with an
extra matrix which is used for calculating surface colours.

The call is:    CALL SURSHC (XRAY, IXDIM, YRAY, IYDIM, ZMAT,
                             WMAT)                   level 3

XRAY, YRAY      are arrays containing the  X- and Y-user co-
                ordinates.
IXDIM, IYDIM    are the  dimensions of  ZMAT, WMAT, XRAY and
                YRAY (>= 2).
ZMAT            is a matrix with the dimension (IXDIM,IYDIM)
                containing the function values.
WMAT            is a matrix with the dimension (IXDIM,IYDIM)
                which is used to calculate surface colours.

Notes:          see SURSHD.


12.11 Plotting a Shaded Surface from a Parametric Function

                         S U R F C P

A three-dimensional parametric function is a function of the
form  (x(t,u), y(t,u), z(t,u)) where  tmin <= t <= tmax  and
umin <= u <= umax. The routine SURFCP plots a shaded surface
from a parametric function.  The colours  of the surface are
calculated from the Z-scaling in the routine  GRAF3D or from
the parameters of the routine ZSCALE.

The call is:  CALL SURFCP (ZFUN, TMIN, TMAX, TSTEP, 
                                 UMIN, UMAX, USTEP)  level 3

ZFUN          is the name of a  FUNCTION subroutine with the
              formal parameters  X, Y and IOPT. If IOPT = 1,
              ZFUN  should  return  the  X-coordinate of the
              parametric function,  if IOPT = 2, ZFUN should
              return the Y-coordinate and  if IOPT = 3, ZFUN
              should return the Z-coordinate.
TMIN, TMAX,   define  the  range  and step size of the first
       TSTEP  parameter. 
UMIN, UMAX,   define the  range  and step size of the second
       USTEP  parameter.

Note:         The user is referred to the notes on SURSHD.

12.12 Plotting a Shaded Surface from Triangulated Data

                         S U R T R I

The routine SURTRI plots a shaded surface  from triangulated
data that can be calculated by the routine TRIANG from a set
of irregularly distributed data points.

The call is:  CALL SURTRI (XRAY, YRAY, ZRAY, N, I1RAY, 
                           I2RAY, I3RAY, NTRI)       level 3

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

Note:         The user is referred to the notes on SURSHD.

12.13 Plotting Isosurfaces

                         S U R I S O

The routine  SURISO plots isosurfaces of the form f(x,y,z) = 
constant.
  
The call is:  CALL SURISO (XRAY, NX, YRAY, NY, ZRAY, NZ, 
                           WMAT, WLEV)               level 3

XRAY, YRAY,   are arrays containing the  X-,  Y-  and Z-user 
      ZRAY    coordinates.
WMAT          is a matrix with the dimension  (NX, NY, NZ) 
              containing the function values.
NX, NY, NZ    are the dimensions of  WMAT,  XRAY,  YRAY  and 
              ZRAY (>= 2).
WLEV          defines the level of the isosurface.

Notes:      - The algorithm used in  SURISO  is based on the
              Marching Cubes method. 
              Reference: Lorensen, W.E. and Cline, H.E., 
              Marching Cubes: a high resolution  3D  surface
              reconstruction algorithm,
              Computer Graphics, Vol. 21, No. 4, pp 163-169 
              (Proc. of SIGGRAPH), 1987.
            - The user is referred to the notes on SURSHD.

                         I S O P T S

The routine  ISOPTS  calculates  an isosurface  of  the form 
f(x,y,z) = constant.  A triangulation of the calculated iso-
surface is returned.
  
The call is:  CALL ISOPTS (XRAY, NX, YRAY, NY, ZRAY, NZ,  
                           WMAT, WLEV, XTRI, YTRI, ZTRI, 
                           NMAX, NTRI)               level 3

XRAY, YRAY,   are arrays containing the  X-,  Y-  and Z-user 
      ZRAY    coordinates.
WMAT          is a matrix with the dimension  (NX, NY, NZ) 
              containing the function values.
NX, NY, NZ    are the dimensions of  WMAT,  XRAY,  YRAY  and 
              ZRAY (>= 2).
WLEV          defines the level of the isosurface.
XTRI, YTRI,   are arrays  containing  the calculated triang-
      ZTRI    les.  The first three coordinates  contain the
              first triangle, the next three coordinates the
              second triangle and so on.  The triangles  are
              returned in anti-clockwise orientation. 
NMAX          is the maximal number  of elements for the ar-
              rays XTRI, YTRI and ZTRI.
NTRI          is the returned number of  calculated  triang-
              les. 

12.14 Plotting 3-D Bars

                         B A R S 3 D

BARS3D plots three-dimensional bars.

The call is:  CALL BARS3D (XRAY, YRAY, Z1RAY, Z2RAY, XWRAY, 
                           YWRAY, ICRAY, N)          level 3

XRAY          is an array of  user coordinates  defining the 
              position of the bars on the X-axis.
YRAY          is an array of  user coordinates  defining the
              position of the bars on the Y-axis.
Z1RAY         is an array of user coordinates containing the
              start points of the bars on the Z-axis.
Z2RAY         is an array of user coordinates containing the
              end points of the bars on the Z-axis.
XWRAY         is an array of  user coordinates  defining the 
              width of the bars in X-direction.
YWRAY         is an array of  user coordinates  defining the
              width of the bars in Y-direction.
ICRAY         is an array  of colour  values  used  for  the
              bars.  The foreground  colour  is used for the 
              value  -1.
N             is the number of bars.

Note:         Legends are supported for 3-D bar graphs.
              Legend entries are done for each new colour in
              ICRAY.

12.15 Plotting 3-D Contours

                       C O N S H D 3 D

The routine CONSHD3D plots a  shaded surface  from a  matrix
where colour values are connected with contours.

The call is:  CALL CONSHD3D (XRAY, IXDIM, YRAY, IYDIM, 
                               ZMAT, ZLVRAY, NLEV)   level 3

XRAY, YRAY    are arrays containing the  X- and Y-user coor-
              dinates.
ZMAT          is a matrix with the dimension (IXDIM,IYDIM)
              containing the function values.
IXDIM, IYDIM  are the  dimensions of  ZMAT,  XRAY  and  YRAY
              (>= 2).
ZLVRAY        is an array containing the levels. 
NLEV          is the number of levels.

Note:         The user is referred to the notes on SURSHD 
              and CONSHD.

12.16 Parameter Setting Routines

                         L A B L 3 D

The routine  LABL3D  modifies  the appearance  of labels and
axis titles plotted on the 3-D box.

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

COPT          is a character string that can have the values 
              'STANDARD',   'HORIZONTAL',   'PARALLEL'   and 
              'OTHER'.  For  the  default  mode  'STANDARD', 
              hardware  fonts  cannot  be  used for plotting
              labels and axis titles. For that case,  DISLIN
              will switch to the vector font COMPLX.
                                 Default: COPT = 'STANDARD'.

                         N O H I D E

The suppression of hidden lines in the routines SURFUN, SUR-
MAT and SURFCE can be disabled with a call to NOHIDE.

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

                         S H L S U R

The  surfaces  plotted by the routines  SURFUN,  SURMAT  and
SURFCE can be protected  from  overwriting  with the routine
SHLSUR.

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


                         S U R O P T

Surface lines plotted  with the routine  SURFCE  can be sup-
pressed for the X- and Y-directions. 

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

COPT          is a character string that can have the values
              'XISO',  'YISO' and 'BOTH'.  If COPT = 'XISO',
              surface lines in the  Y-direction will be sup-
              pressed by SURFCE.  If COPT = 'YISO',  surface
              lines in the X-direction will be suppressed.
                                     Default: COPT = 'BOTH'.

                         S U R V I S

The routine SURVIS  determines  which part  of a  surface is
plotted.

The call is:  CALL SURVIS (CVIS)               level 1, 2, 3

CVIS          is a character string that can have the values
              'AUTO',  'TOP',  'BOTTOM'  and 'BOTH'.  'AUTO' 
              means that the value 'TOP'  is used for closed
              surfaces  such as a sphere and that  'BOTH' is
              used for non closed surfaces such  as surfaces
              plotted by SURSHD, SURFCP and SURTRI.
                                     Default: CVIS = 'AUTO'.

                          S U R C L R

The routine  SURCLR  defines  the  colours  of the upper and 
lower side of surfaces plotted by the routines SURFUN,  SUR-
MAT and SURFCE.

The call is:  CALL SURCLR (ICTOP, ICBOT)       level 1, 2, 3

ICTOP, ICBOT  are colour values  where  the value  -1  means 
              that the current  colour is used.
                                          Default: (-1, -1).

                          S H D M O D

The routine  SHDMOD  defines some shading parameters such as
flat or smooth shading.

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

COPT          is a character string containing an option.
CKEY          is a character string containing a keyword:
 = 'SURFACE'  If CKEY = 'SURFACE', COPT can have  the values
              'FLAT'  and  'SMOOTH'.  If COPT = 'SMOOTH',  a 
              raster  format  is needed  for the output gra-
              phics format  (for example METAFL ('XWIN')  or
              METAFL ('TIFF')). The default value is  COPT =
              'FLAT'.
 = 'CULLING'  If CKEY = 'CULLING', COPT can have  the values
              'ON',  'OFF' and 'FRONT'.  COPT = 'ON' enables
              backface  culling,   'COPT' = 'FRONT'  enables
              front face culling  and  COPT = 'OFF' disables
              face culling.  By default, backface culling is
              enabled.  This means that  faces with a clock-
              wise orientation of vertices will not be plot-
              ted. 
 = 'SYMBOLS'  This option defines 2-D or 3-D symbols for the
              routine CURV3D.  COPT can have the values '2D'
              and '3D'. The default value is COPT = '2D'.
 = 'CURVE'    This option defines 2-D or 3-D curves  for the
              routine CURV3D.  COPT can have the values '2D'
              and '3D'. The default value is COPT = '2D'.
 = 'ZSCALE'   This option enables  or disables the calculat-
              ing of colour values from the Z-coordinates in
              the routines SURSHD,  SURFCP and SURTRI.  COPT
              can have the values  'ON'  and  'OFF'. The de-
              fault value is COPT = 'ON'.

                          S U R M S H

The routine SURMSH can enable additional grid lines for sur-
faces, or disable the shading of a surface.

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

COPT          is a character string that can have the values
              'ON', 'OFF', 'ONLY', 'LINES' and 'POINTS'. For
              COPT = 'ONLY',  the shading of the  surface is
              done in background colour to allow hidden line
              removal for the mesh lines.
                                      Default: COPT = 'OFF'.

                          M S H C L R

The routine MSHCLR sets the colour for grid lines. Different
colours can be selected for the upper and lower side of sur-
faces if the routine SETFCE is used before.

The call is:  CALL MSHCLR (ICLR)               level 1, 2, 3

ICLR          is a colour value where the value -1 means  
              that the current colour is used.
                                         Default: ICLR = -1.

                        S E T F C E

The routine  SETFCE  selects the surface side for which mesh
colours or material parameters  are applied  by the routines
MSHCLR and MATOP3.

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

COPT          is a character string that can have the values
              'TOP', 'BOTTOM' and 'BOTH'.
                                      Default: COPT = 'TOP'.

                        Z S C A L E

The routine  ZSCALE defines an alternate Z-scaling that will
be used to calculate colour  values  in the routines  SURSHD
and SURFCP.

The call is:  CALL ZSCALE (ZMIN, ZMAX)         level 1, 2, 3

ZMIN,ZMAX     define  the range  of the Z-scaling. For loga-
              rithmic scaling of the Z-axis,  ZMIN  and ZMAX
              must be exponents of base 10.

                           C L I P 3 D

The routine CLIP3D defines 3-D clipping in the world coordi-
nate  system  or in the eye coordinate system,  or disables
clipping.

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

COPT          is a character string that can have the values
              'WORLD', 'EYE' and 'NONE'.
                                    Default: COPT = 'WORLD'.

                           V C L P 3 D

If 3-D clipping is done in the eye coordinate system,  front
and back  clipping  planes can be defined  with  the routine
VCLP3D.

The call is:   CALL VCLP3D (XFRONT, XBACK)     level 1, 2, 3

XFRONT, XBACK  are  the distances  from the viewpoint in ab-
               solute  3-D  coordinates.  A  negative  value
               means infinity.
                                         Default: (1., -1.).

                           H S Y M 3 D

The routine  HSYM3D  sets  the symbol  size  for 3-D symbols 
plotted by SYMB3D and CURV3D.

The call is:  CALL HSYM3D (H)                  level 1, 2, 3

H             is the symbol height in absolute 3-D coordina-
              tes.                         Default: H = 0.08

                            R O T 3 D

The routine  ROT3D  sets rotation angles for 3-D symbols and
solids.

The call is:  CALL ROT3D (AX, AY, AZ)          level 1, 2, 3

AX, AY, AZ    are rotation  angles  in degrees for rotations
              about the X-, Y-  and Z-axes. Rotation is done
              around  the  centre  point  of  symbols  in  a 
              counter-clockwise direction when  looking from
              a positive axis toward the origin of the axis.
                                       Default: (0., 0., 0.)

                           T H K C 3 D

The routine THKC3D sets the thickness of 3-D curves. 

The call is:  CALL THKC3D (XTHK)               level 1, 2, 3

XTHK          is the thickness in absolute 3-D coordinates.
                                        Default: XTHK = 0.04

                           M S H C R V

The routine  MSHCRV sets the resolution of the mesh used for
3-D curves. 

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

N             is the number of mesh lines  around the curve.
              If N = 0, the number of mesh lines  is automa-
              tically calculated by DISLIN. 
                                              Default: N = 0


12.17 Lighting

Lighting can be enabled  for some shading routines such SUR-
SHD,  SURFCP, SURTRI and  SURISO where up to 8 light sources
can be defined.  General lighting can be turned off or on in
DISLIN with the routine LIGHT while single light sources can
be turned off or on with  the routine  LITMOD.  The  routine 
LITPOS defines  the position  of light  sources and the rou-
tines LITOP3 and  MATOP3 modify lighting  and material para-
meters. Finally, the routine  GETLIT  calculates  the colour
value for a specified point and normal.

                         L I G H T

The routine LIGHT enables lighting for shading routines such
as SURSHD, SURFCP and SURISO.

The call is:  CALL LIGHT (CMODE)               level 1, 2, 3

CMODE         is a character string that can have the values
              'ON' and 'OFF'.
                                     Default: CMODE = 'OFF'.

                         L I T M O D

Up to 8 light sources can be defined in DISLIN.  The routine 
LITMOD enables or disables single light sources.

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

ID            is the  ID  of the light source in the range 1 
              to 8. 
CMODE         is a character string that can have the values 
              'ON' and 'OFF'. The default values are CMODE = 
              'ON' for light source 1 and  CMODE = 'OFF' for
              the other light sources.

                         L I T P O S

The routine LITPOS defines the position of light sources.

The call is:  CALL LITPOS (ID, XP, YP, ZP, COPT) 
                                               level 1, 2, 3

ID            is the  ID  of the light source in the range 1
              to 8. 
XP, YP, ZP    define the position of the light source.
              If  COPT = 'ABS',  the parameters must contain
              absolute  3-D coordinates,  if  COPT = 'USER',
              they  must  contain  user  coordinates  and if
              COPT = 'ANGLE', the position must be specified
              by two angles and a radius (see VIEW3D). 
COPT          is a character string defining  the meaning of
              XP, YP and ZP.
                  Default: (2*X3AXIS, -2.5*Y3AXIS, 2*Z3AXIS,
                                                     'ABS').

                         L I T O P T

The routine LITOPT modifies the constant, linear and quadra-
tic attenuation factors of light sources.

The call is:  CALL LITOPT (ID, XVAL, COPT)     level 1, 2, 3

ID            is the  ID  of the light source in the range 1
              to 8. 
XVAL          is a floating point number containing  the new
              lighting parameter. 
COPT          is a character string that can have the values
              'CONSTANT', 'LINEAR' and 'QUADRATIC'.
                 Defaults: (1., 'CONSTANT'), 
                          (0., 'LINEAR'), (0., 'QUADRATIC').

                         L I T O P 3

The routine LITOP3 modifies the ambient, diffuse and specu-
lar intensities of light sources.

The call is:  CALL LITOP3 (ID, XR, XG, XB, COPT) 
                                               level 1, 2, 3

ID            is the  ID  of the light source in the range 1
              to 8. 
XR, XG, XB    are floating point numbers in the range 0 to 1
              for R, G and B.
              lighting parameter. 
COPT          is a character string that can have the values
              'AMBIENT', 'DIFFUSE' and 'SPECULAR'.
                 Defaults: (0., 'AMBIENT'), (1., 'DIFFUSE'), 
                                           (1., 'SPECULAR').

                         M A T O P T

The routine MATOPT modifies material parameters.

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

XVAL          is a floating point number  containing the new
              material parameter. 
COPT          is a character string that can have  the value 
              'EXPONENT'.
                                  Default: (0., 'EXPONENT').


                         M A T O P 3

The routine  MATOP3 modifies material parameters such as am-
bient, diffuse and specular colour.  Material parameters can
be defined for different sides  of a surface  if the routine
SETFCE is used before.

The call is:  CALL MATOP3 (XR, XG, XB, COPT)   level 1, 2, 3

XR, XG, XB    are floating point numbers in the range 0 to 1
              containing  the new material parameters for R, 
              G and B.
COPT          is a character string that can have the values 
              'AMBIENT', 'DIFFUSE' and 'SPECULAR'.
                      Defaults: (0.2, 0.2, 0.2, 'AMBIENT'),
                                (0.8, 0.8, 0.8, 'DIFFUSE'),
                                (0.0, 0.0, 0.0, 'SPECULAR').            

                         G E T L I T

The routine GETLIT calculates colour values for given points
and their normals specified in absolute coordinates. 

The call is:  CALL GETLIT (XP, YP, ZP, XN, YN, ZN, ICLR) 
                                               level 1, 2, 3

XP, YP, ZP    are the  X-,  Y- and Z-user coordinates of the 
              point.
XN, YN, ZN    are the  X-, Y- and Z-coordinates of the point
              normal.
ICLR          is the returned colour value. ICLR contains an
              explicit RGB value. 

12.18 Surfaces from Randomly Distributed Points

The routine SURMAT assumes that  function values  are in the
form of a matrix  and  correspond  to a  linear grid  in the
XY-plane. If three-dimensional data points are given as ran-
domly distributed points of the form  X(N),  Y(N) and  Z(N),
the routine  GETMAT  can be used to calculate a function ma-
trix.

                         G E T M A T

The routine GETMAT calculates a function matrix for randomly
distributed data points.

The call is:  CALL GETMAT (XRAY, YRAY, ZRAY, N, ZMAT, NX,
                           NY, ZVAL, IMAT, WMAT)  level 2, 3

XRAY, YRAY,   are arrays containing the randomly distributed
   ZRAY       data points.
N             is the number of points.
ZMAT          is the function matrix  of the dimension  (NX,
              NY) calculated by GETMAT.  The matrix elements
              correspond to a linear  grid in  the  XY-plane
              whose limits are determined by the scaling va-
              lues in GRAF3D or SURSZE.
NX, NY        are the dimensions of ZMAT, IMAT and WMAT.
ZVAL          will be used  as a value  for matrix  elements
              when no data points  can be  found in  an area
              around the corresponding grid points. In gene-
              ral, the start scaling of the  Z-axis  will be
              used for ZVAL.
IMAT          is a  working matrix of the dimension (NX,NY).
              After a call to  GETMAT,  IMAT(I, J)  contains
              the number of random  data points  found in an
              area  around  the grid points.  The  value  -1
              means that a random data value lies  at a grid
              point.
WMAT          is a working matrix of the dimension (NX, NY).

If Pi is a data point,  the routine  GETMAT  finds  the grid
rectangle in the  XY-plane  in which the point lies.  By de-
fault,  Pi affects  all grid points  which lie up  to 2 grid
lines from Pi.  A problem can arise  when  creating a  large
matrix from sparse data points  because certain  grid points
may not lie near the actual random data points.

An simple method to smooth surfaces  from sparse data points
is to  enlarge  the region  around the randomly  distributed
data points where grid points are searched. This can be done
using the routine MDFMAT.

                         M D F M A T

The routine MDFMAT modifies the algorithm in GETMAT.

The call is:  CALL MDFMAT (IX, IY, W)          level 1, 2, 3

IX, IY        are the number of grid lines in the X- and  Y-
              direction which determine the size  of the re-
              gion around data points.
W             is a weighting number.
                                       Default: (2, 2, 2.0).

12.19 Projection of 2-D-Graphics into 3-D Space

Two-dimensional  graphics  in the  XY-plane can be projected
onto a plane in 3-D space.  Therefore, all 2-D plot routines
can be used in 3-D space.

                         G R F I N I

The routine GRFINI defines a plane in the 3-D box onto which
all plot vectors will be projected. The plane in the 3-D box
corresponds to a region in the  XY-plane which is determined
by AXSPOS and AXSLEN. GRFINI sets the level to 1.

The call is:  CALL GRFINI (X1, Y1, Z1, X2, Y2, Z2,
                                       X3, Y3, Z3)   level 3

X1, Y1, Z1    are the absolute 3-D coordinates  of the lower
              left corner of the 3-D plane.
X2, Y2, Z2    are the absolute 3-D coordinates  of the lower
              right corner of the 3-D plane.
X3, Y3, Z3    are the absolute 3-D coordinates  of the upper
              right corner of the 3-D plane.

Note:         If (NXA,NYA) is the lower left corner, NXL the
              width and NYL the height of the region  deter-
              mined by the routines AXSPOS and  AXSLEN,  the
              point  (X1,Y1,Z1)  corresponds  to  (NXA,NYA),
              (X2,Y2,Z2) to (NXA+NXL-1,NYA)  and  (X3,Y3,Z3)
              to (NXA+NXL-1,NYA-NYL+1), respectively.

                         G R F F I N

The routine  GRFFIN  terminates a projection into 3-D space.
The level will be set back to 3.

The call is:  CALL GRFFIN

12.20 Using the Z-Buffer

The DISLIN routines  SURSHD,  SURFCP,  SURTRI and SURISO use
automatically a 32-bit floating point  Z-buffer  for hidden-
surface elimination  or a depth sort  depending on smooth or
flat shading. The Z-buffer or depth sort can also be enabled
directly  for hidden-surface elimination in elementary plot-
ting routines such as SPHE3D and CONE3D.

                       Z B F I N I

The routine  ZBFINI  creates a Z-buffer. The graphics output
format must be set  to a raster  format,  or to PDF. For PDF
output,  an internal image is created for raster operations,
where the resolution of the internal image  can be  modified
with the routine ZBFSCL. 

The call is:  CALL ZBFINI (IRET)                 level 1,2,3

IRET          is the returned status (0: no errors).

                       Z B F F I N

The routine  ZBFFIN  terminates  writing  to a Z-buffer  and
frees the allocated space.  For screen output,  the internal
frame buffer is copied back to the graphics window.  For PDF
output,  the internal  image  is copied  to the  PDF file in 
transparency mode.

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

                        Z B F M O D

The routine ZBFMOD can disable the Z-buffer in DISLIN.

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

COPT          is a character string that can have the values
              'ON' and 'OFF'. The keyword 'OFF' disables the
              Z-buffer  in routines  that  automatically use 
              it. A call to ZBFINI has also no affect for if
              the Z-buffer is disabled.
                                       Default: COPT = 'ON'.

                       Z B F R E S
 
The routine ZBFRES resets the Z-buffer to it's initial valu-
es without changing a corresponding frame buffer. 

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

                       Z B F E R S
 
The routine ZBFERS erases the frame buffer  connected with a
Z-buffer.

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

The following both  elementary routines  can be used to plot
triangles and lines directly to the Z-buffer.

                       Z B F T R I

The routine ZBFTRI plots a smooth triangle where hidden-sur-
face elimination is done with the Z-buffer.

The call is:  CALL ZBFTRI (XRAY, YRAY, ZRAY, IRAY)   level 3

XRAY, YRAY,   are the X-, Y-  and Z-coordinates of the three
       ZRAY   corners of the triangle in user coordinates.
IRAY          is an integer  array containing  the three co-
              lour values of the triangle corners.          

                       Z B F L I N

The routine  ZBFLIN plots a line in the current colour where
the  Z-buffer is used for hiddenline elimination.  This rou-
tine is used by SURSHD and SURFCP for drawing surface grids.

The call is:  CALL ZBFLIN (X1, Y1, Z1, X2, Y2, Z2)   level 3

X1, Y1, Z1    are the user coordinates of the start point.
X2, Y2, Z2    are the user coordinates of the end point.

                       Z B F S C L
 
The routine  ZBFSCL  changes  the  resolution of an internal 
image which is used for raster operations for PDF output.
The resolution of the internal image corresponds to the DIS-
LIN plot page converted to points, where 1 point = 1 / 72
inch.  This resolution  is multiplied with the value in ZBF-
SCL.  For example:  the internal  image corresponding to the
default page 'DA4L' has the resolution 1263 x 892 points.

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

X             is a scaling factor for the resolution
              (1.0 <= X <= 10.0).
                                                Default: 1.5

                         D B F I N I

The routine  DBFINI  initializes  a depth sort  for  polygon 
faces. A depth sort is useful for hidden-surface elimination
if  the  output  format  is no  raster  format  so  that the 
Z-buffer cannot be used.

The call is:  CALL DBFINI (IRET)                 level 1,2,3

IRET          is the returned status (0: no errors).

                         D B F F I N

The routine  DBFFIN  terminates the depth sort.  All polygon
faces  are  sorted and plotted.  The polygon  faces with the 
greatest distance from the viewpoint are plotted first. 

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

                        D B F M O D

The routine DBFMOD can disable the depth sort.

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

COPT          is a character string that can have the values
              'ON' and 'OFF'. The keyword 'OFF' disables the
              depth  in routines  that automatically use it. 
              A call to DBFINI  has also no affect  for that
              case.
                                       Default: COPT = 'ON'.

12.21 Elementary Plot Routines

                         S T R T 3 D

The routine  STRT3D  moves the  pen  to a  three-dimensional
point.

The call is:  CALL STRT3D (X, Y, Z)                  level 3

X, Y, Z       are the absolute 3-D coordinates of the point.

                         C O N N 3 D

The routine CONN3D plots a line from the current pen positi-
on to a three-dimensional point. The line will be cut off at
the sides of the 3-D box. Different line styles can be used.

The call is:  CALL CONN3D (X, Y, Z)                  level 3

X, Y, Z       are the absolute 3-D coordinates of the point.

                         V E C T R 3

The routine VECTR3 plots a vector in the 3-D box.

The call is:  CALL VECTR3 (X1, Y1 ,Z1, X2, Y2, Z2, IVEC)
                                                     level 3

X1, Y1, Z1    are the absolute  3-D coordinates of the start
              point.
X2, Y2, Z2    are the absolute  3-D coordinates of  the  end
              point.
IVEC          defines  the arrow head.  If IVEC = -2,  a 3-D
              cone is used  for the  arrow head.  Otherwise,
              IVEC has the same meaning as in VECTOR.

                         T R I A 3 D

The routine TRIA3D plots a triangle.

The call is:  CALL TRIA3D (XRAY, YRAY, ZRAY)         level 3

XRAY, YRAY,   are the X-, Y-  and Z-coordinates of the three
      ZRAY    vertices of the triangle  in user coordinates.
              The vertices should be specified in a counter-
              clockwise orientation from the viewpoint since
              backface culling  is enabled in DISLIN by  de-
              fault.

Note:         If lighting is enabled, a normal vector of the
              triangle is automatically generated  by DISLIN
              for calculating colours.

The next three routines VTX3D, VTXC3D and VTXN3D define ver-
tices for plotting lines,  points,  curves,  triangles, qua-
drilaterals  and polygons.  Note  that  backface culling  is
enabled by default in DISLIN. Therefore, vertices for shaded
triangles,  quadrilaterals  and polygons should be specified
in a  counter-clockwise  orientation,  or they  will  not be
plotted if backface culling is on.

                          V T X 3 D

The routine  VTX3D  plots lines,  points, curves, triangles,
quadrilaterals or polygons from a set of vertices.

The call is:  CALL VTX3D (XRAY, YRAY, ZRAY, N, COPT) level 3

XRAY, YRAY,   define vertices in user coordinates.
      ZRAY
N             is the number of vertices.
COPT          is a character string  that defines how verti-
              ces are plotted:
 = 'POINTS'   The  vertices  are  plotted  with a small  '+' 
              sign,  where  the size  of the  symbol  can be 
              modified with HSYMBL.
 = 'LINES'    Separated lines are plotted, each specified by
              a pair of vertices.
 = 'CURVE'    A series of connected lines is plotted.
 = 'PLINE'    The same as  'CURVE' except that the last ver-
              tex is connected with the first vertex.
 = 'TRIANG'   Separate shaded triangles are plotted for each
              set of three vertices.
 = 'TSTRIPS'  A  series  of triangles  is  plotted connected 
              along shared edges.  The triangles are  (1, 2,
              3),  (3, 2, 4),  (3, 4, 5),  (5, 4, 6),  ....,
              where  the  vertices  are numbered by 1, 2, 3,
              ..., n.
 = 'QUADS'    Separate shaded quads are plotted for each set
              of four vertices.
 = 'QSTRIPS'  A series of quads  is plotted  connected along
              shared edges. The quads are (1, 2, 4, 3),  (3,
              4, 6, 5), (5, 6, 8, 7), ...., where the verti-
              ces are numbered by 1, 2, 3, ..., n.
 = 'POLYGON'  A shaded polygon is plotted where  the polygon
              should be convex. The polygon is rendered by a
              series of triangles.

Note:         If  lighting  is enabled,  normal  vectors for 
              calculating  colour values  are  automatically
              generated by DISLIN.

                         V T X C 3 D

The routine VTXC3D is a similar routine to VTX3D except that
a user  can specify  additional colour values for the verti-
ces.

The call is:  CALL VTXC3D (XRAY, YRAY, ZRAY, ICRAY, N, COPT)
                                                     level 3

XRAY, YRAY,   define vertices in user coordinates.
      ZRAY
ICRAY         contains the colour values of vertices. 
N             is the number of vertices.
COPT          is a character string  that defines how verti-
              ces are plotted (see VTX3D).


                         V T X N 3 D

The routine VTXN3D is a similar routine to VTX3D except that
a normal vector can be specified for each vertex.

The call is:  CALL VTXN3D (XRAY,  YRAY,  ZRAY, XNRAY, YNRAY,
                           ZNRAY, N, COPT)           level 3

XRAY, YRAY,   define vertices in user coordinates.
      ZRAY
XNRAY, YNRAY, contain the normal vectors for each vertex.
      ZNRAY
N             is the number of vertices.
COPT          is a character string  that defines how verti-
              ces are plotted (see VTX3D).

The  following  routines  plot  elementary  solids  such  as 
spheres, cones and quads.  All solids can be rotated  around
the  centre point  if rotation angles  are defined  with the 
routine  ROT3D.  Three-dimensional  transformations  such as 
shifting,  scaling and rotation about an axis can be defined
with the routines TR3SHF, TR3SCL and TR3ROT.  Smooth or flat
shading  can be used and  hidden-surface elimination  can be
enabled with the routines  ZBFINI and DBFINI. For closed so-
lids such as spheres and quads, only the top faces are plot-
ted while for non closed solids such as cones and tubes, the
top and bottom faces are plotted.  This behaviour can be mo-
dified with the routine SURVIS. By default, backface culling
is enabled  for all  solids  which can be  disabled with the 
routine  SHDMOD.  Lighting  can be enabled  with the routine 
LIGHT and additional grid lines will be plotted after a call
to SURMSH with the parameter 'ON'.

                         S P H E 3 D

The routine SPHE3D plots a sphere.

The call is:  CALL SPHE3D (XM, YM ,ZM, R, N, M)      level 3

XM, YM, ZM    are the user coordinates of the centre point.
R             is  the  radius  of the sphere in user coordi-
              nates.
N, M          define the horizontal  and vertical resolution
              of the sphere.

                         C O N E 3 D

The routine CONE3D plots a cone or a truncated cone.

The call is:  CALL CONE3D (XM, YM, ZM, R, H1, H2, N, M) 
                                                     level 3

XM, YM, ZM    are the  user coordinates  of the lower centre
              point.
R             is the radius of the cone in user coordinates.
H1, H2        are the heights of the truncated cone. If H1 =
              H2, the cone is not truncated. 
N, M          define the horizontal  and vertical resolution
              of the cone.

                         P I K E 3 D

The routine PIKE3D plots a cone specified by two points.

The call is:  CALL PIKE3D (X1, Y1, Z1, X2, Y2, Z2, R, N, M)
                                                     level 3

X1, Y1, Z1    are  the  user  coordinates  of  the  starting
              centre point.
X2, Y2, Z2    are the user coordinates of the ending point.
R             is the radius of the cone in user coordinates.
N, M          define the horizontal  and vertical resolution
              of the cone.

                         C Y L I 3 D

The routine CYLI3D plots a cylinder.

The call is:  CALL CYLI3D (XM, YM, ZM, R, H, N, M)   level 3

XM, YM, ZM    are the  user coordinates  of the lower centre
              point.
R             is the radius  of the cylinder in user coordi-
              nates.
H             is the height  of the cylinder in user coordi-
              nates.
N, M          define the horizontal  and vertical resolution
              of the cylinder.

                         T U B E 3 D

The routine TUBE3D plots a tube.

The call is:  CALL TUBE3D (X1, Y1, Z1, X2, Y2, Z2, R, N, M)
                                                     level 3

X1, Y1, Z1    are the user coordinates  of the starting cen-
              ter point.
X2, Y2, Z2    are the user coordinates  of the ending centre
              point.
R             is the radius of the tube in user coordinates.
N, M          define the horizontal  and vertical resolution
              of the tube.

                         D I S K 3 D

The routine DISK3D plots a disk.

The call is:  CALL DISK3D (XM, YM, ZM, R1, R2, N, M) level 3

XM, YM, ZM    are the user coordinates  of the centre point.
R1, R2        are the inner and outer radii  in user coordi-
              nates.
N, M          define the horizontal  and vertical resolution
              of the disk.

                         Q U A D 3 D

The routine QUAD3D plots a quad.

The call is:  CALL QUAD3D (XM, YM, ZM, XL, YL, ZL)   level 3

XM, YM, ZM    are the user coordinates of the centre point.
XL, YL, ZL    are the  length  of the edges in X-, Y- and Z-
              direction in user coordinates.

                         P Y R A 3 D

The routine PYRA3D plots a pyramid or a truncated pyramid.

The call is:  CALL PYRA3D (XM, YM, ZM, XL, H1, H2, N)
                                                     level 3

XM, YM, ZM    are the  user coordinates  of the lower centre
              point.
XL            is the length of the pyramid in user coordina-
              tes.
H1, H2        are the heights  of the  truncated  pyramid in
              user coordinates.  If H1 = H2,  the pyramid is
              not truncated.
N             can have the values  3 and 4  and defines  the
              number of sides.  

                         P L A T 3 D

The routine  PLAT3D  plots  a Platonic solid. The 5 Platonic
solids are tetrahedron,  cube,  octahedron, dodecahedron and
icosahedron.  

The call is:  CALL PLAT3D (XM, YM, ZM, XL, COPT)     level 3

XM, YM, ZM    are the user coordinates of the centre point.
XL            is the length of an edge in user coordinates.
COPT          is a character string that can have the values
              'TETR', 'CUBE', 'OCTA'', 'DODE' and 'ICOS'.

                         S Y M B 3 D

The routine SYMB3D plots a 3-D symbol.

The call is:  CALL SYMB3D (N, XM, YM, ZM)            level 3

N             is the symbol number between 0 and 5. The sym-
              bols are cube,  tetrahedron, octahedron, dode-
              cahedron, icosahedron and sphere.  
XM, YM, ZM    are the user coordinates of the centre point.

Note:         The size  of  3-D symbols  can be defined with
              the routine HSYM3D.

                         T O R U S 3 D

The routine TORUS3D plots a torus.

The call is:  CALL TORUS3D (XM,  YM,  ZM, R1, R2, H, A1, A2, 
                            N, M)                    level 3

XM, YM, ZM    are the user coordinates of the centre point.
R1, R2        are the inner  and outer radii in user coordi-
              nates.
H             is the height  of the torus  in user coordina-
              tes.
A1, A2        are the starting and end angles in degrees.
N, M          define the horizontal  and vertical resolution
              of the torus.

12.22 Export of 3-D Objects to the PLY Polygon File Format

3-D objects plotted by DISLIN can be exported as polygons to
PLY files  between the routines PLYINI and PLYFIN.  Polygons
are stored in  ASCII format  in form  of vertices and edges.
Colour information is included.

                         P L Y I N I

The routine PLYINI  initializes  the output of polygons to a 
PLY file.  The polygons are sent to the output device and to
the PLY file.

The call is:  CALL PLYINI (COPT)                     level 3

COPT          is a character  string that defines the format 
              of the  PLY  file.  COPT  can  have  the value 
              'STANDARD'. 

                         P L Y F I N

The routine PLYFIN  terminates  the output  of polygons to a 
PLY file.

The call is:  CALL PLYFIN (CFIL, CSTR)               level 3

CFIL          is a character  string that contains  the name 
              of the PLY file.

CSTR          is a character  string  that  is written  as a 
              comment to the PLY file.

Note:         Backface culling  should be disabled  with the
              routine SHDMOD. Otherwise, polygons written to
              the PLY file depend on the viwepoint.


12.23 Transformation of Coordinates

                         P O S 3 P T

The routine POS3PT converts three-dimensional user coordina-
tes to absolute 3-D coordinates.

The call is:  CALL POS3PT (X, Y, Z, XP, YP, ZP)      level 3

X, Y, Z       are the user coordinates.
XP, YP, ZP    are the absolute 3-D coordinates calculated by
              POS3PT.

The absolute 3-D coordinates can also be calculated with the
following functions:

              XP = X3DPOS (X, Y, Z)
              YP = Y3DPOS (X, Y, Z)
              ZP = Z3DPOS (X, Y, Z)

                         R E L 3 P T

The routine REL3PT converts user coordinates to plot coordi-
nates.

The call is:  CALL REL3PT (X, Y, Z, XP, YP)          level 3

X, Y, Z       are the user coordinates.
XP, YP        are the plot coordinates calculated by REL3PT.

The corresponding functions are:

              XP = X3DREL (X, Y, Z)
              YP = Y3DREL (X, Y, Z)

                         A B S 3 P T

The routine ABS3PT converts absolute 3-D coordinates to plot
coordinates.

The call is:  CALL ABS3PT (X, Y, Z, XP, YP)          level 3

X, Y, Z       are the absolute 3-D coordinates.
XP, YP        are the plot coordinates calculated by ABS3PT.

The corresponding functions are:

              XP = X3DABS (X, Y, Z)
              YP = Y3DABS (X, Y, Z)

The next routines define  3-D base transformations which are
applied to  3-D plot routines.  The transformations  can  be
combined in any order, but note  that matrix multiplications
are not commutative. Different orders may give different re-
sults.

                         T R 3 S H F

The routine  TR3SHF defines a shifting of user 3-D coordina-
tes.

The call is:  CALL TR3SHF (XSHF, YSHF, ZSHF)         level 3

XSHF, YSHF,   are user coordinates that define the magnitude
      ZSHF    of shifting in X-, Y- and Z-direction.

                         T R 3 S C L

The routine  TR3SCL  defines a scaling of user 3-D coordina-
tes.

The call is:  CALL TR3SCL (XSCL, YSCL, ZSCL)         level 3

XSCL, YSCL,   are  scaling  factors  for  the X-,  Y- and Z-
      ZSCL    direction.

                         T R 3 R O T

The routine  TR3ROT  defines a rotation  about an axis.  The
axes of the 3-D box are used as rotation axes where the ori-
gin of the  axis system is located in the centre of the  3-D
box (see Figure 12.1). 

The call is:  CALL TR3ROT (XROT, YROT, ZROT)         level 3

XROT, YROT,   are rotation  angles  in degrees for rotations 
      ZROT    about the X-, Y-  and Z-axes. Rotation is done 
              in a counter-clockwise direction when  looking
              from a positive axis  toward the origin of the
              axis.

Note:         The order  of rotations is X-axis,  Y-axis and
              then Z-axis.  This means that TR3ROT (A, B, C)
              has  the  same affect  as  TR3ROT (A, 0., 0.), 
              TR3ROT (0., B, 0.) and TR3ROT (0., 0., C).

                         T R 3 A X S

The routine  TR3AXS  defines a  rotation  about an arbitrary
axis.

The call is:  CALL TR3AXS (X, Y, Z, A)               level 3

X, Y, Z       define the axis  which goes from the origin to
              the point (X, Y, Z).

A             is a  rotation  angle in degrees.  Rotation is
              done  in  a counter-clockwise  direction  when
              looking  from  the point  (X, Y, Z) toward the 
              origin.

                         T R 3 R E S

The routine TR3RES resets 3-D transformations.

The call is:  CALL TR3RES                            level 3

12.24 Examples

            PROGRAM EXA12_1
            DIMENSION IXP(4),IYP(4)
            DATA IXP/200,1999,1999,200/
           *     IYP/2600,2600,801,801/
            EXTERNAL ZFUN  

            CALL SETPAG('DA4P')
            CALL DISINI
            CALL PAGERA
            CALL COMPLX

            CALL AXSPOS(200,2600)
            CALL AXSLEN(1800,1800)
            CALL NAME('X-axis','X')
            CALL NAME('Y-axis','Y')
            CALL NAME('Z-axis','Z')
            CALL TITLIN('Surface Plot (SURFUN)',2)
            CALL TITLIN('F(X,Y) = 2*SIN(X)*SIN(Y)',4)

            CALL GRAF3D(0.,360.,0.,90.,0.,360.,0.,90.,
           *            -3.,3.,-3.,1.)
            CALL HEIGHT(50)
            CALL TITLE
            CALL SHLSUR
            CALL SURFUN(ZFUN,1,10.,1,10.)

      C     Grid in the XY plane
            CALL GRFINI(-1.,-1.,-1.,1.,-1.,-1.,1.,1.,-1.)
            CALL NOGRAF
            CALL GRAF(0.,360.,0.,90.,0.,360.,0.,90.)
            CALL DASHL
            CALL GRID(1,1)
            CALL GRFFIN
      C     Grid in the YZ plane
            CALL GRFINI(-1.,-1.,-1.,-1.,1.,-1.,-1.,1.,1.)
            CALL GRAF(0.,360.,0.,90.,-3.,3.,-3.,1.)
            CALL GRID(1,1)
            CALL GRFFIN
      C     Shading in the XZ plane
            CALL GRFINI(-1.,1.,-1.,1.,1.,-1.,1.,1.,1.)
            CALL SHDPAT(7)
            CALL SOLID
            CALL AREAF(IXP,IYP,4)
            CALL GRFFIN
            CALL DISFIN
            END     

            FUNCTION ZFUN(X,Y)
            FPI=3.14159/180.
            ZFUN=2*SIN(X*FPI)*SIN(Y*FPI)
            END


            PROGRAM EXA12_2
            CHARACTER*60 CTIT1,CTIT2
            EXTERNAL ZFUN

            CTIT1='Surface Plot of the Parametric Function'
            CTIT2='[COS(t)*(3+COS(u)),
           *              SIN(t)*(3+COS(u)), SIN(u)]'
            PI=3.14159

            CALL SETPAG('DA4P')
            CALL METAFL('POST')
            CALL DISINI
            CALL HWFONT
            CALL PAGERA
            CALL AXSPOS(200,2400)
            CALL AXSLEN(1800,1800)
            CALL INTAX

            CALL TITLIN(CTIT1,2)
            CALL TITLIN(CTIT2,4)

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

            CALL VKYTIT(-300)
            CALL GRAF3D(-4.,4.,-4.,1.,-4.,4.,-4.,1.,
           *                          -3.,3.,-3.,1.)

            CALL HEIGHT(40)
            CALL TITLE

            CALL SURMSH('ON')
            STEP=2*PI/30.
            CALL SURFCP(ZFUN,0.,2*PI,STEP,0.,2*PI,STEP)
            CALL DISFIN
            END

            FUNCTION ZFUN(X,Y,IOPT)
            FPI=3.14159/180.

            IF(IOPT.EQ.1) THEN
              ZFUN=COS(X)*(3+COS(Y))
            ELSE IF(IOPT.EQ.2) THEN
              ZFUN=SIN(X)*(3+COS(Y))
            ELSE
              ZFUN=SIN(Y)
            END IF
            END


            PROGRAM EXA12_3
            PARAMETER (N=18)
            DIMENSION XRAY(N),YRAY(N),Z1RAY(N),Z2RAY(N),XWRAY(N),
           *          YWRAY(N),ICRAY(N)
            CHARACTER*80 CBUF

            DATA XRAY/1., 3., 8., 1.5, 9., 6.3, 5.8, 2.3, 8.1, 3.5,
           *         2.2, 8.7, 9.2, 4.8, 3.4, 6.9, 7.5, 3.8/
            DATA YRAY/5., 8., 3.5, 2., 7., 1.,4.3, 7.2, 6.0, 8.5,
           *         4.1, 5.0, 7.3, 2.8, 1.6, 8.9, 9.5, 3.2/
            DATA Z1RAY/0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,
           *           0., 0., 0., 0., 0., 0., 0., 0./
            DATA Z2RAY/4.,5.,3.,2.,3.5,4.5,2.,1.6,3.8,4.7,
           *           2.1, 3.5, 1.9, 4.2, 4.9, 2.8
            DATA ICRAY/30, 30, 30, 30, 30, 30, 100, 100, 100, 100,
           *           100, 100, 170, 170, 170, 170, 170, 170/

            DO I=1,N
              XWRAY(I)=0.5
              YWRAY(I)=0.5
            END DO

            CALL SETPAG('DA4P')
            CALL METAFL('PS')
            CALL DISINI
            CALL PAGERA
            CALL HWFONT
            CALL AXSPOS(200,2600)
            CALL AXSLEN(1800,1800)

            CALL NAME('X-axis','X')
            CALL NAME('Y-axis','Y')
            CALL NAME('Z-axis','Z')
            CALL TITLIN('3-D Bars / BARS3D',3)

            CALL LABL3D('HORI')
            CALL GRAF3D(0.,10.,0.,2.,0.,10.,0.,2.,0.,5.,0.,1.)
            CALL GRID3D(1,1,'BOTTOM')
            CALL BARS3D(XRAY,YRAY,Z1RAY,Z2RAY,XWRAY,YWRAY,ICRAY,N)

            CALL LEGINI(CBUF,3,20)
            CALL LEGTIT(' ')
            CALL LEGPOS(1300,1100)
            CALL LEGLIN(CBUF,'First',1)
            CALL LEGLIN(CBUF,'Second',2)
            CALL LEGLIN(CBUF,'Third',3)
            CALL LEGEND(CBUF,3)

            CALL HEIGHT(50)
            CALL TITLE
            CALL DISFIN
            END
