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 plotted as a coloured rectangle where the X- and Y-coor- dinates determine the position of the rectangle and the Z- coordinate defines the colour. Colours are calculated from a scaled colour bar which is, by default, arranged as a rain- bow. The following plotting routines require special gra- phics devices that can display a wide range of colours, such as a workstation or a PC with a VGA card. These devices will be called colour graphics systems throughout this chapter. A laserprinter with a PostScript emulation can also be used for 3-D colour graphics. Notes: - A colour graphics system can be chosen with the parameters 'CONS', 'XWIN' and 'XWIi' in the rou- tine METAFL where i is a window number between 1 and 5. With the parameters 'POST' and 'PSCL', PostScript files can be created. - The output of plot commands to the screen may be buffered. To send the buffer to the screen, the statement CALL SENDBF must be used. - Up to 256 colours can be displayed at the same time. Colours are numbered in the range 0 to 255 where the number is an index in the current co- lour table. DISLIN provides several colour tab- les. 11.2 X Window Terminals X Window terminals are the usual graphics displays on work- stations. In DISLIN, the X Window emulation can be activated with the keywords 'CONS', 'XWIN' and 'XWIi' in the routine METAFL where i is a window number between 1 and 5. For the keyword 'CONS', the entire screen will be used for graphics output while for the other keywords, smaller windows are created. The keywords 'XWIN' and 'XWI1' have the same mea- ning. By default, the position of windows depends upon the window number. Window 1 is situated in the lower right cor- ner, window 2 in the upper right corner, window 3 in the up- per left corner, window 4 in the lower left corner and win- dow 5 in the centre of the screen. The position and size of windows can be changed with the routines WINDOW and WINSIZ. Notes: - Normally, a program using X Window emulation is blocked in the termination routine DISFIN and waiting for a mouse button 2 event to continue program execution. This behaviour of DISLIN can be modified with the routine WINMOD. - To conserve current screen and window colours, the number of colours on an X Window screen is reduced in DISLIN from 256 to 129 colours. This can be changed with the routine CLRMOD. - Backing store for an X graphics window can be en- abled with CALL X11MOD ('STORE'). Normally, back- ing store is done automatically by the X server. - Multiple windows can be used for graphics output on an X Window screen. 11.3 PostScript Files PostScript files can be created from within DISLIN if the keywords 'POST' and 'PSCL' are used in METAFL. For the key- word 'POST', the greyscale table 'RGREY' will be preloaded by DISINI and the graphics will be plotted with a white background. For the keyword 'PSCL', the colour table 'RAIN' will be preloaded and the graphics will be plotted with a black background. To create a colour PostScript file with a white background, use the keyword 'POST' in METAFL and the routine SETVLT to load a new colour table. 11.4 Clearing the Screen E R A S E The routine ERASE clears the screen of a colour graphics system or of a graphics terminal. In general, this is done by DISINI at the beginning of a plot. The call is: CALL ERASE level 1, 2, 3 11.5 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.6 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. Analog: ZAXLG plots a logarithmically scaled colour bar. Note: The user is referred to the notes on secondary axes in chapter 4. 11.7 Plotting Data Points The routines CURVE3, CURVX3, CURVY3 and CRVMAT plot three- dimensional data points. CURVE3 plots random points from X-, Y- and Z-arrays, CURVY3 plots points as columns, CURVX3 plots data points as rows while CRVMAT plots a coloured sur- face according to a matrix. 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) 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. Notes: - CURVE3, CURVY3 and CRVMAT 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. - 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 plotfiles, the plotting of points with the colour 0 can be suppressed with the routine NOBGD. - The routines CONMAT and SURMAT are analogs to CRVMAT and plot contours and surfaces of space. 11.8 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. S E T C L R The routine SETCLR defines the colour used for text and lines. The call is: CALL SETCLR (NCOL) level 1, 2, 3 NCOL is a colour number in the range 0 to 255. Default: NCOL = 255 S E T R G B The routine SETRGB defines the foreground colour specified in RGB coordinates. SETRGB sets the nearest entry in the co- lour table that matches the RGB coordinates. This means that a colour will not be defined exactly if it is not contained in the colour table. The call is: CALL SETRGB (XR, XG, XB) level 1, 2, 3 XR, XG, XB are the RGB coordinates of a colour in the range 0 to 1. 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. 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 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 plotfiles. The call is: CALL NOBGD level 1, 2, 3 S E T V L T SETVLT selects a colour table. The call is: CALL SETVLT (CVLT) level 1, 2, 3 CVLT is a character string that defines the colour table. = 'SMALL' defines a small colour table with the 8 co- lours: 1 = BLACK, 2 = RED, 3 = GREEN, 4 = BLUE, 5 = YELLOW, 6 = ORANGE, 7 = CYAN and 8 = MAGENTA. = 'VGA' defines the 16 standard colours of a VGA gra- phics card. = 'RAIN' defines 256 colours arranged in a rainbow where 0 means black and 255 means white. = 'SPEC' defines 256 colours arranged in a rainbow where 0 means black and 255 means white. This colour table uses more violet colours than 'RAIN'. = 'GREY' defines 256 grey scale colours where 0 means black and 255 is white. = 'RRAIN' is the reverse colour table of 'RAIN'. = 'RSPEC' is the reverse colour table of 'SPEC'. = 'RGREY' is the reverse colour table of 'GREY'. The default colour table is 'RGREY' for Post- Script files created with the keyword 'POST' in the routine METAFL, and otherwise 'RAIN'. M Y V L T The routine MYVLT changes the current colour table. The call is: CALL MYVLT (XR, XG, XB, N) level 1, 2, 3 XR, XG, XB are arrays containing RGB coordinates in the range 0 to 1. N is the number of colour entries. S E T I N D The routine SETIND allows the user to change the current colour table. The call is: CALL SETIND (INDEX, XR, XG, XB) level 1, 2, 3 INDEX is an index between 0 and 255. XR, XG, XB are the RGB coordinates of a colour in the range 0 to 1. Sometimes, it is easier to specify colours as HSV coordina- tes where H is the hue, S the saturation and V the value of a colour. The following routines convert coordinates from the HSV to the RGB model and vice versa. H S V R G B The routine HSVRGB converts HSV coordinates to RGB coordina- tes. The call is: CALL HSVRGB (XH, XS, XV, XR, XG, XB) level 1, 2, 3 XH, XS, XV are the hue, saturation and value of a colour. XH must be in the range 0 to 360 degrees while XS and XV can have values between 0 and 1. In the HSV model, colours lie in a spectral order on a six-sided pyramid where red corres- ponds to the angle 0, green to 120 and blue to 240 degrees. XR, XG, XB are the RGB coordinates in the range 0 to 1 calculated by HSVRGB. R G B H S V The routine RGBHSV converts RGB coordinates to HSV coordina- tes. The call is: CALL RGBHSV (XR, XG, XB, XH, XS, XV) level 1, 2, 3 R E V S C R The routine REVSCR exchanges the colours with the indices 0 and 255. The call is: CALL REVSCR 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.9 Elementary Image Routines The following routines allow transfering of image data be- tween windows, files and arrays. I M G I N I The routine IMGINI initializes transfering of image data with the routines RPIXEL, RPIXLS, RPXROW, WPIXEL, WPIXLS and WPXROW. The call is: CALL IMGINI level 1, 2, 3 I M G F I N The routine IMGFIN terminates transfering of image data with the routines RPIXEL, RPIXLS, RPXROW, WPIXEL, WPIXLS and WPXROW. The call is: CALL IMGFIN level 1, 2, 3 R P I X E L The routine RPIXEL reads one pixel from memory. The call is: CALL RPIXEL (IX, IY, ICLR) level 1, 2, 3 IX, IY is the position of the pixel in screen coordi- nates. ICLR is the returned colour value of the pixel. W P I X E L The routine WPIXEL writes one pixel into memory. The call is: CALL WPIXEL (IX, IY, ICLR) level 1, 2, 3 IX, IY is the position of the pixel in screen coordi- nates. ICLR is the new colour value of the pixel. R P I X L S The routine RPIXLS copies colour values from a rectangle in memory to an array. The call is: CALL RPIXLS (IRAY, IX, IY, NW, NH) level 1, 2, 3 IRAY is a byte array containing the returned colour values. IX, IY contain the starting point in screen coordina- tes. NW, NH are the width and height of the rectangle in screen coordinates. W P I X L S The routine WPIXLS copies colour values from an array to a rectangle in memory. The call is: CALL WPIXLS (IRAY, IX, IY, NW, NH) level 1, 2, 3 IRAY is a byte array containing the colour values. IX, IY contain the starting point in screen coordina- tes. NW, NH are the width and height of the rectangle in screen coordinates. R P X R O W The routine RPXROW copies one line of colour values from memory to an array. The call is: CALL RPXROW (IRAY, IX, IY, N) level 1, 2, 3 IRAY is a byte array containing the returned colour values. IX, IY contain the starting point in screen coordina- tes. N is the number of image data. W P X R O W The routine WPXROW copies colour values from an array to a line in memory. The call is: CALL WPXROW (IRAY, IX, IY, N) level 1, 2, 3 IRAY is a byte array containing the colour values. IX, IY contain the starting point in screen coordina- tes. N is the number of image data. Note: IMGINI and IMGFIN must be used with the rou- tines RPIXEL, WPIXEL, RPIXLS, WPIXLS, RPXROW and WPXROW. R I M A G E The routine RIMAGE copies an image from memory to a file. The call is: CALL RIMAGE (CFIL) level 1, 2, 3 CFIL is the name of the output file. A new file version will be created for existing files (see FILMOD). Notes: - Images are stored with an ASCII header of 80 bytes length followed by the binary image data. - A single image file can be displayed with the routine WIMAGE or with the utility program DISIMG. A sequence of image files can be dis- played with the utility program DISMOV. W I M A G E The routine WIMAGE copies an image from a file to memory. The call is: CALL WIMAGE (CFIL) level 1, 2, 3 CFIL is the name of the input file. R T I F F The routine RTIFF copies an image from memory to a file. The image is stored in the device-independent TIFF format. The call is: CALL RTIFF (CFIL) level 1, 2, 3 CFIL is the name of the output file. A new file version will be created for existing files (see FILMOD). Notes: - This image format can be used to export images created with DISLIN into other software pack- ages or to transfer them to other computer systems. - A TIFF file created by DISLIN can be displayed with the routine WTIFF or with the utility program DISTIF. W T I F F The routine WTIFF copies an TIFF file created by DISLIN from a file to memory. The call is: CALL WTIFF (CFIL) level 1, 2, 3 CFIL is the name of the input file. Note: The position of the TIFF file and a clipping window can be defined with the routines TIFORG and TIFWIN. T I F O R G The routine TIFORG defines the upper left corner of the screen where the TIFF file is copied to. The call is: CALL TIFORG (NX, NY) level 1, 2, 3 NX, NY is the upper left corner in screen coordina- tes. T I F W I N The routine TIFWIN defines a clipping window of the TIFF file that can be copied with the routine WTIFF to the screen. The call is: CALL TIFWIN (NX, NY, NW, NH) level 1, 2, 3 NX, NY is the upper left corner of the clipping win- dow in pixels. NW, NH are the width and height of the clipping win- dow in pixels. R P N G The routine RPNG copies an image from memory to a PNG file. The call is: CALL RPNG (CFIL) level 1, 2, 3 CFIL is the name of the output file. A new file version will be created for existing files (see FILMOD). R B F P N G The routine RBFPNG copies an image from memory as a PNG file to a buffer. The call is: CALL RBFPNG (CBUF, NMAX, N) level 1, 2, 3 CBUF is a character buffer where the image is copied to in PNG format. NMAX defines how many bytes can be copied to CBUF. N is the returned length of the buffer. N <= 0, if an error occurs. The following routines allow programs to create up to 5 win- dows for graphics output on an X Window terminal. Note, that multiple windows can be used with X Window emulation but are not compatible with other file formats in DISLIN. O P N W I N The routine OPNWIN creates a new window for graphics output on the screen. The call is: CALL OPNWIN (ID) level 1, 2, 3 ID is the window number between 1 and 5. Normal- ly, window 1 will be created in the lower right corner, window 2 in the upper right cor- ner, window 3 in the upper left corner, win- dow 4 in the lower left corner and window 5 in the center of the screen. Notes: - The file format must be set to X Window emula- tion in the routine METAFL (i.e. with the key- word 'XWIN'). - The size and position of windows can be chan- ged with the routines WINDOW and WINSIZ. - Windows can be closed and selected with the routines CLSWIN and SELWIN. - A created window with OPNWIN is selected auto- matically for graphics output. - The routine WINMOD affects the handling of windows in the termination routine DISFIN. C L S W I N The routine CLSWIN closes a window created with OPNWIN. The call is: CALL CLSWIN (ID) level 1, 2, 3 ID is the window number between 1 and 5. S E L W I N The routine SELWIN selects a window on the screen where the following graphics output will be sent to. The call is: CALL SELWIN (ID) level 1, 2, 3 ID is the window number between 1 and 5. W I N I D The routine WINID returns the ID of the currently selected window. The call is: CALL WINID (ID) level 1, 2, 3 ID is the returned window number. W I N T I T The routine WINTIT changes the window title of the currently selected window. The call is: CALL WINTIT (CSTR) level 1, 2, 3 CSTR is a character string containing the new window title. 11.11 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 index in the range 0 to 255. 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 index in the range 0 to 255. 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 index between 0 and 255. 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.12 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.13 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