NAGContour

DESCRIPTION

-- Introduction --

NAGContour generates a contour plot from a set of data values in a two-dimensional space. The points may either be on a regular grid or scattered over the domain. By default the contour lines are placed by the module. However, the user may control either the contour range and number of contour lines, or the minimum contour height and contour interval. Optionally, a pair of axes and a contour key may be drawn; a centred title at the top may be used to annotate the plot, and the data points may be displayed. Hardcopy output may be sent directly to a printer; Encapsulated PostScript (EPS) files may be generated for later processing.

NAGContour is implemented using the NAG Graphics Library. As such it uses the Adobe PostScript NAG Graphical Interface to generate hardcopy output. Color PostScript files are generated; when sent to a monochrome printer lines of different color are distinguishable through shades of grey.

-- Contouring --

An interpolating surface function f(x,y) is constructed through the set of data points (x,y,z). This function is then evaluated over an intermediate rectangular grid (known as tracking grid) and the resultant values at the nodes (intersections) of the grid are contoured using a tracking method based on [1]. The Renka and Cline interpolation method [2] is used.

The number of horizontal and vertical mesh lines in the tracking grid is dependent on the number of nodes in the x and y direction in the input lattice.

-- Default Settings --

By default the contour range is set to the range of data values present in the input lattice and the number of contour lines is set to 5. The minimum and maximum settings on the widgets "Contour", "Min Level", "Max Level", and "Interval" are such that no more than 20 contour lines can be constructed for the range of data values in the lattice.

-- Text --

A maximum string length of 255 characters is imposed on all text strings used.

All text has been implemented using the NAG Graphics Library, employing Hershey fonts or native hardware fonts. You may use all in-string keyword facilities also available to users of the NAG Graphics Library. A short description of the most important features is given in this section.

Keywords are available to support such actions as changing the current text font (perhaps to a Greek font), modifying the size and relative position of characters within the string (perhaps to draw subscripts, superscripts or mathematical expressions), etc.

Keywords may be specified as an integral part of any text string supplied to NAG Graphics [3]. Their presence will automatically be detected and the appropriate actions taken; they will not appear on the output plot. Each keyword consists of a delimiter symbol, followed by a one or two- character keyword mnemonic, which may be in upper or lower case. The keyword delimiter is an exclamation mark (`!'); As a simple example, let us take the string `E = mc!u2!N' which may be used to plot the expression E=mc**2. This string contains two keywords:

(a) Keyword !u indicates that all of the following characters up to the next delimiter should be interpreted as a superscript.

(b) Keyword !N is added to ensure that the current point is returned to the base line ready to plot any subsequent text.

The range of in-string keywords is summarised in Table 1. Where appropriate, the relative movement of the current point (up or down, in units of the current character height) and scale factor (relating to character size and spacing), are indicated.

Table 1: In-string keywords, excluding those for font changes

Mnemonic Description Movement Scale Factor ----------------------------------------------------------------

A Shift above the fraction line 1.0 1.0 B Shift below the fraction line -1.0 1.0 U Move up to superscript level 0.6 0.62 D Move down to subscript level -0.35 0.62 E Move to exponent level 0.94 0.44 I Move to index level -0.94 0.44 L Move to lower subscript level -1.125 0.62 N Move to normal or base line level 1.0

S Save current point and character size on stack R Restore previous current point and character size from stack ! Display the current symbol

Note: either upper or lower case characters may be used for the mnemonic.

In order to make effective use of the in-string keyword facility you should bear the following points in mind:

(a) The maximum number of keyword delimiters permissible in a single string is 30.

(b) The NAG Graphics Library utilises a stack to keep track of the current point and character size during the plotting of any given string. Up to 10 levels can be stored.

(c) The Hershey fonts supplied as part of the NAG Graphics Library offer a wide range of symbols, including mathematical symbols, and as such it is possible to plot quite complex formulae.

(d) Fraction lines can be plotted by selecting the Hershey Meteorological Symbol font (see Table 2) and plotting the character `X'. The length of the fraction line is determined by the number of `X's plotted.

(e) The keyword delimiter symbol can be plotted by duplicating the delimiter symbol within the input string.

(f) The `save' command can be used to temporarily set the `normal' line level for subsequent plotting. The new base line position is added to the stack until such time as a `restore' command is issued.

As well as giving you the opportunity to modify character positions and size, in-string keywords allow you to change the current font. This allows you, for example, to plot Greek characters as an integral part of your output text string.

The form of the in-string keyword used to select a specific font is the same as previously defined, except that the character mnemonic is replaced by a numeric value ranging from 1 to 25.

You have a choice of 25 different fonts; these can be accessed by issuing the mnemonics (with a preceding delimiter) detailed in Table 2. For ease of use, some fonts have been given a one-character mnemonic which can be used in place of the associated numeric value.

Table 2: In-string keywords for font changing

Mnemonic Description Mnemonic Description --------------------------------------------------------- 01 Simplex Roman 14 Cyrillic 02 Duplex Roman 15 Triplex Roman 03 Complex Roman 16 Triplex Italic 04 or g Simplex Greek 17 Map Symbols 05 Complex Greek 18 Astronomical Symbols 06 Complex Italic 19 Music Symbols 07 or m Mathematical Symbols 20 Monospace Typewriter 08 Meteorological Symbols 21 Typewriter 09 Gothic English 22 Simplex 10 or w Simplex Script 23 Italic 11 Complex Script 24 Complex 12 Gothic Italian 25 Complex Cyrillic 13 Gothic German

Note: either upper or lower case characters may be used for the mnemonics.

It may be useful to bear the following points in mind when using in-string keywords to change fonts:

(a) The leading zero may be omitted for fonts 01 through 09. However, to avoid potential ambiguity, especially if numeric values follow the supplied in-string keyword, it is recommended that the leading 0 is retained. For example, the string `!11 is a number' will be plotted as ` is a number' using font style 11, whereas `!011 is a number' will give `1 is a number' plotted using font 1.

(b) The NAG Graphics Library offers you a choice of two Greek Hershey fonts: simplex and complex. Issuing the in-string keyword mnemonic G will give you the default simplex Greek font. To select the complex font you will need to explicitly request font number 05.

References

[1] Heap, B.R., and Pink, M.G. Three Contouring Algorithms. NPL Report DNAMS1, 1969.

[2] Cline, A.K., and Renka, R.L. A Storage-Efficient Method for Consruction of a Thiessen Triangulation. Rocky Mountain J. Math., 14, pp. 119 - 139, 1984.

[3] Grandle, R.E. and Nystrom, P.A. A method for usage of a large calligraphy set under RSX-11M. Proceedings of the Digital Equipment Computer Users Society, November 1980, 391-395.

INPUTS

Port: InLat
Type: Lattice
Constraints: 1..2-D.

Height values z are extracted from a specified data channel of the input lattice, at data points (x,y). The lattice must be two-dimensional (uniform, perimeter, or curvilinear), with two data coordinates, or one-dimensional curvilinear with two data coordinates. Any data type, and number of data channels may be supplied. The points need not be on a regular grid, but may be scattered.

All values are converted to double precision before being processed by the NAG Graphics Library. The data region used for the display is derived automatically from the extreme data values in the x and y direction.

WIDGETS

Port: Annotation
Type: Radio Box
Menu Item: No Annotation
Menu Item: Annotation

If annotation is selected, a text slot will appear in which a plot title may be typed. This title will be plotted above the contour plot.

Port: Hardcopy
Type: Radio Box
Menu Item: Print
Menu Item: Save
Menu Item: Save as...
Menu Item: Set Printer Command

Hardcopy output (sent directly to a printer or generated as an EPS file for later processing) may be obtained through the selection of the menu marked "File" on the menu bar of NAGContour.

By selecting "Print" hardcopy output will be sent directly to the printer; the printout uses an intermediary PostScript file, and no permanent print files will be generated. The current print command will be used.

By selecting "Set Printer Command" you may change the printer command, for example to specify the destination printer.

By selecting "Save" a PostScript file will be generated; its default file name will be "NAGContour.ps" and it resides in the directory from which Explorer was launched.

By selecting "Save as..." you may change the file name to which any EPS files will be written (see Filename).

Port: Fonts
Type: Radio Box
Menu Item: Hardware Only
Menu Item: Hardware/Hershey
Menu Item: Hershey Only

By default, and by selecting "Hardware Only", all text will be plotted using hardware fonts. However, you may prefer to select Hershey fonts, for example if some mathematical expression is to be used in the title of the plot.

By selecting "Hardware/Hershey", all text will be plotted using hardware fonts, unless keywords are detected in the input string for the plot title, in which case all text will be plotted using Hershey fonts.

By selecting "Hershey Only", all text will be plotted using Hershey fonts.

Port: Filename
Type: File Browser

If the "Filename" option is selected from the "File" menu on the menu bar of NAGContour, then you may select the file name to which any EPS files will be written. Selection is through the Iris Explorer File Browser.

Port: Channel
Type: Slider

If more than one data channel is present in InLat, the "Channel" widget is made visible on the module control panel. It allows you to select which data channel is to be used for contouring.

Port: Contours
Type: Slider

The number of contour heights to be displayed may be set through the "Contours" widget. Between 1 and 20 contours may be selected.

Port: Contour Key
Type: Radio Box
Menu Item: No Key
Menu Item: Contour Key

All contours are labelled in principle, although the contouring routine may decide that insufficient space is available on the contour line to plot the label. As such the option exists to request a separate contour key to be drawn.

If a contour key is requested, then contours will be labelled using an index. If no contour key is requested, then contours will be labelled using the actual contour height.

Port: Key Position
Type: Option Menu
Menu Item: Dummy
Menu Item: Legend Bottom Right
Menu Item: Legend Bottom Left
Menu Item: Legend Top Right
Menu Item: Legend Top Left

The position of the contour key if present, may be set to one of the following: Top Right, Top Left, Bottom Right, or Bottom Left. Please note, that this will only have an effect on the position of the contour key on the screen. If hardcopy output is requested, then the contour key will always be drawn to the right of the contour plot.

Port: Scatter Plot
Type: Radio Box
Menu Item: No Data Points
Menu Item: Display Points

Optionally, the data points to be contoured may be displayed on the contour plot.

Port: Plot Title
Type: Text

The text to be used as the main title to be displayed at the top of the plot may be specified in the text slot marked "Plot Title".

A maximum of 256 characters may be entered in the text slot. Incorrect strings will be rejected, and an indication will be given of the nature of the error.

You are recommended to use input strings of reasonable length; if strings are too long to fit in the allocated space they will be clipped to the size of the plot.

Port: Axes
Type: Radio Box
Menu Item: No Axes
Menu Item: Axes

Optionally a pair of axes may be drawn on the left- hand side and bottom of the plot. The (numerical) annotation is generated automatically.

Port: Min Level
Type: Dial

The minimum of the range of contour heights to be drawn may be set if the contour mode is "Contour Range" or "Contour Interval". In these cases the widget will become visible on the module control panel.

Port: Max Level
Type: Dial

The maximum of the range of contour heights to be drawn may be set if the contour mode is "Contour Range". In this case the widget will become visible on the module control panel.

Port: Interval
Type: Dial

A contour interval may be specified if the contour mode is "Contour Interval". In this case the widget will become visible on the module control panel.

The minimum and maximum values displayed on the dial are such that a maximum of 20 contour heights may be drawn starting from the minimum contour height specified in "Min Level", with the maximum level .

Port: Mode
Type: Option Menu
Menu Item: Automatic Placement
Menu Item: Number Of Contours
Menu Item: Contour Interval

If "Automatic Placement" is specified, the contour range is determined by the range of heights in the input data values. The range is divided into (N-1) intervals, where N is the number of contours requested, and contours are drawn at the height represented by the mid-point of each interval.

If "Contour Range" is specified, the contour range is divided into intervals of size S=(MAX-MIN)/(N-1), where N is the number of contours requested, and MAX and MIN are the maximum and minimum values of the contour range as specified by the widget settings on "Max Level" and "Min Level", respectively. Contours are drawn from MIN to MAX at intervals of S.

If "Contour Interval" is specified, the contour range is divided into intervals of size S, where S is specified by the widget setting on "Interval". Contours are drawn from MIN at intervals of S, where MIN is the minimum contour height as specified by the widget setting on "Min Level".

Port: Set Printer Command
Type: Text

You may change the printer command from the current setting, for example to specify the destination printer.

OUTPUTS

Port: Picture
Type: Geometry

The contours generated are sent to the geometry output port "Picture".

Port: Key
Type: Geometry

The contour key (if requested) is sent to the geometry output port "Key". Geometry output will always be confined by the range (0,1) in both x and y direction, and you may wish to connect this port to the "Screen" port on the Render module, to ensure that the key does end up in the corners of the plot. (See Key Position).

PROBLEMS