PSCDOC:DRAWCGM.DOC 30 October 1990 DRAWCGM is a package of FORTRAN and C routines, which are designed to be called from a user FORTRAN program. The package can create a CGM metafile and store and manipulate graphics data. This CGM file can then be interpreted by the GPLOT program. This new version of DRAWCGM includes the ability to do interactive graphics a la PLOT10. It uses the same drivers as GPLOT, and can be set to handle output devices including Tektronix, X Windows, SUN, PostScript, besides the standard CGM character or binary metafile output options. The UNICOS and VMS versions of DRAWCGM installed at the PSC will support Tektronix, Textronix 4207, PostScript, CGM character and CGM binary output devices, whose names are referred to as "tek", "tek4207", "ps", "cgmc" and "cgmb". An alternate version of DRAWCGM, named DRAWCGMX, is available on UNICOS and VMS, and supports X-Windows, whose name is referred to as "xws", as well as the other output devices. Version: 3.4 Help: man drawcgm VMS setup: SETUP DRAWCGM (simply makes DRAWCGM and the VAX C run time libraries available implicitly at LINK time.) Document: drawcgm.doc VMS examples: DOC$ROOT1:[EXAMPLES.DRAWCGM] CGMPR1.FOR, CGMPR2.C, CGMPRB.CGMB, CGMPRB.COM, CGMPRB.CPR, CGMPRB.LOG, CGMPRB.JOB, DEVICES.CGMB, DEVICES.COM, DEVICES.CPR, DEVICES.FOR, DEVICES.JOB, DEVICES.LOG, DRAWPR1.CGMB, DRAWPR1.COM, DRAWPR1.CPR, DRAWPR1.FOR, DRAWPR1.LOG, DRAWPR1.JOB, DRAWPR2.CGMB, DRAWPR2.COM, DRAWPR2.CPR, DRAWPR2.FOR, DRAWPR2.LOG, DRAWPR2.JOB, SIMPLE.CGMB, SIMPLE.COM, SIMPLE.CPR, SIMPLE.FOR, SIMPLE.LOG, SIMPLE.JOB, UNICOS_DEFS.H, VMS usage: LINK myprog, PSC$LIB:DRAWCGM/LIB, SYS$LIBRARY:VAXCRTL/LIB or, if you've typed SETUP DRAWCGM, LINK myprog or, for the version which includes X-windows, LINK myprog, PSC$LIB:DRAWCGMX/LIB, SYS$SHARE:VAXCRTL.EXE/SHARE, - SYS$SHARE:DECW$XLIBSHR.EXE/SHARE CFS examples: /usr/local/examples/drawcgm/ cgmpr1.f, cgmpr2.c, cgmprb.com, cgmprb.job, devices.cgmb, devices.com, devices.cpr, devices.f, devices.job, devices.job, drawpr1.com, drawpr1.f, drawpr1.job, drawpr2.com, drawpr2.f, drawpr2.job, simple.com, simple.f, simple.job, unicos_defs.h, CFS source: /usr/local/src/lib/drawcgm/ blueyellow.clr, cgmgen.c, drawcgm.f, drawcgm.com, earthtone.clr, gray.clr, invspect.clr, invwaves.clr, makefile, makefile.old, pseudspect.clr, spect.clr, unicos_defs.h, unix_defs.h, waves.clr, UNICOS usage: cf77 -l /usr/local/lib/libdrawcgm.a MYPROG.F or, for the X-windows version, cf77 -l /usr/local/lib/libdrawcgmx.a -lX11 -lnet -lXaw MYPROG.F Supplier: Joel Welling See also: ANIMATION, CGM, DI3000, DISSPLA10, DISSPLA11, GPLOT, GTEX, NCARGKS2, P3D, PLOT10, SMDLIB, Introduction DrawCGM is a package of subroutines, written in C, which can directly create a CGM metafile. This means that you can, if you wish, avoid the occasional hassles of interfacing to DISSPLA, DI3000 or NCAR, and trying to manipulate them to get the results you desire. DrawCGM was written by Joel Welling at the PSC. In response to user's needs to produce simple raster images, the PSC has written a small subroutine library called DrawCGM. This library can be used to produce full color CGM image files suitable for animation from two-dimensional arrays of real numbers. Facilities to add labels, color bars, sets of lines and polygons are also present. DrawCGM contains some simple routines for enlarging images and for interpolating between pairs of images. INTRODUCTION As an example of the use of DrawCGM, consider the case of a hydrodynamicist who wishes to make a movie of the evolution of a two-dimensional pressure field. The goal is to take a floating point array of pressure data which might be 100 elements in each direction and drop it as a color image every few iterations of the evolution code. The user would add three sets of calls to his code. The first of these would establish his color table and initialize the graphics software; it would be called once at the beginning of execution. The color table provides the map between the data values and the colors ultimately seen on the screen; a correct choice of table is very useful in bringing out detail in the data. The next set of calls would take his density array and scale it to the appropriate size (determined by the desired output size and the screen resolution -- see below), convert the floating point array to integers, and 'draw' the resulting integer array into the CGM file. At this point things like color bars and labels could also be added. This set of calls would be made each time a frame was to be dropped. After the last image is created, there is one final call to shut down the graphics software. A color table can be read in from an ASCII list of floating point numbers (some such lists are supplied), or it can be generated at run time by the user or by DrawCGM. The routines GETCTB and RDCLIS do the former; the SETCTB and SETCLR routines do the latter. Graphics output is initiated by the GRFINI routine. Thus a simple implementation of the initialization routines would be a call to SETCTB followed by a call to GRFINI. Note that the color table in effect for a frame is the one which exists when that frame is begun, so if the call to SETCTB follows the call to GRFINI the initial frame will not have the desired color scheme. The final, closing call is generally to a routine called GRFCLS. Each new frame of output after the first must be preceeded by a call to NEWFRM, which separates images in the CGM file. Note that NEWFRM should not be called immediately after GRFINI or immediately before GRFCLS, or a blank frame will result. The user can choose to enlarge the data array by linear interpolation or by bicubic spline interpolation, via the routines STRLIN and STRSPL respectively. Notice that if spline interpolation is used on data which is not smooth, ringing, overshoot, and other unpleasant artifacts can result. Once a floating point data array of the desired size (see below) has been produced, it must be mapped into the range of integers spanned by the color table. For linear mappings this can be done with the routine RTOINT, which does all the necessary scaling automatically. The routine DRAWIT will lay down the resulting integer array as a color image. This can be embellished with vertical or horizontal color bars from VRTCBR or HORCBR respectively or labels from LABEL, among other things. COLOR TABLES Drawing on an output screen usually consists of taking some set of the pixels (picture elements) that make up the screen, and changing their color. The pixels are the little dots that you can see if you look closely at most screens; they are the reason that a diagonal line looks like a sequence of tiny squares instead of a smooth line. Each pixel corresponds to a physical location in the memory of the device displaying the image; the color of the pixel depends on the integer value stored in that location. The Color Table supplies the map between the number stored in memory and the color that appears on the screen. The color table is literally a table, each entry of which holds three intensity values: one each for the primary colors red, green, and blue. (They are almost always presented in that order, by the way). For example, if a value of 10 in memory was to correspond to pure red, color table entry 10 would consist of the three numbers (1.0, 0.0, 0.0) to turn red all the way on and green and blue completely off. Similarly, white is (1.0, 1.0, 1.0) and black is (0.0,0.0,0.0). The color table supported by DrawCGM has 256 entries, numbered from 0 through 255. By convention, 0 is the 'background color'; any part of the image with nothing else in it will have color 0. Color 1 is usually used for labelling, the boundaries of color bars, and the like. Thus a typical situation would have color 0 white and color 1 black. To display a two-dimensional array of real number data as an image, that data is first mapped into integers falling into some region of the color table supported by the device. For example, if the dynamical range of the data was between -37.0 and 400.0 units of some variable, the user might scale that range of reals into the range of integers between 2 and 255 for display. That scaling might be linear, in which case it could be carried out by the DrawCGM routine RTOINT. It might also be nonlinear, for example logarithmic. In this case the user could produce a real array to which the nonlinear transformation had been applied, and then use RTOINT to produce the integer array needed. If the data is mapped to some subset of the total available color indices, the unused color indices can be used for something else. For example, if the data is mapped to indices 2 through 255, then indices 0 and 1 can be used to set the background color and the color for labels respectively. If the user wants to display two sets of data simultaneously, for example temperature and pressure, each set of data can be mapped to a different, non-overlapping region of the color table. Then different schemes can be used for each image. DrawCGM supports a facility for reading and writing lists of colors. The color tables are stored in simple ASCII text files called color lists. Each color in the list is represented by an integer denoting the color index, followed by three real values giving the red, green, and blue intensities (between 0.0 and 1.0) respectively. The format of these numbers is free; as long as there are a total of four values per entry the list will be read correctly. The following three lines are an example of a valid color list: 1 0.0 0.5 1.0 2 0.0 1.0 0.0 3 1.0 0.5 0.0 When a color list is written (by PUTCTB or WRCLIS), it looks like a longer version of the above. The routines GETCTB and RDCLIS will read such a list back into a color table. When a color list is read, it is scaled by linear interpolation to fill the designated part of the color table. For example, it would be possible to read the three line color table above into color indices 2 through 255. If this were done, the red intensity would rise and the blue intensity would fall linearly over the range of indices, while the green intensity would peak in the middle. It is assumed that a color list contains a continuous range of indices. For example, if the second line were omitted from the table above it would be equivalent to specifying 0.0 for all intensities of index 2. However, there is no requirement that the indices given begin with 1; the lines could be numbered 57 through 59 with no change in effect on input. COORDINATES IN DRAWCGM In DrawCGM, positions on the display surface are described in terms of real-valued x and y coordinates. By default these coordinates range between 0.0 and 1.0; this can be changed by the SETSCL or SETWCD routines. The lower left corner of the routine is at the minimum coordinate values ((0.0, 0.0) by default). To specify the location of a rectangle, the user gives the x and y coordinates of the lower left and upper right corners. Certain display devices will put some limits on the part of this coordinate space which actually gets displayed. For example, at the Pittsburgh Supercomputing Center, the Peritek device which is the heart of the animation system displays only the top 90% of the image. If one tries to do an animation on this device using DrawCGM, everything with a y coordinate less than 0.1 will be cut off by the frame of the monitor when the movie is displayed. To help users plan for this, the routine WINFRM can be used to draw a rectangle around the region which is visible on the display. It is best to avoid drawing data right up against the edge of the visible window; we recommend that a 5% margin be left all around the edge of the frame. Thus a good range of coordinates for doing animation at the PSC would be x values between 0.05 and 0.95, and y values between 0.15 and 0.95 . IMAGE DIMENSIONS AND PIXEL SIZES For speed in doing animation, the animation system at the PSC avoids scaling of images as they are displayed. This means that a 10 by 10 array will cover 10 pixels in each direction when displayed. Note that this may not correspond to the size of the rectangle that was given for the display of the image. At this point, the image will be drawn on the Peritek with its lower left corner in the correct place; this will potentially put the upper right corner in the wrong place. In the future resizing may be done automatically, but if this is necessary it will result in undesirably coarse images. Thus it is necessary to make the dimensions of the image to be displayed fit the coordinates on the screen into which it is to be drawn. This is very easy to do. On the Peritek, the coordinate distance in each direction (from 0.0 to 1.0 unless reset by SETSCL or SETWCD) is spanned by 512 pixels. Thus the correct raster size in a given direction is 512 times the coordinate distance between the two corners in that direction. For example, consider an image which is to lie between the coordinates (0.25, 0.25) and (0.75, 0.75) on the Peritek screen. In each direction, the raster which is to produce the image should have 512*(0.75-0.25)=256 elements. The STRLIN and STRSPL routines can be used to accomplish this. Note that the output of DrawCGM is a perfectly valid CGM file even if this scaling is not done, and it can be properly displayed on a variety of devices (for example, Tektronix terminals or Postscript printers). The nicety of proper raster scaling is only needed for good animation. OUTPUT DEVICES DrawCGM supports output to all the devices supported by GPlot, the CGM translater developed at the PSC. This means that it is possible to do graphics in DrawCGM and have the output drawn directly on your workstation or terminal, rather than going through an intermediate CGM file. If you make no specific calls to select the output device, DrawCGM will produce a binary CGM image file as output. To change the output device, use the routine DEVICE, which must be called before the first call to GRFINI or NEWFRM. If you direct the output of DrawCGM to an interactive device, you may want the package to pause automatically between frames of output. The routine STPAUS causes each new frame action to pause until the user hits the 'return' key; UNPAUS turns this behavior back off again. FILE SIZES The output files produced by DrawCGM can be quite large. A single image frame which fills the screen of the Peritek output device used for animation includes 230K pixels worth of information, and occupies roughly 460 Vax blocks. A full 30 seconds of animation at 30 frames per second involves 900 such frames, for a total of almost 420K Vax blocks. In practice the files produced are somewhat smaller than this, but the scale is roughly correct. It is important for the user to make sure there is sufficient space available to receive the output file as it is produced, and to show consideration for other users by getting the file off disk as soon as practical. LIST OF ROUTINES: Array and image manipulation routines: CPYINT Copies one integer array into another. HORFLP Invert a 2-D integer array horizontally. IMGMSK Mask parts of an integer array with values from another array. INTERP Interpolate an integer array between two other integer arrays. RTOINT Convert a real array to integers in a given range. STRLIN Enlarge a 2-D real array by linear interpolation. STRSPL Enlarge a 2-D real array by bicubic spline interpolation. VRTFLP Invert a 2-D integer array vertically. Attribute setting routines: FILCLR Set the color index with which polygons will be filled. LINCLR Set the color with which a polyline will be drawn. MRKCLR Set the color with which markers will be drawn. MRKTYP Set the type of mark used for markers. MRKSIZ Set the size of markers. Color table manipulation routines: GETCLR Queries one element of the color table. GETCTB Read in part or all of a color table from a color list file. PUTCTB Write part or all of a color table to a color list file. RDCLIS Read a color list file into a set of color arrays. SETCLR Set one element of the color table. SETCTB Set the color table to one of several predefined spectra. WRCLIS Write a color list file from a set of color arrays. Control routines: GRFCLS Shuts down DrawCGM at the close of output. GRFINI Initializes DrawCGM for output. NEWFRM Begins a new frame. DEVICE Set the output device driver to be used. STPAUS Cause DrawCGM to pause after each frame. STPCNM Set the CGM picture name associated with future pictures TGLDBG Turn debugging messages on or off. UNPAUS Cause DrawCGM to cease pausing after each frame. Coordinate transformation setting routines: SETSCL Set the coordinate system preserving aspect ratio of data SETWCD Set the coordinate system disregarding aspect ratio of data Drawing routines: CIRCLE Draw a circle, either filled or unfilled. CGRID Draw a Cartesian coordinate grid on a portion of the picture. CLRRCT Clear a rectangle to the background color. DRAWIT Draw an integer raster to an open frame. DRWCGM Moves while drawing a line (i.e. 'pen down'). See MOVCGM. DRWPIX Draw a simple integer array to a CGM file with one call. HORCBR Draw a horizontal color bar into an open frame. LABEL Draw a label of a given color and size into an open frame. MOVCGM Moves without drawing a line (i.e. 'pen up'). See DRWCGM. PLTBAR Plot part or all of a color table as a set of three line graphs. PLYGON Draw a polygon. PLYLIN Draw a polyline, a set of connected points. PLYMRK Draw a polymarker, a set of point markers. VRTCBR Draw a vertical color bar into an open frame. WINFRM Draw a window frame around the display region visible in animation. SUBROUTINE DOCUMENTATION: *** Array and Image Manipulation Routines *** Cpyint Purpose: To copy one integer array into another. Access: CALL Cpyint(Ifield,Ofield,Nxdim,Nydim) Parameters: Ifield [integer array, input] -The array to copy. Ofield [integer array, output] -The target array, into which Ifield is copied. Nxdim,Nydim [integer, input] -The dimensions of Ifield and Ofield. Discussion: This utility routine simply copies Ifield to Ofield. Horflp Purpose: To invert a 2-D integer array horizontally. Access: CALL Horflp(Ipixel,Nxdim,Nydim) Parameters: Ipixel [integer array, input] -This is the image array to be inverted. Nxdim,Nydim [integer, input] -The dimensions of Ipixel. Discussion: This routine simply inverts an image left-to-right. This is useful for constructing whole symmetric systems from single quadrants. For example, an image representing data in the x>0, y>0 quadrant might be drawn, then alternately flipped with Horflp and Vrtflp and redrawn (with appropriate offsets) to form a single complete image. Interp Purpose: To calculate an integer array by interpolation between two other integer arrays. Access: CALL Interp(Min,Max,Ipixel,Nxdim,Nydim,Iframe,Nframes) Parameters: Min [integer array, input] -This image represents the lower bound of the interpolation. Max [integer array, input] -This image represents the upper bound of the interpolation. Ipixel [integer array, output] -This is the target array; it receives the interpolated image. Nxdim,Nydim [integer, input] -The dimensions of Min, Max, and Ipixel. Iframe [integer, input] -The relative position of the frame in the interpolation series. Nframes [integer, input] -The total number of frames in the interpolation series. Discussion: During animation, images are displayed 30 times a second. If a user has only enough data for a few tens of frames, additional frames must be generated from the available data in order to produce smooth animation which lasts long enough to be interesting. Interp aids in doing this, by calculating an image by linear interpolation between two input images. Suppose one wanted to produce an animation lasting 30 seconds, but data was available from only 100 discrete times in the evolution of the system being studied. Since a 30 second animation requires 900 images, 9 output images would have to be produced from each set of data. The interpolants between any pair of adjoining data frames could be produced as follows. The data available for time T could be scaled and converted to integers, and then supplied to Interp as the input array Min. The data from time T+1 would be similarly converted to an image and supplied as array Max. Nframes would be 9 for this example. As Interp was called with values for Iframe from 1 to 9, the output array Ipixel would contain successive interpolants in the series needed to 'fade' Min into Max. Because of the way image values are mapped to colors on the screen, colored structures in the resulting animation will appear to move gradualy from those corresponding to the image Min to those corresponding to Max. The interpolation points are chosen so that there are actually Nframes steps in the series between Min and Max. Iframe=1 produces an image identical to Min, and Iframe=Nframes produces an image which still contains a fraction of the Min image. This is done so that a series of frames generated in this way will continue to animate smoothly as an image that previously served as a Max becomes a new Min. Imgmsk Purpose: To mask parts of an integer array with values from another integer array. Access: CALL Imgmsk(Mfield,Nxmask,Nymask,Ipixel,Nxdim,Nydim) Parameters: Mfield [integer array, input] -The mask to be applied to the image Ipixel. Nxmask,Nymask [integer, input] -The dimensions of Mfield. Ipixel [integer array, input and modified on output] -The image to which the mask Mfield is applied. Nxdim,Nydim [integer, input] -The dimensions of Ipixel. Discussion: If an element of the array Mfield is non-zero, the corresponding region of the image array Ipixel is replaced with the value in Mfield. The effect of this is to overlay the image Mfield onto the image Ipixel, with the underlieing image showing through where the overlay was set to zero, the background color. Note that there is no requirement that the two images be the same size. Typically Ipixel is larger than Mfield; if this is the case each cell of Mfield will cover a rectangle of Ipixel sufficiently large that the boundaries of the two images match. Note that this means that Mask can be used to enlarge integer images, simply by setting Ipixel initially to zero and supplying the image to be enlarged as Mfield. The scaling that results is constant scaling; there is no interpolation between values. A typical use of Imgmsk would be to overlay weather data on a map, or to overlay geographical boundaries onto a set of weather data. Rtoint Purpose: To convert a real array to integers, mapping it into a given range of values. Access: CALL Rtoint(Rarray,Iarray,Nxdim,Nydim,Rmn,Rmx,Imn,Imx) Parameters: Rarray [real array, input] -The real array to be scaled and converted to integer format. Iarray [integer array, output] -The integer array into which the output data is written. Nxdim,Nydim [integer, input] -The x and y dimensions respectively of Rarray and Iarray. Rmn,Rmx [real, input] -Values specifying the lower and upper bounds of the input data in Rarray. Imn,Imx [integer, input] -The values into which input data equal to Rmn and Rmx respectively will be mapped. Discussion: Rtoint maps the real input array Rarray linearly into the integer output array Iarray, such that input values equal to Rmn will be mapped into the value Imn, and input values equal to Rmx will be mapped into the value Imx. The mapping is linear, so that an input value midway between Rmn and Rmx will be mapped into an integer midway between Imn and Imx. Note that values outside the range between Rmn and Rmx will be mapped into integers outside the range of Imn to Imx. This is done for speed, and also to ensure that scaling errors are clearly visible on the final output. Strlin Purpose: To enlarge a 2-D real array by linear interpolation. Access: CALL Strlin(Small,Nsx,Nsy,Big,Nx,Ny) Parameters: Small [real array, input] -The input array, to be enlarged. Nsx,Nsy [integer, input] -The dimensions of Small. Big [real array, output] -The target array, into which the enlarged values will be written. Nx,Ny [integer, input] -The dimensions of Big. Discussion: Strlin enlarges an input array by linear interpolation. This is generally the routine of choice for scaling the data to be displayed to the size required by the number of pixels to be covered (see the section on Image Dimensions and Pixel Sizes). Strspl Purpose: To enlarge a 2-D real array by bicubic spline interpolation. Access: CALL Strspl(Small,Temp,Nsx,Nsy,Big,Nx,Ny) Parameters: Small [real array, input] -The input array, to be enlarged. Temp [real array, input] -Scratch space, of the same dimensions as Small. Nsx,Nsy [integer, input] -The dimensions of Small and Temp. Big [real array, output] -The target array, into which the enlarged values will be written. Nx,Ny [integer, input] -The dimensions of Big. Discussion: Strspl enlarges an input data array by bicubic spline interpolation. Note that discontinuities in the input data can result in ringing, overshoot or undershoot, or other unpleasant artifacts in the caluculated output array. In the current implementation, Strspl can handle a maximum size for the enlarged array of 1200 elements in each direction. Vrtflp Purpose: To invert a 2-D integer array vertically. Access: CALL Vrtflp(Ipixel,Nxdim,Nydim) Parameters: Ipixel [integer array, input] -This is the image array to be inverted. Nxdim,Nydim [integer, input] -The dimensions of Ipixel. Discussion: This routine simply inverts an image left-to-right. This is useful for constructing whole symmetric systems from single quadrants. For example, an image representing data in the x>0, y>0 quadrant might be drawn, then alternately flipped with Horflp and Vrtflp and redrawn (with appropriate offsets) to form a single complete image. *** Attribute Setting Routines *** Filclr Purpose: To set the color index with which polygons will be filled. Access: CALL Filclr(Icolor) Parameters: Icolor [integer, input] -The color index with which to fill future polygons. Discussion: Filclr sets the color of polygons drawn by Plygon. All subsequent Plygon calls will produce polygons of the given color, until another Filclr call occurs. Note that some routines, such as the color bar routines and Clrrct, draw polygons and thus call Filclr internally. Thus it is wise to call Filclr at the beginning of each series of Plygon calls, rather than trusting that a previous call to Filclr will remain in effect. In any case, the beginning of a new frame resets the polygon color. Linclr Purpose: To set the color with which a polyline will be drawn. Access: CALL Linclr(Icolor) Parameters: Icolor [integer, input] -The color index with which to draw future polylines. Discussion: Linclr sets the color of polylines drawn by Plylin. All subsequent Plylin calls will produce lines of the given color, until another Linclr call occurs. Note that some routines, such as the color bar routines and Pltbar, draw polygons and thus call Linclr internally. Thus it is wise to call Linclr at the beginning of each series of Plylin calls, rather than trusting that a previous call to Linclr will remain in effect. In any case, the beginning of a new frame resets the polyline color. Mrkclr Purpose: To set the color with which markers will be drawn. Access: CALL Mrkclr(Icolor) Parameters: Icolor [integer, input] -The color index with which to draw future markers. Discussion: Mrkclr sets the color of polymarkers drawn by Plymrk. All subsequent Plymrk calls will produce markers of the given color, until another Mrkclr call occurs. Note that some routines may call Mrkclr internally. Thus it is wise to call Mrkclr at the beginning of each series of Plymrk calls, rather than trusting that a previous call to Mrkclr will remain in effect. In any case, the beginning of a new frame resets the marker color. Mrksiz Purpose: To set the size with which markers will be drawn. Access: CALL Mrksiz(Size) Parameters: Size [real, input] -The size with which to draw future markers. Discussion: Mrksiz sets the size of polymarkers drawn by Plymrk. All subsequent Plymrk calls will produce markers of the given size, until another Mrksiz call occurs. The size (parameter Size) is given as a fraction of the default size. For example, calling Mrkclr with a parameter of 2.0 will result in markers twice the normal size; using a parameter of 0.5 will result in markers half the normal size. Note that, in keeping with the definition of CGM, point markers (see Mrktyp below) are never resized; they are always drawn with the smallest possible point. Note that some routines may call Mrksiz internally. Thus it is wise to call Mrksiz at the beginning of each series of Plymrk calls, rather than trusting that a previous call to Mrksiz will remain in effect. In any case, the beginning of a new frame resets the marker size. Mrktyp Purpose: To set the marker type which markers will be drawn. Access: CALL Mrktyp(Itype) Parameters: Itype [integer, input] -The marker type with which to draw future markers. Discussion: Mrktyp sets the color of polymarkers drawn by Plymrk. All subsequent Plymrk calls will produce markers of the given type, until another Mrkclr call occurs. The available marker types, and the Itype values which produce them, are as follows: Itype Marker 1 '.' (the smallest possible point) 2 '+' (a plus sign) 3 '*' (a star or asterisk) 4 'o' (a circle or 'o') 5 'x' (a cross or 'x') Note that, in keeping with the definition of CGM, point markers (see Mrktyp below) are never resized; they are always drawn with the smallest possible point. Note that some routines may call Mrktyp internally. Thus it is wise to call Mrktyp at the beginning of each series of Plymrk calls, rather than trusting that a previous call to Mrktyp will remain in effect. In any case, the beginning of a new frame resets the marker type. *** Color Table Manipulating Routines *** Getclr Purpose: To query one element of the color table. Access: CALL Getclr(Index,Rval,Gval,Bval,Setflg) Parameters: Index [integer, input] -The color index to be queried. Rval,Gval,Bval [real, output] -These parameters return the red, green, and blue intensities respectively (between 0.0 and 1.0) of the specified index. If the index has never been set, the returned values will be 0.0 . Setflg [logical, output] -Setflg returns .TRUE. if the queried index has been set since the beginning of this DRAWCGM run, .FALSE. otherwise. Discussion: Getclr can be used to retrieve entries from the working color table. Note that if a value has been set since the beginning of the frame, the value returned may not correspond to the value encoded in the output of DRAWCGM for the frame in progress. GETCTB Purpose: To read in part or all of a color table from a color list file. Access: CALL GETCTB(Min,Max,Fname,Ierror) Parameters: Min,Max [integer, input] -The minimum and maximum color table entries to be assigned. Fname [character string, input] -Fortran 77 character string of the color list file to be read. Ierror [integer, output] -On return, Ierror contains one of the following: Ierror Meaning 0 The color list was read successfully. 1 It was impossible to open the color list file. 2 An error occurred while reading the color list file. Discussion: GETCTB will read a color list into the working color table. Note that it must be called before the beginning of a frame for it to be valid for that frame. It is legitimate to call GETCTB before calling GRFINI to set the color table for the first frame. The values given in the color list are scaled by linear interpolation to span the range of colors between Min and Max inclusively. The minimum and maximum indices in the color list are also irrelevant; the color scheme loaded will be shifted to the region of the color table between Min and Max. However, the color list should contain a continuous range of indices between the minimum and maximum indices given. The order of the entries in the color list is irrelevant. See the Color Tables section for more information on color lists. Putctb Purpose: To write part or all of a color table to a color list file. Access: CALL Putctb(Min,Max,Fname,Ierror) Parameters: Min,Max [integer, input] -The minimum and maximum color indices to be written. Fname [character string, input] -Fortran 77 character string of the color list file to be written. Ierror [integer, output] -On return, Ierror contains one of the following: Ierror Meaning 0 The color list was read successfully. 1 It was impossible to open the color list file. 2 An error occurred while writing the color list file. Discussion: Putctb simply dumps the given segment of the working color table to the named file, from Min through Max inclusive. See the Color Tables section for more information on color lists. Rdclis Purpose: To read a color list file into a set of color arrays. Access: CALL Rdclis(Rarray,Garray,Barray,Nclrs,Min,Max,Fname,Ierror) Parameters: Rarray,Garray,Barray [real array, output] -These are the arrays into which the color list is read. Red values are stored in Rarray, green in Garray, and blue in Barray. Nclrs [integer, input] -The dimension of Rarray, Garray, and Barray. Min,Max [integer, input] -The minimum and maximum color array entries assigned are Min+1 and Max+1 respectively. Fname [character string, input] -Fortran 77 character string of the color list file to be read. Ierror [integer, output] -On return, Ierror contains one of the following: Ierror Meaning 0 The color list was read successfully. 1 It was impossible to open the color list file. 2 An error occurred while reading the color list file. Discussion: Rdclis will read a color list into a set of color arrays. These values may then be examined or manipulated by the user, and then possibly installed in the working color table using SETCLR. Note that working color table entries must be made before the beginning of a frame for it to be valid for that frame. It is legitimate to call SETCLR before calling GRFINI to set the color table for the first frame. *NOTE*: The color values are assigned to array elements Min+1 through Max+1 inclusive. The offset of 1 is to bring the customary numbering of color indices (starting from zero) into compliance with the Fortran convention of indexing arrays from 1. The values given in the color list are scaled by linear interpolation to span the range of array entries between Min+1 and Max+1 inclusively. The minimum and maximum indices in the color list are also irrelevant; the color scheme loaded will be shifted to the region of the color table between Min and Max. However, the color list should contain a continuous range of indices between the minimum and maximum indices given. The order of the entries in the color list is irrelevant. See the Color Tables section for more information on color lists. SETCLR Purpose: To set one element of the color table. Access: CALL SETCLR(Index,Rval,Gval,Bval) Parameters: Index [integer, input] -The color index to be set. Rval,Gval,Bval [real, input] -The red, green, and blue values respectively to be assigned to the given color index. Discussion: The user can set working color table entries directly with SETCLR. Valid indices run from 0 through 255 inclusive. Note that working color table entries must be made before the beginning of a frame for it to be valid for that frame. It is legitimate to call SETCLR before calling GRFINI to set the color table for the first frame. Setctb Purpose: To set the color table to one of several predefined spectra. Access: CALL Setctb(Ischm) Parameters: Icschm [integer, input] -This value selects the color scheme which will be loaded into the color table. Icschm Description ------ ----------- 1 Gray scale 2 Blue fading into yellow 3 Waves of green in red fading to blue 4 Pseudospectral (red to blue) 5 Inverted Pseudospectral (blue to red) Discussion: An out-of-range index causes no color table to be generated; i.e. the previous colors will remain in effect. Color indices 0 and 1 are set to white and black respectively, if the index is in the above range. Color indices 2 through 255 are set according to the selected scheme. Wrclis Purpose: To write a color list file from a set of color arrays. Access: CALL Wrclis(Rarray,Garray,Barray,Nclrs,Min,Max,Fname,Ierror) Parameters: Rarray,Garray,Barray [real array, output] -These are the arrays into which the color list is read. Red values are stored in Rarray, green in Garray, and blue in Barray. Nclrs [integer, input] -The dimension of Rarray, Garray, and Barray. Min,Max [integer, input] -The minimum and maximum color array entries written are Min+1 and Max+1 respectively. Fname [character string, input] -Fortran 77 character string of the color list file to be written. Ierror [integer, output] -On return, Ierror contains one of the following: Ierror Meaning 0 The color list was read successfully. 1 It was impossible to open the color list file. 2 An error occurred while writing the color list file. Discussion: Wrclis will write a valid color list from a set of color arrays. *NOTE*: The color values are written from array elements Min+1 through Max+1 inclusive. The offset of 1 is to bring the customary numbering of color indices (starting from zero) into compliance with the Fortran convention of indexing arrays from 1. See the Color Tables section for more information on color lists. *** Control Routines *** Grfcls Purpose: To shut down DRAWCGM at the close of output. Access: CALL Grfcls() Parameters: None. Discussion: GRFCLS must always be called at the end of a DRAWCGM session, to properly terminate graphical output. DRWPIX will call GRFCLS automatically if it is called with Istat= 2. Grfini Purpose: To initialize DRAWCGM for output. Access: CALL Grfini() Parameters: None. Discussion: GRFINI must always be called to initiate graphical output. DRWPIX will call GRFINI automatically if appropriate. Newfrm Purpose: To begin a new frame. Access: CALL Newfrm() Parameters: None. Discussion: NEWFRM must always be called to terminate one output frame and begin another. DRWPIX will call NEWFRM if it is called with Istat= 1. Device Purpose: To set the output device used by DrawCGM. Access: CALL Device(Dev) Parameters: Dev [character string; input] -The device to be used for output by DrawCGM. Discussion: DrawCGM can use any of the device drivers useable by GPlot, the CGM translation program written at the Pittsburgh Supercomputing Center. If the user makes no call to Device, the output image(s) will be stored as binary CGM metafiles. However, by calling Device with the appropriate parameter, other devices can be selected. The devices available at any given installation will vary, but some possible devices and the parameter strings which invoke them are as follows: Dev Device cgmb Binary CGM (the default) cgmc Clear text CGM ps Postscript page description language tek Tektronix terminal tek4207 Tektronix 4207 color terminal xws X-windows Device names should be given in lower case. Note that Device must be called before the first call to Grfini or Newfrm; beyond that point the device is set. If the tektronix output device or any other screen-oriented device is used, the user is responsible for pausing the display between frames. If the user takes no action, newly drawn frames will be immediately erased and replaced with subsequent frames. Note that Clear text CGM files can be very large, especially if they contain raster images. This device should be used for diagnostic purposes only. Stpaus Purpose: To cause DrawCGM to pause after each frame of output. Access: CALL Stpaus() Parameters: None. Discussion: Normally DrawCGM proceeds directly from one frame of output to the next without pausing. This is appropriate if the output device is a CGM file or some other non-interactive device, but it will cause a frame to disappear as soon as it is drawn on an interactive output device. A call to Stpaus causes DrawCGM to pause each time Newfrm or Grfcls is called and print a message asking the user to 'Hit to continue'. (This message is written to Fortran unit 6). DrawCGM then looks for a line of input on Fortran unit 5, and proceeds when it has read one. The routine Unpaus undoes the effects of Stpaus. Stpcnm Purpose: To assign a CGM picture name to future pictures. Access: CALL Stpcnm(Name, Ierr) Parameters: Name [character string; input] -name to be given to all pictures until the next call to Stpcnm. Ierr [integer; output] -returns non-zero if for some reason the picture name could not be set. Discussion: The CGM metafile standard allows any picture to have a name associated with it. By default DrawCGM leaves this name null. Stpcnm allows a (non-null) name to be used; it is implementd as an internal parameter setting for compatibility with earlier versions. Tgldbg Purpose: To enable or disable debugging output from the CGM generator level of DrawCGM. Access: CALL Tgldbg(Ierr) Parameters: Ierr [integer; output] -returns non-zero if for some reason the debugging state could not be toggled. Discussion: The first time the user calls Tgldbg, debugging output is enabled. The second time debugging output is disabled. Subsequent calls turn debugging on and off respectively. Note that a great deal of output can be produced this way. The user may find out a great deal more than he or she wanted to know by enabling debugging unnecessarily. Unpaus Purpose: To cause DrawCGM to cease pausing after each frame of output. Access: CALL Unpaus() Parameters: None. Discussion: Normally DrawCGM proceeds directly from one frame of output to the next without pausing. This can be changed by the routine Stpaus, which causes DrawCGM to print a message and wait for the user to type a carriage return at each call to Newfrm or Grfcls. Unpaus undoes the effect of Stpaus, causing DrawCGM to proceed without pausing to the next frame (if any). *** Coordinate Transformation Routines *** Setscl Purpose: To conveniently set the coordinate system so that a given set of points will be centered and undistorted. Access: CALL Setscl(Xarray,Yarray,Npts) Parameters: Xarray,Yarray [real array,input] -The x and y coordinates of the user's data. Npts [integer,input] -The dimension of Xarray and Yarray Discussion: By default, DrawCGM uses a 1.0 by 1.0 drawing area, with coordinate ranges of 0.0 to 1.0 in both directions and the origin at the lower left corner of the display. If these coordinates are inconvenient, they can be reset by using Setscl or Setwcd (see below). Setscl is designed to easily reset the coordinate system. Given two one-dimensional arrays containing x and y coordinates, Setscl will calculate the square area which encloses all the given points and set the coordinate system so that the drawing area is centered on that square area. A 5 percent margin is left around all edges of the output device. Note that this procedure produces a coordinate system in which the aspect ratio of the data is preserved. For example, if all the data points given fit within a box 20 units wide by 1 unit high, the final image will only occupy the middle 1/20th of the display. None of the data points will be mapped into the region above or below this band. Changing the coordinate system does not change the number of pixels on the output screen. If the output is ultimately to end up on a device for which pixel sizes matter (for example, the animation system at the Pittsburgh Supercomputing Center), the information in the introductory section 'Image Dimensions and Pixel Sizes' should be considered when rescaling coordinates. Note also that Setscl does no drawing of its own; it only sets up the coordinate system. Setscl can be called at any time; the new coordinate system goes into effect immediately. Setwcd Purpose: To arbitrarily set the coordinate system. Access: CALL Setwcd(Xmin,Ymin,Xmax,Ymax,Ierr) Parameters: Xmin,Ymin [real, input] -The x and y coordinates for the lower left corner of the output device. Xmax,Ymax [real, input] -The x and y coordinates for the upper right corner of the output device. Ierr [integer, output] -Error code; returns non-zero if unsuccessful. Discussion: By default, DrawCGM uses a 1.0 by 1.0 drawing area, with coordinate ranges of 0.0 to 1.0 in both directions and the origin at the lower left corner of the display. If these coordinates are inconvenient, they can be reset by using Setwcd or Setscl (see above). Setwcd takes two real coordinate pairs and redefines DrawCGM's internal coordinates so that these pairs will fall at the lower left and upper right corners of the output device. Note that this can produce a coordinate system in which the aspect ratio of the data may not be preserved. For example, if the x and y coordinates have the same units in the user's program, but the corner coordinates the user passes to Setwcd are not the corners of a square in the user's coordinates, distortion will result. A figure the vertices of which form a square in the user's coordinates will appear as a rectangle in the output. If Xmin equals Xmax or Ymin equals Ymax, Ierr returns non-zero and the coordinate system is not changed. Changing the coordinate system does not change the number of pixels on the output screen. If the output is ultimately to end up on a device for which pixel sizes matter (for example, the animation system at the Pittsburgh Supercomputing Center), the information in the introductory section 'Image Dimensions and Pixel Sizes' should be considered when rescaling coordinates. Note also that Setwcd does no drawing of its own; it only sets up the coordinate system. Setwcd can be called at any time; the new coordinate system goes into effect immediately. *** Drawing Routines *** Circle Purpose: To draw a circle, either filled or unfilled. Access: CALL Circle(Xcenter,Ycenter,Radius,Filled) Parameters: Xcenter [real, input] -The X coordinate of the center of the circle. Ycenter [real, input] -The Y coordinate of the center of the circle. Radius [real, input] -The radius of the circle. Filled [logical, input] -True if the circle is to be filled. Discussion: Circle draws a circle of the given size at the given position. Actually, depending on the value of Filled, Circle calls Plylin or Plygon to draw a 64-sided figure which should look acceptably circular. If Filled is false, the circle will be drawn with the color currently set via Linclr; only the outline of the circle is drawn. If Filled is true, a filled circle is drawn with the color currently set by Filclr. The circle drawn by this routine is "round" in the coordinate system of the picture. As long as the picture coordinate system uses the same scale in the X and Y directions, the circle will both "be" round, and "appear" round when displayed. However, if the routine Setwcd is used to define a coordinate system with different X and Y scales, circles drawn by Circle will appear elliptical. Cgrid Purpose: To draw a Cartesian grid on a portion of the picture. Access: CALL Cgrid(Xmin,Xmax,Nx,Ymin,Ymax,Ny) Parameters: Xmin [real, input] -The X coordinate of the lower left corner of the grid. Xmax [real, input] -The X coordinate of the upper right corner of the grid. Nx [integer, input] -The number of vertical grid lines along the X direction. Ymin [real, input] -The Y coordinate of the lower left corner of the grid. Ymax [real, input] -The Y coordinate of the upper right corner of the grid. Ny [integer, input] -The number of horizontal grid lines along the Y direction. Discussion: Cgrid will draw evenly spaced Cartesian grid lines in the portion of the picture defined by the corners (Xmin,Ymin) and (Xmax,Ymax). There will be Nx vertical lines, occurring at equal intervals between Xmin and Xmax, including the endpoints. However, if Nx=1, a single grid line will be drawn halfway between Xmin and Xmax. Similar rules are used to define the Y grid lines. There is no need for the grid lines to fill the entire picture. In the default DrawCGM coordinate system, for instance, just the upper left quarter of the picture would be covered with grid lines if we called Cgrid with Xmin=0.0, Xmax=0.5, Ymin=0.5 and Ymax=1.0. The lines are drawn by the DrawCGM routines Movcgm and Drwcgm. Hence, the color of the lines may be altered by calling Linclr before calling Cgrid. The grid lines will actually produce square boxes if Nx and Ny are equal and (Xmax-Xmin) and (Ymax-Ymin) are equal, or more generally, if (Xmax-Xmin)/Nx equals (Ymax-Ymin)/Ny. However, these boxes will not appear square if the underlying coordinate system does not have equal X and Y extent, which can happen if the DrawCGM routine Setwcd is used to define the coordinate system. Clrrct Purpose: To clear a rectangle to the background color. Access: CALL Clrrct(Xmin,Ymin,Xmax,Ymax) Parameters: Xmin,Ymin [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the lower left corner of the area to be cleared. Xmax,Ymax [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the upper right corner of the area to be cleared. Discussion: This routine simply draws a rectangle of the background color over the specified area, functionally clearing it. This may be useful for writing text over some section of an image. Drawit Purpose: To draw an integer raster to an open frame. Access: CALL Drawit(Ipixel,Nxdim,Nydim,Xmin,Ymin,Xmax,Ymax) Parameters: Ipixel [integer array, input] -The nxdim by nydim array to be drawn. Nxdim,Nydim [integer, input] -The dimensions of Ipixel. Xmin,Ymin [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the lower left corner of the image. Xmax,Ymax [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the upper right corner of the image. Discussion: Drawit draws the integer array Ipixel to the currently open frame, using the color scheme in effect for that frame. Drwcgm Purpose: To draw to a specified point (x,y) Access: CALL Drwcgm(X,Y) Parameters: X,Y [real,input] -These are the x and y coordinates of the point to be drawn to. Note that the starting point for the line must be set via an earlier call to Movcgm or Drwcgm. Discussion: Drwcgm is the equivalent to "move with pen down" routines found in many other graphics packages. It requires knowledge of where it should begin drawing and where it should draw to. The starting point part is provided by an initial call to Movcgm before any series of calls to Drwcgm. Once Movcgm has been called once, Drwcgm may then be called an indefinite number of times in succession without intervening calls to Movcgm. If, however, a call is made to some other drawing primitive, a call to Movcgm must again be made to set up Drwcgm calls or the routine will continue from the last point it was called with, which may produce unwanted line segments in the user's picture. Drwpix Purpose: To trivially draw a simple integer array to a CGM file. Access: CALL Drwpix(Istat,Xmin,Ymin,Xmax,Ymax,Ipixel,Nxdim,Nydim,Icschm) Parameters: Istat [integer, input] -Istat specifies whether the CGM file will be closed after this image is written. Istat = 1 specifies that more frames will follow; Istat = 2 specifies that this is to be the last frame. Xmin,Ymin [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the lower left corner of the image. Xmax,Ymax [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the upper right corner of the image. Ipixel [integer array, input] -The nxdim by nydim array to be drawn. Nxdim,Nydim [integer, input] -The dimensions of Ipixel. Icschm [integer, input] -The color scheme to be used. See the description of Setctb for the allowed values. Discussion: DRWPIX is a 'shortcut' routine, carrying out the functions of GRFINI, NEWFRM, and GRFCLS as needed. The simplest program using DRAWCGM would be a single call to DRWPIX with Istat=2, Ipixel an integer array with values between 0 and 255, and the other parameters set appropriately. Next simplest would be a series of calls to DRWPIX, all but the last with Istat=1. Istat=2 is used for the last call to close the CGM file. When called with Istat=1, DRWPIX leaves the frame into which it draws open so that other calls may be added if desired. Istat=2 closes the frame and the CGM file, but note that a call to DRWPIX with Istat=2 is equivalent to a call with Istat=1 followed by a call to GRFCLS. To save recomputing the color table at each call, the first call to DRWPIX can be made with a valid non-zero value of Icschm, and subsequent calls can be made with Icschm=0. Horcbr Purpose: To draw a horizontal color bar into an open frame. Access: CALL Horcbr(Xmin,Ymin,Xmax,Ymax,Ncmin,Ncmax,Lstr,Rstr,Ilbclr,Size) Parameters: Xmin,Ymin [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the lower left corner of the color bar. Xmax,Ymax [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the upper right corner of the color bar. Ncmin,Ncmax [integer, input] -The minimum and maximum color indices to be included in the color bar respectively. Lstr,Rstr [character string, input] -Fortran 77 character strings to label the left and right ends of the color bar respectively. Ilbclr [integer, input] -The color index with which to write the labels. Size [real, input] -The size of each character in the labels (between 0.0 and 1.0). Discussion: Horcbr draws a horizontal color bar, frames it with color 1, and adds the labels in the color given. Note that the appropriate value of Size is small, say 0.025 (40 characters per line). Note that not all output devices are capable of properly scaling the text on output. In some cases the text may come out larger or smaller than the size given. Label Purpose: To draw a label of a given color and size into an open frame. Access: CALL LABEL(Xorg,Yorg,String,Iclr,Size) Parameters: Xorg,Yorg [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the lower left corner of the rectangle in which the text will appear. String [character string, input] -A Fortran 77 character string containing the text to be written. Iclr [integer, input] -The index of the color to be used. Size [real, input] -The size of each character (between 0.0 and 1.0). Discussion: LABEL simply writes a string of text on the output device at the coordinates given. The text size is the size of a single character in standard coordinate units, so a value of 0.025 (or 40 characters across the width of the screen) would be typical. Note that not all output devices are capable of properly scaling the text on output. In some cases the text may come out larger or smaller than the size given. Movcgm Purpose: To move to coordinate (x,y) and leave no trace of its movement Access: CALL Movcgm(X,Y) Parameters: X,Y [real,input] -These are the x and y coordinates (between 0.0 and 1.0) of the point to which to move the 'pen'. Note that Movcgm must be called at least once before the first of any series of calls to Drwcgm. Discussion: Movcgm is the equivalent to "move with pen up" routines found in many graphics packages. It moves to a point and saves the location of that point as the "where should I begin?" information used by a subsequent call to Drwcgm. Note that Movcgm must be called once before every series of consecutive calls to Drwcgm. If another drawing routine is called, Movcgm must be called again to set up the starting point for Drwcgm or else Drwcgm will continue drawing from the last point it was called with, which may produce unwanted line segments in the user's picture. Pltbar Purpose: To plot part or all of a color table as a set of three line graphs. Access: CALL Pltbar(Xmin,Ymin,Xmax,Ymax,Minclr,Maxclr,Irclr,Igclr,Ibclr) Parameters: Xmin,Ymin [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the lower left corner of the plotting region. Xmax,Ymax [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the upper right corner of the plotting region. Minclr,Maxclr [integer, input] -The minimum and maximum color table indices to be plotted. Irclr,Igclr,Ibclr [integer, input] -The color indices with which to plot the red, green, and blue color curves respectively. Discussion: This routine is provided primarily for debugging purposes, as it supplies a convenient way to spot unassigned or inappropriate color table entries. It can be drawn above a horizontal color bar to very good effect, and it allows the examination of color tables on non-color output devices. Plygon Purpose: To draw a polygon. Access: CALL Plygon(Npts,X,Y) Parameters: Npts [integer, input] -The number of boundary points for the polygon; the dimension of X and Y. X [real array, input] -The list of X coordinates for the polygon boundaries. Y [real array, input] -The list of Y coordinates for the polygon boundaries. Discussion: Plygon draws a polygon by linking the vertices given in the X and Y arrays, closing the loop by linking the last vertex back to the first. The polygon is filled with the color index currently selected via Filclr. Plylin Purpose: To draw a polyline, a set of connected points. Access: CALL Plylin(Npts,X,Y) Parameters: Npts [integer, input] -The number of boundary points for the polyline; the dimension of X and Y. X [real array, input] -The list of X coordinates for the polyline vertices. Y [real array, input] -The list of Y coordinates for the polyline vertices. Discussion: Plylin draws a set of line segments by linking the vertices given in the X and Y arrays. The polyline is drawn with the color index currently selected via Linclr. Plymrk Purpose: To draw a polymarker, a set of point markers. Access: CALL Plymrk(Npts,X,Y) Parameters: Npts [integer, input] -The number of points in the polyline; the dimension of X and Y. X [real array, input] -The list of X coordinates for the markers. Y [real array, input] -The list of Y coordinates for the markers. Discussion: Plymrk draws a set of markers at the points given in the X and Y arrays. The markers are drawn with the type, color, and size currently selected by Mrktyp, Mrkclr, and Mrksiz respectively. Vrtcbr Purpose: To draw a vertical color bar into an open frame. Access: CALL Vrtcbr(Xmin,Ymin,Xmax,Ymax,Ncmin,Ncmax,Bstr,Tstr,Ilbclr,Size) Parameters: Xmin,Ymin [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the lower left corner of the color bar. Xmax,Ymax [real, input] -These are the x and y coordinates (between 0.0 and 1.0) of the upper right corner of the color bar. Ncmin,Ncmax [integer, input] -The minimum and maximum color indices to be included in the color bar respectively. Bstr,Tstr [character string, input] -Fortran 77 character strings to label the bottom and top of the color bar respectively. Ilbclr [integer, input] -The color index with which to write the labels. Size [real, input] -The size of each character in the labels (between 0.0 and 1.0). Discussion: Vrtcbr draws a vertical color bar, frames it with color 1, and adds the labels in the color given. Note that the appropriate value of Size is small, say 0.025 (40 characters per line). Note that not all output devices are capable of properly scaling the text on output. In some cases the text may come out larger or smaller than the size given. winfrm Purpose: To draw a 'window frame' around the display region visible in video animation. Access: CALL Winfrm() Parameters: none. Discussion: Winfrm draws a rectangular box with corners at coordinates (0.0, 0.1) and (1.0,1.0), and then divides the box with crosshairs. Color index 1 is used for the lines of the box. Winfrm can be used to check that a program is drawing images that lie within the region visible on the PSC's animation system. A clear border of around 0.05 units is recommended between the important parts of the output image and the box boundaries, for aesthetic reasons and to avoid distortion near the edge of the screen. CHANGES FROM EARLIER RELEASES The following changes may break programs which ran using earlier releases of DrawCGM: (1) With Release 3.0, the old routine MASK has been renamed IMGMSK to avoid a conflict with a Cray system routine. The following new features have been added to DrawCGM since earlier releases: (1) Release 3.0 allows the use of all the GPlot device drivers, and includes the routine DEVICE to permit device selection. The default device is still binary CGM. (2) Release 3.0 allows the production of debugging output via the routine TGLDBG. (3) Release 3.0 allows coordinate system rescaling via the routines SETSCL and SETWCD. (4) Release 3.0 allows the production of markers, via the routines PLYMRK, MRKCLR, MRKTYP, and MRKSIZ. (5) Release 3.1 allows setting of CGM picture titles, via the routine STPCNM. EXAMPLE PROGRAMS The following is about the simplest possible DrawCGM program. It draws a single unlabelled image using a single call to DRWPIX. IMPLICIT NONE INTEGER Nxsmall,Nysmall,Nxbig,Nybig PARAMETER (Nxsmall=10,Nysmall=10,Nxbig=300,Nybig=300) REAL Xmin,Ymin,Xmax,Ymax PARAMETER (Xmin= 0.1,Ymin=0.2,Xmax= 0.7,Ymax=0.8) INTEGER Maxclr,Minclr PARAMETER (Maxclr=247,Minclr=20) INTEGER Ipixel(Nxbig,Nybig),Ierr REAL Input(Nxsmall,Nysmall),Pixel(Nxbig,Nybig) EXTERNAL Getdat,Strlin,Rtoint,DRWPIX * * Get the data. (This routine is in this module) * CALL Getdat(Input,Nxsmall,Nysmall) * * Stretch and quantize it, then draw a single image with a single * call to DRWPIX. * CALL Strlin(Input,Nxsmall,Nysmall,Pixel,Nxbig,Nybig) CALL Rtoint(Pixel,Ipixel,Nxbig,Nybig,0.0,1.0,Minclr,Maxclr) CALL DRWPIX(2,Xmin,Ymin,Xmax,Ymax,Ipixel,Nxbig,Nybig,2) STOP END SUBROUTINE Getdat(Input,Nxdim,Nydim) IMPLICIT NONE INTEGER Nxdim,Nydim,I,J REAL Input(Nxdim,Nydim) INTRINSIC Float,Mod DO 10 i= 1,Nxdim DO 10 j= 1,Nydim Input(i,j)= Float(I+J)/(2.0*Nxdim) * Input(i,j)= float(Mod((i*j),Nxdim))/Nxdim 10 CONTINUE RETURN END The following routine reads a color table, and plots two identical frames. The frames use the color table read, and include a label, a color bar, and an image. IMPLICIT NONE INTEGER Nxsmall,Nysmall,Nxbig,Nybig PARAMETER (Nxsmall=10,Nysmall=10,Nxbig=300,Nybig=300) REAL Xmin,Ymin,Xmax,Ymax,Xmincb,Xmaxcb,Xlabel,Ylabel PARAMETER (Xmin= 0.1,Ymin=0.2,Xmax= 0.7,Ymax=0.8) PARAMETER (Xmincb=0.78, Xmaxcb=0.88, Xlabel=0.1, Ylabel=0.93) INTEGER Maxclr,Minclr,Nclr PARAMETER (Maxclr=247,Minclr=20,Nclr=248) INTEGER Ipixel(Nxbig,Nybig),Ierr REAL Input(Nxsmall,Nysmall),Pixel(Nxbig,Nybig) EXTERNAL GETCTB,SETCLR,GRFINI,Label,Strlin,Rtoint,Drawit, 1 Vrtcbr,NEWFRM,GRFCLS,Exit,Getdat * * Read in part of the color table, and add a couple of entries * by hand. GETCTB reads DrawCGM's internal floating point color * arrays from the named files, mapping them by linear * interpolation into the array entries bounded by the 1st and * 2nd parameters. Note that (by tradition) the color table * entries are numbered from zero, so that the minimum acceptable * value of the first parameter is zero. Color index zero * corresponds to the background color. Ierr returns 0 if all * went OK. * CALL GETCTB(Minclr,Maxclr,'COLORS',Ierr) IF (Ierr.NE.0) then WRITE(6,*) ' GETCTB returned ',Ierr CALL Exit(2) ENDIF CALL SETCLR(0,1.0,1.0,1.0) CALL SETCLR(1,0.0,0.0,0.0) * * Get the data. (This routine is in this module) * CALL Getdat(Input,Nxsmall,Nysmall) * * Initialize the CGM generator and begin output * CALL GRFINI() * * Use linear interpolation to stretch the data, map it into * integers, draw it, and add a vertical color bar. * CALL Label(Xlabel,Ylabel,'Stretch by Linear Interp.', 1 1,0.03) CALL Strlin(Input,Nxsmall,Nysmall,Pixel,Nxbig,Nybig) CALL Rtoint(Pixel,Ipixel,Nxbig,Nybig,0.0,1.0,Minclr,Maxclr) CALL Drawit(Ipixel,Nxbig,Nybig,Xmin,Ymin,Xmax,Ymax) CALL Vrtcbr(Xmincb,Ymin,Xmaxcb,Ymax, 1 Minclr,Maxclr,'1e-7','1e+3',1,0.03) * * Start a new frame, and draw the same data again. * CALL NEWFRM() CALL Label(Xlabel,Ylabel,'Second frame, same as the first.', 1 1,0.03) CALL Drawit(Ipixel,Nxbig,Nybig,Xmin,Ymin,Xmax,Ymax) CALL Vrtcbr(Xmincb,Ymin,Xmaxcb,Ymax, 1 Minclr,Maxclr,'1e-7','1e+3',1,0.03) * * Shut down the CGM generator * CALL GRFCLS() STOP END SUBROUTINE Getdat(Input,Nxdim,Nydim) IMPLICIT NONE INTEGER Nxdim,Nydim,I,J REAL Input(Nxdim,Nydim) INTRINSIC Float,Mod DO 10 i= 1,Nxdim DO 10 j= 1,Nydim Input(i,j)= Float(I+J)/(2.0*Nxdim) * Input(i,j)= float(Mod((i*j),Nxdim))/Nxdim 10 CONTINUE RETURN END The following routine is a simpleminded example of the use of the coordinate transformation routines: Program Junk REAL Xarr(20),Xarr(20),Outarray(20),Mini,Maxi INTEGER I,J C DO 10 I =1,20 Xarr(i) = -100.+ i*12. Xarr(i) = 100.- i*12. 10 CONTINUE C C Create interior minima and maxima in the X and Y arrays to be sure that C routine Mnmx doesn't just use end values: C Xarr(5) = 153. Xarr(7) = -112. Yarr(5) = 112. Yarr(7) = -153. c C Write out initial values c WRITE(6,'(XA)'),'Initial values' DO 20 i=1,20 WRITE(6,'(XA,I2,A2,2F9.3)'),'Xarr,Yarr(',I,')=',Xarr(I),Yarr(I) 20 CONTINUE C CALL Mnmx(Xarr,Yarr,20,Mini,Maxi) WRITE(6,'(XA,F9.3)'),'Mini=',Mini WRITE(6,'(XA,F9.3)'),'Maxi=',Maxi C C Scale x-values: C CALL Sclcrd(Xarr,Outarray,20,Mini,Maxi) C C Copy output vector to x-values - DO NOT DO THIS IF YOU DO COMPUTATIONS C ELSEWHERE IN YOUR MAIN PROGRAM THAT USE THE X-VALUES IN YOUR OWN UNITS! C DO 30 I=1,20 Xarr(I) = Outarray(I) 30 CONTINUE C C Scale y-values: C CALL Sclcrd(Yarr,Outarray,20,Mini,Maxi) C C Copy output vector to y-values - DO NOT DO THIS IF YOU DO COMPUTATIONS C ELSEWHERE IN YOUR MAIN PROGRAM THAT USE THE Y-VALUES IN YOUR OWN UNITS! C DO 40 I=1,20 Yarr(i) = Outarray(I) 40 CONTINUE C C Write the result C DO 50 I=1,20 WRITE(6,'(XA,I2,A2,2F9.3)'),'Xarr,Yarr(',I,')=',Xarr(I),Yarr(I) 50 CONTINUE END