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

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

or: void axis3d (float x3axis, float y3axis, float z3axis);

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

Additional 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.).

The following figure shows the default 3-D box:

Figure 12.1: Default 3-D Box

12.2 Defining View Properties

The following routines define view properties such as viewpoint, target point, view angle and view orientation.

P R O J 3 D

The routine PROJ3D defines perspective or orthographic projection.

The call is: CALL PROJ3D (COPT) level 1

or: void proj3d (const char *copt);

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

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

or: void view3d (float xvu, float yvu, float zvu, const char *cvu);

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 rotation 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 centre of the 3-D box. XVU and YVU must be specified in degrees and ZVU in absolute 3-D coordinates.

CVU is a character string defining the meaning of XVU, YVU and ZVU.
Default: (2*X3AXIS, -2.5*Y3AXIS, 2*Z3AXIS, 'ABS').

Additional 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 (XFOC, YFOC, ZFOC, CVU) level 1, 2, 3

or: void vfoc3d (float xfoc, float yfoc, float zfoc, const char *cvu);

XVU, YVU, ZVU 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 XFOC, YFOC and ZFOC.
Default: (0., 0., 0., 'ABS').

V U P 3 D

The rotation of the camera around the viewing axis is defined by an angle.

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

or: void vup3d (float ang);

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

V A N G 3 D

VANG3D defines the view angle. It specifies the field of view of the lens.

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

or: void vang3d (float ang);

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

or: void vscl3d (float xfac);

XFAC defines the scaling factor.
Default: XFAC = 1.0.

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 plotted in the 3-D box.

The call is: CALL GRAF3D (XA, XE, XOR, XSTP, YA, YE, YOR, YSTP, ZA, ZE, ZOR, ZSTP) level 1

or: void graf3d (float xa, float xe, float xor, float xstp, float ya, float ye, float yor, float ystp, float za, float ze, float zor, float zstp);

XA, XE are the lower and upper limits of the X-axis.

XOR, XSTP are the first X-axis label and the step between labels.

YA, YE are the lower and upper limits of the Y-axis.

YOR, YSTP are the first Z-axis label and the step between labels.

ZA, ZE are the lower and upper limits of the Z-axis.

ZOR, ZSTP are the first Z-axis label and the step between labels.

Additional 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 plotting of certain start labels to avoid overplotting of labels. This option can be disabled 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

or: void box3d (void);

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

or: void grid3d (int igrid, int jgrid, const char *copt);

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

or: void curv3d (const float *xray, const float *yray, const float *zray, int n);

Additional 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 default, CURV3D plots 2-D symbols. 3-D symbols are plotted after CALL SHDMOD ('3D', 'SYMBOL') or if the Z-buffer is enabled before.

C R V T 3 D

CRVT3D is a similar routine to CURV3D, but can show more attributes.

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

or: void crvt3d (const float *xray, const float *yray, const float *zray, const float *rray, const int *icray, int n);

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

or: void curv4d (const float *xray, const float *yray, const float *zray, const float *wray, int n);

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 intensities. The minimum and maximum of WRAY are used for the colour scaling.

N is the number of data points.

Additional 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 Plotting 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 vectors are displayed as arrows.

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

or: void field3d (const float *x1ray, const float *y1ray, const float *z1ray, const float *x2ray, const float *y2ray, const float *z2ray, int n, int ivec);

X1RAY, Y1RAY, Z1RAY are arrays that contain the X-, Y- and Z-coordinates of the start points.

X2RAY, Y2RAY, Z2RAY are arrays that contain the X-, Y- and Z-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

or: void vecf3d (const float *xvray, const float *yvray, const float *zvray, const float *xpray, const float *ypray, const float *zpray, int n, int ivec);

XVRAY, YVRAY, ZVRAY are arrays that contain the X-, Y- and Z-coordinates of vectors.

XPRAY, YPRAY, ZPRAY are arrays that contain the X-, Y- and Z-coordinates of the start points.

N is the number of vectors.

IVEC is an integer that specifies the form of the arrows (see VECTR3).

Additional notes:

The length of the arrows is automatically scaled by DISLIN in the routine VECF3D. This behaviour can be changed with the routine VECOPT, that may also modify the appearance of arrows.
The vectors can be scaled with different colours 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 3

or: void vecmat3d (const float *xv, const float *yv, const float *zv, int nx, int ny, int nz, const float *xp, const float *yp, const float * zp, int ivec);

Additional 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 3

or: void stream3d (const float *xv, const float *yv, const float *zv, int nx, int ny, int nz, const float *xp, const float *yp, const float * zp, const float *xs, const float *ys, const float *zs, int n);

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

N is the number of statrting points (N >= 0).

Additional 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 1, 2, 3

or: void stmpts3d (const float *xv, const float *yv, const float *zv, int nx, int ny, int nz, const float *xp, const float *yp, const float * zp, float x0, float y0, float z0, float *xray, float *yray, int nmax, int *n);

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, ZRAY are arrays of the dimension NMAX that will 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.

Additional 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 call is: CALL SURFUN (ZFUN, IXP, XDEL, IYP, YDEL) level 3

or: void surfun ((float) (*zfun()), int ixp, float xdel, int iyp, float ydel);

ZFUN is the name of a FUNCTION subroutine that returns the function value for a given X- and Y-coordinate. ZFUN must be declared EXTERNAL 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 values 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) level 3

nbsp; CALL SURFCE (XRAY, IXDIM, YRAY, IYDIM, ZMAT) level 3

or: void surmat (const float *zmat, int ixdim, int iydim, int ixp, int iyp);

nbsp; void surfce (const float *xray, int ixdim, const float *yray, int iydim, const float *zmat);

XRAY, YRAY are arrays containing the X- and Y-user coordinates.

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 between grid lines in the X- and Y-direction. These parameters determine the density of surfaces plotted by SURMAT. For positive values, the surface will be interpolated linearly. For a negative value, the absolute value will be used as a step for plotted surface 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.

Additional notes:

The suppression of hidden lines can be disabled with CALL NOHIDE.
Surfaces can be protected from overwriting with CALL SHLSUR if the hidden-line algorithm is not disabled.
The limits of the base grid are determined by the parameters in GRAF3D or can be altered 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 and
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 value is 'BOTH'.
The statement CALL SURCLR (ICTOP, ICBOT) defines the colours of the upper and lower side of a surface where ICTOP and ICBOT contain 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

or: void surshd (const float *xray, int ixdim, const float *yray, int iydim, const float *zmat);

Additional notes:

The statement CALL ZSCALE (ZMIN, ZMAX) defines 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 used for the surface.
A flat shading or a smooth shading can be selected with the routine SHDMOD. The default is flat shading. SURSHD uses automatically 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 backface 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 normal 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

or: void surshc (const float *xray, int ixdim, const float *yray, int iydim, const float *zmat, const float *wmat);

XRAY, YRAY are arrays containing the X- and Y-user coordinates.

IXDIM, IYDIM are the dimensions of ZMAT, 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.

Additional 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, IXDIM, TMIN, TMAX, TSTEP, UMIN, UMAX, USTEP) level 3

or: void surfcp ((float) (*zfun()), float tmin, float tmax, float tstep, float umin, float umax, float );

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, TSTEP define the range and step size of the first parameter.

UMIN, UMAX, USTEP define the range and step size of the second parameter.

Additional 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

or: void surtri (const float *xray, const float *yray, const float *zray, int n, const int *i1ray, const int *i2ray, const int *i3ray, int ntri);

XRAY is an array containing the X-coordinates of data points.

YRAY is an array containing the Y-coordinates of data points.

ZRAY is an array containing the Z-coordinates of data points.
N is the number of data points.

I1RAY, I2RAY, I3RAY is the Delaunay triangulation of the points (XRAY, YRAY) calculated by the routine TRIANG.

NTRI is the number of triangles in I1RAY, I2RAY and I3RAY.

Additional 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

or: void suriso (const float *xray, int nx, const float *yray, int ny, const float *zray, int nz, const float *wmat, float wlev);

Additional 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 isosurface is returned.

The call is: CALL ISOPTS (XRAY, NX, YRAY, NY, ZRAY, NZ, WMAT, WLEV, XTRI, YTRI, ZTRI, NMAX, NTRI) level 3

or: void isopts (const float *xray, int nx, const float *yray, int ny, const float *zray, int nz, const float *wmat, float wlev, float *xtri, float *ytri, float *ztri, int nmax, int *ntri);

XRAY, YRAY, ZRAY are arrays containing the X-, Y- and Z-user 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, ZTRI are arrays containing the calculated triangles. 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 arrays XTRI, YTRI and ZTRI.

NTRI is the returned number of calculated triangles.

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

or: void bars3d (const float *xray, const float *yray, const float *z1ray, const float *z2ray, const float *xwray, const float *ywray, const int *icray, int n);

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 colour value -1.

N is the number of bars.

Additional 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

or: void conshd3d (const float *xray, int ixdim, const float *yray, int iydim, const float *zmat, const float *zlvray, int nlev);

Additional 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

or: void labl3d (const char *copt);

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, SURMAT and SURFCE can be disabled with a call to NOHIDE.

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

or: void nohide (void);

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

or: void shlsur (void);

S U R O P T

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

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

or: void suropt (const char *copt);

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 suppressed 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

or: void survis (const char *cvis);

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, SURMAT and SURFCE.

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

or: void surclr (int ictop, int icbot);

ICTOP, ICBOT are colour values. 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

or: void shdmod (const char *copt, const char *ckey);

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 graphics 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 clockwise orientation of vertices will not be plotted.

= '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 calculating of colour values from the Z-coordinates in the routines SURSHD, SURFCP and SURTRI. COPT can have the values 'ON' and 'OFF'. The default value is COPT = 'ON'.

S U R M S H

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

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

or: void surmsh (const char *copt);

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.

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

or: void mshclr (int iclr);

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

or: void setfce (const char *copt);

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 SURTRI, SURSHD, SURFCP, CONSHD and CONTRI.

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

or: void zscale (float zmin, float zmax);

ZMIN,ZMAX define the range of the Z-scaling. For logarithmic 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 coordinate system or in the eye coordinate system, or disables clipping.

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

or: void clip3d (const char *copt);

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

or: void vclp3d (float xfront, float xback);

XFRONT, XBACK are the distances from the viewpoint in absolute 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, CURV3D. and CURV4D.

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

or: void hsym3d (float h);

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

S E T R E S 3 D

The routine SETRES3D sets the symbol size for the 3-D symbol with the number 0 (cube) plotted by SYMB3D, CURV3D. and CURV4D.

The call is: CALL SETRES3D (XL, YL, ZL) level 1, 2, 3

or: void setres3d (float xl, float yl, float zl);

XL, YL, ZL is the cube size in absolute 3-D coordinates.
Default: (0.08, 0.08, 0.08)

A U T R E S 3 D

The routine AUTRES3D calculates the symbol size for cubes from the number of data points.

The call is: CALL AUTRES3D (IXDIM, IYDIM, IZDIM) level 1, 2, 3

or: void autres3d (int ixdim, int iydim, int izdim);

IXDIM, IYDIM, IZDIM are the number of data points in the X-, Y- and Z-directions.

Additional note:

HSYM3D, SETRES3D and AUTRES3D can overwrite each other for the symbol 'cube'.

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

or: void rot3d (float ax, float ay, float az);

AX, AY, AZ are rotation angles in degrees for rotations about the X-, Y- and Z-axes. Rotation is done around the center 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

or: void thkc3d (float xthk);

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

or: void mshcrv (int n);

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

12.17 Lighting

Lighting can be enabled for some shading routines such as SURSHD, 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 routines LITOP3 and MATOP3 modify lighting and material parameters. 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

or: void light (const char *cmode);

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

or: void litmod (int id, const char *cmode);

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

or: void litpos (int id, float xp, float yp, float zp, const char *copt);

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 quadratic attenuation factors of light sources.

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

or: void litopt (int id, float xval, const char *copt);

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 specular intensities of light sources.

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

or: void litop3 (int id, float xr, float xg, float xb, const char *copt);

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.

COPT is a character string that can have the values 'AMBIENT', 'DIFFUSE' and 'SPECULAR'.
Defaults: (0., 0., 0., 'AMBIENT'), (1., 1., 1., 'DIFFUSE'), (1., 1., 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

or: void matopt (float xval, const char *copt);

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 ambient, 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

or: void matop3 (float xr, float xg, float xb, const char *copt);

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

or: int getlit (float xp, float yp, float zp, float xn, float yn, float zn);

XP, YP, ZP are the X-, Y-and Z-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 randomly distributed points of the form X(N), Y(N) and Z(N), the routine GETMAT can be used to calculate a function matrix.

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

or: void getmat (const float *xray, const float *yray, const float *zray, int n, float *zmat, int nx, int ny, float zval, int *imat, float *wmat);

XRAY, YRAY, ZRAY are arrays containing the randomly distributed 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 values 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 general, 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).

The value ZMAT(J, K) of the corresponding grid point (J, K) is calculated by the formula:

where:

j, k are indices from 1 to NX and 1 to NY, respectively.

Di is the distance of the grid point (i, k) from the point Pi.

w is a weighting number (Default: 2.0).

n is the number of data points lying in the area around the grid point (j, k).

If Pi is a data point, the routine GETMAT finds the grid rectangle in the XY-plane in which the point lies. By default, 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. Figure 12.2 shows the results of GETMAT using different values of IX and IY.

Figure 12.2: Results of GETMAT

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

or: void mdfmat (int ix, int iy, float w);

IX, IY are the number of grid lines in the X- and Y-direction which determine the size of the region around data points.

W is a weighting number.
Default: (2, 2, 2.0).

The following figure shows modifications of the above example:

Figure 12.3: Modification of GETMAT

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

or: void grfini (float x1, float y1, float z1, float x2, float y2, float z2, float x3, float y3, float z3);

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.

Additional note:

If (NXA,NYA) is the lower left corner, NXL the width and NYL the height of the region determined 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 level 2, 3

or: void grfini (void);

G R F I M G

The routine GRFIMG includes a PNG, BMP, TIFF or GIF file into a 3-D plane defined by GRFINI. This routine can only be used if the output format is a raster format (screen or image file).

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

or: void grfimg (const char *cfil);

CFIL is a character string that contains the filename.

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 plotting 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

or: int zbfini (void);

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

Z B F F I N

The routine ZBFFIN terminates writing to a Z-buffer. For screen output, the internal frame buffer is copied back to the graphics window.

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

or: void zbfini (void);

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

or: void zbfmod (const char *copt);

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 values without changing a corresponding frame buffer.

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

or: void zbfres (void);

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

or: void zbfers (void);

Z B F T R I

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

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

or: void zbftri (const float *xray, const float *yray, const float *zray, const int *iray);

XRAY,YRAY,ZRAY are the X-, Y-, and Z-coordinates of the three corners of the triangle in user coordinates.

IRAY is an integer array containing the three colour 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 routine is used by SURSHD and SURFCP for drawing surface grids.

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

or: void zbflin (float x1, float y1, float z1, float x2, float y2, float z2);

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 DISLIN plot page converted to points, where 1 point = 1 / 72 inch. This resolution is multiplied with the value in ZBFSCL. 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

or: void zbfscl (float x);

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

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

or: int dbfini (void);

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

or: void dbffin (void);

D B F M O D

The routine DBFMOD can disable the depth sort.

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

or: void dbfmod (const char *copt);

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

or: void strt3d (float x, float y, float z);

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 position 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

or: void conn3d (float x, float y, float z);

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

or: void vectr3 (float x1, float y1, float z1, float x2, float y2, float z2, int ivec);

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

or: void tria3d (const float *xray, const float *yray, const float *zray);

XRAY, YRAY, ZRAY are the X-, Y- and Z-coordinates of the three 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 default.

Additional 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 vertices for plotting lines, points, curves, triangles, quadrilaterals 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

or: void vtx3d (const float *xray, const float *yray, const float *zray, int n, const char *copt);

XRAY, YRAY, ZRAY define vertices in user coordinates.

N is the number of vertices.

COPT is a character string that defines how vertices 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 vertex is connected with the first vertex.

= 'TRIANG' Separate shaded triangles are plotted for each set of three vertices.

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

= 'QSTRIPES' 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 vertices 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.

Additional 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 vertices.

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

or: void vtxc3d (const float *xray, const float *yray, const float *zray, const int *icray, int n, const char *copt);

XRAY, YRAY, ZRAY define vertices in user coordinates.

ICRAY contains the colour values of vertices.

N is the number of vertices.

COPT is a character string that defines how vertices 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

or: void vtxn3d (const float *xray, const float *yray, const float *zray, const float *xnray, const float *ynray, const float *znray, int n, const char *copt);

XRAY, YRAY, ZRAY define vertices in user coordinates.

XNRAY, YNRAY, ZNRAY contain the normal vectors for each vertex.

N is the number of vertices.

COPT is a character string that defines how vertices 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 solids such as spheres and quads, only the top faces are plotted while for non closed solids such as cones and tubes, the top and bottom faces are plotted. This behaviour can be modified 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 SUMSH 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

or: void sphe3d (float xm, float ym, float zm, float r, int n, int m);

XM, YM, ZM are the user coordinates of the centre point.

R is the radius of the sphere in user coordinates.

N, M defines 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

or: void cone3d (float xm, float ym, float zm, float r, float h1, float h2, int n, int m);

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 defines 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

or: void pike3d (float x1, float y1, float z1, float x2, float y2, float z2, float r, int n, int m);

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 defines 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

or: void cyli3d (float xm, float ym, float zm, float r, float h, int n, int m);

XM, YM, ZM are the user coordinates of the lower centre point.

R is the radius of the cylinder in user coordinates.

H is the height of the cylinder in user coordinates.

N, M defines 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

or: void tube3d (float x1, float y1, float z1, float x2, float y2, float z2, float r, int n, int m);

X1, Y1, Z1 are the user coordinates of the starting centre point.

X2, Y2, Z2 are the user coordinates of the ending centre point.

R is the radius of the tube in user coordinates.

H is the height of the cylinder in user coordinates.

N, M defines 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

or: void disk3d (float xm, float ym, float zm, float r1, float r2, int n, int m);

XM, YM, ZM are the user coordinates of the centre point.

R1, R2 are the inner and outer radii in user coordinates.

N, M defines 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

or: void quad3d (float xm, float ym, float zm, float xl, float yl, float zl);

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

or: void pyra3d (float xm, float ym, float zm, float xl, float h1, float h2, int n);

XM, YM, ZM are the user coordinates of the lower centre point.

XL is the length of the pyramid in user coordinates.

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

or: void plat3d (float xm, float ym, float zm, float xl, const char *copt);

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

or: void symb3d (int n, float xm, float ym, float zm);

N is the symbol number between 0 and 5. The symbols are cube, tetrahedron, octahedron, dodecahedron, icosahedron and sphere.

XM, YM, ZM are the user coordinates of the centre point.

Additional 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

or: void torus3d (float xm, float ym, float zm, float r1, float r2, float h, float a1, float a2, int n, int m);

XM, YM, ZM are the user coordinates of the centre point.

R1, R2 are the inner and outer radii in user coordinates.

H is the height of the torus in user coordinates.

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

or: void plyini (const char *copt);

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

or: void plyfin (const char *cfil, const char *cstr);

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.

Additional 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 coordinates to absolute 3-D coordinates.

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

or: void pos3pt (float x, float y, float z, float *xp, float *yp, float *zp);

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

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

or: void rel3pt (float x, float y, float z, float *xp, float *yp);

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

or: void abs3pt (float x, float y, float z, float *xp, float *yp);

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

T R 3 S H F

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

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

or: void tr3shf (float xshf, float yshf, float zshf);

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

T R 3 S C L

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

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

or: void tr3scl (float xscl, float yscl, float zscl);

XSCL, YSCL, ZSCL are scaling factors for the X-, Y- and Z-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 origin 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

or: void tr3rot (float xrot, float yrot, float zrot);

XROT, YROT, ZROT are rotation angles in degrees for rotations 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.

Additional 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

or: void tr3axs (float x, float y, float z, float a);

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

or: void tr3res (void);

12.24 Examples

Next | Previous | Contents

The call is:	CALL AXIS3D (X3AXIS, Y3AXIS, Z3AXIS)	level 1, 2, 3
or:	void axis3d (float x3axis, float y3axis, float z3axis);

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

The call is:	CALL PROJ3D (COPT)	level 1
or:	void proj3d (const char *copt);

The call is:	CALL VIEW3D (XVU, YVU, ZVU, CVU)	level 1, 2, 3
or:	void view3d (float xvu, float yvu, float zvu, const char *cvu);

The call is:	CALL VFOC3D (XFOC, YFOC, ZFOC, CVU)	level 1, 2, 3
or:	void vfoc3d (float xfoc, float yfoc, float zfoc, const char *cvu);

XVU, YVU, ZVU	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 XFOC, YFOC and ZFOC. Default: (0., 0., 0., 'ABS').

The call is:	CALL VUP3D (ANG)	level 1, 2, 3
or:	void vup3d (float ang);

The call is:	CALL VANG3D (ANG)	level 1, 2, 3
or:	void vang3d (float ang);

The call is:	CALL VSCL3D (XFAC)	level 1, 2, 3
or:	void vscl3d (float xfac);

The call is:	CALL GRAF3D (XA, XE, XOR, XSTP, YA, YE, YOR, YSTP, ZA, ZE, ZOR, ZSTP)	level 1
or:	void graf3d (float xa, float xe, float xor, float xstp, float ya, float ye, float yor, float ystp, float za, float ze, float zor, float zstp);

XA, XE	are the lower and upper limits of the X-axis.
XOR, XSTP	are the first X-axis label and the step between labels.
YA, YE	are the lower and upper limits of the Y-axis.
YOR, YSTP	are the first Z-axis label and the step between labels.
ZA, ZE	are the lower and upper limits of the Z-axis.
ZOR, ZSTP	are the first Z-axis label and the step between labels.

The call is:	CALL GRID3D (IGRID, JGRID, COPT)	level 3
or:	void grid3d (int igrid, int jgrid, const char *copt);

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.

The call is:	CALL CURV3D (XRAY, YRAY, ZRAY, N)	level 3
or:	void curv3d (const float xray, const float yray, const float *zray, int n);

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.

The call is:	CALL CRVT3D (XRAY, YRAY, ZRAY, RRAY, ICRAY, N)	level 3
or:	void crvt3d (const float xray, const float yray, const float zray, const float rray, const int *icray, int n);

The call is:	CALL CURV4D (XRAY, YRAY, ZRAY, WRAY, N)	level 3
or:	void curv4d (const float xray, const float yray, const float zray, const float wray, int n);

The call is:	CALL FIELD3D (X1RAY, Y1RAY, Z1RAY, X2RAY, Y2RAY, Z2RAY, N, IVEC)	level 3
or:	void field3d (const float x1ray, const float y1ray, const float z1ray, const float x2ray, const float y2ray, const float z2ray, int n, int ivec);

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

The call is:	CALL VECF3D (XVRAY, YVRAY, ZVRAY, XPRAY, YPRAY, ZPRAY, N, IVEC)	level 3
or:	void vecf3d (const float xvray, const float yvray, const float zvray, const float xpray, const float ypray, const float zpray, int n, int ivec);

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

The call is:	CALL VECMAT3D (XV, YV, ZV, NX, NY, NZ, XP, YP, ZP, IVEC)	level 3
or:	void vecmat3d (const float xv, const float yv, const float zv, int nx, int ny, int nz, const float xp, const float yp, const float zp, int ivec);

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

The call is:	CALL STREAM3D (XV, YV, ZV, NX, NY, NZ, XP, YP, ZP, XS, YS, ZS, N)	level 3
or:	void stream3d (const float xv, const float yv, const float zv, int nx, int ny, int nz, const float xp, const float yp, const float zp, const float xs, const float ys, const float *zs, int n);

The call is:	CALL STMPTS3D (XV, YV, ZV, NX, NY, NZ, XP, YP, ZP, X0, Y0, Z0, XRAY, YRAY, ZRAY, NMAX, N)	level 1, 2, 3
or:	void stmpts3d (const float xv, const float yv, const float zv, int nx, int ny, int nz, const float xp, const float yp, const float zp, float x0, float y0, float z0, float xray, float yray, int nmax, int *n);

The call is:	CALL SURFUN (ZFUN, IXP, XDEL, IYP, YDEL)	level 3
or:	void surfun ((float) (*zfun()), int ixp, float xdel, int iyp, float ydel);

ZFUN	is the name of a FUNCTION subroutine that returns the function value for a given X- and Y-coordinate. ZFUN must be declared EXTERNAL 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.

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

or:	void surmat (const float *zmat, int ixdim, int iydim, int ixp, int iyp);
nbsp;	void surfce (const float xray, int ixdim, const float yray, int iydim, const float *zmat);

XRAY, YRAY	are arrays containing the X- and Y-user coordinates.
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 between grid lines in the X- and Y-direction. These parameters determine the density of surfaces plotted by SURMAT. For positive values, the surface will be interpolated linearly. For a negative value, the absolute value will be used as a step for plotted surface 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.