















                                       PPL+

                     PLOTPLUS PLUS: ENHANCEMENTS TO PLOTPLUS




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


                                  Jerry Davison
                                  NOAA/PMEL/TMAP

                                    April 1994
 I. 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 years
 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 appendix II
 for information on using gksm2ps.


 II. ENHANCED COMMANDS DESCRIPTION

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.

 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
 cancelled; specification of the endpoints may be omitted when cancelling
 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.


CLSPLT

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


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 appendix I 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).

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 conjuction 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 interpolator 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 (aka draftsman style). 
 At this time the magnitude of the non-zero value has no bearing on the
 plot.  The default is zero.


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.


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 appendix I 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)


 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.
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 appendix I 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.


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'.


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 appendix II for information on
 that.
 

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.


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.

 do_key If 0 the key will not be displayed; if 1 the key will be displayed.  Default
 is 1.

 orient If 0 the key is horizontal (by default on top of the figure); if 1 the key is
 vertical (by default on the right).  Default value is 0.
 
 klab_siz If non-zero, klab_siz is the height of key label characters in inches.  If 0,
 SHADE selects a reasonable height; default is 0.
    
 klab_inc If non-zero every klab_inc key level is labelled; if 0, SHADE selects a
 suitable value.  Default value is 0.

 klab_dig is the number of significant digits (klab_dig > 0) or decimal places
 (klab_dig < 0) in the key.  Default is 3.

 klab_len is the maximum number of characters in a key label.  Default is 9. 

 kx_lo X-coordinate of the left side of the key, in inches.

 kx_hi X-coordinate of the right side.

 ky_lo Y-coordinate of the bottom of the key, in inches.

 ky_hi Y-coordinate of the top.

 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 labelled.  Labels will contain 4 significant digits
 to a maximum of 8 digits.  The entire key will occupy a rectangle from (9.4,1.4) to (10.2,7.4) in
 inches. 


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 I: 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 PostsScript 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 (see appendix II) 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      dashed-dotted
 17    3   5, cyan      long dashed
 18    3   6, magenta   dashed and double-dotted 

 19    1   0, white     solid

                        APPENDIX II: 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 GKSM 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 opion
 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.


