Keyword and Named Color Parameters

Three categories of parameters described in this appendix:

Using These Parameters

Visual Numerics has provided, for your convenience, a set of JWAVE wrapper functions for use in graphics applications. These wrapper functions can be called from a JWAVE Java client application to generate most of the types of plots that are available in PV-WAVE. These JWAVE wrappers include:

JWAVE_BAR3D Function Produces a 3D bar chart.
JWAVE_CONTOUR Function Produces a contour plot.
JWAVE_HISTOGRAM Function Produces a histogram plot.
JWAVE_PIE Function Produces a pie chart.
JWAVE_PLOT Function Produces 2D plots.
JWAVE_SURFACE Function Produces surface plots.

They are described in

Appendix B, JWAVE Convenience Wrappers

This appendix describes the parameters that you can set in the Java client application for use by these JWAVE wrapper functions. In the Java client application, you set these parameters using methods such as:

JWaveExecute.setParam
JWaveView.setNamedColor
JwaveView.setNamedColorSet

For example, the following method sets a color parameter called Background in the Java client application:

myJWaveView.setNamedColor("BACKGROUND", Java.awt.Color.yellow)

Then, in the JWAVE wrapper function, this color is retrieved with:

back = GET_NAMED_COLOR("BACKGROUND", Default='000000'xL)

The Background parameter is commonly used to set the background color for plots. It is described on

Keyword Parameters

NOTE: Named Color Parameters are listed on page C-18. Named ColorSet Parameters are listed on page C-19.

Ax

Specifies the angle of rotation about the x-axis, in degrees, towards the viewer. The default is +30 degrees.

The surface represented by the 2D array is first rotated, Az (see the Az keyword) degrees about the z-axis, then by Ax degrees about the x-axis, tilting the surface towards the viewer (Ax 0), or away from the viewer.

NOTE: This keyword is effective only if the PV-WAVE !P.T3d system variable is not set. If !P.T3d is set, the 3D to 2D transformation used by is contained in the 4-by-4 array !P.T. Refer to the PV-WAVE Reference for information on system variables.

Az

Specifies the counterclockwise angle in degrees of rotation about the z-axis (when looking down the z-axis toward the origin). The order of rotation is Az first, then Ax.

NOTE: This keyword is effective only if the PV-WAVE system variable !P.T3d is not set. Refer to the PV-WAVE Reference for information on system variables.

Box

Places a box around the labels in a Date/Time axis. If you set the keyword to a value of 1, boxes are drawn around all the labels of the Date/Time axis.

By default, no boxes are drawn. For information on Date/Time axes, refer to the PV-WAVE User's Guide.

C_Annotation

Sets the label that will be drawn on each contour.

Usually, contours are labeled with their value. This parameter, an array of strings, allows any text to be specified. The first label is used for the first contour drawn, and so forth. If Levels is specified, the elements of C_Annotation correspond directly to the levels specified, otherwise, they correspond to the default levels chosen by the PV-WAVE CONTOUR procedure. If there are more contour levels than elements in C_Annotation, the remaining levels are labeled with their values.

Use of C_Annotation implies use of the Follow keyword.

C_Charsize

Sets the size of the characters used to annotate contour labels.

Normally, contour labels are drawn at three-fourths the size used for the axis labels (specified by the Charsize keyword or the !P.Charsize system variable in PV-WAVE). This keyword allows the contour label size to be specified independently. Use of this keyword implies use of the Follow keyword.

Charsize

Sets the overall character size for the annotation. A Charsize of 1.0 is normal. The size of the annotation on the axes may be set, relative to Charsize, with XCharsize, YCharsize, and ZCharsize. The main title is written with a character size of 1.25 times this parameter.

Charthick

Sets the thickness of characters drawn with the software fonts. Normal thickness is 1.0, double thickness is 2.0, and so on. (If this keyword is omitted, the value of the PV-WAVE system variable !P.Charthick is used.)

C_Labels

Specifies which contour levels should be labeled. By default, every other contour level is labeled.

C_Labels allows you to override this default and explicitly specify the levels to label. This parameter is an array, converted to integer type if necessary. If the Levels keyword is specified, the elements of C_Labels correspond directly to the levels specified, otherwise, they correspond to the default levels chosen by the PV-WAVE CONTOUR procedure. Setting an element of the array to zero causes that contour level to not be labeled. A nonzero value forces labeling.

Use of this keyword implies use of the Follow keyword.

C_Linestyle

Specifies the linestyle used to draw each contour.

As with C_Colors, C_Linestyle is an array of linestyle indices. If there are more contour levels than linestyles, the linestyles are cyclically repeated. The following table lists the available linestyles and their keyword indices:


Index	X Windows Style	Windows Style
0	Solid	Solid
1	Dotted	Short dashes
2	Dashed	Long dashes
3	Dash dot	Long-short dashes
4	Dash-dot-dot-dot	Long-short-short dashes
5	Long dashes	Long dashes

NOTE: The current contouring algorithm draws all the contours in each cell, rather than following contours. Hence, some of the more complicated linestyles will not be suitable for some applications.

Clip

JWAVE_HISTOGRAM

Specifies the coordinates of a rectangle used to clip the graphics output. Graphics that fall inside the rectangle are displayed; graphics that fall outside the clipping rectangle are not displayed.

The rectangle is specified as an array of the form [X₀, Y₀, X₁, Y₁], giving data coordinates of the lower-left and upper-right corners, respectively.

C_Thick

Specifies the line thickness of lines used to draw each contour level. As with C_Colors, C_Thick is an array of line thickness values, although the values are floating-point. If there are more contours than thickness elements, elements are repeated. If omitted, the overall line thickness specified by the Thick keyword parameter or the PV-WAVE system variable !P.Thick is used for all contours.

Follow

If set to a nonzero value, forces the PV-WAVE CONTOUR procedure to use the line-following method instead of the cell-drawing method.

CONTOUR can draw contours using one of two different methods:

The cell-drawing method, used by default, examines each array cell and draws all contours emanating from that cell before proceeding to the next cell. This method is efficient in terms of computer resources but does not allow contour labeling.
The line-following method searches for each contour line and then follows the line until it reaches a boundary or closes. This method gives better looking results with dashed linestyles, and allows contour labeling, but requires more computer time. It is used if any of the following keywords is specified: C_Annotation, C_Charsize, C_Labels, Follow, or Path_Filename.

Although these two methods both draw correct contour maps, differences in their algorithms can cause small differences in the resulting plot.

Font

An integer that specifies the graphics text font index.

Font index -1 selects the software fonts, which are drawn using vectors.
Font number 0 selects the hardware font of the output device.

NOTE: Hardware font drivers that support 3D transformations include X Windows, WIN32 (on Windows NT platforms only), PostScript, and WMF (on Windows NT platforms only).

Gridstyle

Lets you change the linestyle of tick intervals.

The default is a solid line. Other linestyle choices and their index values are listed in the following table:


Index	X Windows Style	Windows Style
0	Solid (default)	Solid (default)
1	Dotted	Short dashes
2	Dashed	Long dashes
3	Dash dot	Long-short dashes
4	Dash-dot-dot-dot	Long-short-short dashes
5	Long dashes	Long dashes

One possible use for this keyword is to create an evenly spaced grid consisting of dashed lines across your plot region. To do this, first set the Ticklen keyword to 0.5. This ensures that the dashed tick style will appear correctly on your plot. Then set the Gridstyle keyword to the style you want to use.

Levels

Specifies an array containing the contour levels (maximum of 150) drawn by the PV-WAVE CONTOUR procedure.

A contour is drawn for each level specified in Levels. If Levels is omitted, the data range is divided into approximately six equally-spaced levels.

Linestyle

Specifies the linestyle used to draw the lines or connect data points.

UNIX Users: The line join style is "miter," that is, the outer edges of two lines extend to meet at an angle.

Windows Users: The line join style is "round."

The linestyle index is an integer, as shown in the following table:


Index	X Windows Style	Windows Style
0	Solid	Solid
1	Dotted	Short dashes
2	Dashed	Long dashes
3	Dash dot	Long-short dashes
4	Dash-dot-dot-dot	Long-short-short dashes
5	Long dashes	Long dashes

Sets the maximum number of levels on a Date/Time axis. For example, assume that the Date/Time data contains years, months, days, hours, minutes, and seconds. If this keyword is set to three, then the Date/Time axis will show three levels: seconds, minutes, and hours.

Max_Value

Data points with values equal to or above this value are ignored when contouring. Cells containing one or more corners with values above Max_Value will have no contours drawn through them.

NLevels

The number of equally-spaced contour levels that are produced by CONTOUR. The maximum is 150. (Default: 6)

If the Levels parameter, which explicitly specifies the value of the contour levels, is present this keyword has no effect. If neither parameter is present approximately six levels are drawn.

If the minimum and maximum Z values are Z_min and Z_max, then the value of the ith level is:

Z_min + (i + 1)(Z_max - Z_min)/(NLevels + 1)

where i ranges from 0 to NLevels - 1.

Noclip

Enforces the default clipping behavior, which is to clip graphics at the boundary of the Plot Data Region (area bounded by the coordinate axes).

Nodata

JWAVE_HISTOGRAM

If this keyword is set to a nonzero value, only the axes, titles, and annotation are drawn. No data points are plotted.

Noerase

JWAVE_HISTOGRAM

If set to a nonzero value, specifies that the screen or page is not to be erased. By default the screen is erased, or a new page is begun, before a plot is produced.

Nsum

Indicates the number of data points to average when plotting.

If Nsum is larger than 1, every group of Nsum points is averaged to produce one plotted point. If there are m data points, then m / Nsum points are displayed. On logarithmic axes a geometric average is performed.

It is convenient to use Nsum when there is an extremely large number of data points to plot because it plots fewer points, the graph is less cluttered, and it is quicker.

Polar

Polar plots are produced when this keyword is set to a nonzero value.

The X and Y parameters, both of which must be present, are first converted from polar to cartesian coordinates. The first parameter is the radius, and the second is , expressed in radians.

Position

JWAVE_HISTOGRAM

Allows direct specification of the plot window.

Position is a four-element array giving, in order, the coordinates[(x₀, y₀), (x₁, y₁)] of the lower-left and upper-right corners of the data window. Coordinates are expressed in normalized units ranging from 0.0 to 1.0.

When setting the position of the window, be sure to allow space for the annotation, which resides outside the window. PV-WAVE outputs the message

%, Warning: Plot truncated.

if the plot region is larger than the screen or page size. The plot region is the rectangle enclosing the plot window and the annotation.

When plotting in three dimensions, the Position keyword is a six-element array with the first four elements describing, as above, the XY position, and with the last two elements giving the minimum and maximum z-coordinates. The Z specification is always in normalized coordinate units.

Psym

Specifies the symbol used to mark each data point.


!P.Psym Value	Symbol Drawn
0	No symbol, connect points with solid lines
1	Plus sign
2	Asterisk
3	Period
4	Diamond
5	Triangle
6	Square
7	X
8	User-defined, see the USERSYM procedure
9	Undefined
10	Data points are plotted in the histogram mode. Horizontal and vertical lines connect the plotted points, as opposed to the normal method of connecting points with straight lines.
-value	Negative values connect symbols with solid lines

Normally, Psym is 0, data points are connected by lines, and no symbols are drawn to mark the points. Specify this keyword to mark data points with symbols. The keyword Symsize is used to set the size of the symbols.

Negative values of Psym cause the symbol designated by |Psym| to be plotted at each point with solid lines connecting the symbols. For example, a Psym value of -5 plots triangles at each data point and connects the points with lines.

The Psym keyword can specify an array of plot symbols. If an array is used, each plot symbol value in the array is applied, in order, to create the plot symbols that make up the graph. The symbols are repeated, as needed, to complete the entire graph of the data set.

NOTE: Forty-one new graphic symbols have been added for PV-WAVE plot routines. These new symbols include:

Psym=11...Psym=41

(Psym=10 is reserved)

See also Solid_Psym.

Skirt

A skirt around the array at a given z value is drawn if this keyword parameter is nonzero. The z value is expressed in data units.

If the skirt is drawn, each point on the four edges of the surface is connected to a point on the skirt which has the given z value, and the same x and y values as the edge point. In addition, each point on the skirt is connected to its neighbor.

Solid_Psym

If this parameter is set to a nonzero value, symbols are drawn with solid lines no matter which linestyle is used to connect the symbols. By default, symbols are drawn with the currently specified linestyle.

Spline

If this parameter is set to a nonzero value, specifies that contour paths are to be interpolated using cubic splines.

Use of this keyword implies the use of the Follow keyword. The appearance of contour plots of arrays with low resolution may be improved by using spline interpolation. In rare cases, contour lines that are close together may cross because of interpolation.

Splines are especially useful with small data sets (less than 15 array dimensions). With larger data sets the smoothing is not as noticeable and the expense of splines increases rapidly with the number of data points.

You may specify the length of each interpolated line segment in normalized coordinates by including a value with this keyword. The default value is 0.005 which is obtained when the parameter Spline is present. Smaller values for this parameter yield smoother lines, up to the resolution of the output device, at the expense of more computations.

Subtitle

Produces a subtitle underneath the x-axis containing the text in this string parameter.

Symsize

Specifies the size of the symbols drawn when Psym is set. The default size of 1.0 produces symbols approximately the same size as a character.

The Symsize keyword can specify an array of symbol sizes. If an array is used, each plot symbol size in the array is applied, in order, to size the plot symbols that make up the graph. The symbol sizes are repeated, as needed, to complete the entire graph of the data set.

Thick

JWAVE_HISTOGRAM

Controls the thickness of the lines connecting points. A thickness of 1.0 is normal, 2.0 is double-wide, etc.

Tickformat

Lets you use FORTRAN-style format specifiers to change the format of tick labels on the x-, y-, and z-axes.

The resulting plot's tick labels are formatted with a total width of five characters carried to two decimal places. As expected, the width field expands automatically to accommodate larger values.

Note that only the I (integer), F (floating-point), and E (scientific notation) format specifiers can be used with Tickformat. Also, you cannot place a quoted string inside a tick format. For example, ("", F5.2, "") is an invalid Tickformat specification.

See also [XYZ]Tickformat.

Ticklen

Controls the length of the axis tick marks, expressed as a fraction of the window size. The default value is 0.02. Ticklen of 0.5 produces a grid, while a negative Ticklen makes tick marks that extend outside the plot region, rather than inwards.

Title

JWAVE_HISTOGRAM

Sets a string used for the main title centered above the plot window.

The text size of this main title is larger than the other text by a factor of 1.25.

XCharsize, YCharsize, ZCharsize

The size of the characters used to annotate the x-, y-, and z-axes and their titles.

This field is a scale factor applied to the global scale factor set by the PV-WAVE system variable !P.Charsize or the keyword Charsize.

See also Charsize.

XGridstyle, YGridstyle, ZGridstyle

Lets you change the linestyle of tick intervals on the x-, y-, and z-axes.

The default is a solid line.


Index	X Windows Style	Windows Style
0	Solid (default)	Solid (default)
1	Dotted	Short dashes
2	Dashed	Long dashes
3	Dash dot	Long-short dashes
4	Dash-dot-dot-dot	Long-short-short dashes
5	Long dashes	Long dashes

See also Gridstyle.

XMargin, YMargin, ZMargin

A two-element array specifying the margin around the sides of the plot window, in units of character size. Default margins are 10 (left margin) and 3 (right margin) for the x-axis, 4 (bottom margin) and 2 (top margin) for the y-axis. For the z-axis the default margins are both 0.

XMinor, YMinor, ZMinor

The number of minor tick intervals on the x-, y-, and z-axes. If set to 0, the default, PV-WAVE automatically determines the number of minor ticks in each major tick mark interval. Setting this parameter to -1 suppresses the minor ticks, and setting it to a positive, nonzero number n produces n minor tick intervals, and n - 1 minor tick marks.

XRange, YRange, ZRange

JWAVE_HISTOGRAM

The desired data range of the x-, y-, and z-axes, a two-element array. The first element is the axis minimum, and the second is the maximum. PV-WAVE will frequently round this range.

XStyle, YStyle, ZStyle

JWAVE_HISTOGRAM

Allows specification of axis options such as rounding of tick values and selection of a box axis. Each option is encoded in a bit. See the following table for details:

Axis Options
Bit	Value	Function
0	1	Exact. By default the end points of the axis are rounded in order to obtain even tick increments. Setting this bit inhibits rounding, making the axis fit the data range exactly.
1	2	Extend. If this bit is set, the axes are extended by 5% in each direction, leaving a border around the data.
2	4	None. If this bit is set, the axis and its text is not drawn.
3	8	No box. Normally, JWAVE_PLOT and JWAVE_CONTOUR draw a box style axis with the data window surrounded by axes. Setting this bit inhibits drawing the top or right axis.
4	16	Inhibits setting the y-axis minimum value to zero, when the data are all positive and nonzero. The keyword YNozero sets this bit temporarily.

NOTE: The ZStyle keyword has no effect in Date/Time plots.

XTickformat, YTickformat, ZTickformat

Lets you use FORTRAN-style format specifiers to change the format of tick labels for the x-, y-, and z-axes.

This keyword works basically the same way as the Tickformat keyword.

See also Tickformat.

XTicklen, YTicklen, ZTicklen

JWAVE_HISTOGRAM

Functions the same as the keyword Ticklen. [XYZ]Ticklen, however, can be applied to the x-, y-, and z-axes. [XYZ]Ticklen supersedes the value of the Ticklen setting.

XTickname, YTickname, ZTickname

A string array, of up to 30 elements, containing the annotation of each major tick mark.

If omitted, or if a given string element that contains the null string, PV-WAVE labels the tick mark with its value. To suppress the tick label, supply a string array of one-character-long blank strings. You can do this with the command:

REPLICATE(' ', N)

(Null strings cause PV-WAVE to number the tick mark with its value.) Note that if there are n tick mark intervals, there are n + 1 tick marks and labels.

XTicks, YTicks, ZTicks

The number of major tick intervals to draw for the x-, y-, and z-axes. If omitted PV-WAVE will select from three to six tick intervals. Setting this field to n, where n 0, produces exactly n tick intervals, and n + 1 tick marks.

XTickv, YTickv, ZTickv

The data values for each tick mark, an array of up to 30 elements.

This keyword allows you to directly specify tick data values, producing graphs with non-linear tick marks. PV-WAVE scales the axis from the first tick value to the last, unless you directly specify a range. If you specify n tick intervals, you must specify n + 1 tick values.

XTitle, YTitle, ZTitle

JWAVE_HISTOGRAM

Specifies a string to be used as a title below the x-, y-, and z-axes.

See also Title

XType, YType, ZType

JWAVE_HISTOGRAM

Specifies a linear axis if zero; specifies a logarithmic axis if one; and if set to 2, enables compressed Julian numbers to be used directly with the graphics procedures.

NOTE: YType has no effect in Date/Time plots.

YNozero

Inhibits setting the minimum y-axis value to zero when the y data are all positive and nonzero, and no explicit minimum y value is specified (using Yrange).

By default, the y-axis spans the range of 0 to the maximum value of y, in the case of positive y data.

ZAxis

Specifies the placement of the z-axis.

By default, the z-axis is drawn at the upper-left corner of the axis box. To suppress the z-axis, use ZAxis = -1 in the call. The position of the z-axis is determined from ZAxis as follows:

1 = lower-right, 2 = lower-left, 3 = upper-left, and 4 = upper-right.

Named Color Parameters

NOTE: Keyword Parameters are listed on page C-2. Named ColorSet Parameters are listed on page C-19.

Axis

Specifies an AWT color object used to draw the axis. (Default: Color.white)

Background

JWAVE_HISTOGRAM

Specifies an AWT color object to which the screen is set when the ERASE procedure is called. (Default: Color.black)

NOTE: Not all devices support erasing the background to a color index.

Bottom

Specifies an AWT color object used to draw the lower part of the surface. If not specified, the bottom is drawn with the same color as the top (the top is specified with the Color keyword).

NOTE: If the x-axis rotation is between 90 and 270 degrees, the top of the surface will be colored with the color specified by the Bottom keyword.

Color

JWAVE_HISTOGRAM

Specifies an AWT color object to set the color of text, lines, solid polygon fill, data, axes, and annotation. (Default: Color.white)

Named ColorSet Parameters

NOTE: Keyword Parameters are listed on page C-2. Named Color Parameters are listed on page C-18.

C_Colors

An array of AWT color objects used to set the color used to draw each contour.

If there are more contour levels than elements in C_Colors, the elements of the color array are cyclically repeated.

ColumnColors

An array of AWT color objects specifying the color for each column of bars. Must have the same number of colors as the second dimension of Z. Only one of RowColors or ColumnColors may be used.

Fill_Colors

Color_Index If present, specifies an array of AWT Color objects to be used in the contour plot. Element i of this array contains the color of contour level number i - 1. Element 0 contains the background color. There must be one more color than there are number of contour levels. This keyword is only valid of the Filled keyword is set.

RowColors

An array of AWT color objects specifying the color for each row of bars. Must have the same number of colors as the first dimension of Z. Only one of RowColors or ColumnColors may be used.

Copyright © 1999, Visual Numerics, Inc. All rights reserved.