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