Appendix C: PLOTPLUS PLUS: Ferret Enhancements to PLOTPLUS 

    A User's Guide to the TMAP Modifications of the Plotplus Graphics Package 

Jerry Davison 

NOAA/PMEL/TMAP 

April 1994 

Note: this document also exists at
http://ferret.pmel.noaa.gov/FERRET_17sep07/Documentation/PPLUS_Users_Guide/pplus_enhance_user_guide.html 

It is included here with changes only to the formatting. Appendices 1 and 2 of the original document are renumbered here as sections 3 and 4. Note that section 4, which describes generating postscript plots with gksm2ps is duplicated in the main Ferret Users Guide in the section "Metafile Translation" (p.262 ) . 


Appendix C Sec1  PLOTPLUS HISTORY, EVOLUTION 

Plotplus is a scientific graphics package with a long history. I have traced it only a small distance, and what I know is sketchy. My present understanding is that a number of users at the Oregon State University department of Oceanography contributed over a number of year to a graphics package with both original and pre-existing algorithms and code; PLOT1, PLOT2,  PLOT3 and PLOT4 successively became the current standard. Don Denbo took a strong interest in improving the package; from his work evolved PLOT5. He came to PMEL, improved PLOT5 further, and Plotplus was born. While here he made modifications for the TMAP group to that code to support the Graphics Kernel System, GKS, an international standard for programming computer graphics applications. This user's guide describes  modifications I made to Plotplus to extend the use of GKS within it; this version will no doubt evolve as well. 

The guide addresses itself only to the TMAP modifications to Plotplus. The Plotplus manual describes all other aspects of the current version as supported by its author and should be consulted for information about using Plotplus. 

The TMAP GKS enhancements of Plotplus include modification and addition of  several PPL commands, including: 

ALINE,
CLSPLT,
COLOR,
CONSET,
FILL,
LINE,
LIST,
PEN,
PLTNME,
PLTYPE,
SHADE,
SHAKEY,
SHASET. 

This version of PPL+ is modified to be used with the public domain GKS library XGKS. X Windows is the only supported device type. There is in addition a utility, gksm2ps, to generate monochrome and color hard copy of PPL+ plots. `gksm2ps' was written by Larry  Oolman at the University of Wyoming; I modified it for use with PPL+. Please see the Ferret Users Guide  for information on using gksm2ps. 


Appendix C Sec2  ENHANCED COMMANDS DESCRIPTION 


Appendix C Sec2.1  ALINE/qualifier line#, minx, miny, maxx, maxy, set 

Draws the line associated with the specified line number between 2 points (see PEN for more on this). Two modes are available. In immediate mode the line is drawn when the command is given. Deferred mode permits setting of several lines (with individual endpoints) to be drawn whenever the PLOT command is given. Deferred mode is included so that examples of each linetype used in a plot can be provided as part of a key. The ALINE command does not modify data in the plot buffer; lines drawn can be considered as labels. The ALINE command given with no arguments resets all set lines to OFF. 

NOTE: ALINE does not work well when the plot has a time axis, and it fails in some other circumstances. It is simpler to draw a line on a plot with a PLOT/OVERLAY command, such as 

yes? LET xpts={4,8} 

yes? LET ypts={-3,0}
yes? PLOT/VS/LINE/OVER/NOAX/NOLAB/COLOR=/THICK=/DASH=(...) xpts,ypts 

If you want the line to go outside the plot box: 

yes? PLOT/VS/OVER/SET....
yes? PPL window,off
yes? PPL plot/over 

When you have a time axis on the plot, you will need time coordinates to use in assigning point locations. Use the ideas in the FAQ "how can I overlay symbols on a plot with a time axis?" at http://ferret.pmel.noaa.gov/FERRET_17sep07/FAQ/custom_plots/time_series_symbol_overlay.html 

ALINE Arguments: 

 line# The line to be drawn will be of the type, thickness, and color associated with this line number. 

 minx X-component of the first endpoint. 

 miny Y-component of the first endpoint. 

 maxx X-component of the second endpoint. 

 maxy Y-component of the second endpoint. 

 set is optional. If omitted, execution mode is immediate. If ON, sets deferred mode for the specified line number. If OFF, drawing the line is canceled; specification of the endpoints may be omitted when canceling ALINE for a line. Execute LIST ALINE to find which lines are set, and their coordinates. 

 Valid qualifier: 

 /[NO]USER determines whether user coordinates or inches will be used in locating the line. Default is /user. 


Appendix C Sec2.2  CLSPLT 

Modified to be compatible with GKS metafile use. Closes the currently open plot file. 


Appendix C Sec2.3  COLOR n, red, green, blue 

Sets the color of a single color using the RGB color model. Specify with no arguments to reset colors 1 through 6 to their default values. These six colors are used as the line colors in line and contour plots. See "GKS line bundles"  for more on line color and bundles. 

 n color index 

 red The intensity of red, with a value from 0 to 100% 

 green The intensity of green 

 blue The intensity of blue 

In the present version of PPL+, colors of indices 0 and 1, corresponding to the plot window background and foreground, are restricted to black (intensities all 0) or white (intensities all 100). 


Appendix C Sec2.4  CONSET hgt, nsig, narc, dashln, spacln, cay, nrng, dslab, spline_tension, draftsman 

Two new parameters  have been added, spline_tension and draftsman. Spline_tension controls a spline fitting routine for contour lines and is used primarily in conjunction with the narc parameter to alter the way contour lines are drawn. The new parameter draftsman enables the user to specify either horizontally oriented contour labels (draftsman style) or the default, contour labels running along contour lines. 

 hgt height of contour labels (default=.08 inches) 

 nsig no. of significant digits in contour label (default=2) 

 narc number of line segments to use to connect contour points (default=1) 

 dashln dash length of dashes mode (default=.04 inches) 

 spacln space length of dashes mode (default=.04 inches) 

 cay is the interpolation scheme. If CAY=0.0, Laplacian interpolation is used. 

The resulting surface tends to have rather sharp peaks and dips at the data points (like a tent with poles pushed up into it). There is no chance of spurious peaks appearing. As CAY is increased, Spline interpolation predominates over the Laplacian, and the surface passes through the data points more smoothly. The possibility of  spurious peaks increases with CAY. CAY = infinity is pure Spline interpolation. An over relaxation process in used to perform the interpolation. A value of CAY=5.0 (the default) often gives a good surface. 

 nrng Any grid points farther than NRNG away from the nearest data point will be set to "undefined" [1.0E35] (default=5) 

 dslab nominal distance between labels on a contour line (default = 5.0 inches) 

 spline_tension a real value that affects the fit of the contour line. sometimes it's called the tension factor. This value indicates the curviness desired. If abs(spline_tension) is nearly zero (e.g. .01) the resulting curve is approximately a cubic spline. If abs(spline_tension) is large (e. g. 10) the resulting curve is nearly a polygonal line. If spline_tension equals zero, the resulting curve will be calculated by the original algorithm in PPL. This will result in a cubic polynomial fit. This parameter is only applied if narc is greater than 1. Otherwise, straight lines are drawn between data points and no interpolated points are contoured. A typical value for spline_tension is 1, and the typical useful range of values is .01 to 10.  The spline interpolation used in this calculation will result in erroneous plots for certain large values of spline_tension (about 20 or greater).  It is up to the user to choose an appropriate value of spline_tension to avoid this error.  No error checking is conducted in the interpolation routine for this condition because the error depends highly on the data being interpolated.  The default for spline_tension is zero, so the standard contour line fit is used unless something else is input.  NOTE: While it may seem that this feature somewhat overlaps the feature documented in the parameter cay above, this is not true. The parameter cay and the associated feature is only implemented if both the grid and data are read in directly using the RD command.  In that case, CONSET must be input  before RD.  On the other hand, when using the spline_tension feature described here, this is not needed as interpolation is carried out at the time the contour lines are drawn. 

 draftsman a real value that controls the label format. If draftsman is set to zero, the original label style is used. This style writes the labels along contour lines at varied angles. If draftsman is set to anything other than zero, all the labels will be oriented horizontally on the page (a.k.a. draftsman style). At this time the magnitude of the non-zero value has no bearing on the plot. The default is zero. 


Appendix C Sec2.5  FILL/qualifier 

 FILL is a modification of the PPL AREA command. FILL generates a "smooth-bordered" area-filled contour plot of a 2-d field. As with the SHADE command, the SHAKEY and SHASET commands can be used to control the appearance of the plot. The /[NO]WAIT and /[NO]OVERLAY qualifiers are valid, used in the same way as with PLOT, CONTOUR and SHADE. 


Appendix C Sec2.6  LINE n, mark, use 

The original PPL command has been modified. PPL+ uses GKS line bundles to specify line type, thickness, and color. A number of line bundles are defined for each device type and their characteristics depend on the capabilities of the device. See "GKS line bundles" for this information. The LINE command use argument no longer specifies the line type -- whether the line is to be dashed or solid. Specification of the use of marks remains the same. 

 n line number 

 mark data mark 

 use line/mark use specification
0 - line connecting points and no mark at points
1 - mark data points
2 - mark end points only
3 - only marks (no line) 


Appendix C Sec2.7   LIST arg 

New arguments are available to the LIST command to request information about the settings of the added features. 

 arg New arguments are ALINE, SHAKEY, and SHASET. 


Appendix C Sec2.8  PEN n, ndx 

This command has been modified with the use of GKS line bundles in PPL+. It now specifies the line bundle index associated with each line. See section "GKS line bundles" (p. 565) for the type, thickness, and color representation for each line bundle. 

 n The line number. If n is 0, sets the pen used to plot the axes and labels. 

 ndx sets the line bundle index to be used for line n. Default is 1. 


Appendix C Sec2.9  PLTNME metafile_name 

Modified to be compatible with GKS metafile use. Specifies the name to be used when a metafile is being made with each plot. The default is `metafile.plt'. 


Appendix C Sec2.10  PLTYPE icode META 

PLTYPE 3, GKS output,  currently supports only X Windows output. Hardcopy can be generated using the gksm2ps command. 

 icode must be 3 to use the new features. 

A GKS metafile with the default name `metafile.plt' (with sequential version numbers for subsequent plots) is produced with each plot when META is specified. 

After the metafile is set, if you wish to deactivate the metafile output, reenter the PLTYPE command without entering META, e.g., PLTYPE 3. To reactivate, reenter PLTYPE including the META specification, .e.g., PLTYPE 3 META. The gksm2ps command translates the metafiles and generates PostScript output from them. See the Ferret Users Guidefor information on gkem2ps. 


Appendix C Sec2.11  SHADE/qualifier 

Generates a fill area plot of a 2-d field. A rectangular grid is defined when visualizing 2-d fields in PPL; a grid cell is associated with each point. The SHADE command fills in each grid cell with a color determined by the field value at the grid points. 

 The LEV and LIMITS commands can be used, in a way identical to their use with CONTOUR, to determine the levels shaded, and specify intervals. The SHAKEY and SHASET commands also control the appearance of the plot; default colors (or patterns) and key attributes will be used if not specified. The /[NO]WAIT and /[NO]OVERLAY qualifiers are valid, used in the same way as with PLOT and CONTOUR. 


Appendix C Sec2.12  SHAKEY do_key, orient, klab_siz, klab_inc, klab_dig, klab_len, kx_lo, kx_hi, ky_lo, ky_hi 

 This command controls the attributes of the key generated by the SHADE command. The key associates the colors or patterns used in the plot with the field values; its use is optional. LIST SHAKEY will list current settings of the key. 

Example: 

SHAKEY 1, 1, 0, 3, 4, 8, 9.4, 10.2, 1.4, 7.4 

Specifies that the SHADE command draw a vertical key with label size selected automatically and every third color of the key labeled. Labels will contain 4 significant digits to a maximum of 8 digits. The entire key will occupy a rectangle from (x,y) = (9.4,1.4) to (10.2,7.4) in inches. 


Appendix C Sec2.13  SHASET 

SHASET set_pt, red, green, blue 

SHASET SAVE=spknme 

SHASET SPECTRUM=spknme 

SHASET DEFAULT 

SHASET PROTECT 

SHASET RESET 

This command sets the colors used in the plot generated by the SHADE and FILL commands, and takes several forms. By default the shaded plots use a spectrum of color from  blue to red. A user-defined selection of colors can be chosen, saved for future use, and recalled by name. 

SHASET uses the following approach in defining a spectrum. The levels set by the LEV command have lower and upper bounds; SHASET defines a scale from 0 to 100 which spans the interval defined by these bounds. With SHASET you may specify a color at any point along the scale by setting a control point on the scale, along with the red, green, and blue fractions (between 0 and 100% of maximum intensity) defining the color at that point. 

A spectrum is built up by setting colors at a number of points. The SHADE and FILL routines linearly interpolate each red, green, and blue fraction between set points to achieve a smooth transition from point to point.  

When you are interested in creating a custom spectrum to use in SHADE and FILL plots, first execute SHASET with no arguments. This clears all set points except the bottom and top of the scale; the bottom, at zero, is set to black (red, green, and blue fractions all 0% of maximum intensity). The top, at 100, is set to white (with red, green, and blue all 100%). SHASET can then be used to set any point in the scale to any color. 

set_pt defines a point in a scale, from 0 to 100, that spans the levels as set in the LEV command. Set_pt can be negative; when set negative, SHASET deletes this set point from the current spectrum, if present. RGB values need not be specified in this case. 

red The intensity of red in the color at the set point, with a value between 0 and 100%. 

green The intensity of green. 

blue The intensity of blue. 

You may save a spectrum for later use using the SAVE form of the command, where  you give the present spectrum a name. A spectrum can be recalled using the SPECTRUM form of the command. One spectrum, `rainbow', the PPL+ default spectrum, is always available for recall. 

spknme A name to be associated with a particular spectrum. The spectrum is stored in the current directory as spknme.spk, is an ASCII file, and can be edited. One spectrum may be saved in memory by omitting the spknme qualifier (specify SHASET SAVE) ; that spectrum is recalled from memory with SHASET SPECTRUM. 

The DEFAULT form will set the spectrum to the default colors associated with the workstation in use. This is not the PPL+ default but is defined for the device by GKS. 

If you plan to overlay more than one SHADE or FILL in a single plot  ,  specify SHASET PROTECT after each use of either to protect the colors already used in the plot. SHASET RESET resets the internally kept pointer protecting previously used colors, permitting their reassignment. Use the RESET option when you are ready to begin a fresh non-overlay plot. 


Appendix C Sec3  GKS LINE BUNDLES 

GKS employees the concept of line bundles, where lines may be referred to by an index; the index determines the three characteristics of plotted lines, namely, line type, thickness, and color. Line type means whether the line is solid, dotted, dashed, dashed-dotted, etc. Thickness is measured in units beginning with one; two is twice as thick as one, followed by three, three times as thick. Colors are selected using a color index; the color associated with an index can be set using the PPL+ COLOR command. 

The values of these characteristics together determine the line representation. One result of bundle use is that the same line bundle index may be defined to have different representations on different devices. 

On X Windows devices color is usually used to distinguish lines; in that case the line type is always solid. When Postscript hard copy is made from PPL+ metafiles, lines may be rendered as color, but on monochrome printers the only available color is black. Consequently, when output is to a monochrome printer, gksm2ps  uses differing line types to distinguish lines instead of color. Lines of differing thickness are available in both PPL+ X Window output and hard copy. 

The table below presents the line thickness, color index and associated default color for color devices (assuming a white background), and line type for monochrome devices, for the 19 line bundles in PPL+. On color devices, the default color of line index 1 is black if the background is white, and white if the background is black; line bundle index 19 is the  background color (the color index is 0). 

Bundle index 

Thickness 

Color 

Line type (Monochrome devices) 

       

 1 

1 

1, black 

solid 

 2 

1 

2, red 

dashed 

 3 

1 

3, green 

dotted 

4     

1 

4 , blue 

dashed-dotted 

5     

1 

5, cyan 

long dashed 

6 

1 

6, magenta 

dashed and double-dotted 

7 

2 

1, black 

solid 

8 

2 

2, red 

dashed 

9 

2 

3, green 

 dotted 

10 

2 

4, blue 

dashed-dotted 

11 

2 

5, cyan 

long dashed 

12 

2 

6, magenta 

 dashed and double-dotted 

13 

3 

1, black 

solid 

14 

3 

2, red 

dashed 

15 

3 

3, green 

dotted 

16 

3 

4, blue 

dash-dotted 

17 

3 

5, cyan 

long dashed 

18 

3 

6, magenta 

dashed and double-dotted 

19 

1 

0, white 

 

Appendix C Sec4  HARD COPY 

PostScript formatted files suitable for printing can be generated from PPL+ metafiles  using the gksm2ps command. Several command line arguments permit the tailoring of the  output. The command and its arguments are: 

               gksm2ps:Send PostScript translation of GKS metafiles to a file 

                usage:    gksm2ps [-h] [-p landscape||portrait] [-l ps||cps] [-d cps||phaser] \
                        [-X || -o <ps_output_file>] [-R] [-a] [-g WxH+X+Y] [-v] file(s) 

         -h  print this help message
        -p   page orientation, landscape or portrait (default fits to page)
        -l   line styles,  ps == monochrome (default), cps == color
        -d   device type, cps == Postscript (default), phaser == TEK phaser PS
        -X  Send output to your Xwindow for preview instead of a file
        -o   output file name (default name is 'gksm2ps_output.ps')
        -R  do not rename files with a date stamp appended (default is to stamp)
        -a  make hard copy the size of the original plot (default fits to page)
        -g  WxH+X+Y  WIDTH, HEIGHT, XOFFSET, & YOFFSET in points
        -v   list version number of gksm2ps and do nothing else   
        file(s)   The specific metafile(s) to be translated. 

   More about the arguments and their effects: 

 -h Simply print the above help message. 

 -p Specifies  the orientation of the plot on the page to be landscape (with the long side of the page horizontal), or portrait (the short side horizontal). The default fits the plot on the page in the orientaion that best fits. 

 -l  Specifies line styles that will be used in the PS output. Monochrome is the default but color may be more appropriate on color devices. 

 -d Specifies the device type. Phaser printers using transfer sheets are PostScript, but the available plotting area is reduced. The phaser option reduces the size of the plot slightly. 

 -X  This option lets you preview plots on your workstation screen. 

 -o Specifies the output file name. All metafiles translated in a single execution of the gksm2ps command are writen to a single file. 

 -R  The default renaming of the metafiles to be translated is intended to help distinguish metafiles that have been printed from those newly made. This option turns off that renaming. 

 -a  The original size of the PPL plots is captured in the metafile; use this option to create the hard copy that size. The default fits the plot to the available page size. 

 -g  Specify the hard copy plot size and offset in points  (72 points = 1 inch). 

 -v Just lists the version number. 


file(s)  Name the metafiles to be translated; separate the file names with a space. Wild card specification can be used. 


For help with Ferret see our Support Policy