GPLOT A Library of Tools for use with the Graphical Kernel System (GKS) T. G. Worlton Intense Pulsed Neutron Source Argonne National Laboratory and D. Mikkelson University of Wisconsin January 4, 1991 GPLOT Graphics Routines Page i qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq Table of Contents 1. Introduction .............................................. 1 2. Plot Orientation .......................................... 1 3. Device Nomination Routines ................................ 2 4. Basic Plot Routines ....................................... 3 5. Modifying the Plot Layout ................................. 5 5.1 Reducing the Plot Size ............................... 5 5.2 Changing the Plot Origin ............................. 5 5.3 Creating Multiple Plots on a Page .................... 5 5.4 Clipping the Plot .................................... 5 5.5 Framing the Plot/Subplot Areas ....................... 6 5.6 Data Transforms ...................................... 6 6. Writing Text on the Plot .................................. 7 6.1 Text Size and Orientation ............................ 8 6.2 Text Fonts ........................................... 8 6.3 Instruction Font ..................................... 10 7. Drawing Axes .............................................. 10 7.1 Linear Axes .......................................... 12 7.2 Logarithmic Axes ..................................... 12 7.3 Producing Grids and/or Tick Marks .................... 12 8. Drawing Curves ............................................ 13 8.1 Error Bars ........................................... 13 8.2 Line Types ........................................... 13 8.3 Colors ............................................... 14 8.4 Data Markers ......................................... 14 8.5 Interpolation Routines ............................... 15 9. Legends ................................................... 15 10. Vectors With and Without Arrowheads ...................... 16 11. Graphic Primitives ....................................... 17 12. Bar Graphs ............................................... 18 13. Contouring Routines ...................................... 18 14. 3 Dimensional Plotting ................................... 20 14.1 Setting the "workbox" ............................... 21 14.2 Setting the Viewing Parameters. ...................... 21 14.3 Establishing a "relative" coordinate system ......... 23 14.4 3D Output ........................................... 24 GPLOT Graphics Routines Page ii qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq 15. Graphics Input ........................................... 26 15.1 Reading the Cursor Position ......................... 26 15.2 Using the Cursor to Modify the Plot ................. 26 Index ......................................................... 28 Examples ...................................................... 34 GPLOT Graphics Routines Page 1 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq 1. Introduction GPLOT is a collection of routines written to support generation of plots of scientific data with GKS graphics. They have been developed and tested using DEC VAX-GKS 4.0/4.1 which is a level 2c product. Since DEC GKS extensions to the GKS standard have been used, some special features may need to be modified before GPLOT will function correctly with another GKS package. These routines can be linked to your programs by including the following in your link statement: . . . ,GPLOT/OPT. This logical name points to both the DEC VAX GKS library and GPLOT routines. Standard GKS calls may be mixed with calls to GPLOT routines, but you should be aware of attributes and transforms set by GPLOT. One of the primary purposes of GPLOT was to make it easy to convert graphics written for CA-DISSPLA 10.5, so many GPLOT routines originally had the same name and functioned in the same way as DISSPLA 10.5. Since the original version of GPLOT, it has been modified for compatibility with version 11.0 of CA-DISSPLA. DISSPLA 11.0 uses character strings instead of byte strings for text, but uses the same subroutine names as DISSPLA 10.5. The version of GPLOT compatible with DISSPLA 11.0 is now the default. To link this version of GPLOT include "GPLOT_DIR:GPLOT/OPT" at the end of your link statement.: GPLOT provides routines that allow you to create axes and plot data easily. It provides both linear and logarithmic axes and allows marking the data with a variety of symbols and error bars. It also provides routines for placing a legend which labels the curves on the plot. This will automatically show the correct symbol, curve type, and color for each data curve. GPLOT can also do a number of interpolations to fit experimental data. GPLOT has routines for drawing bar graphs, contour plots, and 3D surface plots with hidden-line removal. There are routines for drawing polygons, circles, ellipses, arcs of circles or ellipses, and for drawing vectors with arrow heads. These may be filled or open. GPLOT does not provide blanking of areas like DISSPLA does because GKS supports clipping only at the plot boundary, but for some devices it is possible to erase an area by filling the area with the background color. GPLOT also has some conventions which differ from DISSPLA. For instance, the tic marks are by default to the inside for GPLOT and to the outside for DISSPLA, and GPLOT draws axes at the top and right hand side of the plot area.. 2. Plot Orientation For the laser printers supported by DEC VAX GKS the default orientation is landscape. If you draw a plot intended to be in portrait orientation, your first GPLOT call should be: GPLOT Graphics Routines Page 2 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CALL ORIENT('PORTRAIT') Otherwise your 8.5" X 11" plot will appear scaled down to fit in the landscape orientation. This call must be made before the device nomination call because the page orientation is determined when the device is nominated. For screen devices such as the VAXstation or TK4014 terminal, the plot orientation cannot be changed. The Tektronix 4014 output only device which is used to produce plots on the DEC LN03-Plus also does not support changing to portrait orientation. 3. Device Nomination Routines Before a plot can be generated, one or more workstation devices must be nominated. In most cases, the first GPLOT call should be: CALL GSTART The devices for a given site are defined in the routine GPLOT_SRC:GDINIT.DAT. Information in this file allows plot files to be sent to a particular print queue automatically. Plot files which are to be sent to a print queue automatically are created in the SYS$SCRATCH directory and will be deleted after printing. If GDINIT does not specify a print queue, the output file will be created in your current directory and not printed. Some options in the menu, such as Postscript-file or Tektronix-file are designed to create an output file for later use. You can create your own customized menu by copying the file GPLOT_SRC:GDINIT.DAT to SYS$LOGIN:. And then using the program EDIT_GMENU to modify it as desired. To add new devices, you will need to know the workstation type numbers which are given in the DEC GKS documentation. For plotters to print automatically you will also need the queue name and the name of any form needed to put the printer into the graphics mode. The device name for a hardcopy device usually is the queue name, but can be any name of your choosing. When running in batch mode you will need to include the command: $ DEFINE PLOTTER device-name where "device-name" is the name you have specified in setting up your menu. Information about each device can be obtained during the GMENU display by selecting the device and pressing the help key. The system manager uses a text editor to store site-dependent help information in the file SYS$HELP:GPLOT.HLP then uses the LIBRARY command to insert the new information in SYS$HELP:GPLOT.HLB. For Batch jobs, it is recommended that you make the following the first call to GPLOT: GPLOT Graphics Routines Page 3 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CALL GSTART GSTART will look at the logical names SCREEN and PLOTTER to see which device(s) to activate. If neither of these is defined to be a valid device, GSTART will call GMENU to produce a menu of available graphics devices. If both SCREEN and PLOTTER are defined as valid devices when GSTART is called, the plot will be generated on both at the same time. To stop getting plots on a particular device, deassign SCREEN and/or PLOTTER or define them to be different devices. For instance if you have a program, GRAPH, which calls GSTART you could use the following series of commands to preview a plot and then make a hard copy on the LW print queue (assuming this is a valid queue at your site). $ DEFINE SCREEN TK4014 $ RUN GRAPH $ DEASSIGN SCREEN $ DEFINE PLOTTER LW $ RUN GRAPH If you omitted the second and third commands, the two plots would be generated simultaneously. We do not currently have a way of plotting CGM metafiles, but GKS metafiles can be plotted using a postprocessing routine (use the command POSTGKS to run the GKS postprocessor). Although GMENU and GSTART are the recommended methods of nominating a graphics device, it is possible to nominate many devices with a direct subroutine call. Most of these are included to emulate CA-DISSPLA. The device nomination routine calls currently supported are: Device Call Device CALL GKSM Produce GKS Graphics Metafile. CALL COMPRS Same as GKSM CALL CGMCO Produce CGM Character metafile CALL CGMTO Produce CGM Clear Text metafile CALL POSTSCRIPT Apple Laser Writer CALL PSCRPT(X0,Y0,XW,YW) Same as POSTSCRIPT (arguments ignored) CALL HP7550 Hewlett Packard pen plotter CALL LA50 Produce plot file for LA50. CALL LA75 Produce plot file for LA75. CALL TK4014F Graphics file to be printed on TK4014 emulator CALL QMS Same as TK4014F CALL QMS2 Same as TK4014F CALL TALRS3 Same as TK4014F CALL LN03TK Same as TK4014F CALL TK4014 Graphics terminal with TK4014 emulation CALL VAXSTATION Produce plot on VAXstation window CALL REGIS(I1,I2) Plot on VT240 (I2=0) or VT241 (I2=1) GPLOT Graphics Routines Page 4 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq (I1 is ignored) CALL VT330 Plot on VT330. CALL VT340 Plot on VT340. CALL GMENU Choose device from screen menu CALL GSTART (See above) 4. Basic Plot Routines A basic plot can be generated using the following basic GPLOT calls: CALL GSTART CALL PAGE (PAGEX,PAGEY) (PAGEX and PAGEY are the dimensions of the page. If there is no call to PAGE, then PAGEX and PAGEY take the default values of 8.5 and 11.0. The page orientation will be landscape unless ORIENT('PORTRAIT') is called before GSTART) CALL AREA2D (XAXIS,YAXIS) (XAXIS and YAXIS are the lengths of the axes. AREA2D is one routine which must always be called) CALL XNAME (XNAME,LXNAME) (XNAME is the name of a text string containing the x-axis label. LXNAME is the length of that name. If XNAME ends in a dollar sign ($), LXNAME can be specified as 100 and the dollar sign will be ignored. Text specified in single quotes will work in either GPLOT3 or GPLOT11. If you want to use character string variables in GPLOT3, specify it as %REF(XNAME).) CALL YNAME (YNAME,LYNAME) CALL GRAF (XORIG,XSTEP,XMAX,YORIG,YSTEP,YMAX) (XORIG is the x-data value at the origin of the x-axis. XSTEP is the change in x-data value per axis division, and XMAX is the x-data value at the end of the AXIS. If 'SCALE' is used for XSTEP and/or YSTEP, GPLOT will calculate appropriate values to use.) CALL CURVE (XARRAY,YARRAY,NPNTS,IMARK) (XARRAY and YARRAY are the arrays of x-data values and y- data values, NPNTS is the number of data points in the arrays, and IMARK is an indicator of the data marker frequency. If IMARK=0, no symbols will be plotted and if IMARK > 0 symbols will be plotted every IMARKth point. If IMARK < 0 symbols will be plotted, but no curve will be drawn.) CALL ENDPL (IPLOT) GPLOT Graphics Routines Page 5 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq (ENDPL updates the plot and if the mode is interactive and the device is of type input/output, ENDPL pauses for the user to view the plot. When the user types a RETURN, it closes and deactivates the workstation and zeros some of the plot parameters, so that AREA2D and GRAF must be called again to set up another plot. If IPLOT is greater than zero, information about the plot routine will be written in the lower left corner of the plot. If Workstation Independent Segment Storage (WISS) is active and there is no hardcopy device active, the user will be asked if he wants a hardcopy of that plot frame.) CALL GSTOP A simple plot created using the above routines is illustrated by Example 1 in the Appendix. 5. Modifying the Plot Layout The values of PAGEX and PAGEY set by the call to PAGE determine the aspect ratio of the plot. The axes lengths set by the call to AREA2D together with the page variables determine the sub plot area within the plot area. These values are used to calculate the normalization viewport in Normalized Display Coordinates (NDC) for the plot area and for the sub plot area. The workstation window and viewport are then calculated for these same transforms using the currently active workstation(s). When the data values at the axis extremes have been set by calls to GRAF or XGRAXS and YGRAXS, the data transform is calculated. 5.1 Reducing the Plot Size GPLOT will generate the largest plot that can be produced on the workstation surface while maintaining the aspect ratio indicated by the two PAGE parameters. If you want to generate a smaller plot, you can control the size and position of the plot on the page by using a smaller subplot area and changing the plot origin. 5.2 Changing the Plot Origin GPLOT will try to center the sub plot area within the plot area. For special cases such as when you want to produce multiple plots on a page, you can use one of the following calls to change the sub-plot origin: CALL PHYSOR(XPHYS,YPHYS) (Where XPHYS and YPHYS are the coordinates of the origin of the sub-plot area with respect to the corner of the page) CALL OREL(XOREL,YOREL) (Where XOREL, YOREL is the offset of the sub-plot origin with respect to the previous origin) GPLOT Graphics Routines Page 6 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq 5.3 Creating Multiple Plots on a Page Calls to change the plot origin are particularly useful when you want to create multiple subplots on a page. Each subplot except the last should be terminated with the call: CALL ENDGR(IPLOT) The call to ENDGR will terminate the current plot, but not eject a page so you can produce multiple plots on the same page. See Examples 3, 7, and 14 in the Appendix for ways of using this feature. Note in these examples that the call to AREA2D or YGRAXS together with the call to PHYSOR or OREL determines the portion of the page which will contain the plot. 5.4 Clipping the Plot Points lying outside the page window will always be clipped. To clip all points lying outside the subplot area defined by AREA2D, include the statement CALL GRACE(0.0) The default clipping can be restored by calling GRACE with an argument greater than 0.5. An alternative is to use the GKS routine GSCLIP to turn clipping on and off. 5.5 Framing the Plot/Subplot Areas By default, GPLOT will draw a border around the plot area. To eliminate this plot border, make the call: CALL NOBRDR GPLOT also normally draws a frame around the subplot area with tick marks on both sides and on the top and bottom (unlike DISSPLA). The frame around the subplot area will normally be at the default line width, but can be made thicker with the following calls: CALL FRAME CALL THKFRM (THKNSS) where THKNSS is approximately the thickness in inches. In calculating this, GPLOT assumes a nominal thickness of 0.01". An example of the use of these routines is given in Example Plot 2 in the Appendix. A value of THKNSS=0.04 means that the frame is approximately four times the normal thickness. If THKNSS is greater than or equal to 1.0 it is taken as a factor to multiply the nominal thickness, so THKNSS=4.0 would yield a frame four times the nominal thickness. GPLOT Graphics Routines Page 7 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq 5.6 Data Transforms GPLOT defines three GKS transforms. They transform from the page or subplot area in inches or data units to the workstation viewport. The GKS Workstation viewport is always set to be the same as the GKS normalization window. The page transform attempts to produce the largest plot possible on the display surface without changing the aspect ratio of the plot. The subplot area within the page is defined by the x and y axes in the call to area2d. The origin of the subplot area with respect to the page area (in inches) is referred to as the physical origin. GPLOT provides routines to transform between data units and position with respect to the subplot area. These routines are function routines patterned after those in DISSPLA. To obtain the position of a coordinate point (XVAL,YVAL) in inches relative to the origin, use the calls: XINCH = XPOSN (XVAL,YVAL) YINCH = YPOSN (XVAL,YVAL) To find the data value of a point at a given position on the plot, use the transforms: XVAL = XINVRS (XINCH,YINCH) YVAL = YINVRS (XINCH,YINCH) These routines are particularly useful when doing input from a graphics workstation or when you need to label data points. 6. Writing Text on the Plot It is often desirable to write additional text on the plot. This can be done with the GKS routine GTX or with one of the GPLOT routines. The GPLOT routines for writing text are the following: CALL CHRMSG (XPOS,YPOS,CSTRING) CALL MESSAG (STRING,LSTRING,XPOS,YPOS) CALL RLMESS (STRING,LSTRING,XDATA,YDATA) CALL HEADIN (STRING,LSTRING,HTMULT,NLINES) CALL REALNO (ANUM,IPLACE,XPOS,YPOS) CALL RLREAL (ANUM,IPLACE,XDATA,YDATA) CALL INTNO (INUM,XPOS,YPOS) CALL RLINT (INUM,XDATA,YDATA) GPLOT Graphics Routines Page 8 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CHRMSG is the basic GPLOT routine for text output and all the other GPLOT text routines call CHRMSG. CHRMSG has the same arguments as the GKS text output routine GTX, but CHRMSG includes the capability of switching fonts within the text string or changing character size or position with embedded instructions. This makes it easier to do subscripts, superscripts, special symbols, etc. Example plot 5 in the Appendix shows how subscripts, superscripts and Greek characters can be produced using these in-line switching capabilities. The other routines are included to emulate DISSPLA. The DISSPLA 10.5 text routines were based on an older FORTRAN standard which did not support character strings. For GPLOT3, STRING is a BYTE string of length LSTRING, or a character variable specified as %REF(STRING). For GPLOT11, STRING is a character string variable. Both GPLOT11 and GPLOT3 will accept a string constant in single quotes. If you are using routines with text strings and do not wish to count the length, you can end the string with a dollar sign ($) and set LSTRING=100. For GPLOT11 you can also specify LSTRING as 0. The parameter CSTRING used in CHRMSG is a character string so no string length needs to be passed if CHRMSG is used. In the above routines the text position XPOS and YPOS are in terms of axes units (inches or centimeters), and XDATA and YDATA are in terms of data units. HEADIN is used to center lines of text above the subplot area, so no positioning is needed, but you must pass the total number of heading lines to be used in the variable NLINES. You can also expand the height of the heading characters above the default by setting HTMULT > 1.0. The last four routines are used for writing real numbers and integers on the plot. IPLACE is used to indicate the number of decimal places to use in writing real numbers on the plot. If IPLACE is negative, the number is written in exponent form. It is sometimes useful to know the length of a text string written on a plot for text positioning, etc. The function calls XMESS, XINT, and XREAL can be used to get the length of a text string output by MESSAG, INTNO, RLINT, REALNO, or RLREAL with the current font and character height. They are called as follows: XLENGTH = XMESS(LMESS,IMESS) XLENGTH = XINT(INUM) XLENGTH = XREAL(ANUM,IPLACE) 6.1 Text Size and Orientation The Height and angle of the text may be altered by calling the routines: CALL HEIGHT (HITE) GPLOT Graphics Routines Page 9 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CALL ANGLE (ANG) These routines affect the height and angle of all text written to the screen after they are called. Example plot 2 in the Appendix shows the effect of a call to ANGLE and Example plot 5 shows the use of HEIGHT.1 If calls to the GKS routines GSCHH (HITE) and/or GSCHUP (XVEC,YVEC) are mixed with these calls, they may produce unpredictable results unless you are sure what world coordinate transformation is being used at the time. 6.2 Text Fonts DISSPLA provides a large number of software fonts and some of the DISSPLA font names have been included as valid calls in GPLOT for ease in conversion of graphics programs, but there may be little similarity in the appearance of the two fonts. The font names from DISSPLA which can be used include: CARTOG, COMPLX, DUPLX, FASHON, FUTURA, SCMPLX, SERIF, SIMPLX, SWISSB, SWISSL, SWISSM, TRIPLX, GOTHIC, GREEK, MATHEMATICAL, RUSSIAN, SCRIPT, SPECIAL, and STANDARD. Some of these select an alphabet instead of a font style and thus must be generated in software. Others may have the desired effect on a Postscript printer, but have no effect on other devices. The actual fonts available are both device and GKS implementation specific. For complete control over the font style and precision, use the GKS call: CALL GSTXFP (FONTID,PRECIS) where FONTID is an integer indicating the font to be selected, and PRECIS is an integer indicating the precision required. For highest precision, specify PRECIS = 2 (stroke precision). For medium precision, specify PRECIS = 1 (character precision), and for low precision, specify PRECIS = 0 (String precision). These precision constants are a part of the GKS standard, but the FONTID numbers are device and implementation specific. DEC has used negative numbers for all their fonts except the default font, FONTID = 1, to avoid conflict with future GKS standard font numbers. VAX GKS provides a number of software fonts which are available on any device. To draw text using software fonts requires that the processor calculate all the strokes to be made to draw each character and sends these vectors to the device. Hardware fonts are created by sending a font selection command to the device and then sending the ASCII character codes to the device. Using software fonts can increase the time taken to generate a plot by a factor of ten or more. For speed and efficiency it is always preferable to use hardware fonts. Software fonts will provide higher quality and placement precision unless you can design your graph for the hardware fonts ------------------------------ 1.The current version of DEC GKS produces software characters which are two-thirds of the requested height. The Postscript driver produces characters of the correct height, so mixing hardware and software characters on a postscript printer produces characters of differing heights. GPLOT Graphics Routines Page 10 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq available on a specific plotter or you are using a Postscript plotting device. Postscript plotters are able to generate a variety of fonts in any size and orientation. Postscript is recommended when you want to have higher quality plots, or any time you are going to need a lot of large or heavy text on the plot. Postscript plots can also be printed on a typesetter at even higher quality. DEC VAX-GKS supports a number of software fonts which are described in Appendix G of the DEC GKS Reference Manual. As mentioned, Postscript fonts can be drawn in any size and orientation. Since it is difficult to remember the font numbers, a routine has been included in GPLOT to allow selecting the fonts by name and attribute, using the call: CALL FONT ('font_name','font_attribute'), where the font attributes are 'NORMAL', 'BOLD', 'SLANT' or 'ITALIC', and 'BOLD ITALIC'. The font names for the Apple Laserwriter Plus are shown in Table 6.1 with the font name written in the indicated style. Font Attribute Sample Text Helvetica Normal ABCDEFGabcdefg Helvetica Bold ABCDEFGabcdefg Times Roman Normal ABCDEFGabcdefg Times Roman Bold ABCDEFGabcdefg Times Roman Slant ABCDEFGabcdefg Times Roman Bold Italic ABCDEFGabcdefg Palatino Normal ABCDEFGabcdefg Bookman Normal ABCDEFGabcdefg Helvetica Narrow Normal ABCDEFGabcdefg Chancery Normal ABCDEFGabcdefg Symbol Normal ABCDEFGabcdefg Dingbats Normal ABCDEFGabcdefg Table 6.1 POSTSCRIPT Font Samples It should be noted that the Laserwriter Plus has more fonts than the regular Laserwriter, and other Postscript printers may have some differences in the fonts available. 6.3 Instruction Font The advantage of using the GPLOT text routines instead of the GKS routine GTX for text output is that some capability for special formatting and font-switching within the string have been included. The routine MXiALF (LALPHA,LCHAR), where "i" can be 1- 6, can be used to define up to six special font-switching or instruction characters. In these routines LALPHA is a character or byte string giving the name of the font or character set to be used and LCHAR is a character which is used as a flag to activate the font change or instruction interpretation. Two special GPLOT Graphics Routines Page 11 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq variations of MXiALF (BASALF and MIXALF) have been defined which use the left and right parenthesis as their font switch flag characters, so they only require the parameter LALPHA. If LALPHA = 'INSTRUCTION' the text following the occurrence of the corresponding flag character will be interpreted as instructions until another flag character is found. The instructions which have been implemented are: Ex........Elevate text baseline a fraction "x" of the character height. Lx........Lower text baseline a fraction "x" of the character height. Bi........Backspace "i" characters. Hx........Multiply character height by factor "x". Ax........Move by a fraction of character height "x". The "x" above is either a real number or the letter "X". If the letter "X" is used the corresponding value will reset the variable to the default value. These instructions are interpreted by the subroutine ANLZIN which is called by CHRMSG. All the GPLOT text routines go through CHRMSG so may use these special features for font switching,etc. See Example Plot 5 in the Appendix to see how these instructions are used. 7. Drawing Axes A number of GPLOT routines are available for drawing axes. There are two routines for labelling the axes which are called as follows: CALL XNAME (XNAME,LNAME) CALL YNAME (XNAME,LNAME) where XNAME and YNAME are the labels for the axes and LNAME is the number of characters in the name. If you don't want to count characters, you can add a '$' at the end of BNAME and set LNAME = 100. If XNAME and YNAME are specified as variables instead of text constants in single quotes, they should be BYTE variables for GPLOT3 and CHARACTER variables for GPLOT11. The axes which are generated will have labels and numbers on the bottom and left axes, and will have axes with tic marks on the right and top. This differs from the DISSPLA convention which places the tic marks on the outside by default. Additional axes may be drawn by the calls CALL XGRAXS (XORIG,XSTEP,XMAX,XAXIS,XNAME,LXNAME,XPOS,YPOS) GPLOT Graphics Routines Page 12 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CALL YGRAXS (YORIG,YSTEP,YMAX,YAXIS,YNAME,LYNAME,XPOS,YPOS) The arguments have the same meanings here as described for GRAF, XNAME, and YNAME, except that if LXNAME or LYNAME are negative the numbers and labels will be drawn on the opposite side of the axes. Example Plot 7 shows how YGRAXS can be used together with OREL or PHYSOR to produce multiple subplots on a page. The values at the axis tic marks can be set to integers by the calls CALL XINTAX CALL YINTAX CALL INTAXS It should be noted that the values XSTEP and YSTEP can be replaced by the string 'SCALE' to have the program calculate appropriate step sizes. If you want the tic marks to go to the outside, you can reverse them with the following calls: CALL XREVTK CALL YREVTK The axes drawn will join at the XORIG and YORIG values, but the axes can be made to cross at x = 0.0, y = 0.0 by calling CROSS. This is sometimes useful when one or both axes start at negative values and go to positive. By default the axis labels will be horizontal on the x-axis and vertical on the y-axis. The angle of these labels can be changed with the routines: CALL XAXANG(ANG) CALL YAXANG(ANG) where ANG is the angle from the horizontal in degrees. Example Plot 2 in the Appendix shows how these routines can be used to modify the tic marks and axis labels. Another option is to eliminate the labels at the beginning or the end of the axes, or both. This can be done with the calls: CALL XAXEND (option) CALL YAXEND (option) where "option" is one of the following values: 'NOFIRST','NOLAST', or 'NOENDS'. GPLOT Graphics Routines Page 13 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq 7.1 Linear Axes The basic graph set up routine is GRAF as described previously. GRAF uses data units to define the origin, step size and ending values for the axes. There are two other routines for setting up linear axes which use inches instead of data units for one of the axes. They are: CALL XGRAF (XORIG,XSTP,XMAX,YORIG,YSTEP) CALL YGRAF (XORIG,XSTEP,YORIG,YSTP,YMAX) where XSTEP and YSTEP are given in inches and the other arguments are the same as for the GRAF routine. There is also a routine for setting up a plot with axes labelled with a user specified text string instead of with numbers. These routines are: CALL XLABGR (LXARAY,IXWORD,IXTOT,YORIG,YSTP,YMAX) CALL YLABGR (XORIG,XSTP,XMAX,LYARAY,IYWORD,IYTOT) 7.2 Logarithmic Axes Logarithmic axes can be used instead of linear axes by replacing the call to GRAF with one of the following calls: CALL XLOG (XORIG,XCYCLE,YORIG,YSTEP) CALL YLOG (XORIG,XSTEP,YORIG,YCYCLE) CALL LOGLOG (XORIG,XCYCLE,YORIG,YCYCLE) XLOG and YLOG give semilog plots and LOGLOG does loglog plots. In these routines XCYCLE and YCYCLE are the cycle lengths in axis units, and the other parameters are as in GRAF. Example plot 3 in the Appendix shows the effect of the different logarithmic axes. 7.3 Producing Grids and/or Tick Marks Tick marks are normally generated at each major axis division. To produce additional tick marks, make the following calls: CALL XTICKS(ITICKS) CALL YTICKS(ITICKS) where ITICKS is the total number of tick marks per axis step. These routines are demonstrated in Example Plot 2 in the Appendix. To produce a grid on the plot, use one of the following subroutine calls: GPLOT Graphics Routines Page 14 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CALL GRID (NXGRID,NYGRID) CALL DOTGRID (NXGRID,NYGRID) In these grid routines NXGRID and NYGRID are the numbers of grid lines per division on the x and y axes. DOTGRID is a special grid which produces the dots each one-fifth of an axis division. This is slow, but can be used for interpolation. A dotted grid can also be produced by GRID if the line type is changed to dotted before calling GRID, but the dots will not be synchronous with the axis divisions. 8. Drawing Curves The basic routine for drawing curves in GPLOT is CURVE, as indicated in the basic plot routines section. This routine will draw curves and/or place markers at data points. 8.1 Error Bars It is often desirable to put error bars on the data points being plotted. Three calls have been provided in GPLOT which will draw error bars for the x or y uncertainty or both. Use one of the following calls in place of the call to CURVE and supply the array(s) of error values to be used. The calls are: CALL EYCRV (XARRAY,YARRAY,NPTS,IMARK,EYARY) CALL EXCRV (XARRAY,YARRAY,NPTS,IMARK,EXARY) CALL EXYCRV (XARRAY,YARRAY,NPTS,IMARK,EXARY,EYARY) The default error bar will be a line, but this can be changed to a line with bars on the end by the call: CALL EMARK (2) 8.2 Line Types GPLOT supports the following calls to set the line-type to be used in generating curves: CALL SOLID CALL DOT CALL DASH CALL CHNDOT CALL CHNDSH (DEC GKS extension not supported prior to DEC GKS 4.0) GPLOT Graphics Routines Page 15 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq The thickness of the lines drawn with the curve routines will be the default value for the graphics device unless they have been thickened by a call to THKCRV. The call is: CALL THKCRV (THKNSS) where if THKNSS > 1.0 it is a factor which multiplies the nominal line width. If THKNSS < 1.0 it is approximately the line thickness in inches, although this is somewhat device dependent. THKCRV does not affect the line thickness of lines drawn by other routines. 8.3 Colors When plotting on a color device, it is possible to choose colors by name using the call: CALL NEWCLR ('color') Color names which are recognized include FOREGROUND, BACKGROUND, RED, GREEN, BLUE, CYAN, MAGENTA, YELLOW, BLACK, and WHITE. It will also recognize other colors such as BROWN, GREY, GRAY, PURPLE, AQUA, and PINK for certain devices. The color set by a call to NEWCLR will affect text, markers, and filled areas as well as lines. Since colors are device dependent they will appear differently on different devices, and some trial and error will probably be necessary. Example Plots 6, 8, and 10 demonstrate the use of color if they are run on a color device. Some devices, such as Postscript printers and VAXstations, permit writing in the background color as well as the foreground color, allowing you to erase an area with the background color before writing over it in another color. For more control over colors, you can use the GKS call to set the color representation (GSCR) together with the calls to set color index for the text, polyline, polymarker, and fill area (GSTXCI, GSPLCI, GSPMCI, GSFACI). See the GKS documentation for more details of these calls. You should be aware, however that some GPLOT routines call these GKS color routines with a color index stored in common. 8.4 Data Markers Thirty different data markers are supported by GPLOT for marking data points, with most of the first 18 being the same as those produced by DISSPLA. The exceptions are symbols 11, 14, and 17. Symbols 11 and 14 appear slightly different because triangles are centered on the center of mass in GPLOT instead of at the half height of the triangle as in DISSPLA. GPLOT uses a different symbol for marker 17 because DISSPLA duplicates markers 17 and 0. The symbols automatically increment when multiple curves are drawn on the same plot, but specific markers may be selected by the call GPLOT Graphics Routines Page 16 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CALL MARKER (n) The symbols are plotted at a default size unless a marker scaling factor is applied by the call: CALL SCLPIC (PICFAC) where PICFAC is the marker height scale factor. In some cases different markers will be different sizes because some are drawn by GPLOT subroutines and others are furnished by DEC VAX GKS. Markers furnished by DEC VAX GKS will also be different sizes on different devices because marker size scaling is in terms of the default marker size for the device. If this causes a problem, you can select the markers drawn by GPLOT subroutines. Markers 2,8,10-15, and 22-24 are generated by GPLOT. The other markers are generated by DEC VAX GKS and the size will vary from device to device. There is also a bug in DEC VAX GKS in marker clipping for some devices, so errors may result when you attempt to draw one of those markers outside the clipping rectangle. The first 22 available markers are illustrated in Example 11 in the Appendix. 8.5 Interpolation Routines A number of routines have been included which allow interpolation before drawing the curve through the data points. The default is to draw straight lines connecting the points supplied to the curve routine. If the call to the curve routine is preceded by a call to an interpolation routine, a different curve will be drawn for each of the other methods. The interpolation routines which can be called include: CALL LINEAR CALL BARS(BARWTH) CALL PARA3 CALL PARA5 CALL POLY3 CALL POLY5 CALL PSPLIN CALL RASPLN(TENSN) CALL SPLINE CALL STEP GPLOT Graphics Routines Page 17 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq Here BARWTH is the ratio of the bar width to data interval, and TENSN is a parameter that determines the degree of smoothing by the RASPLN routine. A sample of the effects of some of these interpolation routines is shown in Example 7 in the Appendix. 9. Legends Graphs may be labelled with legend routines similar to those used by DISSPLA except that the GPLOT routines keep track of line color and type as well as symbol type for use in the legend. A legend may be produced as follows:2 PARAMETER NWORDS=100 INTEGER IPKRAY . . . CALL MYLEGN ('Legend Heading$',100) . . . CALL LINES ('Curve 1 Label$',IPKRAY,1) . . . CALL LINES ('Curve 2 Label$',IPKRAY,2) . . . CALL LEGEND (IPKRAY,NCURVE,XPOS,YPOS) Here LMAX is the maximum number of characters in a legend line, NCURVE is the total number of curves, and the last argument in the call to LINES is ICURVE, the curve index. You may want to position the legend where it will not interfere with other curves and text because GPLOT does not always blank the plot as DISSPLA does and the graph can overwrite the legend. For devices that can write in the background color the legend area will be cleared before the legend is written. A complete example showing how to produce a legend on a plot is included in Example Plots 6 and 11 in the Appendix. 10. Vectors With and Without Arrowheads If you wish to draw vectors without using the CURVE calls, GPLOT provides routines to draw vectors in either axes units or data units. They may also include various types of arrow heads if desired. The calls for these routines are: ------------------------------ 2.Note that this example is not applicable to the old version (GPLOT3). GPLOT Graphics Routines Page 18 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CALL VECTOR (XFROM,YFROM,XTO,YTO,IVEC) CALL RLVEC (XFROM,YFROM,XTO,YTO,IVEC) IVEC is a four digit integer specifying the arrowhead to be used. The first digit gives the ratio of width to length and may have values from 0 to 5. The second digit gives the arrowhead size from 0 to 6. The third digit specifies the type of arrowhead: 0 -> Solid 1 -> White 2 -> Open 3 -> Closed The last digit specifies the location of the arrowheads: 0 -> None 1 -> at (XTO,YTO) 2 -> at both ends 3 -> at both ends, pointing out 4 -> at both ends, pointing to (XTO,YTO) Vectors can also be drawn using the following routines to define a starting point and subsequent points to be connected. CALL STRTPT(X0,Y0) CALL CONNPT(XI,YI) Vectors will be drawn using the nominal line width for the graphics device unless THKVEC has been called. To change the line width of lines drawn with vector routines, use the call: CALL THKVEC(THKNSS) where the line width used to draw the vector will be THKNSS times the nominal linewidth if THKNSS > 1.0 or will be approximately THKNSS inches thick if THKNSS < 1.0. 11. Graphic Primitives DEC VAX-GKS provides graphic primitives for drawing arcs, circles, ellipses, and rectangles. It also provides primitives for filling these figures. These have been used by GPLOT to produce easy to use routines for drawing graphics primitives. Some of these correspond in name and calling parameters with DISSPLA routines for blanking areas, however the GPLOT routines only draw the figures, and don't do blanking in most cases. The routine CLRREC can be used to erase a rectangular area on devices which provide this capability (i.e. the HDS graphics terminal, VAXstation, DECWindows terminals, Postscript printers). The GPLOT Graphics Routines Page 19 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq filling of these primitives is dependent on the state of the GKS Fill Area Constants at the time of the call. For some devices an area can be erased by setting the Fill Area Interior Style to solid and the Fill Area Color Index to the background color. See Examples 8-10 to see how the filling is controlled by these variables. CALL BLREC (XORG,YORG,WIDE,HIGH,FRM) CALL BLTREC (XORG,YORG,WIDE,HIGH,ANG,FRM) CALL BLCIR (XORG,YORG,RADIUS,FRM) CALL BLELIP (XORG,YORG,RADX,RADY,ANG,FRM) CALL BLPOLY (XARAY,YARAY,NPTS,FRM) CALL BLSLIC (XORG,YORG,RADIUS,THETA1,THETA2,FRM,IARC) CALL ARC (XORG,YORG,RADIUS,THETA1,THETA2,ICLS,FRM)3 CALL ELARC (XORG,YORG,RAD1,RAD2,ANG,THETA1,THETA2,FRM,IARC) CALL ELPARC (XORG,YORG,RAD1,RAD2,ANG,THETA1,THETA2,ICLS,FRM)4 where the first six routines correspond to DISSPLA routines except the call to BLSLIC has an optional extra parameter, IARC, to indicate the type of circular arc to be drawn. The three valid values of IARC are GATOPN=1, GATPIE=2, and GATCHRD=3 to specify if the arc should be open, pie shaped or chord shaped. ICLS is similar to IARC, except it is a one of the following character strings: 'NONE', 'SLICE', or 'CHORD'. If the file 'SYS$LIBRARY:GKSDEFS.BND' is included by the drawing program, the symbolic names for these parameters may be used, otherwise use the numbers. The routine to draw elliptic arcs, ELARC, is similar to the routine for drawing circular arcs, BLSLIC, except it requires both a major and minor radius for the ellipse. Example plots 8-10 demonstrate the use of these graphic primitive routines. There is a bug in the DEC GKS Postscript driver which causes the ARC and ELPARC routines to work incorrectly on Postscript printers. 12. Bar Graphs GPLOT contains routines to emulate the DISSPLA routines for drawing vertical and horizontal bars. These subroutine calls are: CALL VBARS (XARAY,Y1ARAY,Y2ARAY,NPTS) CALL HBARS (X1ARAY,X2ARAY,YARAY,NPTS) ------------------------------ 3.GPLOT11 only. 4.GPLOT11 only. GPLOT Graphics Routines Page 20 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq CALL BARPAT (ISTYLE) CALL BARWID (BARWTH) These work as the DISSPLA routines except GPLOT patterns are based on the GKS standard patterns and there are only nine different patterns. Example 4 in the Appendix demonstrates the use of these routines. 13. Contouring Routines GPLOT contains several routines for generating contour plots. The relevant routines are CONMAK, CONLIN, and CONTUR. CONMAK makes the contour lines and saves them in its internal data structures. CONLIN is used to set up various line styles for the contour lines of different levels. CONTUR actually plots the contour lines made by CONMAK according to the line styles established by CONLIN. The call CALL CONMAK (w, nx, ny, zIncrement) builds contour lines for a rectangular array of data values, w( , ). It is assumed that w is dimensioned as w(nx,ny). w(i,j) should contain the data value corresponding to the point (xi, yj) of a rectangular grid of points (xi,yj), i = 1,...,nx, j = 1,...,ny. The argument zIncrement gives the increment between contour levels. Alternatively, zIncrement can also be the character string constant 'SCALE', in which case CONMAK will choose rounded levels between the largest and smallest values in w( , ) at which to draw contour lines. In either case there will be a constant increment between contour lines, call it INCR, and contour lines will be calculated for all Z levels of the form K*INCR, K = ...,-1, 0, 1, ... which are between the largest and smallest values stored in w( , ). The call CALL CONLIN (LineNum, MODE, 'NOLABELS', IThick, 1) sets up the characteristics to be used when drawing the contour lines. LineNum is the "number" of the contour line whose characteristics are to be set. The correspondence between the contour level K*INCR and LineNum is LineNum = K MOD nLines where nLines is the total number of line characteristics set by calls to CONLIN. MODE may be one of 'SOLID' -- use a solid line GPLOT Graphics Routines Page 21 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq 'DOT' -- use a dotted line 'DASH' -- use a dashed line 'CHNDOT' -- use a chain dotted line 'CHNDSH' -- use a chain dashed line 'MYCON' -- use line characteristics as computed by the user supplied subroutine MYCON The first five of these values select the specified line styles. If MODE is 'MYCON', the user must provide a subroutine by that name which will set the line characteristics at run time. The use of MYCON is explained more fully below. The argument IThick is an integer specifying a thickness multiplier for line LineNo. Specifically, if IThick = 3, a line three times thicker than the standard line width will be used. The remaining two arguments 'NOLABELS' and 1 must be passed in as shown, but have no effect on the resulting plot. The routine CALL CONTUR (nLines, 'NOLABELS', DrawFlag) draws the contour lines. The argument nLines must be the total number of line characteristics set by calls to CONLIN. The argument DrawFlag must be either of the character strings 'DRAW' or 'NODRAW'. This determines whether each contour line will be drawn or not drawn by default. 'NODRAW' is only useful in conjunction with the user supplied routine MYCON. MYCON can selectively permit lines at various levels to be drawn in case the default is set to 'NODRAW'. The remaining argument 'NOLABELS' must be passed in as shown, but has no effect on the resulting plot. If the MODE 'MYCON' was selected for a particular line characteristic, then the user MUST supply a subroutine MYCON (RArray,IArray) which will be called by CONTUR before a contour is plotted using that characteristic. In this way MYCON can change the appearance of particular contour lines. The two arguments of MYCON are arrays: REAL RArray(2) INTEGER IArray(9) Currently, the only positions in the arrays that are used are: RArray(1) -- Contains the Z-level of the current contour line being drawn. IArray(1) -- Contains the value of current curve thickness multiplier. This may be GPLOT Graphics Routines Page 22 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq changed depending on the Z-level to highlight specific levels if desired. IArray(9) -- Contains the default curve drawing flag value. 0 = 'NODRAW' 1 = 'DRAW' This may be changed to selectively omit or include various Z-levels. Example 13 in the Appendix illustrates the use of these routines. 14. 3 Dimensional Plotting GPLOT now includes routines for drawing 3-Dimensional vectors, curves and surfaces. The 3-Dimensional objects are drawn in a 3D region called the "workbox" which can be viewed from various positions outside the workbox. To use the 3-Dimensional plotting features in GPLOT, your program must first set up the page and subplot area as for 2- Dimensional plots. The 3D workbox will be projected into the subplot area specified in the call to AREA2D. The projection used is determined from the 3D workbox and various viewing parameters as described in the next two subsections. Meaningful defaults for the workbox and viewing parameters are provided and the subroutines in the next two sections may be omitted if the defaults are acceptable. 14.1 Setting the "workbox" The 3D workbox can be specified using the routines Volm3D or Axes3D. Specifically, the call CALL Volm3D( xSize, ySize, zSize ) would set the 3D workbox to extend from zero to xSize in the x direction, from zero to ySize in the y direction, and from zero to zSize in the z direction. These values adjust the 3D aspect ratios of the resulting plots. If all three parameters are equal, the workbox will appear cubical. If zSize is much smaller than xSize and ySize, the resulting workbox will be quite flat. The workbox establishes a coordinate system called the "absolute 3D" coordinate system. Names can be applied to the axis using the calls CALL X3NAME( LxName, IxName ) CALL Y3NAME( LyName, IyName ) CALL Z3NAME( LzName, IzName ) GPLOT Graphics Routines Page 23 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq in which the parameters have the same effect as in the corresponding 2D routines XNAME, YNAME. The above operations can be combined into one call to the routine Axes3D as shown: CALL Axes3D( LxName, IxName, LyName, IyName, LzName, 1 IzName, xSize, ySize, zSize ) The default workbox size is 1.0 X 1.0 X 1.0 with blank labels. If these defaults are satisfactory, calls to the above routines may be omitted. However, if these routines are used, they must be used BEFORE Graf3D is called. 14.2 Setting the Viewing Parameters. Once the workbox has been set up, the observer's position and the point at which the observer is looking can be specified in one of several ways. The observer's position is called the Center Of Projection or COP. The point at which the obsever is looking is called the View Reference Point or VRP. To set the COP, use one of the calls: CALL VuAbs ( xAbs, yAbs, zAbs ) CALL VuAngl( Phi, Theta, Radius ) CALL View ( x3, y3, z3) The parameters xAbs, yAbs and zAbs specify the COP in terms of the "absolute 3D" coordinate system determined by the workbox. The parameters x3, y3 and z3 specify the COP in terms of the "relative 3D" coordinate system that will be placed on the workbox when Graf3D is called. The parameters to VuAngl specify the COP relative to the VRP as follows: Phi - specifies the angle in the xy-plane between the positive x axis and the projection of the ray from VRP to COP Theta - specifies the angle between the ray from VRP to COP and the xy-plane. Radius - specifies the distance from the VRP to the COP in absolute 3D coordinates. NOTE: The default COP is at ( -1.5, -1.5, 1.5 ) in absolute 3D coordinates. If a program specifies the COP, it should be outside of the 3D workbox. IF the specified COP is too close to the workbox, GPlot will move it so that the distance between it and the center of the work box is at least 1.5 times the length of the diagonal of the workbox. If the specified COP is more than 20 times the workbox GPLOT Graphics Routines Page 24 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq diagonal away, GPLOT will use 20 times the workbox diagonal. To set the VRP, use one of the calls: CALL FclAbs( xAbs, yAbs, zAbs ) CALL FclAng( Phi, Theta, Radius ) CALL FclPt ( x3, y3, z3) The parameters to FclAbs and FclPt specify the VRP in terms of the "absolute 3D" and "relative 3D" coordinates respectively. The parameters to FclAng specifiy the VRP relative to the COP as follows: Radius - specifies the distance from the COP to the VRP in absolute 3D coordinates. Theta - specifies the angle between the ray from COP to VRP and the xy-plane. Phi - specifies the angle in the xy-plane between the positive x axis and the projection of the ray from COP to VRP. FclAng should be called after VuAbs, or View have set the position of the COP as desired. NOTE: The default VRP is at ( 0.5, 0.5, 0.5 ) in absolute 3D coordinates. If a program specifies the VRP, it should lie in the 3D workbox. IF the specified VRP lies outside of the workbox, GPlot will move it into the 3D workbox. Ordinarily, GPLOT will adjust the projection of the workbox onto the screen so that the entire workbox is visible. If desired, a program may adjust the projection so that less of the workbox is visible in order to "zoom" in on one part of a 3D object. This can be done using the call CALL VisAng( Angle ) Angle specifies the angle at the COP that is subtended by the virtual screen on which the 3D world is projected. If Angle is made quite small, the effect is to "zoom" in on a portion of the workbox. NOTE: The GPLOT implementation of VisAng differs from the same named routine in DISSPLA. GPLOT always assumes a square virtual screen and so only one is specified whereas DISSPLA allows a rectangular screen specified by two angles. GPLOT Graphics Routines Page 25 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq 14.3 Establishing a "relative" coordinate system The 3D workbox will be given a relative 3D coordinate system by a call to Graf3D. Graf3D actually builds the projection as determined by the workbox and other viewing parameters and draws the axis system. Consequently, GRAF3D MUST be called AFTER the routines that establish the workbox and viewing parameters mentioned above, but BEFORE any routines to draw 3D objects given in the next section. Graf3D is called as follows: CALL Graf3D( x3Orig, x3Step, x3Max, 1 y3Orig, y3Step, y3Max, 2 z3Orig, z3Step, z3Max ) The parameters are interpreted in the same way as the parameters to the 2D routine GRAF. As with the 2D graf routines, many variations on the appearance of the axes are allowed. This is accomplished using the calls CALL zIntAx CALL zTicks( iTicks ) CALL zRevTk CALL zAxCtr CALL zAxEnd( Flag ) CALL zNoNum CALL zAxAng( Angle ) CALL zLabGr( LabelList, LabelLength, NLabels ) The corresponding 2D calls such as xIntAx, yNoNum, etc., will also affect the appearance of the 3D axis system. The effect of these calls is generally similar to the corresponding 2D GPLOT and DISSPLA calls. Note however that there are small differences in the interpretation of some of the parameters between the 2D and 3D routines. For example, the default direction for tick marks in 3D is directed outward from the workbox. Also, the rotation Angle specified in xAxAng, yAxAng and zAxAng will be interpreted as a rotation from a "normal" orientation which is parallel to the axis with the top of the letters pointed towards the axis. However, as the viewing parameters are changed, this would occasionally leave some of the lettering oriented generally downward. GPLOT calculates the orientation of the lettering and if it is "upside down" the lettering is rotated by 180 degrees. 14.4 3D Output GPLOT provides 3 dimensional vectors, curves, and surfaces using the calls: CALL Vectr3( xAbsFr, yAbsFr, zAbsFr, GPLOT Graphics Routines Page 26 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq 1 xAbsTo, yAbsTo, zAbsTo, IVEC ) CALL RlVec3( xFrom, yFrom, zFrom, 1 xTo, yTo, zTo, IVEC ) CALL Curv3D( xAray, yAray, zAray, NPts, IMark ) CALL Surmat( ZMat, IXPts, IXDim, IYPts, IYDim, WkArea ) The vector and curve routines are analogous to the corresponding 2D routines. The parameters to Vectr3 specify 3D positions in "absolute 3D" coordinates whereas the parameters to RlVec3 and Curv3D specify the coordinates in terms of the "relative" coordinate system set up by the call to Graf3D. 3D surfaces are drawn using the routine Surmat. The parameters to Surmat are: ZMat -- Real array with IxDim rows and IyDim columns, containing the z values of a grid of points defining the surface. The z values are specified in terms of "relative" coordinates. IXPts -- The increment between successive rows of ZMat that are to be used in drawing the surface. For example, if IXPts = 2, Surmat will only use the data from alternate rows of ZMat. IYPts -- The increment between successive columns of ZMat that are to be used in drawing the surface. For example, if IYPts = 3, Surmat will only use the data from every third column of ZMat. IxDim, IyDim -- The dimensions of the array ZMat WkArea -- Not used, but retained for compatability with DISSPLA. Note that the x and y coordinates of the points on the surface are not specified directly in the call to Surmat. It is assumed that ZMat contains the Z-values of the surface evaluated on a grid of points (x,y) that are evenly spaced in the x and y directions. By default the ranges of x and y values of the data points are assumed to be the same as the ranges specified in the call to Graf3D. These default ranges can be changed with the call CALL SurSze( XMin, XMax, YMin, YMax ) which specifies the new range of x and y values to be associated with the z values in ZMat. This will NOT change the calibrations GPLOT Graphics Routines Page 27 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq on the axes, or alter the "relative" coordinate system specified in Graf3D, but will adjust the position and shape of the surface relative to the workbox. If a surface is to be constructed from data values that correspond to points (x,y) that do not form a regular grid of points, some preprocessing of the surface is necessary. GPlot provides the routines BGNMAT, MDFMAT, GETMAT and ENDMAT to approximate the z-values of a surface on a regular grid of points given points (x,y,z) which have x, y coordinates distributed randomly in the rectangle [ X3Orig, X3Max ] K [ Y3Orig, Y3Max ]. These routines may be used to construct a matrix ZMat, with up to 101 rows and 101 columns from an arbitrary number of scattered points. These routines are used as follows. The size of the matrix ZMat that is to be constructed first must be specified using BGNMAT: CALL BGNMAT( IXDim, IYDim ) Then GETMAT would be called one or more times to approximate the effect on the surface due to a collection of randomly scattered points (x,y,z). The call CALL GETMAT( xAray, yAray, zAray, nPoints, junk ) accepts three real arrays containing nPoints values specifying the coordinates of scattered data points. (The parameter "junk" is retained for compatibility with earlier versions of DISSPLA.) It is assumed that each of the scattered points should add to the value of the surface at nearby regularly spaced grid points. For each scattered data point, (x,y,z), GETMAT accumulates the effect on each nearby grid point. Finally, the call CALL ENDMAT( ZMat, junk ) produces the array of z values needed by Surmat from the information accumulated during previous calls to GETMAT. The value returned in ZMat(i,j) is a weighted average of the z-values of scattered data points (x,y,z) that were "close" to the grid point (Xi, Yi). Each of the z values is weighted by Weight = 1/(Distance + Offset) ** Power where Distance is the distance from (x,y) to (Xi, Yi) and Offset is a small positive value to avoid dividing by 0. Some of the parameters used in this process are set by the call CALL MDFMAT( Ix, Iy, Power ) GPLOT Graphics Routines Page 28 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq Ix specifies the number of rows of ZMat above and below the data point that are to be affected by the data point. Similarly, Iy specifies the number of columns of ZMat left and right of the data point that are to be affected. Power specifies the value of Power to be used in the calculation of the weight. The default value for each of these quantities is 2. MDFMAT need not be called if these defaults are acceptable. 15. Graphics Input Graphics input can be obtained from input/output devices such as the VAXstation, the VT240/241, and the Tektronix 4014 emulators like the HDS 2200GX. 15.1 Reading the Cursor Position To turn on the cursor and read the cursor position when input is terminated, use the call: CALL HWINPT(XPOS,YPOS) Input is terminated on the VAXstation by clicking the left-hand button on the mouse. Input is terminated on the other devices by typing a RETURN. When positioning the cursor on a Tektronix emulator, holding down the shift key before pressing the arrow keys will speed up cursor movement. HWINPT will return the cursor position in inches relative to the physical origin specified by the call to AREA2D. To obtain the position in data units, use the call: CALL HWDATA (XVAL,YVAL) If these routines are included when plotting on an output only device, an error message will be returned. 15.2 Using the Cursor to Modify the Plot The subroutine CURSON was written to allow interaction with the plot on some devices (currently only the VAXstation and the HDS terminals). It allows displaying the cursor position, optionally adding cursor position or text information to the plot and selecting a rectangular subplot area to zoom in on. Use the following syntax to call CURSON: CALL CURSON(KEY,X0,X1,Y0,Y1) where KEY is a CHARACTER*1 variable and X0,X1,Y0,Y1 are REAL*4 variables. When CURSON is called the cursor cross hairs are turned on. On the VAXstation, a continuous display of cursor position in data units will be displayed in the upper right corner of the plot. On the HDS the cursor coordinates will be displayed each time a return is typed. CURSON also allows input from the keyboard to add text to or delete text from the plot. GPLOT Graphics Routines Page 29 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq It is recommended that both the hardcopy device and the screen device be nominated before entering CURSON. The only Tektronix 4014 emulator which currently supports all these features is the HDS graphics terminal, because a proprietary erase function has been used. For more consistent results between the screen and hardcopy when you use the HDS terminal as the screen device, software fonts are used on postscript printers when both devices are nominated. The following keys are recognized by CURSON: H (D) Set text direction horizontal V Set text direction vertical - Set text direction upside down and backward A Allow input of text angle (default is 0.0R) X Write x-coordinate on plot Y Write y-coordinate on plot P Write both x and y coordinates on plot G Enter beginning/ending position of vector/arrow W Enter arrowhead type to be used in G command. (Default is IVEC=0, no arrowhead) T Write Text on plot (you are prompted for input) The text will be in the current default size. An up-arrow will cause text to go into superscript mode and a down-arrow will cause it to go into subscript mode. The right-arrow will cause text size to be 1.5 times the default size and the left-arrow will cause it to be 0.67 times the default size. Use PF2 to end superscript mode, subscript mode, or to return to the default size. PF3-G will cause text to go into Greek mode. PF3-N will set text back to normal. While in text mode, the DELETE key can be used to delete the previously typed character. The area erased on the screen may be larger than it should be if you are in superscript mode subscript mode, or at some text angles. B Write x and y coordinates to plot and to a file (writing to a file not yet implemented) C Write x-coordinate to plot and to a file (writing to a file not yet implemented) L,U defines the Lower left and Upper right corner of a box which will be drawn on the screen. Once a box has been drawn the Zoom command may be used to zoom in on the selected region. Z Zoom in to selected box region, or Zoom back out to original region. D Delete previous segment added to plot. Q Quit editing plot without saving additions (plot will be redrawn on the screen without additions). E Exit from CURSON and save additions to plot. GPLOT Graphics Routines -- Index Page 30 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq Index A ANGLE, 8, 11, 22, 23, 24, 27, 28 AREA2D, 4, 5, 6, 20, 26, 28 B BARPAT, 18, 28 BARS, i, 1, 13, 18, 28 BARWID, 18, 28 BGNMAT, 25 BLCIR, 17, 28 BLELIP, 17, 28 BLPOLY, 17, 28 BLREC, 17, 28 BLSLIC, 17, 18, 28 BLTREC, 17, 28 C CARTOG, 8, 28 CGMCO, 3 CGMTO, 3 CHNDOT, 13, 28 CHNDSH, 13, 28 CHRMSG, 7, 10, 28 COMPLX, 8, 28 COMPRS, 3 CONLIN, 18, 19, 20, 28 CONMAK, 18, 19, 28 CONTUR, 18, 19, 20, 28 CROSS, 11, 26, 28 CURSON, 26, 27 CURV3D, 24 CURVE, 1, 4, 13, 15, 16, 20, 24, 28 D DASH, 13, 28 define plotter, 2, 3, 28 define screen, 2, 28 DOT, 13, 28 DOTGRID, 13, 28 DUPLX, 8, 28 E EDIT_GMENU, 2 ELARC, 18, 28 EMARK, 13, 28 ENDGR, 5, 28 ENDMAT, 25 ENDPL, 4, 28 EXCRV, 13, 28 EXYCRV, 13, 28 EYCRV, 13, 28 F GPLOT Graphics Routines -- Index Page 31 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq FASHON, 8, 28 FCLABS, 22 FCLANG, 22 FCLPT, 22 FONT, i, 7, 8, 9, 10, 28 fontid, 8, 29 FRAME, 6, 29 FUTURA, 8, 29 G GETMAT, 25 GKSM, 3, 29 GMENU, 2, 3, 29 gothic, 8, 29 GRACE, 6, 29 GRAF, 4, 5, 11, 12, 23, 29 GRAF3D, 21, 22, 23, 24, 25 greek, 7, 8, 27, 29 GRID, 12, 13, 19, 24, 25, 29 GSCHH, 8, 29 GSCHUP, 8, 29 GSTART, 2, 3, 29 GSTOP, 4, 29 GSTXFP, 8, 29 GTX, 7, 10, 29 H HBARS, 18, 29 HEADIN, 7, 29 HEIGHT, 7, 8, 10, 14, 29 HP7550, 3 HWDATA, 26, 29 HWINPT, 26, 29 I instruction, i, 10, 29 INTAXS, 11, 29 INTNO, 7, 29 L LA50, 3, 29 LA75, 3, 29 LEGEND, 1, 15, 16, 29 LINEAR, i, 1, 12, 15, 29 LINES, 7, 13, 14, 15, 16, 17, 18, 19, 20, 29 LINEST, 29 LN03TK, 3 LOGLOG, 12, 29 LW, 2, 3, 29 M MARKER, 4, 14, 15, 29 mathematical, 8, 29 MDFMAT, 25, 26 GPLOT Graphics Routines -- Index Page 32 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq MESSAG, 7, 29 MXIALF, 10, 29 MYLEGN, 16, 29 N NEWCLR, 14, 30 NOBRDR, 6, 30 O OREL, 5, 11, 30 P PAGE, i, 1, 4, 5, 6, 11, 20, 30 pagex, 4, 5, 30 pagey, 4, 5, 30 PARA3, 15, 30 PARA5, 15, 30 PHYSOR, 5, 11, 30 picfac, 14, 30 POLY3, 15, 30 POLY5, 15, 30 POSTSCRIPT, 3, 8, 9, 10, 14, 17, 18, 27, 30 precis, 8, 30 PSPLIN, 15, 30 Q QMS, 3 R REALNO, 7, 30 RLINT, 7, 30 RLMESS, 7, 30 RLREAL, 7, 30 RLVEC, 16, 30 RLVEC3, 24 russian, 8, 30 S SCLPIC, 14, 30 SCMPLX, 8, 30 script, 8, 30 SERIF, 8, 30 SETCLR, 30 SIMPLX, 8, 30 SOLID, 13, 16, 17, 19, 30 special, 1, 5, 7, 8, 10, 13, 30 SPLINE, 15, 30 standard, 1, 7, 8, 18, 19, 30 STEP, 11, 12, 15, 30 SURMAT, 24, 25 SWISSB, 8, 30 SWISSL, 8, 30 SWISSM, 8, 30 symbols, 1, 4, 7, 14, 30 GPLOT Graphics Routines -- Index Page 33 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq T TALRS3, 3, 30 THKCRV, 13, 14, 30 THKFRM, 6, 30 TK4014, 2, 3, 31 TK4014F, 3, 31 TRIPLX, 8, 31 V VAXSTATION, 2, 3, 17, 26, 31 VBARS, 18, 31 VECTOR, 16, 17, 24, 31 VECTR3, 24 VIEW, 4, 21, 22 VISANG, 23 VOLM3D, 21 VT330, 3, 31 VT340, 3, 31 VUANGL, 22 X XAXANG, 24, 31 XAXEND, 11, 31 xaxis, 11, 31 xcycle, 12, 31 XGRAF, 12, 31 XGRAXS, 5, 11, 31 XINT, 7, 31 XINTAX, 11, 23, 31 XINVRS, 6, 31 XLOG, 12, 31 xmax, 4, 11, 12, 25, 31 XMESS, 7, 31 XNAME, 4, 10, 11, 21, 31 xorig, 11, 31 XPOSN, 6, 31 XREAL, 7, 31 XREVTK, 11, 31 xstep, 4, 11, 12, 31 Y YAXANG, 24, 31 YAXEND, 11, 31 yaxis, 4, 11, 31 ycycle, 12, 31 YGRAF, 12, 31 YGRAXS, 5, 11, 31 YINTAX, 11, 31 YINVRS, 6, 31 YLABGR, 12, 31 YLOG, 12, 31 ymax, 11, 25, 31 YNAME, 4, 10, 11, 21, 31 GPLOT Graphics Routines -- Index Page 34 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq YNONUM, 23, 31 yorig, 4, 11, 12, 31 YPOSN, 6, 31 YREVTK, 11, 31 ystep, 4, 11, 12, 31 Z ZAXANG, 24 ZAXCTR, 23 ZINTAX, 23 ZNONUM, 23 ZREVTK, 23 GPLOT Graphics Routines -- Examples Page 35 qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq Examples Example programs and their output are attached, but they are not included in the table of contents or index.