Vaspackt, A Vector and Streamline Package for Triangular Meshes


David J. Kennison
NCAR, P.O. Box 3000, Boulder, Colorado 80307-3000
email: kennison@ucar.edu

Table of Contents

Note: The mnemonic "DI" appearing occasionally throughout this document stands for "Deferred Implementation" and serves as a link to an explanatory note.


INTRODUCTION

This document describes an NCAR Graphics package called VASPACKT that allows a user to construct, from data on a triangular mesh, plots showing simple vectors, curly vectors, and streamlines. VASPACKT provides a sort of tool kit of FORTRAN subroutines that can be called in various combinations to draw different kinds of plots.

This section is intended to give an overall view of VASPACKT and selected aspects of its design; it covers some details, but, in general, one should refer to the sections "SUBROUTINES" and "PARAMETERS" for detailed descriptions of subroutines and parameters mentioned. (Parameters are mentioned by name; all the names are of the form 'XXX', where XXX is a three-character mnemonic.) The section "ERROR HANDLING" describes error messages written by VASPACKT. The section "EXAMPLES" describes the examples available for VASPACKT.

It is assumed that the reader is familiar with NCAR Graphics in general and has some knowledge of the packages AREAS, EZMAP, and perhaps TDPACK.

The design of VASPACKT is similar to that of an earlier NCAR Graphics Package, called CONPACKT, which allows a user to construct, from data on a triangular mesh, plots showing simple contours and filled contour bands.


Deferred Implementation Note

A few things described in this document have not yet been implemented: In each case, the author awaits user input as to how the above features ought to work and to what degree each is useful.

To warn the user of unimplemented features, sections describing them are marked with a "DI" that serves as a link to this note.


Triangular Mesh Structure

Note: See the CONPACKT example "ctex01" (both the code and the first frame that it produces) for help in understanding the structure of a triangular mesh.

To represent a triangular mesh requires three singly-dimensioned arrays: RPNT defines points, IEDG defines edges (each of which consists of two connected points), and ITRI defines triangles (each of which consists of three connected edges). The elements of each array form "nodes" having nominal lengths as follows:

      PARAMETER (LOPN=6)  !  length of a point node
      PARAMETER (LOEN=4)  !  length of an edge node
      PARAMETER (LOTN=5)  !  length of a triangle node
    
(In some cases, additional elements may be used in some types of nodes, but these are the basic ones that must be present.)

The six elements of a point node are reals, as follows:

  1. the X coordinate of the point;
  2. the Y coordinate of the point;
  3. the Z coordinate of the point;
  4. the X component of the flow field at the point;
  5. the Y component of the flow field at the point;
  6. the Z component of the flow field at the point.
It is the responsibility of the user to ensure that the X, Y, and Z components of the flow field form a vector which is tangent to the surface represented by the triangular mesh.

The four elements of an edge node are integers, as follows:

  1. the base index, in RPNT, of the node defining point 1 of the edge;
  2. the base index, in RPNT, of the node defining point 2 of the edge;
  3. the base index, in ITRI, of the node defining the triangle to the left of the edge, plus the index (1, 2, or 3) of the edge within that triangle node (-1 if there is no triangle to the left);
  4. the base index, in ITRI, of the node defining the triangle to the right of the edge, plus the index (1, 2, or 3) of the edge within that triangle node (-1 if there is no triangle to the right);
The "left" and "right" sides of an edge are defined as they would be by an observer standing on the front side of the surface defined by the triangular mesh, at point 1, and looking toward point 2, of the edge. It is possible, if there are "holes" in the mesh, that there will be no triangle on the left or on the right of an edge, but there must be a triangle on one side or the other.

The five elements of a triangle node are integers, as follows:

  1. the base index, in IEDG, of the node defining edge 1 of the triangle;
  2. the base index, in IEDG, of the node defining edge 2 of the triangle;
  3. the base index, in IEDG, of the node defining edge 3 of the triangle;
  4. a flag set non-zero to block use of the triangle, effectively removing it from the mesh. For simple purposes, the values 0 and 1 suffice; however, see the routines VTTDBF and VTTDBM and the internal parameters 'TBA' and 'TBX' for a description of a scheme allowing one to selectively block triangles by using different bits of this flag;
  5. a flag used by the algorithms that draw simple vectors, curly vectors, and streamlines.
The edges pointed to by a particular triangle node must be given in counter-clockwise order, as viewed from the chosen "front" side of the mesh. In fact, it is the ordering of the nodes that defines which side is the "front" and which side is the "back". In the case of a sphere, one would probably use the outside of the sphere as the "front". In the case of a Moebius strip (which I have experimented with a bit), there is a problem with this - you either have to have a seam across the strip or go around it twice to avoid having a seam - but that's probably not a case of great practical interest ... :-)

The "base index" of a point node, an edge node, or a triangle node is always a non-negative multiple of the length of the node, to which can be added an offset to get the index of a particular element of the node. For example, if IPTT is the base index of a triangle of interest, ITRI(IPTT+1) is its first element, which is the base index of the triangle's first edge. Thus, IEDG(ITRI(IPTT+1)+2) is the second element of the triangle's first edge; that is to say, it is the base index of the second point of the first edge of the triangle with base index IPTT. In a similar fashion, it may be seen that RPNT(IEDG(ITRI(IPTT+1)+2)+3) is the third (Z) coordinate of the second point of the first edge of the triangle with base index IPTT.

It is the pointers from the edge nodes back to the triangle nodes that allow VASPACKT to navigate the mesh, moving from triangle to triangle as it follows a streamline. These pointers are a little tricky to define: if IPTE is the base index of an edge node and IEDG(IPTE+3) is zero or more, saying that there is a triangle to the left of the edge, then IEDG(IPTE+3) is the actual index of that element of the triangle node that points to the edge node; that is, ITRI(IEDG(IPTE+3))=IPTE. The base index of the triangle node defining that triangle is IPTT, where IPTT=LOTN*((IEDG(IPTE+3)-1)/LOTN), and the index of the pointer to the edge within the triangle node is IPTI=IEDG(IPTE+3)-IPTT, so that ITRI(IPTT+IPTI)=IPTE. Similar comments apply to element 4 of an edge node, which points into the triangle node defining the triangle to the right of the edge.

For some types of triangular mesh, the maximum number of points, edges, and triangles can be computed easily:

Once we know, at most, how many points, edges, and triangles we're going to have, we can set parameters defining the space to be reserved for the triangular mesh:

      PARAMETER (MPNT=MNOP*LOPN)  !  space for points
      PARAMETER (MEDG=MNOE*LOEN)  !  space for edges
      PARAMETER (MTRI=MNOT*LOTN)  !  space for triangles
    
Then, we can declare the arrays to hold the point nodes, edge nodes, and triangle nodes defining the triangular mesh:

      DIMENSION RPNT(MPNT),IEDG(MEDG),ITRI(MTRI)
    
In all of the examples, code like that above (throughout the section) will be found.


Types of Triangular Meshes

Descriptions of all the types of triangular meshes that the author has encountered are to be found in the programmer document for CONPACKT, in the section titled "Types of Triangular Meshes". Each of the examples described there could quite easily be turned into an example for VASPACKT by replacing all code involving calls to routines with names of the form CTxxxx by code involving calls to routines with names of the form VTxxxx, and, of course, supplying vector field data instead of simple field data.


Mathematical and Programmatic Considerations

The packages "Vectors" and "Streamlines" work from a rectangular array of data; when that rectangular array is mapped in some manner (for example, onto the surface of a globe), they depend heavily on the use of inverse mapping functions, allowing vectors and streamlines to be generated, positioned, and sized in NDC space, within the plotter frame. Since VASPACKT works from a triangular mesh, the use of inverse mapping functions is, in general, not possible; therefore, vectors and streamlines are generated, positioned, and sized entirely on the surface of the triangular mesh and then projected into a viewing plane and from there into NDC space solely for drawing. As a result, if you are accustomed to using the other packages, you will find the parameter interface for VASPACKT somewhat different. I expended a considerable amount of time and effort in an attempt to more closely match the interfaces of "Vectors" and "Streamlines", some of the resulting code is still in place, and it is possible that the interface may expand during a future enhancement, but the interface as it stands is the natural one, given the way the underlying algorithms work.

The vectors defining the flow field are specified at the vertices of the triangular mesh; at each vertex, X, Y, and Z components are given. Each vector does not, in general, lie in the plane of any of the triangles that meet at its vertex; neither do interpolated vectors in the interiors of triangles. But, in order to trace streamlines through the interiors of triangles, we must be able to project the interpolated vectors at interior points into vectors that do lie in the planes of the triangles, which is tricky. What one is tempted to do is project each interpolated vector into the plane of its triangle using projection lines perpendicular to that plane. Unfortunately, doing that leads to troubling discontinuities at the boundaries of adjoining triangles: it is possible, for example, to have interpolated vectors that seem to imply outward flow from each of a pair of adjoining triangles into the other and this can send the code that traces the streamlines into an infinite loop. Instead, the interpolated vectors are projected into the planes of individual triangles using projection lines radiating from a center point, whose coordinates are given by 'PCX', 'PCY', and 'PCZ'. Doing this ensures continuity of the flow field across the boundaries of adjoining triangles in the principal case of interest: a triangular mesh representing a sphere centered at ('PCX','PCY','PCZ'). In fact, it works in any situation in which the "back" side of each triangle is visible from the point ('PCX','PCY','PCZ') and is not obscured by any other triangle; however, it does not work for completely arbitrary meshes, such as the mushroom-shaped blobs shown in the CONPACKT example "cttd01". This is indeed unfortunate, but, as of this writing, I have not been able to find a better projection method.

Linear interpolation is used to estimate flow field components in the interior of each triangle from user-defined components at the vertices. A possible future enhancement would be to provide optional non-linear interpolation methods which may provide more meaningful results on relatively sparse meshes. For the moment, if you have such a mesh, you will have to use some other package to interpolate to a denser mesh.

Streamlines are traced in a somewhat simplistic fashion, by taking tiny steps in the local interpolated direction of the flow field. Thus, there is cumulative error along each streamline: for example, if the flow field should bend smoothly in one direction, the traced streamline will not bend quite as much as it should. There are ways to compensate for this, but the use of such methods will have to be reserved for future enhancements. Meanwhile, one can make the code trace streamlines more accurately by decreasing the step size ('SLP').


Routines Which May Be Called

The following routines are meant to facilitate the process of creating a triangular mesh of data:

Once a triangular mesh has been defined, the code to draw a vector or streamline plot will probably begin with several calls to set internal parameters affecting the behavior of the routines called after that. All the internal parameters have default values; only those which are to have values different from the default need to be set. Routines which may be called to set the values of parameters are as follows:

In general, once a parameter is given a value by a call to one of these routines, it retains that value until a similar call resets it. Thus, many of the parameter-setting calls need to be done only once and do not need to be repeated for each new vector or streamline plot.

After all required parameters have been set, the process of drawing a vector or streamline plot begins with a call to an initialization routine:

After VTMESH has been called, various other routines may be called:

Four routines may be called when 'MAP' is set to 2, which says that the 3D package TDPACK is being used to project the triangular mesh into the plane.

Finally, to advance the frame, the user must call the SPPS routine FRAME; VASPACKT won't do it.

At any time, it is possible to retrieve the value of an internal parameter by calling one of the three following routines:

Several routines in VASPACKT are not called by the user, but by VASPACKT itself. The default versions of these routines, in all cases but one, do nothing; the routines exist simply to be replaced by the user. These routines are as follows:

Two additional routines are provided for use in error-recovery situations:


Coordinate Systems

The mapping of vectors and streamlines into the plotter frame depends on three things:

By default, to describe lines and other objects on a plot, VASPACKT generates X, Y, and Z coordinates representing points on the triangles defined by the data of the triangular mesh and then discards the Z coordinate, using only the X and Y coordinates as the user coordinates in calls to NCAR Graphics routines.

If 'MAP' is given a positive non-zero value, each triplet of X, Y, and Z coordinates is mapped, prior to use, by a statement of the form

      CALL VTMXYZ (IMAP,XINP,YINP,ZINP,XOTP,YOTP)
    
IMAP is the value of 'MAP'; XINP, YINP, and ZINP are the unmapped (input) 3D coordinates; and XOTP and YOTP are the mapped (output) 2D coordinates to be used as "user coordinates".

The default version of VTMXYZ does the following mappings (where RTOD = 57.2957795130823 (180/pi):

The subroutine VTMXYZ may be replaced by a version which does other desired mappings. If the VASPACKT routines are loaded from a binary library, this can usually be done by just compiling one's own version of the routine, so that it replaces the one from the library. The definitions of mappings 1 and 2 should not be changed.

The way in which "user coordinates" are mapped to "fractional coordinates" in the plotter frame is determined by the current definitions of the "window" in the user system and the "viewport" on the plotter frame. The window and viewport may have been defined by a call to the SPPS routine SET or by calls to GKS routines; the former will be described.

A call to the SPPS routine SET has the form

      CALL SET (XVPL,XVPR,YVPB,YVPT,XWDL,XWDR,YWDB,YWDT,LNLG)
    
All arguments are REALs except for LNLG, which is an INTEGER. The first four arguments must all be between 0 and 1, inclusive; they define a rectangular area in the fractional coordinate space of the plotter frame known as the "viewport". The next four arguments define a rectangular area in "user coordinate" space known as the "window". The final argument indicates whether the mapping of user coordinates into the viewport is to be linear or logarithmic in X and Y.

By default, VASPACKT (specifically, the routine VTMESH ) calls the SPPS routine SET. One may, by zeroing 'SET', prevent this from happening; in that case, one must do the call for oneself or depend on some other utility (such as EZMAP) to have done it.

If VASPACKT calls SET, it always uses LNLG = 1, requesting a linear-linear mapping from the window to the viewport, and it positions the viewport and window as follows: The viewport is positioned as specified by the current values of 'VPL', 'VPR', 'VPB', 'VPT', and 'VPS'. The first four of these specify the position of a "viewport area", in which the viewport is to be centered and made as large as possible; the final one says how the shape of the viewport is to be determined. By default, the position of the window in the user coordinate system is determined by computing the minimum and maximum values of X and Y over all the points of the triangular mesh. 'WDL', 'WDR', 'WDB', and 'WDT' may be used to override this default behavior and specify the exact values to be used in the SET call to define the window.

If the triangular mesh represents data on the surface of a globe of radius 1, then to map the VASPACKT output onto an EZMAP background, one need only set 'MAP' to 1 and initialize EZMAP (which results in a call to the SPPS routine SET).


The Out-of-Range Parameter and Out-of-Range Areas

The parameter 'ORV', if non-zero, specifies an "out-of-range" value. This is only of use when 'MAP' is non-zero, specifying that coordinates are to be mapped by calling the subroutine VTMXYZ. The X coordinate returned by VTMXYZ may be set equal to 'ORV' to indicate that the mapped point is outside the range in which the mapping is defined.

A possible value for 'ORV', if it is to be set non-zero, is 1.E12, which has historically been returned by the EZMAP routines MAPTRN and MAPTRA to indicate a point which is outside the area depicted by a given map projection.

The union of all points for which VTMXYZ returns the out-of-range value constitutes a set of out-of-range areas. Vectors are not placed, and curly vectors and streamlines are not traced, in out-of-range areas (indeed, they cannot be). A binary-halving technique is used to extend lines to the very edge of such areas.

When a line is traced, if two consecutive points are out of range (in range), then the entire line segment connecting those two points is assumed to be out of range (in range). If the detail of the out-of-range areas is small enough, this assumption may cause errors. Giving 'PIS' a non-zero value will cause more points to be examined along each such line segment, thus curing the problem. Alternatively, giving 'PIT' a non-zero value may cure the problem in a more efficient way.


Labels - DI

Two different types of labels may be written by calls to VASPACKT: an informational label and a zero-field label.

The appearance of these labels may be determined in detail by setting parameters:

In all of the above parameter names, a suffixed 'A' means "angle", 'B' means "box flag", 'C' means "color index", 'L' means "line width", 'S' means "size of characters", 'T' means "text of label", 'W' means "white space width", 'X' means "X coordinate", and 'Y' means "Y coordinate".

All labels are written by means of calls to the character-plotting routine PLCHHQ, in the package PLOTCHAR. The angle, in degrees, at which a label is written is determined by 'xxA'. The box flag 'xxB' determines whether or not, prior to writing the label, a box surrounding it is filled, and whether or not, after writing the label, the edge of the box is drawn. If the box is filled, it is done using the color index specified by 'LBC'; if the edge of the box is drawn, it is done using the color index, if any, chosen for the label itself, which is determined by the value of 'xxC'. The line width to be used in drawing the box is determined by 'xxL'. The size (width) of the characters is determined by 'xxS'. The text of the label is determined by 'xxT'; usually, this string may contain embedded substrings of the form '$xxx$', which are to be replaced by the value of the quantity specified by the three-character mnemonic 'xxx'. The width of the "white space" to be left around the label (which defines the dimensions of the box around it) is determined by 'xxW'.


Choosing a Scale Factor - DI

It is possible to specify a scale factor by which field values are to be divided before conversion to a character form for display as a numeric label.

The parameter 'SFS' says how the scale factor is to be chosen. If it is given a value greater than zero, that value is the desired scale factor. If 'SFS' is given a value less than or equal to zero, VASPACKT is directed to choose a scale factor to use, in one of five different ways. The parameter 'SFU' may be retrieved by the user; it specifies the scale factor which has been selected for use.

The scale factor may be displayed as a part of the informational label. This is done by embedding the substring '$SFU$' in the string defining 'ILT'.

The default value of 'SFS' is 1, which essentially specifies that no scale factor is to be used.


Zero Field Detection - DI

The routine VTMESH checks for a flow field which is essentially zero. When such a field is found, 'ZFF' is set non-zero; otherwise, 'ZFF' is zeroed. The value of 'ZFF' may be retrieved by the user.

When 'ZFF' is non-zero, a call to one of the routines VTCVDM, VTCVDR, VTSLDM, VTSLDR, VTSVDM, or VTSVDR will not cause anything to be drawn; instead, the zero-field label will be written.


Workspace Management

The workspace management scheme used in VASPACKT is the same as that used in CONPACKT, even though, at the time of writing, none of the VASPACKT routines requires more than one workspace at a time. The scheme is as follows: The user defines one workspace array of type REAL and another of type INTEGER. In the call to VTMESH that initializes the drawing of a vector or streamline plot, these arrays appear as arguments (called RWRK and IWRK), together with arguments specifying their lengths (LRWK and LIWK). In subsequent calls to other VASPACKT routines that require workspaces, the same arrays appear as arguments, but the lengths do not. The VASPACKT routines cooperate in using these arrays in such a way as not to interfere with one another. Dynamic enlargement of one workspace at the expense of another becomes possible and the probability of running out of space is reduced.

In general, it is safest not to use the workspace arrays for other purposes between one call to a VASPACKT routine and the next (unless the next is to the routine VTMESH, which initializes the workspace pointers).

It is possible to find out how much space has been used in each of the workspace arrays. The parameters 'IWU' and 'RWU' are zeroed by a call to VTMESH and are updated thereafter to reflect maximum usage of space in the arrays. Thus, one might give the arrays large dimensions, create a typical plot, retrieve the values of 'IWU' and 'RWU' to see how much space was actually used, and then reduce the dimensions to more reasonable values.

Currently, workspace usage by all routines can be predicted exactly. However, because this could potentially change in the future, there is a parameter, called 'WSO', that says what to do when a workspace overflow occurs. The four possibilities are as follows: to terminate after printing an error message, to continue running after printing an error message (this is the default), to just continue running without printing anything, or to do a recoverable-error call to SETER and then continue running without printing anything. Of course, in the latter two cases, incomplete plots may result. It is possible to find out whether or not a workspace overflow has occurred during a given call to a VASPACKT routine; this is done by retrieving 'IWU' and 'RWU' and comparing them with the dimensions of the workspace arrays IWRK and RWRK.

If "n" is the number of triangles in the triangular mesh, then

Routines not mentioned above use no workspace.


The Character-Width Multiplier - DI

The parameter 'CWM' is used as a multiplier for all character widths and similar quantities. This makes it possible to scale all such quantities up and down simultaneously. The default value of 'CWM' is 1.


Color-Setting Philosophy

A number of the VASPACKT parameters specify the color of some object The default value of each such parameter is -1, which says that the color is to be determined by the current value of one of the GKS color indices. (The polyline color index is used for lines, the text color index for labels, and the fill area color index for filling label boxes.) If the value of the VASPACKT color-setting parameter for a given object is given a value greater than or equal to zero, it specifies the color index of the color in which the object is to be drawn. Before any object is drawn, the values of the GKS color indices affected are saved; after the object is drawn, the saved values are restored.

This structure allows the use of a tiered approach to color setting. If no color setting whatsoever is done, plots are drawn entirely in the colors specified by the applicable default values of the GKS color indices. If, on the other hand, prior to calling VASPACKT, one defines the color index "IC" (see the next section, "GKS Considerations") and then uses

      CALL GSPLCI (IC)
    
to change the GKS polyline color index, then all polylines drawn by VASPACKT change color. Similarly, one may use the statement

      CALL GSTXCI (IC)
    
to change the GKS text color index and the statement

    CALL GSFACI (IC)
    
to change the GKS fill area color index; the first will cause labels drawn by VASPACKT to change color and the second will cause label boxes filled by VASPACKT to change color.

If, in addition or instead, VASPACKT color-setting parameters are given values greater than or equal to zero, the objects or classes of objects to which those parameters apply are colored accordingly; these colors are used in preference to values preset by calls to GSPLCI, GSTXCI, or GSFACI.

A final opportunity to set color is provided by the user-supplied versions of the "change" routines, with names of the form VTCHxx (DI); calls to GSPLCI, GSTXCI, and GSFACI may occur in such a routine and take precedence over color setting by any other means. Note that, if color is being set for drawing a label, then either or both of the polyline color index and the text color index may need to be set, depending on whether the labels are being drawn by calls to the GKS routine GPL (to draw polylines stroking out the characters) or by calls to the GKS routine GTX (to draw text). In particular, the routine PLCHHQ , in the package PLOTCHAR, which is called by VASPACKT to draw labels, may be directed by the user to draw high-quality characters, which are stroked; medium-quality characters, which are also stroked; or low-quality characters, which are drawn by GTX.


GKS Considerations

Certain assumptions are made by VASPACKT about the state of GKS, as follows:

(1) Like all the utilities in the NCAR graphics package, VASPACKT assumes that GKS has been opened and that the desired workstations have been opened and activated. The statement

      CALL OPNGKS
    
calls the SPPS routine OPNGKS, the GKS equivalent of which is

      CALL GOPKS (6,0)
      CALL GOPWK (1,2,1)
      CALL GACWK (1)
    
creating a single metacode workstation associated with FORTRAN unit 2.

Similarly, at the end of one's program, the workstations must be deactivated and closed and then GKS must be closed. The statement

    CALL CLSGKS
    
calls the SPPS routine CLSGKS, the GKS equivalent of which is

      CALL GDAWK (1)
      CALL GCLWK (1)
      CALL GCLKS
    
(2) It is assumed that the aspect source flags for various quantities are set to "individual". (The NCAR GKS package does this by default, but other packages may not.) To make sure that all the aspect source flags are set correctly, use the following code:

      DIMENSION IASF(13)
      ...
      DATA IASF / 13*1 /
      ...
      CALL GSASF (IASF)
    
(3) Color fill is done by VASPACKT using calls to the GKS routine GFA. To get solid fill, rather than hollow fill, one must call a GKS routine to set the "fill area interior style":

      CALL GSFAIS (1)
    
(This is because the default "fill area interior style", as mandated by the GKS standard, is "hollow", rather than "solid".)

(4) Color-setting by VASPACKT is done by executing calls to the GKS routines GSPLCI, GSTXCI, and GSFACI, with user-defined color indices as arguments. The association of these color indices with colors on the workstations must have been defined previously by the user. This should be done by calling the GKS routine GSCR. The statement

      CALL GSCR (IW,IC,RC,GC,BC)
    
defines, for workstation IW, color index IC, with RGB components RC, GC, and BC. To be consistent with the SPPS routines OPNGKS and CLSGKS, use IW = 1. The value of IC may be any non-negative integer. By default, color index 0 is associated with the color black, which is defined by (RC,GC,BC) = (0.,0.,0.) and is used as the background color, while color index 1 is associated with the color white, which is defined by (RC,GC,BC) = (1.,1.,1.).


SUBROUTINES

All of the VASPACKT routines have six-character names beginning with the letters 'VT'. The user-callable ones are described in detail below.


VTBACK (RPNT,IEDG,ITRI,RWRK,IWRK)

This routine draws a background for a vector or streamline plot.

The initial version of VTBACK does very little. User feedback will be useful in determining what this routine is eventually made to do.

Usage

The routine VTBACK may be called at any time after the initialization call to VTMESH. All it does is draw the perimeter of the current viewport; it does this by calling PERIM, in the package GRIDAL.

Arguments

All five arguments are arrays used in a previous call to one of the routines VTMESH, VTMVRW, or VTMVIW.

RPNT (REAL array, dimensioned as specified in the last call to VTMESH, input) is the user's mesh-point array.

IEDG (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's edge array.

ITRI (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's triangle array.

RWRK (REAL array, dimensioned as specified in the last call to VTMESH or VTMVRW, input/output) is the current real workspace array.

IWRK (INTEGER array, dimensioned as specified in the last call to VTMESH or VTMVIW, input/output) is the current integer workspace array.


VTCHIL (IFLG) - DI

This routine provides user control as the informational label is drawn.

Usage

The routine VTCHIL is not to be called by the user. It is called several times by VASPACKT while the informational label is positioned and drawn. The default version of VTCHIL does nothing. A user-supplied replacement may change attributes such as color and line width (by calling the SPPS routine SETUSV or the appropriate GKS routines).

The text of the label may be retrieved by means of a "CALL VTGETC ('CTM',CVAL)". The text of the label may be changed by means of a "CALL VTSETC ('CTM',CVAL)"; this should only be done during a call with IFLG = 1 or IFLG = 3, and, if it is done for one of those values, it should be done for the other.

The parameters 'LBX' and 'LBY' will have been set to the X and Y coordinates of the center point of the label, in the current user coordinate system.

Arguments

IFLG (INTEGER, input) is positive if an action is about to be taken, negative if an action has just been completed. The action in question is defined by the absolute value of IFLG, as follows:


VTCHZF (IFLG) - DI

This routine provides user control as a constant-field message is drawn.

Usage

The routine VTCHZF is not to be called by the user. It is called several times by VASPACKT while the zero-field label is positioned and drawn. The default version of VTCHZF does nothing. A user-supplied replacement may change attributes such as color and line width (by calling the SPPS routine SETUSV or the appropriate GKS routines).

The text of the label being written may be retrieved by means of a "CALL VTGETC ('CTM',CVAL)". The text of the label may be changed by means of a "CALL VTSETC ('CTM',CVAL)"; this should only be done during a call with IFLG = 1 or 3 and, if it is done for one of those two values, it should also be done for the other.

The parameters 'LBX' and 'LBY' will have been set to the X and Y coordinates of the center point of the label, in the current user coordinate system.

Arguments

IFLG (INTEGER, input) is positive if an action is about to be taken, negative if an action has just been completed. The action in question is defined by the absolute value of IFLG, as follows:


VTCVDM (RPNT,IEDG,ITRI,RWRK,IWRK,IAMA,RTPL)

VTCVDR (RPNT,IEDG,ITRI,RWRK,IWRK)

These routines are used to draw curly vectors for a velocity field defined on a triangular mesh.

Usage

Either of the routines VTCVDM and VTCVDR may be called at any time after the initialization call to VTMESH.

VTCVDM generates the vectors, masks them against a user-specified area map, and generates calls to a user-specified routine - one call for each polyline resulting from the masking process. Each such polyline lies entirely within precisely one of the areas defined by the area map. The user routine may examine the information provided by its arguments, describing the area the polyline is in, and either draw or not draw the polyline. The object of masking the curly vectors may be simply to avoid drawing them through label boxes or it may be something more complicated, like limiting the drawing of the vectors to the ocean areas on an EZMAP background.

VTCVDR generates and draws the vectors, with no masking. (Actually, it's implemented by calling VTCVDM with an argument array IAMA having its single element set to zero, which turns off masking.)

Each curly vector is just a short streamline, of a length, as measured on the surface of the triangular mesh, proportional to the magnitude of the velocity field at the center of the vector. See the descriptions of 'VFR', 'VRL', and 'VRM', which may be used to control the sizes of the vectors.

To distribute the curly vectors more or less evenly on the surface of the triangular mesh, the triangles are considered in random order. A curly vector is placed in a triangle (and centered on its center point) if and only if certain conditions are met: 1) no curly vector has previously passed through the triangle; 2) the largest angle between the velocity vectors at any pair of vertices of the triangle is less than the maximum value specified by 'AM1'; 3) two lines traced, from the starting point, in the two directions perpendicular to the velocity field, for the distance specified by 'TTL', do not cross any curly vector previously drawn; and 4) the entire curly vector can be drawn without crossing or passing too close to any curly vector previously drawn (as determined by tracing lines perpendicular to the velocity field at intervals along the curly vector and of the lengths specified by the values of 'TTS' and 'TTL') or being terminated for some other reason (like hitting an external edge of the mesh, entering a triangle containing another curly vector, or entering a triangle where the largest angle between the velocity vectors at any pair of vertices of the triangle is larger than the value specified by 'AM2').

No curly vector will be placed in any triangle of the mesh that is blocked, as specified by the current values of the blocking masks 'TBA' and 'TBX' and the blocking flag for the triangle.

See the example "vtex02".

Arguments

The first five arguments are arrays used in a previous call to one of the routines VTMESH, VTMVRW, or VTMVIW.

RPNT (REAL array, dimensioned as specified in the last call to VTMESH, input) is the user's mesh-point array.

IEDG (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's edge array.

ITRI (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's triangle array.

RWRK (REAL array, dimensioned as specified in the last call to VTMESH or VTMVRW, input/output) is the current real workspace array.

IWRK (INTEGER array, dimensioned as specified in the last call to VTMESH or VTMVIW, input/output) is the current integer workspace array.

IAMA (INTEGER array, dimensioned as specified in a call to ARINAM, in the package AREAS, input/output) is an array containing an area map which is to be used to mask the curly vectors as they are drawn. If no masking is desired, use an array with its first element zeroed.

RTPL (EXTERNAL subroutine) is the user subroutine which is to process the polylines which result from masking the curly vectors against the area map. It must be declared EXTERNAL in the routine which calls VTCVDM. It will be called repeatedly and must have the following form:

      SUBROUTINE RTPL (XCS,YCS,NCS,IAI,IAG,NAI)
      DIMENSION XCS(*),YCS(*),IAI(*),IAG(*)
      ...
      (CODE TO PROCESS POLYLINE DEFINED BY ARGUMENTS)
      ...
      RETURN
      END
      
The real arrays XCS and YCS hold the X and Y coordinates of NCS points defining a polyline which is to be considered for drawing. For each I greater than or equal to 1 and less than or equal to NAI, IAI(I) is the area identifier for the area in which the polyline lies, relative to the edge group IAG(I). The X and Y coordinates are all normalized device coordinates and it may be assumed that the appropriate SET call has been done. If it is decided to draw the line, it may be done with a call to the SPPS routine CURVE, to the DASHCHAR routine CURVED, to the DASHPACK routine DPCURV, or to the GKS routine GPL.

If the only object of using VTCVDM is to avoid drawing curly vectors through areas having negative area identifiers, then the routine VTDRPL may be used for RTPL. In the routine that calls VTCVDM, insert the declaration

      EXTERNAL VTDRPL
      
and then use VTDRPL for the last argument.

For more information, see the description of the argument LPR of the AREAS subroutine ARDRLN.


VTDRPL (XCS,YCS,NCS,IAI,IAG,NAI)

This routine provides a useful polyline-drawer for other routines.

Usage

If one of the routines VTCVDM, VTSLDM, or VTSVDM is called, and the only object of using it, instead of VTCVDR, VTSLDR, or VTSVDR is to avoid drawing the lines through areas identified by an area map as having negative area identifiers, then, in the routine containing the call, put the declaration

      EXTERNAL VTDRPL
      
and, in the call, use VTDRPL for the argument RTPL. Each time VTDRPL is called, it draws the polyline defined by its first three arguments if, and only if, none of the area identifiers defined by the other three arguments is negative.

Arguments

XCS (a REAL array of dimension at least NCS, input) is an array containing the X coordinates of NCS points defining a polyline.

YCS (a REAL array of dimension at least NCS, input) is an array containing the Y coordinates of NCS points defining a polyline.

NCS (INTEGER, input) is the number of points defining the polyline.

IAI (an INTEGER array of dimension at least NAI, input) is an array of area identifiers for the area in which the polyline lies. For each I from 1 to NAI, IAI(I) is the area identifier of the area with respect to the edge group IAG(I).

IAG (an INTEGER array of dimension at least NAI, input) is an array of group identifiers. See the description of IAI, above.

NAI (INTEGER, input) is the number of area identifiers in the array IAI and the number of group identifiers in the array IAG.


VTGETC (PNAM,CVAL)

This routine is used to get the current value of a parameter of type CHARACTER.

Usage

Use the statement

      CALL VTGETC (PNAM,CVAL)
      
at any time to retrieve in CVAL the current character value of the parameter whose name is PNAM. If that parameter is an array, the array element specified by the current value of 'PAI' will be the one retrieved.

Arguments

PNAM (CHARACTER, input) is the name of a parameter whose character value is to be retrieved. Only the first three characters of PNAM are examined. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of just 'CTM', use 'CTM - CHARACTER TEMPORARY'.

CVAL (CHARACTER, output) is a variable in which the value of the parameter specified by PNAM is to be returned.


VTGETI (PNAM,IVAL)

This routine is used to get the current integer value of a parameter.

Usage

Use the statement

      CALL VTGETI (PNAM,IVAL)
      
at any time to retrieve in IVAL the current integer value of the parameter whose name is PNAM. If that parameter is an array, the array element specified by the current value of 'PAI' will be the one retrieved.

Arguments

PNAM (CHARACTER, input) is the name of a parameter whose integer value is to be retrieved. Only the first three characters of PNAM are examined. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of just 'SVT', use 'SVT - SIMPLE VECTOR THINNING FLAG'.

IVAL (INTEGER, output) is a variable in which the value of the parameter specified by PNAM is to be returned. If the parameter is of type INTEGER and has the value "i", then IVAL = i; if the parameter is of type REAL and has the value "r", then IVAL = INT(r).


VTGETR (PNAM,RVAL)

This routine is used to get the current real value of a parameter.

Usage

Use the statement

      CALL VTGETR (PNAM,RVAL)
      
at any time to retrieve in RVAL the current real value of the parameter whose name is PNAM. If that parameter is an array, the array element specified by the current value of 'PAI' will be the one retrieved.

Arguments

PNAM (CHARACTER, input) is the name of a parameter whose real value is to be retrieved. Only the first three characters of PNAM are examined. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of just 'AHL', use 'AHL - ARROWHEAD LENGTH'.

RVAL (REAL, output) is a variable in which the value of the parameter specified by PNAM is to be returned. If the parameter is of type INTEGER and has the value "i", then RVAL = REAL(i); if the parameter is of type REAL and has the value "r", then RVAL = r.


VTMESH (RPNT,NPNT,LOPN, ... )

(The remaining arguments are IEDG, NEDG, LOEN, ITRI, NTRI, LOTN, RWRK, LRWK, IWRK, and LIWK.)

Initializes the drawing of simple vectors, curly vectors, and/or streamlines on a triangular mesh. VTMESH ignores triangles of the triangular mesh that are blocked by the user, as specified by the low-order bits of the blocking masks 'TBA' and 'TBX' and the blocking flag for each triangle.

Usage

The routine VTMESH is called to initialize the process of drawing a plot showing simple vectors, curly vectors, and/or streamlines, using a triangular array of data. The arguments define the data arrays, a real workspace array, and an integer workspace array.

When VTMESH is called: The dimensions of all the arrays are transferred to variables in COMMON, so that those dimensions may be omitted from calls to other VASPACKT routines. Some needed constants that cannot be set in DATA statements (because their values may be different on different machines) are computed. The internal pointers used to manage workspace usage are initialized. The average length of the edges in the mesh ('AEL') is computed. The ranges of the X, Y, and Z coordinates of the points in the mesh ('XMN', 'XMX', 'YMN', 'YMX', 'ZMN', and 'ZMX') and the ranges of the flow field magnitudes 'DMN' and 'DMX') are determined. The parameter 'ZFF' is set appropriately. The ranges of the 2D coordinates of the mapped points of the mesh in the drawing plane are determined. If VASPACKT is to call the SPPS routine SET, appropriate arguments are determined and SET is called; otherwise, GETSET is called to retrieve the arguments from the user's call to SET. Numeric-label quantities that depend on the range of values in the flow field are initialized (see 'NEL', 'NET', 'NEU', 'NLS', 'NLS', 'NOF', and 'NSD'. A scale factor may be chosen (see 'SFS' and 'SFU').

Arguments

RPNT (REAL array, dimensioned greater than or equal to NPNT x LOPN, input) is the user's mesh-point array.

NPNT (INTEGER, input) is the number of elements in RPNT (that is, the number of points in the triangular mesh, times LOPN).

LOPN (INTEGER, input) is the length of a point node.

IEDG (INTEGER array, dimensioned greater than or equal to NEDG x LOEN, input) is the user's edge array.

NEDG (INTEGER, input) is the number of elements in IEDG (that is, the number of edges of the triangular mesh, times LOEN).

LOEN (INTEGER, input) is the length of an edge node.

ITRI (INTEGER array, dimensioned greater than or equal to NTRI x LOTN, input) is the user's triangle array.

NTRI (INTEGER, input) is the number of elements in ITRI (that is, the number of triangles of the triangular mesh, times LOTN).

LOTN (INTEGER, input) is the length of a triangle node.

RWRK (REAL array, dimensioned LRWK, input/output) is the real work array.

LRWK (INTEGER, input) is the length of RWRK.

IWRK (INTEGER array, dimensioned LIWK, input/output) is the integer work array.

LIWK (INTEGER, input) is the length of IWRK.


VTMVIW (IWKO,IWKN,LWKN)

This routine is called to move what VASPACKT has in the current integer workspace array to a new array.

Usage

When, in the execution of a VASPACKT routine, the amount of space left in the integer workspace array is found to be insufficient, if 'WSO' has the value 3, the error-handling routine SETER is called with an appropriate error message. If, in addition, the user has turned recovery mode on, execution continues and, eventually, control is returned to the user. At that point, the user should detect the fact that an error has occurred. If he/she chooses to try to recover from the error, VTMVIW may be of use: it may be called to move everything from the current integer workspace array to a new (and presumably bigger) one, after which it may be possible to resume execution.

Arguments

IWKO (an input array of type INTEGER, dimensioned as specified in a previous call to VTMESH or VTMVIW) is the current ("old") integer workspace array.

IWKN (an output array of type INTEGER, dimensioned LWKN) is the array which is to become the new integer workspace array.

LWKN (INTEGER, input) is the dimension of the array IWKN.


VTMVRW (RWKO,RWKN,LWKN)

This routine is called to move what VASPACKT has in the current real workspace array to a new array.

Usage

When, in the execution of a VASPACKT routine, the amount of space left in the real workspace array is found to be insufficient, if 'WSO' has the value 3, the error-handling routine SETER is called with an appropriate error message. If, in addition, the user has turned recovery mode on, execution continues and, eventually, control is returned to the user. At that point, the user should detect the fact that an error has occurred. If he/she chooses to try to recover from the error, VTMVRW may be of use: it may be called to move everything from the current real workspace array to a new (and presumably bigger) one, after which it may be possible to resume execution.

Arguments

RWKO (an input array of type REAL, dimensioned as specified in a previous call to VTMESH or VTMVRW) is the current ("old") real workspace array.

RWKN (an output array of type REAL, dimensioned LWKN) is the array which is to become the new real workspace array.

LWKN (INTEGER, input) is the dimension of the array RWKN.


VTMXYZ (IMAP,XINP,YINP,ZINP,XOTP,YOTP)

This routine defines mappings from the 3D coordinate system of the triangular mesh to the 2D "user" coordinate system in which the mapped vectors and streamlines are being drawn.

Usage

VTMXYZ is not to be called by the user. It is called by various VASPACKT routines when 'MAP' is non-zero. A user may supply his or her own version of the routine in order to define other mappings.

The first argument in a call to VTMXYZ will always be positive; the call is intended to map the X, Y, and Z coordinates of a point from the 3D space in which the triangular mesh is defined to X and Y "user" coordinates in the 2D space of the drawing plane.

(Note, however, that, if the same routine is being used as a replacement for both VTMXYZ and the analogous CONPACKT routine CTMXYZ, then negative values of the first argument can occur and one should review the discussion of that routine.)

The default version of VTMXYZ is as follows:

      SUBROUTINE VTMXYZ (IMAP,XINP,YINP,ZINP,XOTP,YOTP)
        DATA RTOD / 57.2957795130823 /  !  (radians to degrees)
        IF (IMAP.EQ.1) THEN
          RLAT=RTOD*ASIN(ZINP/SQRT(XINP*XINP+YINP*YINP+ZINP*ZINP))
          IF (XINP.EQ.0..AND.YINP.EQ.0.)
            RLON=0.
          ELSE
            RLON=RTOD*ATAN2(YINP,XINP)
          END IF
          CALL MAPTRA (RLAT,RLON,XOTP,YOTP)
        ELSE IF (IMAP.EQ.-1) THEN
          CALL MAPTRI (XINP,YINP,XOTP,YOTP)
        ELSE IF (IMAP.EQ.2) THEN
          CALL TDPRPT (XINP,YINP,ZINP,XOTP,YOTP)
        ELSE
          XOTP=XINP
          YOTP=YINP
        END IF
        RETURN
      END
      
When VTMXYZ is called with IMAP = 1, the incoming X, Y and Z coordinates are assumed to represent points on the surface of a sphere of radius 1; from these, it computes values of latitude and longitude and calls the EZMAP routine MAPTRA to find the X and Y coordinates on the map of the projection of the specified point on the globe; those coordinates are returned as the outgoing X and Y coordinates.

When IMAP = -1 (which can only happen if the call comes from the package CONPACKT), the incoming X and Y coordinates are assumed to be the X and Y coordinates of a projected point on the map; the EZMAP routine MAPTRI is called to find the latitude and longitude of the original point on the globe and those values are returned as the outgoing X and Y coordinates. If the point is off the map (as, for example, when an orthographic projection is used and the point is outside the circle of radius 1 into which the visible hemisphere of the earth is mapped by that projection), then MAPTRI will return the value 1.E12 (which should be declared the "out-of-range" value, 'ORV', for VASPACKT).

When VTMXYZ is called with IMAP = 2, the incoming X, Y, and Z coordinates are assumed to represent points on an arbitrary mesh in 3-space; these are projected to an image plane by calling the routine TDPRPT, in the 3D package TDPACK.

Note that calling VTMXYZ with IMAP = -2 does not use TDPACK; furthermore, when 'MAP' is given the value 2, 'ORV' should not be set non-zero; there is no "out-of-range" value.

If IMAP is anything else, the input X and Y coordinates are simply returned as the output X and Y coordinates.

If VTMXYZ is changed to do a new mapping for a particular value of 'MAP', it must be made to respond properly to a first argument with value +'MAP' or -'MAP' .

Arguments

IMAP (INTEGER, input) is greater than zero if the object of the call is to do a forward mapping and less than zero if the object of the call is to check the "out-of-range" status of a point in the user coordinate system. The absolute value of IMAP will be equal to the current value of 'MAP', identifying the mapping to be used.

XINP (REAL, input) is used in one of two ways:

YINP (REAL, input) is used in one of two ways:

ZINP (REAL, input) is only used when IMAP is greater than zero, in which case it is the Z coordinate of a point on the triangular mesh. When IMAP is less than zero, ZINP is ignored.

XOTP (REAL, output) and YOTP (REAL, output) are used in one of two ways:

To reiterate: if the point (XINP,YINP) cannot be mapped for any reason, some recognizable impossible value should be returned for both of XOTP and YOTP and 'ORV' should be given that value, thereby allowing VASPACKT routines that call VTMXYZ to determine whether or not a point being mapped is visible or not. The value used for this purpose by the EZMAP routines MAPTRA and MAPTRI is 1.E12.


VTRSET

Resets all parameters to their initial default values.

Usage

Use "CALL VTRSET" to reset all parameters to their default values.

Arguments

None.


VTSETC (WHCH,CVAL)

This routine is called to set the value of a parameter of type CHARACTER.

Usage

Use the statement

      CALL VTSETC (PNAM,CVAL)
      
to give the parameter whose name is PNAM the character value CVAL. If that parameter is an array, the element specified by the current value of 'PAI' will be the one changed.

Arguments

PNAM (CHARACTER, input) is the name of a parameter to be given a character value. Only the first three characters of PNAM are examined. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of 'CTM', use 'CTM - CHARACTER TEMPORARY'.

CVAL (CHARACTER, input) is a character constant or variable, the value of which is to be given to the parameter specified by PNAM.


VTSETI (WHCH,IVAL)

This routine is called to give a new integer value to a parameter.

Usage

Use the statement

      CALL VTSETI (PNAM,IVAL)
      
to give the parameter whose name is PNAM the integer value IVAL. If that parameter is an array, the element specified by the current value of 'PAI' will be the one changed.

Arguments

PNAM (CHARACTER, input) is the name of a parameter to be given an integer value. Only the first three characters of PNAM are examined. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of 'SVT', use 'SVT - SIMPLE VECTOR THINNING FLAG'.

IVAL (INTEGER, input) is an expression, the value of which is to be given to the parameter specified by PNAM. If the parameter is of type INTEGER, it is given the value IVAL; if the parameter is of type REAL, it is given the value REAL(IVAL).


VTSETR (WHCH,RVAL)

This routine is called to give a new real value to a parameter.

Usage

Use the statement

      CALL VTSETR (PNAM,RVAL)
      
to give the parameter whose name is PNAM the real value RVAL. If that parameter is an array, the element specified by the current value of 'PAI' will be the one changed.

Arguments

PNAM (CHARACTER, input) is the name of a parameter to be given a real value. Only the first three characters of PNAM are examined. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of 'AHL', use 'AHL - ARROWHEAD LENGTH'.

RVAL (REAL, input) is an expression, the value of which is to be given to the parameter specified by PNAM. If the parameter is of type INTEGER, it is given the value INT(RVAL); if the parameter is of type REAL, it is given the value RVAL.


VTSLDM (RPNT,IEDG,ITRI,RWRK,IWRK,IAMA,RTPL)

VTSLDR (RPNT,IEDG,ITRI,RWRK,IWRK)

These routines are used to draw streamlines for a velocity field defined on a triangular mesh.

Usage

Either of the routines VTSLDM and VTSLDR may be called at any time after the initialization call to VTMESH.

VTSLDM generates the streamlines, masks them against a user-specified area map, and generates calls to a user-specified routine - one call for each polyline resulting from the masking process. Each such polyline lies entirely within precisely one of the areas defined by the area map. The user routine may examine the information provided by its arguments, describing the area the polyline is in, and either draw or not draw the polyline. The object of masking the streamlines may be simply to avoid drawing them through label boxes or it may be something more complicated, like limiting the drawing of the streamlines to the ocean areas on an EZMAP background.

VTSLDR generates and draws the streamlines, with no masking. (Actually, it's implemented by calling VTSLDM with an argument array IAMA having its single element set to zero, which turns off masking.)

The following algorithm is used to achieve a pleasing distribution of streamlines on a triangular mesh consisting of N triangles:

The net effect of this rather complicated process is to fill the surface of the triangular mesh with groups of streamlines that are positioned at approximately regular intervals, as specified by 'SLS'.

As each streamline is drawn, arrowheads are drawn at regular intervals of 'AHS' along its length. Each arrowhead is constructed by drawing two short, possibly slightly curved, lines of the length specified by 'AHL': where the two lines meet, at the streamline, the angle between them is determined by 'AHA' and each maintains a constant angle with respect to the flow field along its entire length. This technique avoids the problem of using straight arrowheads that could cross the streamline in turbulent regions, where the streamline is bending sharply.

The arrowheads on each streamline are shifted along it by a random amount that is unique to that streamline. This is meant to avoid having the arrowheads on all of the streamlines generated by a particular streamline generator line up in distracting rows. It can happen that arrowheads on closely-spaced streamlines overlap in a displeasing fashion; in some cases (as, for example, when preparing a particular plot for publication), it may be worthwhile to change the value of 'RNG', which will change the set of random numbers used.

Tracing and/or drawing of each streamline generator, each streamline, and each segment of each arrowhead is done using points that are separated on the surface of the triangular mesh by a distance specified by 'SLP'. Making 'SLP' smaller will give one streamlines that more nearly reflect the actual path of a particle in the flow field, but it will take more time to draw them and the resulting metafile will be larger.

By default, streamlines are drawn in the current foreground color. However, the color of each streamline may vary along its length, as determined by the varying value of an associated quantity chosen by the user. See the descriptions of 'CTV', 'NLV', 'CLR', and 'TVL'.

No streamline will be drawn through any triangle of the mesh that is blocked, as specified by the current values of the blocking masks 'TBA' and 'TBX' and the blocking flag for the triangle.

See the example "vtex03".

Arguments

The first five arguments are arrays used in a previous call to one of the routines VTMESH, VTMVRW, or VTMVIW.

RPNT (REAL array, dimensioned as specified in the last call to VTMESH, input) is the user's mesh-point array.

IEDG (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's edge array.

ITRI (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's triangle array.

RWRK (REAL array, dimensioned as specified in the last call to VTMESH or VTMVRW, input/output) is the current real workspace array.

IWRK (INTEGER array, dimensioned as specified in the last call to VTMESH or VTMVIW, input/output) is the current integer workspace array.

IAMA (INTEGER array, dimensioned as specified in a call to ARINAM, in the package AREAS, input/output) is an array containing an area map which is to be used to mask the streamlines as they are drawn. If no masking is desired, use an array with its first element zeroed.

RTPL (EXTERNAL subroutine) is the user subroutine which is to process the polylines which result from masking the streamlines against the area map. It must be declared EXTERNAL in the routine which calls VTCVDM. It will be called repeatedly and must have the following form:

      SUBROUTINE RTPL (XCS,YCS,NCS,IAI,IAG,NAI)
      DIMENSION XCS(*),YCS(*),IAI(*),IAG(*)
      ...
      (CODE TO PROCESS POLYLINE DEFINED BY ARGUMENTS)
      ...
      RETURN
      END
      
The real arrays XCS and YCS hold the X and Y coordinates of NCS points defining a polyline which is to be considered for drawing. For each I greater than or equal to 1 and less than or equal to NAI, IAI(I) is the area identifier for the area in which the polyline lies, relative to the edge group IAG(I). The X and Y coordinates are all normalized device coordinates and it may be assumed that the appropriate SET call has been done. If it is decided to draw the line, it may be done with a call to the SPPS routine CURVE, to the DASHCHAR routine CURVED, to the DASHPACK routine DPCURV, or to the GKS routine GPL.

If the only object of using VTSLDM is to avoid drawing curly vectors through areas having negative area identifiers, then the routine VTDRPL may be used for RTPL. In the routine that calls VTSLDM, insert the declaration

      EXTERNAL VTDRPL
      
and then use VTDRPL for the last argument.

For more information, see the description of the argument LPR of the AREAS subroutine ARDRLN.


VTSVDM (RPNT,IEDG,ITRI,RWRK,IWRK,IAMA,RTPL)

VTSVDR (RPNT,IEDG,ITRI,RWRK,IWRK)

These routines are used to draw simple vectors for a velocity field defined on a triangular mesh.

Usage

Either of the routines VTSVDM and VTSVDR may be called at any time after the initialization call to VTMESH.

VTSVDM generates the simple vectors, masks them against a user-specified area map, and generates calls to a user-specified routine - one call for each polyline resulting from the masking process. Each such polyline lies entirely within precisely one of the areas defined by the area map. The user routine may examine the information provided by its arguments, describing the area the polyline is in, and either draw or not draw the polyline. The object of masking the vectors may be simply to avoid drawing them through label boxes or it may be something more complicated, like limiting the drawing of the vectors to the ocean areas on an EZMAP background.

VTSVDR generates and draws the vectors, with no masking. (Actually, it's implemented by calling VTSVDM with an argument array IAMA having its single element set to zero, which turns off masking.)

Each simple vector is just an arrow on the triangular mesh, of a length, as measured on the surface of the mesh, proportional to the magnitude of the velocity field at the center of the vector. See the descriptions of 'VFR', 'VRL', and 'VRM', which may be used to control the sizes of the vectors.

If 'SVT' is given a zero value, a simple vector is drawn at the center of every triangle. For a typically dense mesh, this yields far too many vectors, so the default value of the parameter is non-zero, activating a culling algorithm that results in the drawing of simple vectors at the centers of a subset of the triangles. To distribute the vectors more or less evenly on the surface of the triangular mesh, the triangles are considered in random order. For more information, see the description of 'SVT'.

No vector will be placed in any triangle of the mesh that is blocked, as specified by the current values of the blocking masks 'TBA' and 'TBX' and the blocking flag for the triangle.

See the example "vtex01".

Arguments

The first five arguments are arrays used in a previous call to one of the routines VTMESH, VTMVRW, or VTMVIW.

RPNT (REAL array, dimensioned as specified in the last call to VTMESH, input) is the user's mesh-point array.

IEDG (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's edge array.

ITRI (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's triangle array.

RWRK (REAL array, dimensioned as specified in the last call to VTMESH or VTMVRW, input/output) is the current real workspace array.

IWRK (INTEGER array, dimensioned as specified in the last call to VTMESH or VTMVIW, input/output) is the current integer workspace array.

IAMA (INTEGER array, dimensioned as specified in a call to ARINAM, in the package AREAS, input/output) is an array containing an area map which is to be used to mask the simple vectors as they are drawn. If no masking is desired, use an array with its first element zeroed.

RTPL (EXTERNAL subroutine) is the user subroutine which is to process the polylines which result from masking the simple vectors against the area map. It must be declared EXTERNAL in the routine which calls VTCVDM. It will be called repeatedly and must have the following form:

      SUBROUTINE RTPL (XCS,YCS,NCS,IAI,IAG,NAI)
      DIMENSION XCS(*),YCS(*),IAI(*),IAG(*)
      ...
      (CODE TO PROCESS POLYLINE DEFINED BY ARGUMENTS)
      ...
      RETURN
      END
      
The real arrays XCS and YCS hold the X and Y coordinates of NCS points defining a polyline which is to be considered for drawing. For each I greater than or equal to 1 and less than or equal to NAI, IAI(I) is the area identifier for the area in which the polyline lies, relative to the edge group IAG(I). The X and Y coordinates are all normalized device coordinates and it may be assumed that the appropriate SET call has been done. If it is decided to draw the line, it may be done with a call to the SPPS routine CURVE, to the DASHCHAR routine CURVED, to the DASHPACK routine DPCURV, or to the GKS routine GPL.

If the only object of using VTSVDM is to avoid drawing curly vectors through areas having negative area identifiers, then the routine VTDRPL may be used for RTPL. In the routine that calls VTSVDM, insert the declaration

      EXTERNAL VTDRPL
      
and then use VTDRPL for the last argument.

For more information, see the description of the argument LPR of the AREAS subroutine ARDRLN.


VTTDBF (RPNT,IEDG,ITRI,RWRK,IWRK,IFLG,ATOL)

This routine assumes that the triangular mesh is being projected using the 3D package TDPACK. When called, it sets bits of the triangle-blocking flags for all triangles of the mesh that are not currently blocked by the user in such a way as to enable identifying those that are seen from the "wrong side", those that are seen nearly edge-on, and/or those that are partially or completely hidden by other triangles of the mesh.

Let the low-order seven bits of each triangle's blocking flag be numbered (from left to right) B6, B5, B4, B3, B2, B1, and B0; the bits are assigned as follows:

    B6 B5 B4 B3 B2 B1 B0
     \  \  \  \  \  \  \__ reserved for user blocking of triangle
      \  \  \  \  \  \____ right (or only) eye, triangle seen from the wrong side
       \  \  \  \  \______ right (or only) eye, triangle edge-on to the line of sight
        \  \  \  \________ right (or only) eye, triangle hidden by other triangles
         \  \  \__________ left eye, triangle seen from the wrong side
          \  \____________ left eye, triangle edge-on to the line of sight
           \______________ left eye, triangle hidden by other triangles
    
If the final argument (OTEP) in the last call to TDINIT (the offset to the eye position), was greater or equal to zero, then VTTDBF will set bits B3, B2, and B1 of each triangle blocking flag; if OTEP was less than zero, then VTTDBF will set bits B6, B5, and B4 of each triangle blocking flag. Bit B0 is not affected by the call, but the upper bits (B7 and above) are cleared for any triangle that is not blocked by the user.

The blocking flag allows one to maintain visibility information for all triangles of the mesh from two different viewpoints, which means that, by setting the triangle blocking mask parameters 'TBA' and 'TBX' appropriately, one can draw views from those two positions, on each view showing only the triangles visible from that viewpoint.

The argument IFLG allows the caller to say which conditions are to be tested for (as detailed below, in the section "Arguments"); when it is given the value 2 or 3, an algorithm is executed to determine which triangles are partially or completely hidden by other triangles. To run efficiently, this algorithm requires some integer workspace in IWRK; by default, it uses 2500 words, as specified by the value of 'IWB'; increasing the value of 'IWB' (and, of course, the declared length of IWRK) may make this algorithm run even faster. Some experimentation may be required to determine the optimum value to use.

Usage

The routine VTTDBF may be called at any time after the initialization call to VTMESH and the appropriate initialization calls to TDPACK.

Arguments

The first five arguments are arrays used in a previous call to one of the routines VTMESH, VTMVRW, or VTMVIW.

RPNT (REAL array, dimensioned as specified in the last call to VTMESH, input) is the user's mesh-point array.

IEDG (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's edge array.

ITRI (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's triangle array.

RWRK (REAL array, dimensioned as specified in the last call to VTMESH or VTMVRW, input/output) is the current real workspace array.

IWRK (INTEGER array, dimensioned as specified in the last call to VTMESH or VTMVIW, input/output) is the current integer workspace array.

IFLG (INTEGER, input), is an expression, the value of which must be 0, 1, 2, or 3, with meanings as follows:

ATOL (REAL, input), is an expression, the value of which is a tolerance, in degrees, for the "edge-on" tests. If ATOL is less than or equal to zero, edge-on testing is turned off; otherwise, edge-on triangles are those whose center-point normals are within ATOL degrees of being perpendicular to the line of sight to that point.


VTTDBM (IHBX,IEBX,IWBX,IUBX,IHBA,IEBA,IWBA,IUBA)

This routine assumes that the triangular mesh is being projected using the 3D package TDPACK. When called, it sets the values of 'TBA' and 'TBX', which are used as masks for the triangle blocking flags, in such a way as to achieve a particular desired effect.

Let the low-order seven bits of each triangle's blocking flag be numbered (from left to right) B6, B5, B4, B3, B2, B1, and B0; the bits are assigned as follows:

    B6 B5 B4 B3 B2 B1 B0
     \  \  \  \  \  \  \__ reserved for user blocking of triangle
      \  \  \  \  \  \____ right (or only) eye, triangle seen from the wrong side
       \  \  \  \  \______ right (or only) eye, triangle edge-on to the line of sight
        \  \  \  \________ right (or only) eye, triangle hidden by other triangles
         \  \  \__________ left eye, triangle seen from the wrong side
          \  \____________ left eye, triangle edge-on to the line of sight
           \______________ left eye, triangle hidden by other triangles
    
The user sets the B0 bits of the blocking flags directly; the routine VTTDBF is called to set the others. Subsequently, before drawing anything derived from the triangular mesh (streamlines, for example), a call to VTTDBM may be done to determine how the bits of the blocking flags are to be interpreted.

If the final argument (OTEP) in the last call to TDINIT (the offset to the eye position), was greater or equal to zero, VTTDBM will set bits B3, B2, B1, and B0 of 'TBA' and 'TBX', thus generating masks for the right (or only) eye; if OTEP was less than zero, VTTDBM will set bits B6, B5, B4, and B0 of 'TBA' and 'TBX', thus generating masks for the left eye.

Each bit of 'TBX' (an XOR mask) that is a "1" acts as a toggle for the corresponding bit of a triangle's blocking flag, reversing its meaning, while each bit of 'TBA' (an AND mask) that is a "1" acts as a selector for the corresponding bit of a triangle's blocking flag, selecting it as a meaningful bit for testing purposes.

For example, the call

C                x x x x a a a a
C                h e w u h e w u
    CALL VTTDBM (0,0,0,0,1,1,1,1)
    
says that no bits of the triangles' blocking flags are to be toggled and that all of the bits are to be capable of blocking the triangle. The effect will be to block all triangles that are hidden, edge-on, seen from the wrong side, or user-blocked.

The call

C                x x x x a a a a
C                h e w u h e w u
    CALL VTTDBM (0,0,0,0,1,1,0,1)
    
says that no bits of the triangles' blocking flags are to be toggled and that all of the bits except the "wrong-side" flag are to be capable of blocking the triangle. This allows one to (for example) draw the triangular-mesh edges, no matter which side of the mesh the triangles are seen from.

The call

C                x x x x a a a a
C                h e w u h e w u
    CALL VTTDBM (1,1,1,0,1,1,1,1)
    
says that the "hidden", "edge-on", and "wrong-side" bits of the triangles' blocking flags are to be toggled and that all of the bits in the flag are to be capable of blocking the triangle. This would allow one to use only those triangles that not blocked by the user, but are hidden, edge-on, or viewed from the wrong side. (It's not completely clear why one would want to do this, but it's possible to do it.)

Usage

The routine VTTDBF may be called at any time after the initialization call to VTMESH and the appropriate initialization calls to TDPACK.

Arguments

IHBX (INTEGER, input), is an expression, the value of which must be 0 or 1, which provides the value of bit B6 or B3 of 'TBX'. This bit toggles the value of the "hidden" bit of the triangle's blocking flag.

IEBX (INTEGER, input), is an expression, the value of which must be 0 or 1, which provides the value of bit B5 or B2 of 'TBX'. This bit toggles the value of the "edge-on" bit of the triangle's blocking flag.

IWBX (INTEGER, input), is an expression, the value of which must be 0 or 1, which provides the value of bit B4 or B1 of 'TBX'. This bit toggles the value of the "wrong-side" bit of the triangle's blocking flag.

IUBX (INTEGER, input), is an expression, the value of which must be 0 or 1, which provides the value of bit B0 of 'TBX'. This bit toggles the value of the "user" bit of the triangle's blocking flag.

IHBA (INTEGER, input), is an expression, the value of which must be 0 or 1, which provides the value of bit B6 or B3 of 'TBA'. This bit masks the value of the "hidden" bit of the triangle's blocking flag.

IEBA (INTEGER, input), is an expression, the value of which must be 0 or 1, which provides the value of bit B5 or B2 of 'TBA'. This bit masks the value of the "edge-on" bit of the triangle's blocking flag.

IWBA (INTEGER, input), is an expression, the value of which must be 0 or 1, which provides the value of bit B4 or B1 of 'TBA'. This bit masks the value of the "wrong-side" bit of the triangle's blocking flag.

IUBA (INTEGER, input), is an expression, the value of which must be 0 or 1, which provides the value of bit B0 of 'TBA'. This bit masks the value of the "user" bit of the triangle's blocking flag.


VTTDDM (RPNT,IEDG,ITRI,RWRK,IWRK,IDIA)

This routine assumes that routines from the 3D package TDPACK are being used to project the 3-dimensional triangular mesh into a 2-dimensional image space and calls TDLINE repeatedly to draw that part of the mesh which is unblocked, where the blocking is as specified by the blocking masks 'TBA' and 'TBX' and the blocking flags for the triangles.

Usage

The routine VTTDDM may be called at any time after the initialization call to VTMESH. It is given arrays defining a triangular mesh of data, a real workspace array, an integer workspace array, and a flag that can be used to suppress certain portions of the mesh.

Arguments

The first five arguments are arrays used in a previous call to one of the routines VTMESH, VTMVRW, or VTMVIW.

RPNT (REAL array, dimensioned as specified in the last call to VTMESH, input) is the user's mesh-point array.

IEDG (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's edge array.

ITRI (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's triangle array.

RWRK (REAL array, dimensioned as specified in the last call to VTMESH or VTMVRW, input/output) is the current real workspace array.

IWRK (INTEGER array, dimensioned as specified in the last call to VTMESH or VTMVIW, input/output) is the current integer workspace array.

IDIA (INTEGER, input), if non-zero, is the index of an element in each edge node that acts as a flag to indicate whether that edge is to be drawn (zero) or not (non-zero). See the example "cttd01", for the analogous CONPACKT routine CTTDDM, which uses this feature to suppress the drawing of those edges of the mesh that were diagonals of the quadrilaterals of the original mesh from which the triangular mesh was created. Note that, if this feature is used, code must be inserted to create the specified elements in the edge nodes.


VTTDFM (RPNT,IEDG,ITRI,RWRK,IWRK)

This routine assumes that routines from the 3D package TDPACK are being used to project the 3-dimensional triangular mesh into a 2-dimensional image space and uses routines from that package to fill those triangles of the mesh that are unblocked, where the blocking is as specified by the blocking masks 'TBA' and 'TBX' and the blocking flags for the triangles. The fill is done in the color specified by the last call to the GKS routine GSFACI.

Usage

The routine VTTDFM may be called at any time after the initialization call to VTMESH. It is given arrays defining a triangular mesh of data, a real workspace array, and an integer workspace array.

Arguments

All five arguments are arrays used in a previous call to one of the routines VTMESH, VTMVRW, or VTMVIW.

RPNT (REAL array, dimensioned as specified in the last call to VTMESH, input) is the user's mesh-point array.

IEDG (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's edge array.

ITRI (INTEGER array, dimensioned as specified in the last call to VTMESH, input) is the user's triangle array.

RWRK (REAL array, dimensioned as specified in the last call to VTMESH or VTMVRW, input/output) is the current real workspace array.

IWRK (INTEGER array, dimensioned as specified in the last call to VTMESH or VTMVIW, input/output) is the current integer workspace array.


VTTMRG (IDIM,JDIM,RLAT,RLON,RDAT, ... )

(The remaining arguments are ISCR, SVAL, RTMI, RPNT, MPNT, NPNT, LOPN, IEDG, MEDG, NEDG, LOEN, ITRI, MTRI, NTRI, and LOTN.)

The routine VTTMRG ("VaspackT, Triangular Mesh from Rectangular mesh on Globe") is intended to simplify the process of creating triangular meshes of a particular type: given arrays defining a rectangular grid of data deformed to wrap around the globe, it returns arrays defining a triangular mesh representing the data.

Usage

This routine is called using a FORTRAN statement like the following:
        CALL VTTMRG (IDIM,JDIM,            !  dimensioning information
     +               RLAT,RLON,RDAT,ISCR,  !  data arrays, scratch array
     +               SVAL,RTMI,            !  special value, index mapper
     +               RPNT,MPNT,NPNT,LOPN,  !  point node array
     +               IEDG,MEDG,NEDG,LOEN,  !  edge node array
     +               ITRI,MTRI,NTRI,LOTN)  !  triangle node array
      

Arguments

IDIM (INTEGER, input) is the first dimension of the rectangular mesh.

JDIM (INTEGER, input) is the second dimension of the rectangular mesh.

RLAT and RLON (REAL arrays, dimensioned IDIM x JDIM, input) specify the latitudes and longitudes of the node points of the rectangular mesh. The mesh is the collection of quadrilaterals defined by corner points having indices (I,J), (I+1,J), (I,J+1), and (I+1,J+1), for all pairs (I,J) such that I is between 1 and IDIM-1, inclusive, and J is between 1 and JDIM-1, inclusive. The mesh may (and, indeed, probably will) touch itself along certain "seams", but it must not overlap itself.

RDAT (REAL array, dimensioned IDIM x JDIM, input) specifies the data values at the points of the rectangular mesh.

ISCR (INTEGER array, dimensioned IDIM x JDIM x 4, scratch) is a scratch array required by VTTMRG.

SVAL (REAL, input) is a value which, if used in the array RDAT, marks that datum as "special" or "missing". If there are no such values in the array RDAT, set SVAL to some value known not to occur in it.

RTMI ("Routine To Map Indices", user subroutine, input) is a user-defined subroutine describing how the edges of the rectangular mesh, as deformed onto the surface of the globe, fit together. RTMI allows VTTMRG to create a triangular mesh that contains only as many distinct points as there were different points in the rectangular mesh and that has no "seams" where the edges of the rectangular mesh came together.

RTMI must be declared EXTERNAL in the routine that calls VTTMRG; it will be called using FORTRAN statements like this:

        CALL RTMI (IDIM,JDIM,IINI,JINI,IINO,JINO)
      
The arguments IDIM and JDIM are as defined above. The arguments IINI and JINI are input expressions of type INTEGER defining the indices of a particular point of the rectangular mesh (where IINI is between 1 and IDIM and JINI is between 1 and JDIM, inclusive). The arguments IINO and JINO are output variables of type INTEGER that receive the values to be used for the specified point of the mesh in place of IINI and JINI. In general, IINO = IINI and JINO = JINI everywhere except at points that are coincident with other points of the mesh. For example, if the rectangular mesh wraps around the globe in such a way that the entire bottom and top edges of the mesh (for J = 1 and J = JDIM, respectively) each map into a single point (typically the south pole and the north pole, respectively) and the left and right edges of the mesh (for I = 1 and I = IDIM) are coincident on the globe, then one would define RTMI as follows:

      SUBROUTINE RTMI (IDIM,JDIM,IINI,JINI,IINO,JINO)
        IF (JINI.EQ.1) THEN          !  point in first row of mesh
          IINO=1
          JINO=1
        ELSE IF (JINI.EQ.JDIM) THEN  !  point in last row of mesh
          IINO=1
          JINO=JDIM
        ELSE IF (IINI.EQ.IDIM) THEN  !  point in last column of mesh
          IINO=1
          JINO=JINI
        ELSE                         !  all other points of the mesh
          IINO=IINI
          JINO=JINI
        END IF
        RETURN
      END
      
RPNT (REAL array, dimensioned greater than or equal to MPNT x LOPN, output) receives the point array.

MPNT (INTEGER, input) is the dimension of RPNT.

NPNT (INTEGER, output) is the number of elements returned in RPNT (that is, the number of points in the triangular mesh, times LOPN).

LOPN (INTEGER, input) is the length of a point node.

IEDG (INTEGER array, dimensioned greater than or equal to MEDG x LOEN, output) receives the edge array.

MEDG (INTEGER, input) is the dimension of IEDG.

NEDG (INTEGER, output) is the number of elements returned in IEDG (that is, the number of edges of the triangular mesh, times LOEN).

LOEN (INTEGER, input) is the length of an edge node.

ITRI (INTEGER array, dimensioned greater than or equal to NTRI x LOTN, output) receives the triangle array.

MTRI (INTEGER, input) is the dimension of ITRI.

NTRI (INTEGER, output) is the number of elements returned in ITRI (that is, the number of triangles of the triangular mesh, times LOTN).

LOTN (INTEGER, input) is the length of a triangle node.


VTTMTL (NTTO,TBUF,MBUF,NBUF, ... )

VTTMTX (NTTO,TBUF,MBUF,NBUF,EPST, ... )

(In each case, the remaining arguments are IPPP, MPPP, NPPP, IPPE, MPPE, NPPE, RPNT, MPNT, NPNT, LOPN, IEDG, MEDG, NEDG, LOEN, ITRI, MTRI, NTRI, and LOTN.)

The routines VTTMTL ("VaspackT, Triangular Mesh from Triangle List") and VTTMTX (" ..., eXtended") make it relatively easy to obtain, from an collection of triangles in 3-space, a triangular mesh in the form required by VASPACKT. Of course, the collection isn't entirely arbitrary, since the triangles should fit together to form a mesh.

One need not supply information specifying which pairs of triangles adjoin; VTTMTL and VTTMTX can figure that out for themselves. However, it must be the case that, when two triangles have an edge in common, they have the entire edge in common (i.e., there must be at most one triangle to the left of each edge and at most one triangle to the right of each edge).

VTTMTL requires that the coordinates of a vertex that two triangles have in common be computed exactly the same in both triangles. Sometimes, this is a difficult thing to ensure; in such cases, one may call VTTMTX instead and provide an additional argument, EPST, that defines what it means for two coordinate values to be "identical". Note that VTTMTX is a little slower and it requires a larger scratch array IPPP for use in sorting the points (because the tree-sort nodes must contain backward pointers as well as forward pointers).

Usage

VTTMTL and VTTMTX are called using FORTRAN code something like the following. (Note that the details may change from one program to another: for example, some of the DIMENSION statements could be in a calling routine and the various parameters could be passed as arguments.)

C
C Declare the maximum number of points, edges, and triangles expected.
C
        PARAMETER (MNOP=maximum_number_of_points,MPPP=MNOP)
        PARAMETER (MNOE=maximum_number_of_edges,MPPE=MNOE)
        PARAMETER (MNOT=maximum_number_of_triangles)
C
C Declare the lengths of a point node, an edge node, and a triangle
C node, respectively.
C
        PARAMETER (LOPN=4,LOEN=5,LOTN=4)
C
C Declare the lengths of the arrays in which the triangular mesh is to
C be formed.
C
        PARAMETER (MPNT=MNOP*LOPN)  !  space for points
        PARAMETER (MEDG=MNOE*LOEN)  !  space for edges
        PARAMETER (MTRI=MNOT*LOTN)  !  space for triangles
C
C Declare the arrays to hold the point nodes, edge nodes, and triangle
C nodes of the triangular mesh.
C
        DIMENSION RPNT(MPNT),IEDG(MEDG),ITRI(MTRI)
C
C Declare a triangle buffer in which to store triangles temporarily.
C This buffer makes it possible to randomize the order in which the
C triangles of the mesh are processed.  This is necessary to ensure
C friendly behavior by the tree sorts that are done to identify points
C and edges that more than one triangle have in common.  The size of
C the buffer (MBUF) and the number of triangles processed from it at
c a time when the buffer is full (KBUF) are dependent on the size of
C the user's triangular mesh.
C
        PARAMETER (MBUF=5021,KBUF=173)
C
        DIMENSION TBUF(18,MBUF)
C
C Declare a scratch array to be used to sort points.
C
        DIMENSION IPPP(2,MPPP)
C
C Declare a scratch array to be used to sort edges.
C
        DIMENSION IPPE(2,MPPE)
C
C Initialize various counters.
C
        NPPP=0  !  number of points in point sorter
        NPPE=0  !  number of edges in edge sorter
        NBUF=0  !  number of triangles in triangle randomizing buffer
        NTRI=0  !  number of triangles in final triangle list
C
C Loop on the triangles in the mesh.
C
        DO 101 I=1,number_of_triangles_in_arbitrary_mesh
C
C If the triangle buffer is full, process KBUF randomly-chosen
C triangles from it, leaving the remainder at the beginning of
C the buffer.
C
          IF (NBUF.GE.MBUF) THEN
            CALL VTTMTL (KBUF,                 !  number to process
     +                   TBUF,MBUF,NBUF,       !  triangle buffer
     +                   IPPP,MPPP,NPPP,       !  point sorting array
     +                   IPPE,MPPE,NPPE,       !  edge sorting array
     +                   RPNT,MPNT,NPNT,LOPN,  !  point node array
     +                   IEDG,MEDG,NEDG,LOEN,  !  edge node array
     +                   ITRI,MTRI,NTRI,LOTN)  !  triangle node array
          END IF
C
C Generate triangle I and put it in the triangle buffer.
C
          NBUF=NBUF+1
C
          TBUF( 1,NBUF)=X coordinate of point 1 of triangle I
          TBUF( 2,NBUF)=Y coordinate of point 1 of triangle I
          TBUF( 3,NBUF)=Z coordinate of point 1 of triangle I
          TBUF( 4,NBUF)=X flow component at point 1 of triangle I
          TBUF( 5,NBUF)=Y flow component at point 1 of triangle I
          TBUF( 6,NBUF)=Z flow component at point 1 of triangle I
C
          TBUF( 7,NBUF)=X coordinate of point 2 of triangle I
          TBUF( 8,NBUF)=Y coordinate of point 2 of triangle I
          TBUF( 9,NBUF)=Z coordinate of point 2 of triangle I
          TBUF(10,NBUF)=X flow component at point 2 of triangle I
          TBUF(11,NBUF)=Y flow component at point 2 of triangle I
          TBUF(12,NBUF)=Z flow component at point 2 of triangle I
C
          TBUF(13,NBUF)=X coordinate of point 3 of triangle I
          TBUF(14,NBUF)=Y coordinate of point 3 of triangle I
          TBUF(15,NBUF)=Z coordinate of point 3 of triangle I
          TBUF(16,NBUF)=X flow component at point 3 of triangle I
          TBUF(17,NBUF)=Y flow component at point 3 of triangle I
          TBUF(18,NBUF)=Z flow component at point 3 of triangle I
C
  101   CONTINUE
C
C Process any triangles that remain in the triangle buffer.
C
        IF (NBUF.NE.0) THEN
          CALL VTTMTL (NBUF,                 !  number to process
     +                 TBUF,MBUF,NBUF,       !  triangle buffer
     +                 IPPP,MPPP,NPPP,       !  point sorting array
     +                 IPPE,MPPE,NPPE,       !  edge sorting array
     +                 RPNT,MPNT,NPNT,LOPN,  !  point node array
     +                 IEDG,MEDG,NEDG,LOEN,  !  edge node array
     +                 ITRI,MTRI,NTRI,LOTN)  !  triangle node array
        END IF
      
Note that, if the triangle buffer is large enough to hold all the triangles of the mesh at once, the first call to VTTMTL and its enclosing block-IF can be omitted, since all the triangles will be processed out of the buffer by the second call to VTTMTL.

Arguments

NTTO (INTEGER, input) is the number of triangles that VTTMTL is to process from TBUF.

TBUF (REAL array, dimensioned 18 x MBUF, input) is an array of triangles that are to be used to create a triangular mesh. For each J from 1 to NBUF, the elements of TBUF(I,J), for I from 1 to 18, specify a triangle, as follows: TBUF(1,J) through TBUF(3,J) are the X, Y, and Z coordinates of point 1 and TBUF(4,J) through TBUF(6,J) are the X, Y, and Z components of the flow field associated with point 1; similarly, TBUF(7,J) through TBUF(12,J) define point 2 and TBUF(13,J) through TBUF(18,J) define point 3.

MBUF (INTEGER, input) is the second dimension of the array TBUF.

NBUF (INTEGER, input/output), is the number of triangles defined by the current contents of TBUF.

EPST (REAL, input, VTTMTX only), is an epsilon to be used in testing for equality of point coordinate values. Two coordinate values will be considered identical if the absolute value of the difference between them is less than or equal to EPST.

IPPP (INTEGER array, dimensioned 2 x MPPP (if VTTMTL is called) or 3 x MPPP (if VTTMTX is called), scratch) is a scratch array required by CTTMTL to sort points.

MPPP (INTEGER, input) is the second dimension of IPPP, which must be greater than or equal to the total number of distinct points in the triangular mesh.

NPPP (INTEGER, input/output) is the number of elements of IPPP used so far.

IPPE (INTEGER array, dimensioned 2 x MPPE, scratch) is a scratch array required by CTTMTL to sort edges.

MPPE (INTEGER, input) is the second dimension of IPPE, which must be greater than or equal to the total number of distinct edges in the triangular mesh.

NPPE (INTEGER, input/output) is the number of elements of IPPE used so far.

RPNT (REAL array, dimensioned greater than or equal to MPNT x LOPN, output) receives the point array.

MPNT (INTEGER, input) is the dimension of RPNT.

NPNT (INTEGER, output) is the number of elements returned in RPNT (that is, the number of points in the triangular mesh, times LOPN).

LOPN (INTEGER, input) is the length of a point node.

IEDG (INTEGER array, dimensioned greater than or equal to MEDG x LOEN, output) receives the edge array.

MEDG (INTEGER, input) is the dimension of IEDG.

NEDG (INTEGER, output) is the number of elements returned in IEDG (that is, the number of edges of the triangular mesh, times LOEN).

LOEN (INTEGER, input) is the length of an edge node.

ITRI (INTEGER array, dimensioned greater than or equal to NTRI x LOTN, output) receives the triangle array.

MTRI (INTEGER, input) is the dimension of ITRI.

NTRI (INTEGER, output) is the number of elements returned in ITRI (that is, the number of triangles of the triangular mesh, times LOTN).

LOTN (INTEGER, input) is the length of a triangle node.


VTVRLL (RADI,RLAT,RLON,NVEC,VMIN,VMAX, ... )

(The remaining arguments are ICOL, CMIN, CMAX, IAMA, and RTPL.)

Draws a "vector rose" on a globe centered at (0,0,0) and having a radius RADI. The center of the rose is specified by the latitude RLAT and the longitude RLON. The "zero line" of the rose (the first of its component vectors) is assumed to point north.

The "vector rose" consists of NVEC equally-spaced vectors radiating from the center point and tangent to the surface of the globe. Depending on the values of VMIN and VMAX, each vector is drawn either once or twice (with different lengths, in the latter case). The arguments ICOL, CMIN, and CMAX determine the colors to be used. If the vector rose is to be masked against an existing area map, the arguments IAMA and RTPL come into play.

Usage

VTVRLL may be called at any time after VASPACKT has been initialized by calling VTMESH. If the vector rose is to be drawn on top of vectors or streamlines, then the call to VTVRLL should be placed after the call(s) that draw them; otherwise, it should be placed before them.

Arguments

RADI (REAL, input) is the radius of the globe.

RLAT (REAL, input) is the latitude of the center of the vector rose, in degrees.

RLON (REAL, input) is the longitude of the center of the vector rose, in degrees.

NVEC (INTEGER, input) is the number of equally-spaced positions at which vectors are to be drawn, emanating from the point (RLAT,RLON) and tangent to the surface of the globe.

VMIN and VMAX (REAL, input) specify the lengths of the two vectors to be drawn in each of NVEC directions. If VMIN and VMAX are equal, only one vector will be drawn in each direction, except that, if both VMIN and VMAX are zero, the vector lengths used will be as implied by the current values of the VASPACKT parameters 'VFR' and 'VRL'.

ICOL (INTEGER, input) is a flag saying whether or not the vectors are to be drawn in color. If ICOL is zero, they are drawn in the color specified by the current value of the polyline color index. If ICOL is non-zero, the values of CMIN and CMAX will be used to determine the colors to be used.

CMIN and CMAX (REAL, input), if ICOL is non-zero, are values of the associated field being used to determine the colors of vectors and streamlines drawn by VASPACKT. (Even if ICOL is zero, though, the values of CMIN and CMAX must be valid real values that will not cause arithmetic problems.)

IAMA (INTEGER array, dimensioned as specified in a call to ARINAM, in the package AREAS, input/output) is an array containing an area map which is to be used to mask the simple vectors as they are drawn. If no masking is desired, use an array with its first element zeroed.

RTPL (EXTERNAL subroutine) is the user subroutine which is to process the polylines which result from masking the vectors against the area map. It must be declared EXTERNAL in the routine which calls VTVRLL. It will be called repeatedly and must have the following form:

      SUBROUTINE RTPL (XCS,YCS,NCS,IAI,IAG,NAI)
      DIMENSION XCS(*),YCS(*),IAI(*),IAG(*)
      ...
      (CODE TO PROCESS POLYLINE DEFINED BY ARGUMENTS)
      ...
      RETURN
      END
      
The real arrays XCS and YCS hold the X and Y coordinates of NCS points defining a polyline which is to be considered for drawing. For each I greater than or equal to 1 and less than or equal to NAI, IAI(I) is the area identifier for the area in which the polyline lies, relative to the edge group IAG(I). The X and Y coordinates are all normalized device coordinates and it may be assumed that the appropriate SET call has been done. If it is decided to draw the line, it may be done with a call to the SPPS routine CURVE, to the DASHCHAR routine CURVED, to the DASHPACK routine DPCURV, or to the GKS routine GPL.

If the only object of masking is to avoid drawing curly vectors through areas having negative area identifiers, then the routine VTDRPL may be used for RTPL. In the routine that calls VTVRLL, insert the declaration

      EXTERNAL VTDRPL
      
and then use VTDRPL for the last argument.

For more information, see the description of the argument LPR of the AREAS subroutine ARDRLN.


PARAMETERS

The behavior of VASPACKT is controlled by a large number of parameters in internal common blocks to which all of its routines have access. These parameters are described in detail in this section.


Parameter Names

Each of the parameters of VASPACKT is identified by a three-character mnemonic name. For example, 'AHA' is the name of the parameter specifying the angular width of arrowheads.


Parameter Types

Each parameter is intrinsically of type CHARACTER, INTEGER, or REAL, but the type of the parameter is not implied by the form of its name; one must read the description of the parameter to determine its type.


Parameter Defaults

Each parameter has a default value which is intended to yield a reasonable, useful, default behavior. To modify the behavior of VASPACKT routines, one changes the values of the appropriate parameters at the appropriate time.


Parameter Access

The value of a parameter may be set using one of the three routines VTSETC, VTSETI, and VTSETR. Each of these routines has as its first argument a character string beginning with the three-character name of the parameter and as its second argument an expression of the type implied by the last character of the routine name ("C" for "CHARACTER", "I" for "INTEGER", or "R" for "REAL"). Similarly, the current value of a parameter may be retrieved using one of the three routines VTGETC, VTGETI, and VTGETR, each of which has as its first argument the name of the parameter and as its second argument a variable of the type implied by the last character of the routine name.

In general, once a parameter is given a particular value, it retains that value until it is given a new value.


Parameter-Name Arguments

Only the first three characters of the parameter-name argument in calls to the parameter access routines are examined. It is strongly recommended that additional characters be added in order to make the code more readable. For example, a call to set 'AHA' might read

      CALL VTSETI ('AHA - ARROWHEAD ANGULAR WIDTH',45)
    
The additional characters make it much easier to remember what the call is intended to do.


Automatic Type Conversion

Normally, one would use VTSETI to set parameters of type INTEGER and VTSETR to set parameters of type REAL. However, since automatic conversion is done as necessary, this need not be the case. One could, for example, use either of the two statements

      CALL VTSETI ('AHA - ARROWHEAD ANGULAR WIDTH',30)
      CALL VTSETR ('AHA - ARROWHEAD ANGULAR WIDTH',30.)
    
to set the arrowhead angular width (which is intrinsically REAL) to 30 degrees. The first has the virtue of being one character shorter. Similarly, one could use either of the two statements

      CALL VTSETI ('DBG - DEBUG FLAG',1)
      CALL VTSETR ('DBG - DEBUG FLAG',1.)
    
to set 'DBG' (which is intrinsically INTEGER) to 1. (In this case, of course, the first of the two statements seems to make better sense.) If a REAL parameter is to be given a non-integral value (like 3.14159), then VTSETR must be used, of course.


Automatic Restriction of Parameter Values

Some parameters may take on any possible value of the proper type: for example, 'ORV', which specifies an out-of-range value to be used in connection with mapping, may be given any real value. Other parameters may only be given values in a restricted range: for example, 'AHA', which specifies the arrowhead angular width, is restricted to be a real value between 1. and 90., inclusive. The parameter-setting routines attempt to enforce such restrictions. Attempting to give a parameter a value outside its expected range will result in giving it the value at the nearer end of that range. Similarly, attempting to give a non-integral value to a parameter that should be integral will result in truncation of the fractional part.


Parameter Arrays

Some of the parameters are actually arrays. For example, the parameter 'TVL' actually refers to an array of color threshold values. In order to access the Ith element of such a parameter array, one must somehow specify the value of the index I. This is done by making one parameter, named 'PAI', serve as a "parameter array index". Thus, to set the tenth element of 'TVL' to 196.3, one would use the following code:

      CALL VTSETI ('PAI - PARAMETER ARRAY INDEX',10)
      CALL VTSETR ('TVL - COLOR THRESHOLD VALUES',196.3)
    

Parameter Descriptions

Parameter descriptions follow, in alphabetical order. Each description begins with a line giving the three-character mnemonic name of the parameter, the phrase for which the mnemonic stands, the intrinsic type of the parameter, and an indication of whether or not it is an array.

'AEL' - Average Edge Length - Real

The parameter 'AEL' is intended for retrieval only. Prior to any call to VTMESH, it has the value zero. Once VTMESH has been called, the value of 'AEL' is the average length of the edges in that portion of the mesh that has not been blocked by the user by setting the low-order bit of the blocking flag of each triangle in that portion. Other bits of the blocking flags are ignored.

The parameter 'AEL' has no meaningful default value.

'AHA' - Arrowhead Angular Width - Real

The parameter 'AHA' may be given any real value between 1 and 90. It specifies the angle, in degrees, between the sides of the arrowheads used on curly vectors, streamlines, and simple vectors.

The default value of 'AHA' is 30.

'AHL' - Arrowhead Length - Real

The parameter 'AHL' specifies the length of the arrowheads to be used on curly vectors, streamlines, and simple vectors. If 'AHL' is given a negative value, its absolute value specifies a fraction of the length specified by 'VRL'. If 'AHL' is given a positive value, it is interpreted as specified by 'ISP': if 'ISP' is zero, then 'AHL' is an actual length in the coordinate system used for the triangular mesh, but, if 'ISP' is non-zero, then 'AHL' is a multiple of 'EOM'.

The default value of 'AHL' is .04.

'AHS' - Arrowhead Spacing - Real

The parameter 'AHS' specifies the spacing of the arrowheads used on streamlines; it must have a non-negative value, which is interpreted as specified by the value of 'ISP': if 'ISP' is zero, then 'AHS' is an actual length in the coordinate system used for the triangular mesh, but, if 'ISP' is non-zero, then 'AHS' is a multiple of 'EOM'.

The default value of 'AHS' is .16.

'AM1' - Angle Maximum 1 - Real

The parameter 'AM1' specifies the maximum angle, in degrees, to be allowed between the velocity vectors at any pair of vertices of a triangle being considered for use as the starting point of a curly vector, a streamline generator, or a streamline. Its value must be non-negative.

This parameter has the effect of restricting the places where curly vectors, streamline generators, and streamlines start to portions of the mesh where the velocity field is relatively smooth.

See also the description of 'AM2', which is used in a similar fashion.

The default value of 'AM1' is 90.

'AM2' - Angle Maximum 2 - Real

The parameter 'AM2', if non-zero, specifies the maximum angle, in degrees, to be allowed between the velocity vectors at any pair of vertices of a triangle entered by a curly vector, a streamline generator, or a streamline. Its value must be non-negative.

Setting this parameter non-zero has the effect of terminating curly vectors and streamlines that enter portions of the mesh where the velocity field is relatively non-smooth.

The default value of 'AM2' is 0.

'CLR' - Color Index Array - Integer Array

When 'CTV' is given a non-zero value, specifying that streamlines are to be drawn in color, then 'NLV' must also be given a non-zero value and each of the first 'NLV' elements in the parameter array 'CLR' must be set; each element is a color index to be associated with a particular range of values of the auxiliary data field selected by 'CTV'. The value ranges are determined by values in the parameter array 'TVL'.

The parameter array 'CLR' contains no meaningful default values.

'CTM' - Character Temporary - Character - DI

The parameter name 'CTM' refers to a temporary character buffer in VASPACKT; the name may be used to retrieve the contents of that buffer.

The parameter 'CTM' has no meaningful default value.

'CTV' - Color Threshold Value Control - Integer

The parameter 'CTV', if given a non-zero value, turns on coloring of streamlines. Each segment of each streamline is drawn in a color determined by examining values of the auxiliary field specified by the value of 'CTV':

In order for streamlines to be colored, one must also set 'NLV' (specifying the number of colors to be used) and the first 'NLV' elements of the internal parameter array 'CLR' (defining 'NLV' color indices); furthermore, one must choose how the first 'NLV' elements of the internal parameter array 'TVL' are to be set (to specify ranges of values of the auxiliary field for which the different color indices will be used):

The default value of 'CTV' is 0.

'CWM' - Character Width Multiplier - Real - DI

All character size parameters are multiplied by 'CWM'; this makes it easy to scale all the sizes up and down together. Parameters affected by this are 'ILS', 'ILW', 'ZFS', and 'ZFW'.

The default value of 'CWM' is 1.

'DBG' - Debug Flag - Integer

The parameter 'DBG' is a debug flag which may be set non-zero to turn on the drawing of streamline generator lines, subtriangle outlines, and termination test lines associated with the drawing of curly vectors and streamlines. This was and is a tool of interest to the developer of VASPACKT, but could occasionally be useful for debugging user problems.

Related parameters are 'SGC', 'STC', and 'TTC', which can be used to set the colors of different types of debug lines being drawn.

The default value of 'DBG' is 0.

'DMN' - Data Minimum - Real

The parameter 'DMN' is intended for retrieval only. Prior to any call to VTMESH, it has the value zero. Once VTMESH has been called, the value of 'DMN' is the minimum velocity vector magnitude found in the user's data.

The parameter 'DMN' has no meaningful default value.

'DMX' - Data Maximum - Real

The parameter 'DMX' is intended for retrieval only. Prior to any call to VTMESH, it has the value zero. Once VTMESH has been called, the value of 'DMX' is the maximum velocity vector magnitude found in the user's data.

The parameter 'DMX' has no meaningful default value.

'DVA' - Data Value - Real - DI

The parameter 'DVA' is used for character conversions. If a character string representing a particular real value is desired, one can call VTSETR to set the value of 'DVA' and then call VTGETC to retrieve its value (possibly as modified by the current scale factor); if an unscaled value is desired, use the parameter name 'DVU' in the call to VTGETC.

The parameter 'DVA' has no meaningful default value.

'DVU' - Data Value, Unscaled - Real - DI

See the discussion of 'DVA', above.

The parameter 'DVU' has no meaningful default value.

'EOM' - Extent of Mesh - Real

The parameter 'EOM' is intended for retrieval only. Prior to any call to VTMESH, it has the value zero. Once VTMESH has been called, the value of 'EOM' is the maximum extent of the user's mesh in the three coordinate directions, equal to MAX('XMX'-'XMN', 'YMX'-'YMN', 'ZMX'-'ZMN').

The parameter 'EOM' has no meaningful default value.

'ILA' - Informational Label Angle - Real - DI

The parameter 'ILA' specifies the angle (in degrees counterclockwise from a vector pointing to the right) at which the informational label is to be written.

The default value of 'ILA' is 0.

'ILB' - Informational Label Box Flag - Integer - DI

If 'ILB' is zero, the informational label will not be boxed at all. The value 1 implies that the perimeter of the box is to be drawn (in the same color as the label) after the label is drawn. The value 2 implies that the box is to be filled (in the color specified by 'LBC') before the label is drawn. The value 3 implies both of the above.

The default value of 'ILB' is 0.

'ILC' - Informational Label Color Flag - Integer - DI

If 'ILC' is less than zero, the informational label and the box, if any, around it, will be drawn in the color specified by the current text color index; if 'ILC' is greater than or equal to zero, then it specifies the desired color index for the label and the box. If a box is drawn around the label, it is made the same color as the label itself.

The default value of 'ILC' is -1.

'ILL' - Informational Label Line Width - Real - DI

If 'ILL' has a value less than or equal to zero, line width will not be set before drawing a box around the informational label. If 'ILL' has a value greater than zero, it specifies the desired width, as a multiple of the "normal" line width.

The default value of 'ILL' is 0.

'ILP' - Informational Label Positioning Flag - Integer - DI

The parameter 'ILP' says how the informational label is to be positioned. There are nine possible values, each of which specifies a point of the label box which is to lie on the point defined by 'ILX' and 'ILY': the value -4 implies the lower left-hand corner of the label box, -3 implies the center of the bottom of the box, -2 the lower right-hand corner of the box, -1 the center of the left edge of the box, 0 the center of the box, +1 the center of the right edge of the box, +2 the upper left-hand corner of the box, +3 the center of the top edge of the box, and +4 the upper right-hand corner of the box. Left, right, bottom, and top are defined from the viewpoint of someone reading the label right-side up.

The default value of 'ILP' is 4, so the upper right-hand corner of the box will be placed on the point ('ILX', 'ILY').

'ILS' - Informational Label Size - Real - DI

The parameter 'ILS' specifies the nominal size (width) of a character in the informational label, as a fraction of the width of the viewport. This nominal size is multiplied by 'CWM'.

The default value of 'ILS' is .012.

'ILT' - Informational Label Text String - Character - DI

The parameter 'ILT' is a string of 128 or fewer characters, specifying the text of the informational label. The following substrings will be replaced by a numeric value:

      $DMN$ - THE MINIMUM VALUE IN THE DATA ARRAY.
      $DMX$ - THE MAXIMUM VALUE IN THE DATA ARRAY.
      $SFU$ - THE CURRENT SCALE FACTOR.
      
In each case except $SFU$, the given value will have been divided by the current scale factor. A "U" may be inserted just before the final "$" (as in '$DMNU$') to request the use of an unscaled value.

If 'ILT' is given the value ' ' (a single blank), there will be no informational label.

The default value of 'ILT' is 'SCALE FACTOR IS $SFU$'.

'ILW' - Informational Label White Space Width - Real - DI

The parameter 'ILW' specifies the nominal width of white space to be left around the informational label, as a fraction of the width of the viewport. This nominal width is multiplied by 'CWM'.

The default value of 'ILW' is .005.

'ILX' - Informational Label X Position - Real - DI

The parameter 'ILX' specifies the X coordinate of the basepoint of the informational label. The given value is mapped linearly onto the viewport; 0 refers to the left edge of the viewport and 1 to the right edge of the viewport. Values less than 0 or greater than 1 may be used.

The default value of 'ILX' is .98.

'ILY' - Informational Label Y Position - Real - DI

The parameter 'ILY' specifies the Y coordinate of the basepoint of the informational label. The given value is mapped linearly onto the viewport; 0 refers to the bottom edge of the viewport and 1 to the top edge of the viewport. Values less than 0 or greater than 1 may be used.

The default value of 'ILY' is -.02.

'ISP' - Interpretation of Size Parameters - Integer

The parameter 'ISP' says how to interpret the values of certain other parameters having to do with the sizes of things on the triangular mesh: AHL, AHS, SLL, SLP, SLS, SVS, TTL, TTS, and VRL.

The default value of 'ISP' is zero.

'IWB' - Integer Workspace for Blocking - Integer

The parameter 'IWB' specifies the amount of integer workspace to be allotted for use by VTTDBF, which sets the blocking flags for triangles in a triangular mesh being projected by the 3D package TDPACK. Increasing its value may help one of the algorithms executed by VTTDBF to run more efficiently.

The default value of 'IWB' is 2500.

'IWU' - Integer Workspace Used - Integer

The parameter 'IWU' is intended for retrieval only. It is zeroed by the call to VTMESH. Thereafter, as VASPACKT routines are called, the value of 'IWU' is updated to reflect the largest number of words of integer workspace needed at any one time. Therefore, by retrieving its value after an entire plot has been constructed, one may find out how large an integer workspace was actually required.

'LBC' - Label Box Color Index - Integer - DI

If label boxes (of whatever type) are filled, the filling is done using the color index specified by 'LBC'. If 'LBC' is less than zero, the current fill area color index is used.

The default value of 'LBC' is 0, which specifies the background color.

'LBX' - Label Box X Coordinate - Real - DI

Not to be set by the user. The value may be retrieved in one of the routines VTCHIL or VTCHZF. It specifies the X coordinate (in the current user coordinate system) of the center of the box surrounding the label that has caused the routine to be called.

The default value of 'LBX' is 0.

'LBY' - Label Box Y Coordinate - Real - DI

Not to be set by the user. The value may be retrieved in one of the routines VTCHIL or VTCHZF. It specifies the Y coordinate (in the current user coordinate system) of the center of the box surrounding the label that has caused the routine to be called.

The default value of 'LBY' is 0.

'MAP' - Mapping Flag - Integer

If 'MAP' is zero, it says that the X and Y coordinates used to create a plot are to be just the X and Y coordinates of the triangular mesh; the Z coordinates are discarded. If 'MAP' is non-zero, it says that the X, Y, and Z coordinates are to be transformed by calling the user-replaceable subroutine VTMXYZ to obtain X and Y coordinates in the user system in which drawing is done. So far, the default version of VTMXYZ provides two useful mappings:

Using any other non-zero value of 'MAP' will result in the identity mapping.

Of course, one can replace the routine VTMXYZ and build as many different mappings into it as desired, but the above mappings should be included. See the description of VTMXYZ.

The default value of 'MAP' is 0.

'NEL' - Numeric Exponent Length - Integer - DI

Giving 'NEL' a value less than or equal to zero says that exponents in numeric labels should be written in the shortest possible form; plus signs are omitted and the exponent magnitude is written with no leading zeroes. A value "n" which is greater than zero indicates that all exponents should be written with a sign (+ or -) and that the exponent magnitude should be padded with leading zeroes to a length of n characters.

The default value of 'NEL' is 0.

'NET' - Numeric Exponent Type - Integer - DI

The parameter 'NET' says what characters are to be used between the mantissa of a numeric label and the exponent. The value 0 implies the use of an E, as in FORTRAN "E format", the value 1 implies the use of function codes, as expected by the utility PLOTCHAR, to generate "x 10n", where n is a superscript exponent, and the value 2 implies the use of "x10**".

The default value of 'NET' is 1.

'NEU' - Numeric Exponent Use Flag - Integer - DI

Giving 'NEU' a value less than or equal to zero forces the use of the exponential form in all numeric labels. A positive value "n" indicates that the form without an exponent should be used as long as it requires no more than n characters; otherwise the form requiring the fewest characters should be used.

The default value of 'NEU' is 5.

'NLS' - Numeric Leftmost Significant Digit Flag - Integer - DI

Giving 'NLS' the value zero says that the leftmost non-zero digit of a number represented by a numeric label is to be considered its first significant digit. A non-zero value says that the digit in the same digit position as the leftmost non-zero digit of the largest number (in absolute value) in the data field being used is to be considered the leftmost significant digit. This tends to make the numeric labels more nearly consistent with one another. Consider the following example, using three significant digits:

      USING 'NLS'=0: .500 1.00 1.50 ... 9.50 10.5 ...
      USING 'NLS'=1: .5   1.0  1.5  ... 9.5  10.5 ...
      
The default value of 'NLS' is 1.

'NLV' - Number of (Color) Levels - Real

The parameter 'NLV' specifies how many different colors are to be used in drawing streamlines and therefore how many color indices the user has to place in the color index array 'CLR', as well as how many values must, in some manner, be placed in the threshold value array 'TVL'.

The default value of 'NLV' is zero.

'NLZ' - Numeric Leading Zero Flag - Integer - DI

Giving 'NLZ' a non-zero value says that a zero is to placed before any numeric label which would otherwise begin with a decimal point (use "0.345", rather than ".345").

The default value of 'NLZ' is 0.

'NOF' - Numeric Omission Flags - Integer - DI

The parameter 'NOF' says what parts of a numeric label may be omitted. The value 0 says that no part may be omitted. Add a 4 to indicate that a leading "1" or "1." which is unnecessary (as in "1 x 1013") may be omitted, a 2 to indicate that a trailing decimal point (as in "13.") may be omitted, and a 1 to indicate that trailing zeroes (as in "46.200") may be omitted.

Contour line labels generated by VASPACKT and values in the informational label which are known to have been rounded to "nice" values (like '$CIU$', '$CMN$', and '$CMX$') will have trailing zeroes trimmed in any case, no matter what the value of 'NOF' is.

The default value of 'NOF' is 6 (4 + 2).

'NSD' - Number of Significant Digits - Integer - DI

The parameter 'NSD' specifies the maximum number of significant digits to be used in numeric labels representing field values. A negative value "-n" indicates that n significant digits should be used. A positive value "n" indicates that "m+n" digits should be used, where "m" is the number of digits that are the same for all values in the data field. (For example, if the minimum value is "1123.6" and the maximum value is "1125.9", then the value of "m" is 3.)

The default value of 'NSD' is 4.

'ORV' - Out-Of-Range Value - Real

If 'ORV' is non-zero, it specifies an out-of-range value, to be used as the value of X and Y coordinates returned by the mapping routine VTMXYZ to say that a point is out-of range (invisible) under the current mapping.

When 'MAP' = 1, a good value for 'ORV' is 1.E12, since that value is returned by EZMAP routines to signal such a point.

The default value of 'ORV' is 0.

'PAI' - Parameter Array Index - Real

The value of 'PAI' must be set before calling VTGETC, VTGETI, VTGETR, VTSETC, VTSETI, or VTSETR, to access any parameter which is an array; it indicates which element of the array is meant. For example, to set the 10th color index to 14, use code like this:

      CALL VTSETI ('PAI - PARAMETER ARRAY INDEX',10)
      CALL VTSETI ('CLR - COLOR INDEX',14)
      
The default value of 'PAI' is 0.

'PCX' - Projection Center Point X - Real

The parameter 'PCX' specifies the X coordinate of a projection center used in the process of projecting the vectors defining a flow field from 3-space into the plane of an individual triangle of the mesh. The projection lines used all pass through this point.

The default position of the projection center is (0,0,0), which is appropriate for a triangular mesh representing a sphere.

'PCY' - Projection Center Point Y - Real

The parameter 'PCY' specifies the Y coordinate of a projection center used in the process of projecting the vectors defining a flow field from 3-space into the plane of an individual triangle of the mesh. The projection lines used all pass through this point.

The default position of the projection center is (0,0,0), which is appropriate for a triangular mesh representing a sphere.

'PCZ' - Projection Center Point Z - Real

The parameter 'PCZ' specifies the Z coordinate of a projection center used in the process of projecting the vectors defining a flow field from 3-space into the plane of an individual triangle of the mesh. The projection lines used all pass through this point.

The default position of the projection center is (0,0,0), which is appropriate for a triangular mesh representing a sphere.

'PIS' - Point Interpolation Flag for Streamlines - Integer

The parameter 'PIS' specifies the number of points to interpolate between each pair of points defining a segment of a streamline, prior to any mapping implied by 'MAP'. It is intended that a non-zero value should normally be used only if 'MAP' is non-zero, which turns mapping on; the intent is to map straight-line segments of streamlines more nearly correctly into curved-line segments on a background (one drawn by EZMAP, for example).

A negative value of 'PIS' causes ABS('PIS') points to be interpolated, but the interpolated points are not, in general, used to draw the line segment; the object, in this case, is simply to do a finer search for changes in visibility (out-of-range state, as defined by values of 'ORV' returned by the routine VTMXYZ) along the segment.

See also the description of 'PIT', which can be used to cause the interpolation of points on segments of streamlines only in regions where the mapping causes great distortion.

The default value of 'PIC' is 0.

'PIT' - Point Interpolation Threshold - Real

When 'MAP' is non-zero, 'PIT' may also be set non-zero to improve the accuracy with which streamlines are mapped. As the points defining such a line are mapped (using VTMXYZ), VASPACKT looks for a jump in the mapped X coordinates of more than 'PIT' times the width of the current user-coordinate-system window or a jump in the mapped Y coordinates of more than 'PIT' times the height of the current user-coordinate-system window. When such a jump is seen, additional points are interpolated and mapped to reduce all such jumps below the threshold value. This parameter becomes particularly important when using some of the EZMAP projections that project the entire globe to the interior of a circle, in which case the points defining a segment of a streamline can map to points so far apart that the mapped streamlines cross one another.

The use of 'PIT' does not entirely replace the use of 'PIS'; indeed, there are situations in which both can be used to good advantage, particularly when negative values of 'PIS' are used to improve the resolution of the search for changes in out-of-range state along the line segments.

The default value of 'PIT' is 0. It's probably not a good idea to use values less than about .001 or greater than about .1.

'RNG' - Random Number Generator Spinup Flag - Integer

The parameter 'RNG' may be given a different positive value in order to change the set of random numbers that are generated to be used in shifting the positions of arrowheads on adjacent streamlines to prevent them from lining up in an unsightly fashion.

The default value of 'RNG' is zero.

'RWU' - Real Workspace Usage - Integer

The parameter 'RWU' is intended for retrieval only. It is zeroed by the call to VTMESH. Thereafter, as VASPACKT routines are called, the value of 'RWU' is updated to reflect the largest number of words of real workspace needed at any one time. Therefore, by retrieving its value after an entire plot has been constructed, one may find out how large a real workspace was actually required.

'SET' - Do-SET-Call Flag - Integer

Giving 'SET' the value 0 says that no SET call is to be done by VASPACKT; the value 1 says that it is to be done. In the latter case, the call is done by VTMESH (and the values of 'VPL', 'VPR', 'VPB', 'VPT', 'VPS', 'WDL', 'WDR', 'WDB', and 'WDT' come into play.

Arguments 5-8 of a SET call done by the user must be consistent with the ranges of the X and Y coordinates being used by VASPACKT, as specified by the X, Y, and Z coordinates of the points of the triangular mesh, the value of 'MAP', and, if 'MAP' is non-zero, the code of the routine VTMXYZ.

The default value of 'SET' is 1.

'SFS' - Scale Factor Selector - Real - DI

The scale factor is that value (usually, but not necessarily, a power of 10) by which the actual values of flow field magnitudes are to be divided to get the value of a numeric label. If 'SFS' is given a value greater than zero, that value is the scale factor to be used. If 'SFS' is given a value less than or equal to zero, it is truncated to form an integer directing VASPACKT to select a scale factor, as follows:

The default value of 'SFS' is 1.

'SFU' - Scale Factor Used - Real - DI

The parameter 'SFU' is intended for retrieval only; it gives the value of the scale factor selected for use by VASPACKT.

'SGC' - Streamline Generator Color - Integer

The parameter 'SGC' specifies the color index to be used when drawing streamline generator lines, which only happens when the debug flag 'DBG' is turned on. (These lines are usually generated, but not drawn, as part of the process of positioning the streamlines pleasingly.)

The default value of 'SGC' is 1.

'SLL' - Streamline Length (Maximum) - Real

The parameter 'SLL' specifies the maximum length of any streamline drawn. It must be given a positive value, which will be interpreted as specified by 'ISP': if 'ISP' is zero, then 'SLL' is an actual length in the coordinate system used for the triangular mesh, but, if 'ISP' is non-zero, then 'SLL' is a multiple of 'EOM'.

The default value of 'SLL' is 8.

'SLP' - Streamline Point Spacing - Real

The parameter 'SLP' specifies the distance between points used to trace and/or draw streamline generators, streamlines, and termination test lines. It must be given a positive value, which will be interpreted as specified by 'ISP': if 'ISP' is zero, then 'SLP' is an actual length in the coordinate system used for the triangular mesh, but, if 'ISP' is non-zero, then 'SLP' is a multiple of 'EOM'.

The default value of 'SLP' is .001.

'SLS' - Streamline Spacing - Real

The parameter 'SLS' specifies the desired spacing of the streamlines drawn. It must be given a positive value, which is interpreted as specified by 'ISP': if 'ISP' is zero, then 'SLS' is an actual length in the coordinate system used for the triangular mesh, but, if 'ISP' is non-zero, then 'SLS' is a multiple of 'EOM'.

The default value of 'SLS' is .072.

'STC' - Subtriangle Color - Integer

The parameter 'STC' specifies the color index to be used when drawing the outlines of subtriangles that are crossed by streamline generators or streamlines, which only happens when the debug flag 'DBG' is turned on. (Information about these subtriangles is generated as part of the process of positioning the streamlines pleasingly.)

The default value of 'STC' is 1.

'SVS' - Simple Vector Spacing - Real

The parameter 'SVS' helps determine how simple vectors drawn by calls to VTSVDM and VTSVDR are to be thinned. It comes into play only when 'SVT' is given a non-zero value. See the description of 'SVT', below.

If 'SVS' is greater than zero, its value is interpreted as specified by 'ISP': if 'ISP' is zero, then 'SVS' is an actual length in the coordinate system used for the triangular mesh, but, if 'ISP' is non-zero, then 'SVS' is a multiple of 'EOM'.

The default value of 'SVS' is zero.

'SVT' - Simple Vector Thinning Flag - Integer

The parameter 'SVT' specifies whether or not simple vectors drawn by calls to VTSVDM and VTSVDR are to be thinned, as follows: The default value of 'SVT' is 5.

'TBA' - Triangle Blocking Mask - AND - Integer

Associated with each triangle of a triangular mesh is a "blocking flag", the low-order twelve bits of which may be used to "block" the triangle (in effect, remove it from the mesh). Each of the twelve bits may be associated with a particular condition and each of those conditions can be tested individually. If ITBF is the twelve-bit value of a particular triangle's blocking flag, ITBA is the value of 'TBA', and ITBX is the value of 'TBX', then the triangle will be considered blocked if and only if the quantity IAND(IXOR(ITBF,ITBX),ITBA) is non-zero (where IAND and IXOR are functions that perform the logical operations AND and EXCLUSIVE-OR, respectively, of two twelve-bit operands). (Note, however, that the routines VTMESH and VTTDBF use the function IAND(IAND(IXOR(ITBF,ITBX),ITBA),1) instead, so as to examine only the user-set blocking bit.)

Using a "1" for one of the twelve bits of 'TBX' causes the corresponding bit of a triangle blocking flag to be toggled, so that its meaning is reversed. Using a "1" for one of the twelve bits of 'TBA' causes the corresponding bit of a triangle blocking flag to be examined, so that its value is significant in determining blocking of the triangle.

By convention, the rightmost bit of a triangle blocking flag is reserved for direct blocking of triangles by the user of VASPACKT. See the routines VTTDBF and VTTDBM for a description of a scheme that uses a total of six other bits to effect blocking of triangles that are hidden, edge-on, and/or seen from the wrong side by one of the two eyes in the case where VASPACKT is being used in conjunction with TDPACK to draw a perspective view of a triangular mesh.

The default value of 'TBA' is 1 (only the lowest bit of a triangle blocking flag is significant) and the default value of 'TBX' is 0 (none of the bits of a triangle blocking flag are toggled).

'TBX' - Triangle Blocking Mask - XOR - Integer

See the description of 'TBA', above.

'TTC' - Termination Test Color - Integer

The parameter 'TTC' specifies the color index to be used when drawing termination test lines, which only happens when the debug flag 'DBG' is turned on. (These lines are usually generated, but not drawn, as part of the process of positioning the streamlines pleasingly.)

The default value of 'TTC' is 1.

'TTL' - Termination Test Length - Real

The parameter 'TTL' specifies the desired length of lines used in performing termination tests along streamlines.

See the discussion of termination tests in the description of 'TTS', next.

'TTL' must be given a positive value, which will be interpreted as specified by 'ISP': if 'ISP' is zero, then 'TTL' is an actual length in the coordinate system used for the triangular mesh, but, if 'ISP' is non-zero, then 'TTL' is a multiple of 'EOM'.

The default value of 'TTL' is .018.

'TTS' - Termination Test Spacing - Real

The parameter 'TTS' specifies the desired spacing of termination tests along streamlines.

What are "termination tests"? Periodically, as each streamline is traced (at intervals of 'TTS'), the code traces two little lines (of length 'TTL') - one line in each of the two possible directions - that start on the streamline and are everywhere perpendicular to the flow field. If either of these little lines crosses a previously-drawn streamline, tracing of the current streamline is terminated.)

'TTS' must be given a positive value, which will be interpreted as specified by 'ISP': if 'ISP' is zero, then 'TTS' is an actual length in the coordinate system used for the triangular mesh, but, if 'ISP' is non-zero, then 'TTS' is a multiple of 'EOM'.

The default values of 'SLS', 'TTS', and 'TTL' are such that 'SLS' is twice as large as 'TTS', which is itself twice as large as 'TTL'; experiments indicate that this works relatively well. Note that giving 'TTL' a value greater than that of 'SLS' is a bad idea, since then each streamline would be terminated as soon as it began.

The default value of 'TTS' is .036.

'TVL' - Threshold Values - Real Array

The parameter array 'TVL' comes into play when 'CTV' is given a non-zero value, specifying that streamlines are to be drawn in color, in which case 'NLV' must also be given a non-zero value and each of the first 'NLV' elements in the parameter array 'CLR' must be set; each is a color index to be associated with a particular range of values of the auxiliary data field selected by 'CTV'.

The value ranges are determined by the values in 'TVL'. Let S be the interpolated value of the auxiliary data field at the center of a streamline segment, TI the value of the Ith element of 'TVL', CI the value of the Ith element of 'CLR', and N the value of 'NLV'. Then:

If 'CTV' is given a negative value, the user is responsible for putting values into 'TVL'; the values must be in monotonically increasing order.

If 'CTV' is given a positive value, VASPACKT will supply values in 'TVL' (during the call to VTMESH). The value used for TI (assuming minimum and maximum values in the auxiliary data field of Tmin and Tmax) will be Tmin+REAL(I)*(Tmax-Tmin)/REAL(N).

The parameter array 'CLR' contains no meaningful default values.

'VFR' - Vector Fractional Length - Real

The parameter 'VFR' must have a value between 0 and 1, inclusive, and is used as follows in determining the lengths of simple vectors and curly vectors: If 'VRL'R is the realized value of the vector reference length, 'VRM'R is the realized value of the vector reference magnitude, and V is the magnitude of the flow field at the position of a vector to be drawn, then the length of the vector on the triangular mesh is given by the following expression:

'VFR' * 'VRL'R + (1. - 'VFR') * 'VRL'R * ( V / 'VRM'R )

Note that, if 'VFR' is zero, the vector lengths used range from zero to 'VRL' and are linearly related to the magnitude of the flow field, while, if 'VFR' is one, all of the vectors are of length 'VRL', no matter what the magnitude of the flow field is. For values of 'VFR' between zero and one, a specified portion of the length is always present and the remainder of the length reflects the strength of the flow field.

The default value of 'VFR' is zero.

'VPB' - Viewport Bottom - Real

The parameter 'VPB' is only used when 'SET' is non-zero, saying that VASPACKT should do the call to SET; it specifies the position of the bottom edge of the area in which the viewport is to be placed, expressed as a fraction between 0 (the bottom edge of the plotter frame) and 1 (the top edge of the plotter frame). See also the description of 'VPS'.

The default value of 'VPB' is .05.

'VPL' - Viewport Left - Real

The parameter 'VPL' is only used when 'SET' is non-zero, saying that VASPACKT should do the call to SET; it specifies the position of the left edge of the area in which the viewport is to be placed, expressed as a fraction between 0 (the left edge of the plotter frame) and 1 (the right edge of the plotter frame). See also the description of 'VPS'.

The default value of 'VPL' is .05.

'VPR' - Viewport Right - Real

The parameter 'VPR' is only used when 'SET' is non-zero, saying that VASPACKT should do the call to SET; it specifies the position of the right edge of the area in which the viewport is to be placed, expressed as a fraction between 0 (the left edge of the plotter frame) and 1 (the right edge of the plotter frame). See also the description of 'VPS'.

The default value of 'VPR' is .95.

'VPS' - Viewport Shape - Real

The parameter 'VPS' is only used when 'SET' is non-zero, saying that VASPACKT should do the call to SET; it specifies the desired viewport shape, as follows:

The viewport, whatever its final shape, is centered in, and made as large as possible in, the area specified by 'VPL', 'VPR', 'VPB', and 'VPT'.

The default value of 'VPS' is .25.

'VPT' - Viewport Top - Real

The parameter 'VPT' is only used when 'SET' is non-zero, saying that VASPACKT should do the call to SET; it specifies the position of the top edge of the area in which the viewport is to be placed, expressed as a fraction between 0 (the bottom edge of the plotter frame) and 1 (the top edge of the plotter frame). See also the description of 'VPS'.

The default value of 'VPT' is .95.

'VRL' - Vector Reference Length - Real

The parameter 'VRL' specifies the length, on the surface of the triangular mesh, to be used for a simple vector or a curly vector at a position where the flow field has the magnitude specified by 'VRM'. There are several possibilities:

See the discussion of 'VFR', above, for the complete formula showing how 'VRL'R and 'VRM' R are used to determine the length of a particular simple vector or curly vector.

The default value of 'VRL' is zero.

'VRM' - Vector Reference Magnitude - Real

The parameter 'VRM' specifies that magnitude of the flow field for which a simple vector or curly vector of the length specified by 'VRL' is to be drawn. There are two possibilities:

See the discussion of 'VFR', above, for the complete formula showing how 'VRM'R and 'VRL' R are used to determine the length of a particular simple vector or curly vector.

The default value of 'VRM' is zero.

'VVM' - Velocity Vector Minimum Magnitude - Real

The parameter 'VVM' specifies that magnitude of the flow field which is to be considered essentially zero. If a streamline generator, a streamline, or a curly vector reaches a point at which the interpolated flow vector has a magnitude less than 'VVM', it is terminated.

The default value of 'VVM' is zero.

'WDB' - Window Bottom - Real

When VASPACKT does the call to SET (as determined by the value of 'SET'), 'WDB' is used to determine argument number 7, the user Y coordinate at the bottom of the window. If 'WDB' is not equal to 'WDT' , 'WDB' is used. If 'WDB' is equal to 'WDT', VTMESH computes a value to use by examining all the non-blocked triangles of the mesh to see where they fall in user space.

The default value of 'WDB' is 0.

'WDL' - Window Left - Real

When VASPACKT does the call to SET (as determined by the value of 'SET'), 'WDL' is used to determine argument number 5, the user X coordinate at the left edge of the window. If 'WDL' is not equal to 'WDR', 'WDL' is used. If 'WDL' is equal to 'WDR', VTMESH computes a value to use by examining all the non-blocked triangles of the mesh to see where they fall in user space.

The default value of 'WDL' is 0.

'WDR' - Window Right - Real

When VASPACKT does the call to SET (as determined by the value of 'SET'), 'WDR' is used to determine argument number 6, the user X coordinate at the right edge of the window. If 'WDR' is not equal to 'WDL', 'WDR' is used. If 'WDR' is equal to 'WDL' , VTMESH computes a value to use by examining all the non-blocked triangles of the mesh to see where they fall in user space.

The default value of 'WDR' is 0.

'WDT' - Window Top - Real

When VASPACKT does the call to SET (as determined by the value of 'SET'), 'WDT' is used to determine argument number 8, the user Y coordinate at the top of the window. If 'WDT' is not equal to 'WDB' , 'WDT' is used. If 'WDT' is equal to 'WDB', VTMESH computes a value to use by examining all the non-blocked triangles of the mesh to see where they vall in user space.

The default value of 'WDT' is 0.

'WSO' - Workspace Overflow Flag - Integer

The parameter 'WSO' says what to do when a real or integer workspace overflow occurs, as follows:

When execution continues, the resulting plot will be incomplete. The values of 'IWU' and 'RWU' may be retrieved to find out how much workspace would have been used if the call on which the workspace overflow occurred had succeeded; note, however, that if these amounts are provided on a subsequent run, one is still not assured that the workspace overflow will be averted.

The default value of 'WSO' is 1.

'XMN' - X Minimum Value - Real

The minimum value of X in the mesh, as found by VTMESH. For output only.

'XMX' - X Maximum Value - Real

The maximum value of X in the mesh, as found by VTMESH. For output only.

'YMN' - Y Minimum Value - Real

The minimum value of Y in the mesh, as found by VTMESH. For output only.

'YMX' - Y Maximum Value - Real

The maximum value of Y in the mesh, as found by VTMESH. For output only.

'ZFA' - Zero Field Label Angle - Real - DI

The parameter 'ZFA' specifies the angle (in degrees counterclockwise from a vector pointing to the right) at which a zero-field label is to be written.

The default value of 'ZFA' is 0.

'ZFB' - Zero Field Label Box Flag - Integer - DI

If 'ZFB' is zero, the zero-field label will not be boxed at all. The value 1 implies that the perimeter of the box is to be drawn (in the same color as the label) after the label is drawn. The value 2 implies that the box is to be filled (in the color specified by 'LBC') before the label is drawn. The value 3 implies both of the above.

The default value of 'ZFB' is 0.

'ZFC' - Zero Field Label Color Flag - Integer - DI

If 'ZFC' is less than zero, the zero-field label and the box, if any, around it, will be drawn in the color specified by the current text color index; if 'ZFC' is greater than or equal to zero, then it specifies the desired color index for the label and the box. If a box is drawn around the label, it is made the same color as the label itself.

The default value of 'ZFC' is -1.

'ZFF' - Zero Field Flag - Integer - DI

The parameter 'ZFF' may not be set by the user; its retrieved value will be non-zero if and only if VTMESH detected an essentially zero flow field.

The default value of 'ZFF' (prior to any call to VTMESH) is zero.

'ZFL' - Zero Field Label Line Width - Real - DI

If 'ZFL' is less than or equal to zero, line width will not be set before drawing a box around the zero-field label. If 'ZFL' is greater than zero, it specifies the desired width, as a multiple of the "normal" line width.

The default value of 'ZFL' is 0.

'ZFP' - Zero Field Label Positioning Flag - Integer - DI

The parameter 'ZFP' says how the zero-field label is to be positioned. There are nine possible values, each of which specifies a point of the label box which is to lie on the point defined by 'ZFX' and 'ZFY': the value -4 implies the lower left-hand corner of the label box, -3 implies the center of the bottom of the box, -2 the lower right-hand corner of the box, -1 the center of the left edge of the box, 0 the center of the box, +1 the center of the right edge of the box, +2 the upper left-hand corner of the box, +3 the center of the top edge of the box, and +4 the upper right-hand corner of the box. Left, right, bottom, and top are defined from the viewpoint of someone viewing the label right-side up.

The default value of 'ZFP' is 0, so the zero-field label will be centered on the point whose coordinates are 'ZFX' and 'ZFY'.

'ZFS' - Zero Field Label Character Size - Real - DI

The parameter 'ZFS' specifies the nominal size (width) of a character in the zero-field label, as a fraction of the width of the viewport. This nominal size is multiplied by 'CWM'.

The default value of 'ZFS' is .012.

'ZFT' - Zero Field Label Text String - Character - DI

The parameter 'ZFT' specifies the text of the constant-field label, which is written when a constant data field is detected; it is a character string of at most 64 characters. The embedded string '$DVA$' will be replaced by the numeric value of the field.

If 'ZFT' is given the value ' ' (a single blank), the constant-field label will not be written.

The default value of 'ZFT' is 'ZERO FIELD'.

'ZFW' - Zero Field Label White Space Width - Real - DI

The parameter 'ZFW' specifies the nominal width of white space to be left around the zero-field label, as a fraction of the width of the viewport. This nominal width is multiplied by 'CWM'.

The default value of 'ZFW' is .005.

'ZFX' - Zero Field Label X Position - Real - DI

The parameter 'ZFX' specifies the X coordinate of the basepoint of the zero-field label. The given value is mapped linearly onto the viewport; 0 refers to the left edge of the viewport and 1 to the right edge of the viewport. Values less than 0 or greater than 1 may be used.

The default value of 'ZFX' is .5, so the zero-field label is centered horizontally in the viewport.

'ZFY' - Zero Field Label Y Position - Real - DI

The parameter 'ZFY' specifies the Y coordinate of the basepoint of the zero-field label. The given value is mapped linearly onto the viewport; 0 refers to the bottom edge of the viewport and 1 to the top edge of the viewport. Values less than 0 or greater than 1 may be used.

The default value of 'ZFY' is .5, so the zero-field label is centered vertically in the viewport.

'ZMN' - Z Minimum Value - Real

The minimum value of Z in the mesh, as found by VTMESH. For output only.

'ZMX' - Z Maximum Value - Real

The maximum value of Z in the mesh, as found by VTMESH. For output only.


ERROR HANDLING

When a VASPACKT routine detects an error condition, it calls the routine SETER, which is the principal routine in the error-handling package for NCAR Graphics.

By default, SETER prints a line and STOPs. The line printed will look something like this:

    ERROR    3 IN VTGRWS - REAL WORKSPACE OVERFLOW
  
The error number ("3", in the example) may be of use to a consultant (to determine exactly where the error occurred), but is not otherwise meaningful. The actual error message consists of the name of the routine in which the error occurred ("VTGRWS", in the example), a blank, a minus sign, another blank, and, lastly, a short description of the error.

All errors are "recoverable" in the sense that, if the user program puts SETER into "recovery mode", control will be returned to the caller of the VASPACKT routine in which the error occurred. In some cases, it is then possible to take remedial action to get around whatever problem has occurred; in any case, the error flag can be cleared and execution of the user's program can continue.

When SETER is in recovery mode (and, occasionally, even when it is not), error messages may have a somewhat more complicated form, like this:

    VTSLDM/VTGRWS - REAL WORKSPACE OVERFLOW
  
What this particular error message says is that VTSLDM called VTGRWS, which detected an error condition (real workspace overflow) and called SETER. Upon getting control back from VTGRWS, VTSLDM detected the fact that VTGRWS had logged an error. It augmented the error message by prepending its own name, followed by a slash, and then passed control back to the user. Of course, there can be more than two such levels of routine calls indicated in the error message: in a few cases, seven or eight routine names may be listed, each separated from the next by a slash.

The various error conditions in VASPACKT are described in the list below. Each bulleted item includes an error message and a thumb-nail description of the error. The items in the list are arranged in alphabetical order. If you get an error message with one or more prefixed subroutine names, as described above, omit them and look up the result in this list. Note that, since VASPACKT routines sometimes call other routines, elsewhere in NCAR Graphics, that can detect error conditions and call SETER, the error message you get by calling a VASPACKT routine may not be listed here, but in the programmer document for some other package.

This probably indicates an error in the implementation of the package. See the VASPACKT specialist.

One of the routines VTTMRG, VTTMTL, or VTTMTX has been given an edge array (argument IEDG) which is too small. Increase its size.

An attempt to get the current clipping state has resulted in an error. This probably indicates that GKS is in the wrong state.

An attempt to get the current normalization transformation number has resulted in an error. This probably indicates that GKS is in the wrong state.

An attempt to get a color index has resulted in an error. This probably indicates that GKS is in the wrong state.

An attempt to get a line width scale factor has resulted in an error. This probably indicates that GKS is in the wrong state.

An attempt to get the current normalization transformation has resulted in an error. This probably indicates that GKS is in the wrong state.

An attempt to get a color index has resulted in an error. This probably indicates that GKS is in the wrong state.

An attempt to get a color index has resulted in an error. This probably indicates that GKS is in the wrong state.

An attempt has been made to get an element of the parameter array named 'xxx' and the current value of 'PAI' (the "parameter array index") is inappropriate for that parameter array.

A call to VTMESH has been omitted.

The parameter 'WSO' has a value indicating that integer workspace overflow should be treated as a fatal error, and such an overflow has occurred.

VTMVIW or VTMVRW has been called to move the contents of an old workspace array to a new one, and the new one is too small.

The given parameter name ('xxx') is not one of the legal parameter names.

The parameter name ('x') is less than three characters long.

One of the routines VTTMRG, VTTMTL, or VTTMTX has been given a point array (argument RPNT) which is too small. Increase its size.

The parameter 'WSO' has a value indicating that real workspace overflow should be treated as a fatal error, and such an overflow has occurred.

An attempt has been made to set an element of the parameter array named 'xxx' and the current value of 'PAI' (the "parameter array index") is inappropriate for that parameter array.

One of the routines VTTMRG, VTTMTL, or VTTMTX has been given a triangle array (argument ITRI) which is too small. Increase its size.

This error message indicates that, at the time the routine was called, there was an unrecovered outstanding error. In this case, it cannot continue; it forces the error message for the outstanding error to be printed and then substitutes this one for it.


EXAMPLES

Three examples are available for VASPACKT. On a Unix system on which NCAR Graphics has been installed, one may obtain the code for an example and run it by executing the command

      ncargex example_name
  
where "example_name" is one of the following:

      vtex01  vtex02  vtex03
  
To obtain the code for an example without running it, one uses the command

      ncargex -n example_name
  
After the code has been examined and, perhaps, modified, it can be compiled and executed using the commands

      ncargf77 *.f
      a.out
  
The metafile created by executing an example can be viewed using the command

      ctrans metafile_name
  
(It may be necessary to set some environment variables and/or to set other options on the "ctrans" command line.)

Most of the example code is heavily commented to explain what is being done and it is heavily parameterized. For example, one can easily specify the nature of the workstation being used (NCGM, X Windows, PostScript, or PDF in portrait or landscape mode). In many cases, one can select which of the plots an example can draw will actually be drawn and what the resolution of the triangular mesh used in the example will be. In the case of 3D plots, one can easily change the vantage point from which the mesh is viewed, its distance from the eye, whether stereo views or a single view will be drawn, and so on.


The Example "vtex01"

The example "vtex01" produces nine plots illustrating the use of VTSVDM/R to draw simple vectors on the globe and project them in various ways:


The Example "vtex02"

The example "vtex02" produces three plots illustrating the use of VTCVDM/R to draw curly vectors on the globe and project them in various ways:


The Example "vtex03"

The example "vtex03" produces three plots illustrating the use of VTSLDM/R to draw streamlines on the globe and project them in various ways: