                   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 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. The box itself will be cut off at the borders
of the region unless suppressed with the routine NOCLIP.

                         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 the Viewpoint

A viewpoint  is a point in space  from which  the 3-D box is
observed  and determines  how objects  are projected  onto a
2-D plane. Objects will appear small if the viewpoint is far
away.  As the viewpoint is moved closer to the 3-D box,  the
objects will appear larger.

                         V I E W 3 D

The routine VIEW3D defines the viewpoint.

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.

12.3 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.
           -  To avoid overwriting labels, GRAF3D suppresses
              the plotting of certain start labels. This op-
              tion  can be disabled  with the statement CALL
              FLAB3D.
           -  The user is referred  to the notes on  GRAF in
              chapter 4.

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

Note:         Data points will be interpolated linearly. The
              user  is referred  to the  notes  on  CURVE in
              chapter 5.

12.5 Plotting Surfaces

The routines SURFUN, SURMAT, SURFCE and SURSHD plot surfaces
of the three-dimensional  function  Z = F(X,Y).  For SURFUN,
the function values  must be given  by a function  while for
SURMAT, SURFCE and SURSHD, the function values must be given
in the form of a matrix.  SURFUN and  SURMAT assume that the
function values correspond to a linear grid in the XY-plane.
The routines  SURFCE and  SURSHD can be used with non linear
grids.  SURSHD plots a coloured surface  where colour values
are calculated from the Z-scaling in the routine  GRAF3D  or
from the parameters of the routine ZSCALE.

The calls are:  CALL SURFUN (ZFUN, IXP, XDEL, IYP, YDEL) 
                                                     level 3
                CALL SURMAT (ZMAT, IXDIM, IYDIM, IXP, IYP)
                CALL SURFCE (XRAY, IXDIM, YRAY, IYDIM, ZMAT)
                CALL SURSHD (XRAY, IXDIM, YRAY, IYDIM, ZMAT)

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.
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.
XRAY, YRAY      are arrays containing the  X- and Y-user co-
                ordinates.

Notes:       -  The suppression  of hidden lines can be dis-
                abled with CALL NOHIDE.
             -  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. The parameters must be in
                the range  -1 to 255 where the default value
                -1 means that the current colour is used.
             -  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.

12.6 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.7 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.8 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.9 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.10 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 (see VECTOR).

12.11 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)
