In this section the basic characteristics and capabilities of plotc are described. See the separate Input Description and Running the Code sections for more details.
When plotc is run, a variety of input parameters are available to specify the types of curves and symbols to be drawn, information about the axes, the placement of the plot on the page, the text strings to be written, the legend to be used, the fonts and sizes to be used for text, colors, etc. These parameters are specified in a namelist input file supplied by the user, and all of them have default values. Additional input is needed to supply the coordinates of the curves and symbols to be plotted. These coordinates may be specified in a variety of ways, as described in separate sections on the COORS input, the POINTS input, and user-written COORS and POINTS routines. Multiple plots may be created with one input file by simply stacking sets of input data.
The plot is normally displayed on the graphics monitor, using OpenGL graphics routines, and a PostScript file is created that may be printed on a PostScript printer or viewed with a PostScript previewer. The OpenGL and PostScript plots are created separately; i.e., the PostScript plot is not merely a screen capture of the OpenGL plot. The OpenGL plot is intended as a "preview". The PostScript plot allows a wider variety of fonts to be used, with subscripts/superscripts, special symbols, etc.
Plots can be created consisting of multiple curves and/or multiple sets of symbols. The input parameter NCURV specifies the number of curves, and its sign determines whether each curve is to be plotted as a solid line, or in a sequence consisting of different line types (solid, short-dashed, dot-dashed, long-dashed, and dotted.) The input array ICTYPE may be used to change this sequence. The input parameter OFFSET may be used in a multiple curve plot to offset each curve in the x-direction. This parameter is useful, for example, when plotting a family of velocity profiles from a marching analysis at different streamwise stations.
Similarly, the input parameter NSYMB specifies the number of sets of symbols, and its sign determines whether each set is to be plotted as circles, or in a sequence consisting of different symbol types (circle, square, triangle, diamond, inverted triangle, lower right quadrant circle, upper semicircle, rhombus, pentagon, and house.) The input array ISTYPE may be used to change this sequence, and to specify filled instead of open symbols. The size of the symbols is set by the array ISIZE1. Error bars may be included with the symbols, as controlled by the flag IEBAR.
The total number of curves plus the total number of symbol sets is limited to 1000. The total number of points describing the curves and symbol sets is limited to 100,000. These limits may be changed by modifying the file params.h and re-installing the code.
In addition to plotting the curves as vectors (i.e., lines), as described above, the input flag ITYPE may be used to specify a point or vector-symbol plot. In a point plot, each coordinate defining the curve is plotted as a single point. In a vector-symbol plot, each curve is plotted as a line, with symbols distributed every IFREQ points along the curve. A different symbol will be used for each curve in a vector-symbol plot, in the same sequence as described above for plotting sets of symbols. The size of the symbols on a vector-symbol curve is set by ISIZE.
When curves and symbols appear on the same plot, the curves are drawn first, followed by the symbols. When "open" symbols are being drawn the symbols are actually filled in with the background color, then outlined with the color used for lines. Material behind the symbols, such as curves, axes, grid lines, etc., will thus be hidden. This behavior may be changed using the flag IMASK(1).
Plotc can be viewed as a plotting program surrounding two key subroutines - COORS and POINTS. The plotting program takes care of all the boring stuff, like scaling and labeling axes, centering the plot, doing the mapping between user's units and relative (i.e., plotting frame) units, etc. The fun stuff is done by the COORS and POINTS routines.
To get the coordinates of the curves to be plotted, a subroutine named COORS is called. Similarly, to get the coordinates of the points to be plotted as symbols, plus the size of any error bars, a subroutine named POINTS is called. The plotc program contains versions of these subroutines that simply read in coordinates from either the namelist input file or from separate files. The coordinates may be specified in a variety of ways, as described in separate sections for the COORS routine, and for the POINTS routine.
The supplied versions of COORS and POINTS allow a fair amount of variation in how coordinates are specified. However, the real power and flexibility of plotc becomes clearer when you start customizing the code for specific applications by writing your own subroutines COORS and/or POINTS.
Plots are created within a plotting frame measuring FWID × FHGT relative units. The default values for these parameters are 8.5 × 11.0 in portrait mode, and 11.0 × 8.5 in landscape mode. The choice of portrait or landscape mode is determined by the input flag IROT. The values of FWID and FHGT were chosen, obviously, to match the paper size in inches normally used to print the PostScript version of the plot.
Note that the values of FWID and FHGT do not affect the physical size of the window on the graphics monitor used to display the plot. The size of the window depends on the size of the monitor. The shape is determined by the ratio FWID/FHGT. [The maximum dimension of the window will be 80% of the minimum dimension of the monitor. For the default values of FWID and FHGT, and for a 1280 × 1024 monitor, the window will thus be 633 × 819 pixels in portrait mode, and 819 × 633 pixels in landscape mode.] The PostScript plot, of course, is always printed on paper, with default measurements of 8.5 × 11 inches (in portrait mode), or 11 × 8.5 inches (in landscape mode). If necessary, the PostScript plot will be rescaled to fit on the page.
It's important to note the distinction between relative and user's units. Relative units are determined by FWID and FHGT, and are arbitrary units used to specify the limits of the plotting frame. User's units are determined by XMIN, XMAX, YMIN, and YMAX, the starting and ending values for the x- and y-axes. These parameters are described briefly below in the Axes section, and in greater detail in the section describing the namelist AXES input. Some of the input parameters may be specified in either user's or relative units.
Normally, the plot will be centered both horizontally and vertically within the plotting frame. The exact location may be specified, however, using the input parameters XORGN and YORGN.
Plots may be created with or without axes, as specified by the input flags IXAXIS and IYAXIS. For plots with axes, these flags also control whether tick marks or grid lines are drawn. Logarithmic axes may be specified by the flags ILOGX and ILOGY.
The axis limits may be specified by the user using the input parameters XMIN, XMAX, YMIN, and YMAX. These limits may also be computed automatically for either or both axes, as determined by the flag ISCALE. The input parameters XLEN and YLEN specify the actual lengths of the x- and y-axes in relative units. Note that even if a plot is being created without axes, all of these values are still used by plotc to transform user's units into relative units.
The number of intervals on each axis (i.e., one less than the number of tick marks or grid lines) is given by the parameters NINTX and NINTY. Numeric labels are normally placed at each tick mark or grid line. This may be overridden by specifying the number of labels using the parameters NLABX and NLABY.
The axes and plot titles are specified by the variables XTITLE, YTITLE, and PTITLE. These may specified as part of the plotc input, or supplied by subroutine COORS.
By default, the x- and y-axes will intersect at the point (XMIN,YMIN). The intersection point may be changed using the parameters XORGU and YORGU. The input flag IFRAME may be used to put a box around the plot by drawing horizontal lines at YMIN and YMAX, and vertical lines at XMIN and XMAX, with or without tick marks. [The name of this input parameter, IFRAME, was a poor choice. It has nothing to do with the size of the plotting frame.]
Text strings are used in several places when creating a plot. They may be written at user-specified locations on the plot, as described in the next section. A legend table may also be created. Text strings are also used when writing the axis and plot titles, and the numeric axis labels.
The flag ITITLE controls whether or not titles should be written for the axes and for the plot itself. For the plot title, ITITLE also controls whether it is placed at the top of the plot or the frame. Normally the plot title is left-aligned, and the axis titles are centered. This may be changed using the input character array TALIGN.
For the PostScript version of the plot, a variety of fonts may be used for any of the text strings, as specified by the input character array FONTS. The character size for titles and axis labels may be specified using the parameters ISIZET and ISIZEL. In the OpenGL version of the plot, the fonts used currently may not be modified by the user.
In the PostScript plot, special characters (various symbols, Greek letters, etc.), subscripts, and superscripts may be used in text strings. Special characters are included using the notation \nnn, where nnn is the three-digit octal code for the character. Note that a backslash is used, not an ordinary slash. For all fonts except Symbol, nnn is the same as the PostScript octal code for the symbol. For the Symbol font, nnn is the PostScript octal code + 400. The values of nnn for all the characters in the standard fonts and Symbol font are shown in separate tables. These tables were modeled after those in Appendix A of the PostScript Language Reference Manual [Adobe Systems, Inc. (1985)].
Subscripts are included in text strings using the notation \sub[whatever-you-want]. Superscripts are done the same way, but with \sup instead of \sub. For example, "Re\sub[\561]" will appear as Reθ.
You can also change fonts in the middle of a text string. See the section on Text String Characteristics for a listing of the available fonts. For fonts with one-character names, like Helvetica or Italic, use the notation \ftx, where x is the one-letter symbol for the font. For fonts with two-character names, like Helvetica Oblique, use the notation \ft(xx, where xx is the two-letter symbol for the font. This is useful for displaying mathematical variables in an italic or oblique font, as is normally done in technical literature, when the rest of the string is in some other font. For instance, the string "\ftHReynolds Number, \ft(HORe" will appear as Reynolds Number, Re.
As noted earlier, all these special symbols, etc., only work for the PostScript version of the plot. In the OpenGL version of the plot, text strings will appear strictly as specified by the user, with all the ugly \'s.
The "Running the Code" section includes an example using some of these features.
Up to 50 text strings may be written at arbitrary locations on the plot. The maximum number of characters allowed in each string, including those used to specify special characters, subscripts, etc., is 100. The text strings are specified by the input character array ASTR, and their locations by the arrays XSTR and YSTR. The locations may be specified in either relative or user's units, as determined by the input flag NSTR. Each string may be left-aligned, centered, or right-aligned at the specified locations, as determined by the input character array SALIGN. The character size for each string is set using the array ISIZES.
Normally, the area of the plot in which the strings are to appear is masked out before the strings are written. Material behind the strings, such as curves, axes, grid lines, etc., will thus be hidden. This behavior may be changed using the flag IMASK(2).
A two-column legend table may be included on the plot. [A more general legend, with more than two columns, may also be created, as described in the section on the Legend Table in the namelist PTYPE section.] The first column will show each distinct line style and symbol used on the plot, with the lines shown first, followed by the symbols. The second column will consist of user-specified text strings describing the significance of each line style and/or symbol. These text strings are specified by the input character array ALEG. A header may also be written above each column. Its contents are specified by the input character array HDLEG. The character size for the text strings in the legend is set using the parameter ISIZEG.
The location of the legend is specified by the input parameters XLEG and YLEG. The flag ILEGND is used to specify that a legend is to be included, and to determine whether its location is being specified in relative or user's units. A box may be drawn outlining the legend table, as specified by the input flag ILEGBX.
Normally, the area of the plot in which the legend is to appear is masked out before the legend is written. Material behind the legend, such as curves, axes, grid lines, etc., will thus be hidden. This behavior may be changed using the flag IMASK(3).
Colors may be specified independently for any element of the plot - individual curves and/or symbol sets, axes, grid lines, titles, labels, etc. Some colors (BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, and WHITE) may be specified by name using an input character variable. Other colors may be used by specifying the RGB triplet defining the color. In the RGB triplet, each of the values must be in the range 0.0-1.0, where 0.0 represents no contribution of the color, and 1.0 represents maximum intensity of the color. E.g., setting the RGB values to 1.0, 0.0, 0.0, results in red, and 1.0, 0.0, 1.0, results in magenta. The colors resulting from various combinations of RGB values, in 0.1 increments, are shown in separate tables.
Last updated 2 Nov 2005