Appendix C Sec2
ENHANCED COMMANDS DESCRIPTION
Appendix C Sec2.1
ALINE/qualifier line#, minx, miny, maxx, maxy, set
Draw a line on a plot
NOTE: THE ALINE COMMAND IS DEPRECATED AND IS NO LONGER SUPPORTED. Instead we recommend that you use a PLOT command, such as this one.
yes? PLOT/VS/OVER/LINE/NOLAB {minx,maxx}, {miny,maxy}
! where the x and y values are in world coordinates - relative to the range
! labeled along the plot axes
! PLOT qualifiers give you control over line color, thickness, and so on.
! e.g. if the plot is a longitude/latitude plot, this would draw a line
! from lon=300,lat=20 to lon=320,lat=41
yes? PLOT/VS/OVER/NOLAB/LINE/COLOR=red {300,320}, {20,41}
! To draw outside the plot box, define these coordinates so they would lie, in
! WORLD COORDINATE units, outside of the plot axes. Also issue a PPL WINDOW OFF
! command first using PLOT/SET, so that Ferret can draw outside of the window.
yes? PLOT/VS/OVER/NOLAB/LINE/COLOR=blue/THICK/SET {30,60}, {-110,-110}
yes? PPL WINDOW,OFF
yes? PPL PLOT/OVER
! Once a plot has been drawn on the page, symbols such as ($ppl$xmin), ($ppl$xmax) have
! been set. These will be helpful for finding the right values to use.
! Or use variables to define the locations, say to draw some lines marking a tropical region
yes? LET xx = x[gx=var]
yes? LET x1 = `xx[x=@min]`
yes? LET x2 = `xx[x=@max]`
yes? LET y1 = -23
yes? LET y2 = 23
yes? FILL var
yes? PLOT/VS/OVER/LINE/COLOR=black/NOLAB {`x1`, `x2`}, {`y1`,`y1`}
yes? PLOT/VS/OVER/LINE/COLOR=black/NOLAB {`x1`, `x2`}, {`y2`,`y2`}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?"
ALINE 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,yptsIf you want the line to go outside the plot box:
yes? PLOT/VS/OVER/SET.... yes? PPL window,off yes? PPL plot/over
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. (Note that the qualifiers /USER and /NOUSER applied to ALINE, not to PLOT/VS)
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
Note that some of the parameters can be set on the Ferret CONTOUR command with qualifiers. CONTOUR/SIZE, CONTOUR/SIGDIG, and CONTOUR/SPACING are alternative implementations of the PPL CONSET command and have exactly the same effect as issuing PPL CONSET. See the CONTOUR section of Chapter 6 for a description of the CONTOUR qualifiers.
Arguments:
hgt height of contour labels (default=.08 inches) (or use CONTOUR/SIZE=)
nsig no. of significant digits in contour label (default=2) (or use CONTOUR/SIGDIG=)
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). For fine grids, the labels may not show up. Try specifying smaller values for dslab. (or use CONTOUR/SPACING=)
spline_tension 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 value specified for spline_tension is a real number 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 enables the user to specify either horizontally oriented contour labels (draftsman style) or the default, contour labels running along contour lines. The value specifed for draftsman is to be a real number 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 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
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" 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
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_h, annotate
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.
note that starting with Ferret v6.93, the color plot commands have a new key option, /KEY=HORIZONTAL which places the color key immediately above the plot. This is equivalent to specifying PPL SHAKEY,1,0
- 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 1. To locate thekey on the left or bottom, or anywhere else on the page, use the last four arguments to SHAKEY; kx_lo, kx_hi, ky_lo, ky_hi.
- 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. By default the labels are on the right side of a vertical colorbar key and above a horizontal key. To put the labels to the left of a vertical colorbar, send a negative value for klab_size , e.g. -0.1 for labels of size 0.1 on the left of the colorbar. To put labels below a horizontal colorbar, give a positive klab_siz; and to put labels above, use a positive value.
- klab_inc If non-zero every klab_inc key level is labeled; if 0, SHADE selects a suitable value. If klab_inc < 0, then no labels are made. 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. (Prior to V5.53 of Ferret, to change any of kx_lo, kx_hi, ky_lo, ky_hi, you needed to set all four of them.)
- 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.
- annotate =1 to label the ends of the key with the minimum and maximum of the data field
Examples:
PPL 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.
PPL SHAKEY 1,,,,,,,,,,1
Puts the data minimum and maximum at each end of the key. This setting persists jn the session until it is turned off with a 0 as that last argument. The Ferret alias KEYMARK is defined as "PPL SHAKEY 1,,,,,,,,,," and so issuing the commands
KEYMARK 1 ! turns on key annotation, until it is explicitly turned off.
KEYMARK 0 ! turns it off.
Appendix C Sec2.13
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.