Chapter 11: 3-D Colour Graphics 11.1 Introduction This chapter presents subroutines that plot coloured surfa- ces in three dimensions. Coloured surfaces are easy to in- terpret and show the full range of data points. A data point is normally plotted as a coloured rectangle where the X- and Y-coordinates determine the position of the rectangle and the Z-coordinate defines the colour. Colours are calcu- lated from a scaled colour bar which is, by default, ar- ranged as a rainbow. 11.2 Plotting Coloured Axis Systems G R A F 3 The routine GRAF3 plots a 3-D axis system where the Z-axis is plotted as a colour bar. The call is: CALL GRAF3 (XA, XE, XOR, XSTEP, YA, YE, YOR, YSTEP, ZA, ZE, ZOR, ZSTEP) XA, XE are the lower and upper limits of the X-axis. XOR, XSTEP are the first X-axis label and the step be- tween labels. YA, YE are the lower and upper limits of the Y-axis. YOR, YSTEP are the first Y-axis label and the step be- tween labels. ZA, ZE are the lower and upper limits of the Z-axis. ZOR, ZSTEP are the first Z-axis label and the step be- tween labels. Note: GRAF3 must be called from level 1 and sets the level to 3. For additional notes, the user is referred to the routine GRAF in chapter 4. 11.3 Secondary Colour Bars GRAF3 plots a vertical colour bar on the right side of a 3-D axis system which can be shifted with the routines VKXBAR and VKYBAR or suppressed with the routine NOBAR. To plot horizontal colour bars at global positions, the routines ZAXIS and ZAXLG can be used. ZAXIS plots a linearly and ZAX- LG a logarithmically scaled colour bar. The call is: CALL ZAXIS (A, B, OR, STEP, NL, CSTR, IT, NDIR, NX, NY) level 1, 2, 3 A, B are the lower and upper limits of the colour bar. OR, STEP are the first label and the step between la- bels. NL is the length of the colour bar in plot coor- dinates. CSTR is a character string containing the axis name. IT indicates how ticks, labels and the axis name are plotted. If IT = 0, they are plotted in a clockwise direction. If IT = 1, they are plot- ted in a counter-clockwise direction. NDIR defines the direction of the colour bar. If NDIR = 0, a vertical colour bar will be plot- ted; if NDIR = 1, a horizontal colour bar will be plotted. NX, NY are the plot coordinates of the lower left corner. Analogue: ZAXLG plots a logarithmically scaled colour bar. Note: The user is referred to the notes on secondary axes in chapter 4. 11.4 Plotting Data Points The routines CURVE3, CURVX3, CURVY3, CRVMAT, CRVTRI and CRVQDR plot three-dimensional data points. CURVE3 plots ran- dom points from X-, Y- and Z-arrays, CURVY3 plots points as columns, CURVX3 plots data points as rows and CRVMAT plots a coloured surface according to a matrix. The routines CRV- TRI and CRVQDR plot triangles and quadrangles as they are often used in finite element methods. The calls are: CALL CURVE3 (XRAY, YRAY, ZRAY, N) level 3 CALL CURVX3 (XRAY, Y, ZRAY, N) CALL CURVY3 (X, YRAY, ZRAY, N) CALL CRVMAT (ZMAT, IXDIM, IYDIM, IXP, IYP) CALL CRVTRI (XRAY, YRAY, ZRAY, N, I1RAY, I2RAY, I3RAY, NTRI) CALL CRVQDR (XRAY, YRAY, ZRAY, 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. X is the X-pos. of a column of data points. Y is the Y-position of a row of data points. ZMAT is a matrix of the dimension (IXDIM, IYDIM) containing Z-coordinates. The coordinates correspond to a linear grid that overlays the axis system. If XA, XE, YA and YE are the axis limits in GRAF3 or values defined with the routine SURSZE, the relationship between the grid points and the matrix ele- ments can be described by the formula: ZMAT(I,J) = F(X,Y) where X = XA + (I - 1) * (XE - XA) / (IXDIM - 1), I = 1,...,IXDIM Y = YA + (J - 1) * (YE - YA) / (IYDIM - 1), J = 1,...,IYDIM. IXDIM, IYDIM define the dimension of ZMAT (>= 2). IXP, IYP are the number of interpolation steps be- tween grid lines (>= 1). CRVMAT can interpo- late points linearly. I1RAY, I2RAY, is a triangulation of the points (XRAY, I3RAY YRAY). A Delaunay triangulation of data poins can for example calculated with the routine TRIANG. NTRI is the number of triangles in I1RAY, I2RAY and I3RAY. Notes: - The routine above must be called after GRAF3 from level 3. - The size of coloured rectangles can be de- fined with the routine SETRES or calculated automatically by DISLIN using the routine AUTRES. - The routines CRVTRI and CRVQDR can plot smooth surfaces with interpolated colours if the statement CALL SHDMOD ('SMOOTH', 'SUR- FACE') is used before. For this case, a ras- ter format must be defined with METAFL. - For CRVQDR, the data points describe the corners of the quadrangles: the first four points the first quadrangle, the next four points the next quadrangle, and so on. The number of quadrangles is N / 4. - Z-coordinates that lie outside of the axis scaling will be plotted with the colour 0 if they are smaller than the lower limit, or with the colour 255 if they are greater than the upper limit. To reduce computing time and the size of plot files, the plotting of points with the colour 0 can be suppressed with the routine NOBGD. - The routines CONMAT and SURMAT are analogy to CRVMAT and plot contours and surfaces of space. 11.5 Parameter Setting Routines S E T R E S SETRES defines the size of rectangles plotted by CURVE3, CURVY3 and CRVMAT. The call is: CALL SETRES (NPB, NPH) level 1, 2, 3 NPB, NPH are the width and height of rectangles in plot coordinates (> 0). Default: (1,1). A U T R E S With a call to AUTRES, the size of coloured rectangles will be automatically calculated by GRAF3 or CRVMAT. The call is: CALL AUTRES (IXDIM, IYDIM) level 1 IXDIM, IYDIM are the number of data points in the X- and Y- direction, or (0, 0). If IXDIM = 0 and IYDIM = 0, CRVMAT plots rectangles between neigh- bouring data points. This is useful for loga- rithmic axes, where the rectangles should have a different size. S H D M O D Normally, the routines CURVE3, CURVX3, CURVY3 and CRVMAT plot coloured rectangles, but a symbol or pixel mode can be enabled with the routine SHDMOD. The symbols used by the routines above and the size of the symbols can be set with the routines MARKER and HSYMBL. Pixel mode can only be used for screen and image output. The call is: CALL SHDMOD (COPT, 'CURVE') level 1, 2, 3 COPT is a character string that can have the values 'RECT', 'SYMB' and 'PIXE'. Default: COPT = 'RECT'. A X 3 L E N The routine AX3LEN defines the axis lengths of a coloured axis system. The call is: CALL AX3LEN (NXL, NYL, NZL) level 1, 2, 3 NXL, NYL, NZL are the axis lengths in plot coordinates. P O S B A R The routine POSBAR sets the position of colour bars. By de- fault, colour bars are plotted in a vertical direction near the right Y-axis of an axis system. The call is: CALL POSBAR (COPT) level 1, 2, 3 COPT is a character value defining the position of colour bars. = 'FIXED' means that the colour bar is plotted in a vertical direction near the right Y-axis. = 'RIGHT' has nearly the same meaning as the keyword 'FIXED', but the colour bar is automatically moved if labels and an axis title is plotted at the right Y-axis. = 'TOP' means that the colour bar is plotted above the axis system in a horizontal direction. = 'BOTTOM' means that the colour bar is plotted below the axis system in a horizontal direction. = 'LEFT' means that the colour bar is plotted on the left side of the axis system. Default COPT = 'FIXED'. J U S B A R JUSBAR defines alignment of colour bars. The call is: CALL JUSBAR (COPT) level 1, 2, 3 COPT is a character value defining the alignment of colour bars. = 'START' means that the colour bar is plotted at the beginning of the X- or Y-axis. = 'CENTER' means that the colour bar is centred at the X- or Y-axis. = 'END' means that the colour bar is justified at the end of the X- or Y-axis. Default COPT = 'START'. W I D B A R The routine WIDBAR defines the width of a colour bar. The call is: CALL WIDBAR (NZB) level 1, 2, 3 NZB is the width in plot coordinates. Default NZB = 85 F R M B A R The routine FRMBAR defines the thickness of frames around colour bars. The call is: CALL FRMBAR (N) level 1, 2, 3 N is the thickness in plot coordinates. Default N = 0 S P C B A R The routine SPCBAR defines the space between colour bars and axis systems. The call is: CALL SPCBAR (N) level 1, 2, 3 N is the space in plot coordinates. Default N = 85 V K X B A R The routine VKXBAR defines horizontal shifting of colour bars. The distance between the colour bar and the axis sys- tem is, by default, 85 plot coordinates. The call is: CALL VKXBAR (NVFX) level 1, 2, 3 NVFX is an integer that defines the shifting. If NVFX is positive, the colour bar will be shif- ted right; if NVFX is negative the colour bar will be shifted left. Default: NVFX = 0 V K Y B A R The routine VKYBAR defines a vertical shifting of colour bars. The call is: CALL VKYBAR (NVFY) level 1, 2, 3 NVFY is an integer that defines the shifting. If NVFY is positive, the colour bar will be shif- ted up; if NVFY is negative, the colour bar will be shifted down. Default: NVFY = 0 N O B A R The routine NOBAR instructs DISLIN to suppress the plotting of colour bars. The call is: CALL NOBAR level 1, 2, 3 C O L R A N This routine defines the range of colours used for colour bars. By default, the range is 1 to 254. The call is: CALL COLRAN (NCA, NCE) level 1, 2, 3 NCA, NCE are colour numbers in the range 1 to 254. Default: (1, 254). N O B G D With a call to the routine NOBGD, the plotting of points with the colour 0 will be suppressed. This reduces plotting time and the size of plot files. The call is: CALL NOBGD level 1, 2, 3 E X P Z L B The routine EXPZLB expands the numbering of a logarithmical- ly scaled Z-axis to the next order of magnitude that lies up or down the axis limits. The scaling of the colour bar will not be changed. This routine is useful if the range of the Z-axis scaling is smaller than 1 order of magnitude. The call is: CALL EXPZLB (CSTR) level 1, 2, 3 CSTR is a character string defining the expansion of the Z-axis numbering. = 'NONE' means that the numbering will not be expanded. = 'FIRST' means that the numbering will be expanded downwards. = 'BOTH' means that the numbering will be expanded down- and upwards. Default: CSTR = 'NONE'. 11.6 Elementary Plot Routines The following routines plot coloured rectangles and pie sec- tors. They use the hardware features of a colour graphics system or PostScript printer. R E C F L L The routine RECFLL plots a coloured rectangle where the po- sition is determined by the upper left corner. The call is: CALL RECFLL (NX, NY, NB, NH, NCOL) level 1, 2, 3 NX, NY are the plot coordinates of the upper left corner. NB, NH are the width and height in plot coordinates. NCOL is a colour value. P O I N T The routine POINT plots a coloured rectangle where the position is determined by the centre. The call is: CALL POINT (NX, NY, NB, NH, NCOL) level 1, 2, 3 NX, NY are the plot coordinates of the centre point. NB, NH are the width and height in plot coordinates. NCOL is a colour value. R L P O I N The routine RLPOIN plots a coloured rectangle where the position is specified in user coordinates. The call is: CALL RLPOIN (X, Y, NB, NH, NCOL) level 2, 3 Note: RLPOIN clips rectangles at the borders of an axis system. S E C T O R The routine SECTOR plots coloured pie sectors. The call is: CALL SECTOR (NX, NY, NR1, NR2, ALPHA, BETA, NCOL) level 1, 2, 3 NX, NY are the plot coordinates of the centre point. NR1 is the interior radius. NR2 is the exterior radius. ALPHA, BETA are the start and end angles measured in de- grees in a counter-clockwise direction. NCOL is a colour value. Example: CALL SECTOR (100, 100, 0, 50, 0., 360., NCOL) plots a circle around the centre (100,100) with the radius 50 and the colour NCOL. R L S E C The routine RLSEC plots coloured pie sectors where the cen- tre and the radii are specified in user coordinates. The call is: CALL RLSEC (X, Y, R1, R2, ALPHA, BETA, NCOL) level 2, 3 Notes: - For the conversion of the radii to plot coor- dinates, the scaling of the X-axis is used. - Sectors plotted by RLSEC will not be cut off at the borders of an axis system. 11.7 Conversion of Coordinates The function NZPOSN and the subroutine COLRAY convert user coordinates to colour values. N Z P O S N The function NZPOSN converts a Z-coordinate to a colour num- ber. The call is: ICLR = NZPOSN (Z) level 3 Note: If Z lies outside of the axis limits and Z is smaller than the lower limit, NZPOSN returns the value 0 and the routine returns the value 255 if Z is greater than the upper limit. C O L R A Y The routine COLRAY converts an array of Z-coordinates to colour values. The call is: CALL COLRAY (ZRAY, NRAY, N) level 3 ZRAY is an array of Z-coordinates. NRAY is an array of colour numbers calculated by COLRAY. N is the number of coordinates. 11.8 Example PROGRAM EX11_1 ! 3-D Colour Plot PARAMETER (N=100) DIMENSION ZMAT(N,N) FPI=3.1415927/180. STEP=360./(N-1) DO I=1,N X=(I-1.)*STEP DO J=1,N Y=(J-1.)*STEP ZMAT(I,J)=2*SIN(X*FPI)*SIN(Y*FPI) END DO END DO CALL METAFL('POST') CALL DISINI CALL PAGERA CALL PSFONT('Times-Roman') CALL TITLIN('3-D Colour Plot of the Function',1) CALL TITLIN('F(X,Y) = 2 * SIN(X) * SIN(Y)',3) CALL NAME('X-axis','X') CALL NAME('Y-axis','Y') CALL NAME('Z-axis','Z') CALL INTAX CALL AUTRES(N,N) CALL AXSPOS(300,1850) CALL AX3LEN(2200,1400,1400) CALL GRAF3(0.,360.,0.,90.,0.,360.,0.,90., * -2.,2.,-2.,1.) CALL CRVMAT(ZMAT,N,N,1,1) CALL HEIGHT(50) CALL PSFONT('Palatino-BoldItalic') CALL TITLE CALL DISFIN END