Vectors, A Vector Field Plotting Utility

David I. Brown
NCAR, P.O. Box 3000
Boulder, Colorado 80307-3000

Table of Contents

1.0 PREFACE

The vector field plotting utility described here was originally written in the early 1970's and has previously been known as VELVCT. Over the years, a number of enhancements have been made, but the basic capabilities and interface have not changed much. In the fall of 1992 a more extensive revision was undertaken. Both the interface and functionality of the package underwent a major upgrade. There were several goals: first, make the package work more like other utilities in the NCAR Graphics toolkit suite; second, make it easier to use in combination with the other utilities; third, allow easier access to standard coordinate system mappings, including especially the EZMAP transformations; and fourth, improve the information content of the final plot. Most of these goals have been at least partially realized in the current version of the package, although, as usual, not all the envisioned improvements could be accomplished in the time allotted to the task. Since it might be confusing to retain the name of a now obsolete entry point as the utility name, and moreover, as it now seems unwise to share the package name with any entry point name, the new name for the NCAR Graphics vector plotting utility is simply Vectors.

2.0 INTRODUCTION

This document describes the NCAR Graphics utility, known as Vectors, designed to allow a user to plot vector fields given two arrays containing the components of the vectors on a uniform grid in a user-defined coordinate system. In addition, the user may pass in another array of scalar data defined over the same grid space independent of but presumably related in some fashion to the vector data. The utility will then color each vector based on the scalar value at the same grid point. Alternatively, the user can choose to color the vectors based on the vector magnitude at the grid point.

The old utility name, VELVCT, originated as a contraction of 'Velocity Vector'. Beginning with NCAR Graphics Version 3.2, all new routines, whether user-entry points or not, are six characters long and begin with the key letters, 'VV', again standing for 'Velocity Vector' though of course any 2-dimensional vector field may serve as input to the package. The old entry points are still supported through a compatibility version of the VELVCT subroutine, and some, though not all, of the features provided by the new routines are available to these entry points by appropriately setting the compatibility mode internal parameter.

This section is intended to give an overall view of Vectors 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 MESSAGES describes error messages written by Vectors. The section EXAMPLES describes the examples available for Vectors.

It is assumed that the reader is familiar with NCAR Graphics in general and has some knowledge of (or can find and read the documentation for) the utilities AREAS and EZMAP.

2.1 Vectors User-Entry Point Routines

The code to draw a vector field plot (unless using the obsolete entries points discussed at the end of this section) must include a call to the routine VVINIT followed at some point by a call to VVECTR. Before and after the VVINIT call several internal parameter setting routines may be used to alter the behavior of the vector plotting code. Some of these parameters must be set before the call to VVINIT in order to have any (or the correct) effect. In other cases, however, the user can query the information VVINIT has acquired about the target data sets using a parameter getting routine, and then dynamically adjust the parameter to best fit the requirements of the data, before calling VVECTR.

All the internal parameters have default values; only those which are to have values different from the default need to be set. The user may call routines to set the values of parameters 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 do not need to be repeated for each new vector field plot.

The user may retrieve the value of an internal parameter at any time by calling one of the parameter getting routines:

Once you have set required parameters and called VVINIT, drawing the vector field plot is simply a matter of calling the main entry point VVECTR.

VVINIT performs the initialization required for VVECTR to interpret the data properly. The dimensions of the data arrays are copied to internal variables. Depending on the current value of certain internal parameters, the grid space indices are mapped into the X,Y data coordinate system. The mapping from the user coordinate space to the normalized device coordinate (NDC, sometimes also known as fractional coordinate) space is also established using either the routine GETSET, if a previously established mapping is to be used, or the routine SET, if Vectors needs to set up the mapping. Note, however, that the mapping from the data to user coordinate system is left indeterminate at this point. This is because you may choose from several pre-defined mappings, such as an EZMAP projection, or implement a user-defined mapping to implement this transformation. VVINIT and, for that matter, VVECTR have (almost) no knowledge of the mapping being performed.

VVINIT then processes the vector component arrays to find the maximum and minimum vector magnitudes. If a scalar array is to be processed, it extracts the maximum and minimum scalar data values. If the user is coloring the vectors and has not predefined a set of threshold values, the routine sets up an array of values linearly spaced between the maximum and minimum (scalar data or vector magnitude) values. The user is responsible for setting up the color table and defining the number and progression of the colors to be used. If a zero field condition is discovered, a flag is set, causing VVECTR not to attempt to draw any vectors.

After the VVINIT call the user can retrieve the maximum and minimum vector magnitudes and/or scalar data values and based on their value, alter the appearance of the plot by enlarging the maximum size vector, constraining the smallest vector to be rendered at some fraction of the largest vector, or by choosing to eliminate vectors less than some magnitude. The color threshold values could also be examined and possibly modified.

You are now free to call VVECTR, causing the vectors to be rendered according to the established set up. If a border around the plot is desired, call PERIM(1,0,1,0). Finally, to advance the frame, call the SPPS routine FRAME.

Vectors contains two user-modifiable routines that are not invoked directly by the user, but by Vectors itself. The default versions of these routines contain very simple code that may handle a basic case, but little more. These routines are as follows:

Three Vectors routines are supplied to provide compatibility with pre-Version 3.2 codes. You may choose from a variety of compatibility options by setting the compatibility mode parameter CPM appropriately; this offers considerable flexibility in making the transition to the new version of the utility.

2.2 Using Vectors

If the intent is to draw the vector field plot using relatively few computer resources, the following sequence of calls will suffice:

  1. Call parameter-setting routines.

  2. Call VVINIT to initialize the vector field plot.

  3. Call VVECTR to draw the vectors.

  4. If a border around the plot is desired, call PERIM(1,0,1,0)

  5. Call FRAME to advance the plotter frame.

Assuming that step 1 is null and that all default parameter values are used, the resulting plot will look similar to what would have been drawn by VELVCT prior to Version 3.2 of NCAR Graphics.

2.3 Coordinate Systems in Vectors

In order to understand the process of transforming the data contained in the vector component input arrays into arrows of particular length and direction at various positions on an output plot, it would be helpful to differentiate unambiguously each stage of the transformation pipeline within the context of the coordinate systems defined by NCAR Graphics. In this discussion, the following terms are used:

Note that two other coordinate systems used in the VELVCT code prior to Version 3.2, the integer plotter and metacode coordinate system, have been retained only in the compatibility routines; they are not required for any of the low-level rendering routines used currently.

Given the default values of the parameters XC1, XCM, YC1 and YCN, the mapping from grid to data coordinate space is an identity transformation. That is, the data coordinate space extends from (1.0,1.0) to (REAL(M), REAL(N)). However, you may assign any desired boundaries to the data coordinate system by setting XC1, XCM, YC1 and YCN to values of your choice. For satisfactory results this choice needs to be consistent with the user coordinate boundaries established by the SET call and the mapping established by the MAP parameter. In general, the location of an array element A(I,J) in data coordinate space is given as:

      Xdata = XC1 + (I - 1)*(XCM - XC1)/(M - 1)
      Ydata = YC1 + (J - 1)*(YCN - YC1)/(N - 1)
where (XC1,YC1) is the lower boundary of the data coordinate space and (XCM,YCN) is the upper boundary.

If the parameter MAP has values between 0 and 2 Vectors handles the mapping from data space to user and NDC space internally, using the routine VVMPXY. If MAP has any other value the user-modifiable routine VVUMXY is called to perform a mapping defined by the user. Unlike the analogous CONPACK routine, CPMPXY, which has data coordinate inputs and user coordinate outputs, the Vectors mapping routines have data coordinate inputs but NDC outputs. This is because not only position but the direction of the vector require mapping; to ensure consistent mapping of the direction it is necessary to output both ends of the vector in a uniform Cartesian coordinate system. The user coordinate system cannot meet this test because it could be log-scaled or because a Y axis unit might not equal an X axis unit.

The mappings handled internally by Vectors are as follows:

When a user-defined mapping is required, you can modify the user routine, VVUMXY. If the Vectors routines are loaded from a binary library, you can usually replace the library version just by compiling the routine and explicitly linking its object with the NCAR Graphics library.

2.4 The SET Call

The mapping into the plotter frame depends on the boundaries of the user coordinate space and the viewport defined in NDC space. If the user coordinates are not log-scaled and neither axis is mirrored user coordinates and GKS world coordinates are the same. In this case, it is possible to define the user/world coordinate boundaries (also known as the window) and map them to the viewport using GKS calls. However, since the SPPS routine SET performs the same task and works under all conditions recognized by NCAR Graphics, only its use is described here.

A call to the SPPS routine SET has the form

      CALL SET (VPL,VPR,VPB,VPT,WDL,WDR,WDB,WDT,LL)
All arguments are REAL except for LL, which is an INTEGER. The first four arguments must all be between 0 and 1, inclusive; they define a rectangular area on the plotter frame known as the "viewport". The next four arguments define the boundaries of the user coordinate space (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. See the documentation of the SPPS utility for further details.

By default, Vectors calls SET. However, by setting the parameter SET to zero, you may prevent Vectors from doing this; in that case, one must do the call for oneself or depend on some other utility (such as EZMAP) to have done it.

If Vectors calls SET, it always uses LL = 1, requesting a linear-linear mapping from the window to the viewport. The viewport is positioned as specified by the current values of the parameters VPL, VPR, VPB, VPT, and VPS. The first four of these specify the boundaries of a "viewport area", in which the viewport is to be centered and made as large as possible; the final one determines how the shape of the viewport is to be chosen. You could, for example, render several plots within a single plotter frame by setting these parameters to define separate non-overlapping areas for each plot.

By default, the user coordinate boundaries are set equal to the data coordinate boundaries, which, in turn, default to the grid coordinate boundaries (1: M, 1: N) unless the parameters XC1, XCM, YC1, YCN have non-default values. You may override this behavior by setting parameters WDL, WDR, WDB, and WDT to non-default values, explicitly specifying the values used to define the window in the SET call. Normally you would modify the window setting parameters only when the parameter MAP has a non-default value, but Vectors is still expected to perform the SET call. Whereas the viewport area may be set to any part of the plotter frame, without fear of losing the plot, you must be careful setting WDL, WDR, WDB, and WDT, or the region of interest is not likely to match up with the viewport.

When MAP is set to 1, specifying an EZMAP projection, you should give the SET parameter a value of 0, since EZMAP must take charge of the SET call to perform the requested map transformation. If you want to adjust the viewport size or position in this case, do it using the EZMAP call MAPPOS.

When MAP is set to 2, specifying a polar coordinate mapping, you may choose either to leave the SET parameter defaulted and set the user coordinate boundary parameters WDL, WDR, WDB, and WDT appropriately, or else to set the SET parameter to zero and make your own call to the SET routine.

Note that, as long as the parameter MAP is zero, a SET call performed by Vectors will define the window in such a way as to be consistent with the ranges of the X and Y coordinates it generates. If MAP is set non-zero, then you will probably need to set XC1, XCM, YC1, and YCN to transform the grid coordinates into the range of data coordinates expected by Vectors' mapping routine. The call to SET must specify user coordinate boundaries commensurate with the range generated by the data coordinate to user coordinate transformation; if Vectors is to do the call, then you will need to set WDL, WDR, WDB, and WDT to accomplish this.

2.5 Arrow Length, Spacing, and Position

A common problem with using discrete vector arrows to represent a vector field is that as the size of the dataset increases, the vectors become too crowded and the rendering ceases to be intelligible. This problem may be further compounded when the vector field is passed through a non-linear transformation, such as a map projection, that causes many data points to become bunched together in small regions of the plot. The arrows must either become so small that it is difficult to distinguish between them, or they overlap and degenerate into an amorphous mass. Although there is no absolute cure for this problem, Vectors provides a number of features to help you present the data as coherently as possible.

2.5.1 Reference length and magnitude

The length of each vector arrow is determined in relation to a vector reference magnitude that may be specified by the parameter VRM and a vector reference length that may be specified, as a fraction of the viewport width, by the parameter VRL. Vectors belonging to the dataset whose magnitude is equal to the reference magnitude are drawn at the reference length. By default, if VRM is set to 0.0, the reference magnitude is the maximum magnitude in the vector field, but it may be set to any arbitrary value. The default reference length is determined dynamically based on the viewport and the size of the dataset along each dimension.

Note that prior to version 4.0.1 of NCAR Graphics, the reference magnitude was required to be greater than or equal to the largest vector magnitude in the dataset, and was set using the vector high cutoff parameter, VHC. For compatibility with older versions, if VRM has its default value of 0.0, you can still control the reference magnitude using VHC. The advantage of using VRM is that you can choose a "nice" value for the reference magnitude without worrying if any vector magnitudes in the dataset might exceed its value. The arrow in the Maximum Vector legend now actually represents the reference magnitude and need not necessarily be the actual maximum magnitude.

2.5.2 Minimum length and magnitude

By default the size of each vector differs from the reference length by the ratio of its magnitude to the reference magnitude. In practice, a common result of this strictly proportional representation is that low magnitude vectors become too small to be rendered with full detail, particularly on low resolution devices. As a result, their direction, especially, becomes difficult to decipher. Vectors provides a parameter, VFR, that allows you to specify, as a fraction of the reference length, a minimum vector arrow length. When this resource is set to a value greater than 0.0, the smallest magnitude vector is rendered at the specified fraction of the reference length, and intermediate magnitude vectors are rendered at proportionally intermediate lengths. Setting VFR to 1.0 causes all vector arrows to be drawn at the reference length.

The parameter VMN specifies the minimum magnitude a vector must have in order to qualify for drawing. You can use it to eliminate low velocity vectors in order to concentrate attention on the dominant features of a vector field. However, note that VMN also has another role. When it has a non-zero value and VFR is also non-zero, VMN specifies the vector magnitude that is rendered at the minimum length specified by VFR.

2.5.3 Ensuring uniform arrow sizing over a series of plots

In order to ensure that within a series of plots of related data a particular length always represents the same vector magnitude, you must always first set the reference magnitude using parameter VRM (or possibly VHC) explicitly. Otherwise, whatever magnitude happens to be the maximum in each plot will be rendered at the reference length. In addition, if you set VFR to a non-zero value, you should be careful to set VMN non-zero as well. Otherwise the length that VFR specifies will be used to represent whatever magnitude happens to be the minimum in each plot. If you do not want any low magnitude vectors actually eliminated, simply set VMN to a small positive number that is less than the smallest magnitude in any of your data sets.

2.5.4 Controlling the spacing between vector arrows

There are two ways to reduce the crowding of a too densely populated vectorplot. One is to specify array increments greater than unity along one or both dimensions of the data using the parameters XIN and/or YIN. This method has the effect of reducing the density uniformly throughout the data space, and may be the most appropriate if your plot is overly dense throughout. The second way is to set the parameter VMD to a value representing, as a fraction of the viewport width, the minimum distance you want to allow between the locations of neighboring vector arrows. This method requires that you supply a work array to VVINIT and VVECTR but it ensures that the minimum distance between vectors is maintained even after arbitrary non-linear transformations, like many map projections, from data to NDC space.

2.5.5 Arrow Position

Using the VPO parameter, you can control whether the tail, the head, or the center of vector arrow is positioned at the location of the grid point in data space.

2.6 Arrow Styles

Vectors supports three arrow styles: a simple line-drawn arrow, drawn only using a polyline; a filled arrow with an optional edge line and a highly configurable shape; and, a wind barb style, which supports traditional wind barbs glyphs. Each style has its own set of parameters, although there are other parameters that apply, under appropriate conditions, to all styles. By default, Vectors uses line-drawn arrows. Set the parameter AST to 1 in order to activate filled arrows or to 2 to activate wind barbs.

2.6.1 Line-drawn arrows

Line-drawn vector arrows have a fixed shape which the user cannot modify. However, you can control the minimum and maximum size of the vector arrowhead using parameters AMN and AMX. This allows you to ensure that the arrowheads remain recognizable for small-magnitude vectors while not becoming excessively large for high-magnitude vectors.

You can set the thickness of the polylines used to render line-drawn arrows using the LWD parameter. You may notice that as the lines are made thicker the arrows begin to take on a rather fuzzy look. This is an unavoidable consequence of using thick lines, (at least where there is no control of the line join method), and one of the motivations for the development of filled vector arrows.

2.6.2 Filled arrows

Vectors draws filled vector arrows using a solid filled area with an edge outline. Filled arrows have several advantages over line-drawn arrows:

Naturally filled arrows have a few drawbacks as well:

Either the filled area or the edge or both may be colored individually based on the values in the TVL threshold level array. Assuming individual coloring is enabled (see following section) the arrow color mode parameter ACM determines how the colors apply to the arrow fill and edges. When not colored individually the fill color is determined by the current GKS fill color index and the edge color by the current GKS line color index. Appropriate settings of the ACM parameter can cause either the fill or the edge not to be drawn.

The AFO parameter specifies whether the edge should be drawn first with the fill on top or vice versa. Drawing the fill on top ensures that the full extent of the filled area appears, even when the vector arrow is very small. However, in this case you should ensure that the linewidth parameter LWD is given a value greater than 1.0. Otherwise the edges will appear broken and poorly formed.

Seven parameters control the shape of filled vector arrows. Four of these specify the shape of an arrow drawn at the reference length:

Each of these parameters is expressed as a fraction of the reference length.

The other three parameters, AWF, AXF, and AYF, set minimum sizes for AWR, AXR, and AYR, respectively. They are specified as fractions of the parameter with which they are associated. So, for example, if you set AWF to 0.25, the width used for the minimum length arrow will be equal to 0.25 * AWR * the reference length in NDC. The widths used for intermediate length arrows will be sized proportionally between the minimum width and the reference width. This implies that if you set AWF to 1.0, the arrow width will remain constant for all filled arrows, no matter what their length. Setting any of these parameters to 0.0 causes their associated arrow dimension to vary in strict proportion to the arrow length.

2.6.3 Wind barbs

Wind barb glyphs consist of a shaft parallel to the vector direction, and zero or more pennants and/or ticks spaced along the shaft starting at the end nearest the direction from which the flow is coming. However, if the magnitude of the velocity is less than 2.5, a circle replaces the shaft. Half ticks represent 5 units of magnitude, full ticks represent 10 units, and pennants represent 50 units. By convention, the units are knots. The pennants are drawn using a filled polygon, while the ticks, the shaft, and the calm circle are all rendered with polylines. Wind barbs differ from the other arrow styles in several respects: Otherwise, the wind barb style shares the capabilities of the other styles, including the ability to be individually colored based on values in the TVL threshold level array.

As with line elements in all the arrow styles, the linewidth of wind barb line elements is set using the LWD parameter. When not using multi-colored vectors, specify the wind barb color by setting the GKS polyline color index. There are five parameters that are specific to the wind barb arrow style:

2.7 Color Threshold Level Control

A major addition to Vectors for Version 3.2 is the ability to color the vectors either based on the values in an associated scalar data array or based on the vector's magnitude. When a related scalar field, such as temperature or pressure, serves as the basis for determining the color of a set of wind vector data using a suitably graduated color palette, patterns may emerge that would be hard to observe when viewing the data sets separately.

Vectors will not set up a color palette. You must call the GKS routine GSCR to assign RGB values for each color index you intend to use. An example in the examples section includes code for a sample color palette that varies from blue at one end of the scale to red at the other. Currently, a maximum palette of 255colors is allowed. As in all of NCAR Graphics, the color indices used can range from 1 to 255, with index 0 reserved for the background color. You are also responsible for setting up the GKS color index array used by Vectors to determine the color to use for data within a certain range. For example, assuming (1) a palette of 14 colors is desired, (2) the desired RGB values have previously been stored in a 3 x n array called "RGB", and (3) a consecutive series of GKS indices starting at N + 1 is to be used (where N is a previously initialized value between 0 and 255 - 14) you could accomplish both these tasks in a single simple loop:

      DO 100 I=1,14,1
        CALL GSCR (1,I+N,RGB(1,I),RGB(2,I),RGB(3,I))
        CALL VVSETI('PAI -- Parameter Array Index', I)
        CALL VVSETI('CLR -- GKS Color Index', I+N)
      100 CONTINUE
The setting of the color threshold value control parameter, CTV, determines how Vectors handles the selection of color threshold values. If you want Vectors to choose the threshold values, set CTV to a positive value: 1 to color by vector magnitude or 2 to color by scalar array. Set the number of levels parameter NLV to select the number of threshold levels (and the number of colors, with a maximum of 255) to use. When Vectors chooses the threshold levels, it finds the maximum and minimum values in the data, then simply divides the range into NLV equally spaced divisions. The resulting NLV threshold values are stored into the threshold level array, TVL. The first value stored is the minimum data value plus one division increment while the last value is the maximum data value itself. As each vector is processed its color is chosen by finding the first entry in the threshold level array greater than or equal to the data value associated with the vector, retrieving the array subscript for this entry, and then setting the GKS polyline color index to the value in the color index array, CLR, accessed by the same subscript. Assuming as above that 14 levels are desired, the following code would tell Vectors to choose the color levels based on data in the scalar array:

      CALL VVSETI('NLV - Number of Threshold Levels', 14)
      CALL VVSETI('CTV - Color Threshold Value Control', 2)
To set up the threshold level array yourself, make CTV negative: -1 to color by vector magnitude or -2 to color by scalar array value. When CTV is less than or equal to 0, Vectors will not touch the values in the TVL array. Set NLV as before to the number of levels desired, then set the first NLV members of the threshold array to the desired threshold values, keeping in mind from the preceding description how Vectors chooses the color index based on the threshold array values. A basic rule to observe is that the threshold values should increase monotonically as the array subscripts increase. Note also that if the vector's associated data value is larger than all the values in the threshold value array, it will be assigned the color subscripted by the index for the maximum data value. Again assuming 14 colors and also that the desired threshold values are stored in an array called "TVALS", the following code would set up the threshold array and inform Vectors not to modify its contents:

      CALL VVSETI('NLV - Number of Threshold Levels', 14)
      CALL VVSETI('CTV - Color Threshold Value Control', -2)
      DO 200 I=1,14,1
        CALL VVSETI('PAI -- Parameter Array Index', I)
        CALL VVSETR('TVL -- Threshold Value Array', TVALS(I))
  200 CONTINUE
You can also use the color threshold control parameter to retain a threshold array set up by a previous plot (within the same program execution). Suppose you have a program to create several plots using scalar arrays with varying maximum and minimum values. When Vectors picks the threshold values, the color associated with a particular data value may change from plot to plot. To ensure that a given data value is associated with the same color for the complete series of plots, pick one plot (preferably the one with the greatest range) and by setting CTV to a positive value, allow Vectors to set up the threshold array. For the subsequent plots, set CTV negative. All plots will then use the same threshold array, and therefore the colors will be associated with identical ranges of data.

2.8 Other Color Facilities

Besides the implementation of vector coloring according to a related scalar data field or vector magnitude discussed earlier, there are several other points to make about the way the Vectors utility supports the use of color in NCAR Graphics plots.

First you should note that even if you do not take advantage of multiple colors for vectors (the color threshold value control parameter, CTV is set to 0), it is still possible to adjust the color of the vector field as a whole simply by setting the GKS polyline color index at any point before the call to VVECTR.

Basic text elements, such as the Zero Field text block, are by default colored using the current text color index. You may override this behavior by setting the color parameter associated with the text element to a value greater than or equal to 0, causing the parameter value to be used as the GKS color index for the text. In addition, the maximum and minimum vector text blocks have an additional option that can only be activated when the vectors are colored according to magnitude. When the option is active, the text and the vector arrow both are colored using the color associated with that magnitude of vector within the plot.

By default, Vectors draws the optional vector magnitude labels using the same color index as the vector arrow with which each one is associated. However, here again, you may assign a positive or zero value to the parameter LBC to give the labels a uniform color of your choice, or assign a value less than zero to the parameter if you want them to be drawn using the current GKS text color index.

2.9 Masked Vector Overlays Using an Area Map

At times you may need to overlay a vector field on a plot created by another NCAR Graphics utility, such as Conpack. There may be certain areas, such as the boxes containing contour level labels, where you do not want the vector arrows to appear. Beginning with Version 3.2, the Vectors utility supports vector masking based on the contents of a area map previously established using routines from the Areas utility. Most of the information required to use the area map routines is documented elsewhere, either in the descriptions of the Conpack utilities that work with area maps or in the actual documentation of the Areas utility itself. You create the area map and the underlying plot just as you normally would. Then, in order to create the vector overlay, you would need to take the following steps:

      EXTERNAL VVUDMV

2.10 Special Values

If the datum at a particular grid point is unavailable or unreliable, a "special" value, typically a value outside the possible range of valid data, may be assigned to the array element associated with the grid point in question. Since Vectors has at least two and perhaps three separate arrays as input, it uses several parameters to control processing of special value data points. Each of the three input arrays may have its own separately defined special value. The parameters USV, VSV, and PSV are used to set the special values for the U vector component array, the V vector component array, and the P scalar data array, respectively.

Two more parameters control the way Vectors handles the special values. The parameter SVF handles special value processing for the vector component arrays. You may choose from several different methods for deciding whether to draw a vector, given that either one or both of the component array elements may contain a special value. The special color parameter SPC determines the fate of a vector that would otherwise be drawn, but whose associated scalar array data element has a special value. Depending on the setting of SPC, Vectors may eliminate the vector from the plot, or draw it using a special color of your choice, probably outside the palette of colors used to render the range of legitimate scalar data.

2.11 Supplementary Text

You may control the size, justification, color, visibility, and, where appropriate, the content and location of several supplementary text objects in order to improve the appearance and informativeness of a Vectors plot.

2.12 Vectors' Grid Window

Note that the grid window for Vectors is not the same as the grid window for AUTOGRAPH, since the former is expressed with respect to the plotter frame and the latter is expressed with respect to the AUTOGRAPH "graph window". There is an easy conversion from one to the other, however. If AGFL, AGFR, AGFB, and AGFT specify the AUTOGRAPH graph window and AGDL, AGDR, AGDB, and AGDT specify the AUTOGRAPH grid window and CGDL, CGDR, CGDB, and CGDT specify the Vectors grid window, then the following relationships ensure coincidence of the AUTOGRAPH and Vectors grid windows:

      CGDL=AGFL+AGDL*(AGFR-AGFL)
      CGDR=AGFL+AGDR*(AGFR-AGFL)
      CGDB=AGFB+AGDB*(AGFT-AGFB)
      CGDT=AGFB+AGDT*(AGFT-AGFB)
Note what happens when AGFL and AGFB are 0's and AGFR and AGFT are 1's, which is the default situation; in that case CGDL=AGDL, CGDR=AGDR, CGDB=AGDB, and CGDT=AGDT.

2.13 GKS Considerations

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

  1. Like all the utilities in NCAR Graphics, Vectors 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.

  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
  3. It is assumed that the aspect source flags for various quantities are set to "individual". (NCAR GKS 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)
  4. Color-setting by Vectors is done by executing calls to the GKS routines GSPLCI and GSTXCI, 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.).

3.0 SUBROUTINES

All Vectors routines added for NCAR Graphics Version 3.2 and later have six-character names beginning with the letters 'VV'. Current user entry points and user-modifiable routines are described in detail in alphabetical order in this section. Obsolete routines appear in the section following entitled OBSOLETE SUBROUTINES.

3.1 VVECTR (U,V,P,IAM,VVUDMV,WRK)

This routine manages the coordinate system mapping, color setting, auxiliary text output, and drawing of the vector field plot, according to the specifications established by the parameter setting routines and the initialization routine, VVINIT.

3.1.1 Usage

A call to VVINIT must precede the first call to VVECTR, and is again required any time the vector or scalar array data changes, any of the coordinate control parameters are modified, or the number of color threshold levels is modified when Vectors is given the responsibility of setting up the color threshold value array. However, the user may modify text elements or any of the rendering control parameters, and if assuming responsibility for setting up the color threshold array, may also modify the color array parameters, in between multiple invocations of VVECTR.

Arguments to VVINIT establish the sizes of the two or three data arrays. VVINIT places these values into common block variables where they become available to VVECTR. Therefore no size arguments need appear in the VVECTR argument list. When there is no scalar data array, and area masking is not enabled, all but the first two arguments to VVECTR may have dummy values and the invocation would be something like:

      CALL VVECTR(U,V,IDM,IDM,IDM,IDM)
where IDM is an arbitrary variable, INTEGER or REAL, that need not have been initialized. However, any time the color threshold control parameter, CTV has an absolute value of 2, the auxiliary scalar data array is expected, and the P scalar array variable needs to be specified.

The masking capability supported by Vectors allows the user to overlay vector fields on top of graphics produced by other utilities, such as CONPACK contour plots, without encroaching on areas, like label boxes, that should appear in the foreground, uncovered. Normally the area map should be generated and used in the normal way (as described in the AREAS and CONPACK documentation) before calling any routines in the Vectors utility. When the parameter MSK has a non-zero value, masking is enabled and a previously created area map must be passed to VVECTR. VVECTR examines the map, returning an error if the map is invalid or there are more area groups than Vectors can handle, currently 64. Otherwise it only uses the map as a member of the argument list when invoking one of the Areas routines, ARDRLN or ARGTAI. The user must also pass in a user-definable masked drawing subroutine. A simple version of this subroutine, named VVUDMV, is supplied with the Vectors utility, and may suffice for basic masked drawing operations. There is a separate entry describing the usage and argument list for this subroutine in this section.

The last argument in the calling sequence, WRK, is used only when the parameter VMD (Vector Minimum Distance) is given a value greater than 0.0. In this case, Vectors uses the array to keep track of the location of each vector in NDC space so that the distances between vectors can be compared. Based on these comparisons, Vectors eliminates some vectors such that the remaining vectors are separated by at least the specified distance. Otherwise the WRK argument is ignored, and may be passed a dummy argument value.

3.1.2 Arguments

U (REAL 2 dimensional array, dimensioned as specified in last call to VVINIT, input): By default, assumed to contain the first dimensional axis components of the vector field. However, if PLR is non-zero, it is treated as containing the vector magnitudes.

V (REAL 2 dimensional array, dimensioned as specified in last call to VVINIT, input): By default, assumed to contain the second dimensional axis components of the vector field. However, if PLR is non-zero, it is treated as containing the vector angles.

P (REAL 2 dimensional array, dimensioned as specified in last call to VVINIT, input): Array of scalar data that may be used to color the vectors. The grid points are assumed to coincide with the grid points of the U and V arrays. Required only if CTV has an absolute value of 2; otherwise this argument is ignored and may be assigned a dummy value.

IAM (INTEGER array, unknown dimension, input): Area map array previously established by calls to routines in the Areas utility. It is not examined or modified by Vectors. Required only if MSK is set to a non-zero value; otherwise it is ignored and may be assigned a dummy value.

VVUDMV (EXTERNAL subroutine, input): User-definable masked drawing subroutine. See the entry, "VVUDMV", in this section for a discussion of the usage and argument list required for this subroutine. Required only if MSK is set to a non-zero value; otherwise it is ignored and may be assigned a dummy value.

WRK (REAL array, dimensioned as specified in last call to VVINIT, input/output): Work array required only if the parameter VMD is set to a value greater than 0.0. Otherwise may be set to a dummy value.

3.2 VVGETC (CNM,CVL)

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

3.2.1 Usage

Use the statement 

      CALL VVGETC (CNM,CVL)
at any time to retrieve in CVL the current character value of the parameter whose name is CNM.

3.2.2 Arguments

CNM (CHARACTER, input) is the name of a parameter whose character value is to be retrieved. Only the first three characters of CNM are examined. The three characters may either be entirely upper or entirely lower case; mixed case is not recognized. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of just 'MXT', use 'MXT - Maximum Vector Text String'.

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

3.3 VVGETI (CNM,IVL)

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

3.3.1 Usage

Use the statement 

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

3.3.2 Arguments

CNM (CHARACTER, input) is the name of a parameter whose integer value is to be retrieved. Only the first three characters of CNM are examined. The three characters may either be entirely upper or entirely lower case; mixed case is not recognized. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of just 'PLR', use 'PLR - Polar Input Mode'.

IVL (INTEGER, output) is a variable in which the value of the parameter specified by CNM is to be returned.

3.4 VVGETR (CNM,RVL)

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

3.4.1 Usage

Use the statement 

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

3.4.2 Arguments

CNM (CHARACTER, input) is the name of a parameter whose real value is to be retrieved. Only the first three characters of CNM are examined. The three characters may either be entirely upper or entirely lower case; mixed case is not recognized. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of just 'DMX', use 'DMX - Device Maximum Vector Size'.

RVL (REAL, output) is a variable in which the value of the parameter specified by CNM is to be returned.

3.5 VVINIT (U,LU,V,LV,P,LP,M,N,WRK,LW)

VVINIT performs initialization tasks required before VVECTR may be called to plot a vector field, including copying array size information into internal common block variables, establishing coordinate system mappings and boundaries, determining the maximum and minimum vector magnitudes and scalar array values, and, if required, setting up the color threshold value array.

3.5.1 Usage

Call VVINIT before the first invocation of VVECTR and again any time you modify the contents of the input data arrays. You may precede a VVINIT call with any number of calls to the Vectors parameter setting routines (VVSETC, VVSETI, or VVSETR). After the VVINIT call, you may still change certain parameters before calling VVECTR. (Consult the section, PARAMETERS, for further information on this point.)

Set up the two vector component arrays prior to calling VVINIT. To permit multiple purpose use of the array space, the VVINIT argument list includes both the actual size and an assumed size for the first dimension of each input array. Due to FORTRAN array ordering conventions, only the assumed size needs to be specified for the second dimension. (Note: when using the C bindings, mentally exchange all references to first and second dimensions in this discussion.) The arguments LU, LV, and LP contain the actual size of the first dimensions of arrays U, V, and P respectively. Since the grid locations for each of the data arrays are assumed to coincide, a single argument, M, represents the assumed size of the first dimension for all the arrays. Similarly, the argument, N, is the assumed size of the second dimension. The only requirement for the actual second dimension size is that it be greater than or equal to N for each array.

The array specified by the WRK argument and its associated size specifier, LW, are used only when the parameter VMD (Vector Minimum Distance) is given a value greater than 0.0. In this case, Vectors uses the array to keep track of the location of each vector in NDC space so that the distances between vectors can be compared. Based on these comparisons, Vectors eliminates some vectors such that the remaining vectors are separated by at least the specified distance. If VMD is less than or equal to 0.0, you may assign an arbitrary dummy value to WRK, but you should set LW to the integer value 0.

3.5.2 Arguments

U (REAL 2-dimensional array, dimensioned LU x n: n >= N, input): By default, assumed to contain the first dimensional Cartesian components of the vector field. However, if PLR is non-zero, it is treated as containing the vector magnitudes.

LU (INTEGER, input): Actual value of the first dimension of array U.

V (REAL 2-dimensional array, dimensioned LV x n: n >= N, input): By default, assumed to contain the second dimensional Cartesian components of the vector field. However, if PLR is non-zero, it is treated as containing the vector angles.

LV (INTEGER, input): Actual value of the first dimension of array V

P (REAL 2-dimensional array, dimensioned LP x n: n >= N, input): Array of scalar data that may be used to color the vectors. The grid points are assumed to coincide with the grid points of the U and V arrays. Required only if CTV has an absolute value of 2; otherwise this argument is ignored and may be assigned a dummy value.

LP (INTEGER, input): Actual value of the first dimension of array P

M (INTEGER, input): Number of contiguous elements along the first dimensional axis containing data to be processed in each of the arrays U, V, and P (if used).

N (INTEGER, input): Number of contiguous elements along the second dimensional axis containing data to be processed in each of the arrays U, V, and P (if used).

WRK (REAL, array dimensioned n: n >= LW, input/output): Work array required only if the parameter VMD is set to a value greater than 0.0. If required must be dimensioned greater or equal to 2 * M * N. Otherwise may be set to a dummy value.

LW (INTEGER, input): Assumed size of the array WRK. If the parameter VMD is set to a value greater than 0.0, must be set to a value less than or equal to the dimension of the WRK array, but greater than or equal to 2 * M * N. Otherwise, this argument should be assigned the integer value 0.

3.6 VVRSET

Resets all parameters to their initial default values.

3.6.1 Usage

To reset all parameters to their default values:

      CALL VVRSET
There are no arguments.

3.6.2 Arguments

None.

3.7 VVSETC (CNM,CVL)

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

3.7.1 Usage

Use the statement 

      CALL VVSETC (CNM,CVL)
to give the parameter whose name is CNM the character value CVL.

3.7.2 Arguments

CNM (CHARACTER, input) is the name of a parameter to be given a character value. Only the first three characters of CNM are examined. The three characters may either be entirely upper or entirely lower case; mixed case is not recognized. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of 'ZFT', use 'ZFT - Zero Field Text String'.

CVL (CHARACTER, input) is an expression, the value of which is to be given to the parameter specified by CNM.

3.8 VVSETI (CNM,IVL)

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

3.8.1 Usage

Use the statement

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

3.8.2 Arguments

CNM (CHARACTER, input) is the name of a parameter to be given an integer value. Only the first three characters of CNM are examined. The three characters may either be entirely upper or entirely lower case; mixed case is not recognized. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of 'VPO', use 'VPO - Vector Positioning Mode'.

IVL (INTEGER, input) is an expression, the value of which is to be given to the parameter specified by CNM.

3.9 VVSETR (CNM,RVL)

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

3.9.1 Usage

Use the statement 

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

3.9.2 Arguments

CNM (CHARACTER, input) is the name of a parameter to be given a real value. Only the first three characters of CNM are examined. The three characters may either be entirely upper or entirely lower case; mixed case is not recognized. It is recommended that the rest of the character string be used to improve the readability of the code. For example, instead of 'VFR', use 'VFR - Minimum Vector Fractional Length'.

RVL (REAL, input) is an expression, the value of which is to be given to the parameter specified by CNM.

3.10 VVUDMV (XCS,YCS,NCS,IAI,IAG,NAI)

This routine is the user-definable external subroutine used to draw masked vectors. The default version of the routine draws any polyline all of whose area identifiers are greater than or equal to zero.

3.10.1 Usage

'VVUDMV' is the name given to the default version of the masked vector drawing routine, and it is also the name given to the argument through which the external subroutine is passed to VVECTR. However, you may use any acceptable FORTRAN identifier as the name of a user-defined version of the routine. The substitute routine must have an argument list equivalent to the default version of VVUDMV. Also, whether or not the default version is used, the subroutine that calls VVECTR should contain an external declaration of the routine, such as:

      EXTERNAL VVUDMV
If the MSK parameter is set to the value 1, specifying high precision masking, Vectors sends one set of X and Y polyline coordinate arrays to the area masking routine, ARDRLN, for each vector arrow. ARDRLN subdivides the polyline into pieces such that each smaller polyline has a single area identifier with respect to each area identifier group, then makes a call to VVUDMV for each polyline piece. While the default version of VVUDMV only checks to see that none of the area identifiers are negative, a user-defined version could perform more complicated decision processing based on knowledge of the meaning of specific area identifier groups and/or area identifier values. Note that, before invoking VVUDMV, ARDRLN modifies the user coordinate space by making the following calls:

      CALL GETSET(VPL,VPR,VPB,VPT,WDL,WDR,WDB,WDT,LLG)
      CALL SET(VPL,VPR,VPB,VPT,VPL,VPR,VPB,VPT,1)
These calls temporarily turn the user to NDC mapping into an identity, allowing the user to call any of the routines, CURVE, CURVED, or the GKS routines GPL or GFA (for filled vector arrows) to render the polygon piece, without worrying about a possible non-identity mapping between user and world coordinates. If MSK has a value greater than 1, specifying low precision masking, Vectors calls the routine ARGTAI to get the area identifiers with respect to the area identifier groups for a single point that locates the base position of the vector. Vectors then calls the VVUDMV routine itself, passing the coordinate arrays for a complete vector arrow. Thus, a vector arrow whose base position is within an area to be masked can be eliminated, but an arrow whose base position is nearby, but outside, a masked area may intrude into the area. Also, in this case, since faster rendering is the goal, Vectors does not convert the coordinate arrays into normalized device coordinates and do the identity SET call. Therefore, the user should use only CURVE or CURVED to render the polyline, unless there is no possibility of a non-identity user to world coordinate mapping.

VVUDMV contains a separate block of code that handles masked drawing of filled vectors (parameter AST set to 1). However, the default code is unable to determine how to close open polygon fragments correctly. Therefore it completely eliminates vectors that partially protrude into a masked region when high precision masking is specified.

The current version of Vectors supports masked drawing with up to 64 area groups. Vectors will exit with an error message if an area map with more than 64 groups is passed to it.

3.10.2 Arguments

XCS (REAL array, assumed size NCS, input): Array of X coordinates of the points defining the polyline with the given set of area identifiers.

YCS (REAL array, assumed size NCS, input): Array of Y coordinates of the points defining the polyline with the given set of area identifiers.

NCS (INTEGER, input): Number of points; assumed size of the X and Y coordinate arrays, XCS and YCS.

IAI (INTEGER array, assumed size NAI, input): Array of area identifier values. Each value represents the area identifier with respect to the area group in the area group array with the same array index.

IAG (INTEGER array, assumed size NAI, input): Array of area-identifier groups.

NAI (INTEGER, input): Number of area identifier groups. The current version of Vectors supports up to 64 area groups.

3.11 VVUMXY (X,Y,U,V,UVM,XB,YB,XE,YE,IST)

The user may modify this routine to define a custom mapping of vectors from a data coordinate system aligned with the natural boundaries of the vector field to the uniform normalized device coordinate (NDC) system suitable for generating a plot on an output device. It has same parameters as the internal Vectors routine, VVMPXY, used for the predefined mappings employed when the MAP parameter has a value between 0 and 2.

3.11.1 Usage

The user does not call VVUMXY. Vectors calls it only when the parameter MAP has a value other than 0, 1, or 2, the mappings handled by Vectors internally. Note that unlike other user-modifiable mapping routines in NCAR Graphics, such as CPMPXY, that map a single point into the user coordinate system, this routine returns two points, representing both ends of the vector, scaled for magnitude, in the normalized device coordinate (NDC) system. The NDC system is used for output because, as a coordinate system guaranteed to be rectangular and uniform, it serves as a convenient reference system to help map both vector magnitude and direction correctly. The term uniform, as used in this discussion, means that an arbitrary numerical increment along either the X or Y axis has the same length given any offset from the coordinate system origin. The user coordinate system does not qualify, because it may be log-scaled, or the X units may have a different size from the Y units.

In order to implement a custom mapping, you must pick a unique mapping code (a positive integer greater than 2), and then modify VVUMXY to recognize and respond to the chosen code. In the standard distribution of NCAR Graphics, this routine resides in the file, 'vvumxy.f'. VVUMXY has access to a common block called VVMAP that contains a number of variables used to record the current transformation state. In order to accommodate a variety of mapping implementations, VVMAP provides more information than normally required. Consider the values stored in VVMAP as strictly read-only. One essential member of this common block is IMAP, which contains the value currently assigned to the MAP parameter.

When implementing a non-linear mapping, an iterative differential technique will most likely be required. Look at the routine, VVMPXY, in 'vvmpxy.f', which handles the pre- defined mappings, for examples of the method. Both the default transformation (MAP set to 0), in order to account for possible log scaling of the user coordinate axes, and also the Ezmap projection (MAP set to 1) use such a technique. Basically the idea is that the vector components must be proportionally reduced in size enough that an effectively "instantaneous" angle can be calculated, although they must not become so small that the calculation is adversely affected by the floating point precision available for the machine. Additionally, checks must be put in place to prevent the increment from stepping off the edge of the coordinate system space. The pre-defined mappings step in the opposite direction to find the angle whenever an increment in the original direction would fall off the edge.

For more information, see the section titled Coordinate Systems in Vectors.

3.11.2 Arguments

X (REAL, input) Location of the vector along the first dimensional axis in the data coordinate system. When MAP is 0, this is the X Axis. If MAP is 1, it is the longitudinal axis, and if MAP is 2, it is the radial axis. For other values of MAP, those that cause VVUMXY to be invoked, the interpretation is up to the author of the mapping routine.

Y (REAL, input) Location of the vector along the second dimensional axis in the data coordinate system. When MAP is 0, this is the Y Axis. If MAP is 1, it is the latitudinal axis, and if MAP is 2, it is the angular axis. For other values of MAP, those that cause VVUMXY to be invoked, the interpretation is up to the author of the mapping routine.

U (REAL, input) U component of the vector. If TRT is set to 1, the direction of the U component is tangent to the direction of the first dimensional axis in the data coordinate system at the location of the vector. If TRT is set to 0, and MAP has a value of 0 or 2, the direction of the U component is parallel to the horizontal (X axis) in NDC space.

V (REAL, input) V component of the vector. If TRT is set to 1, the direction of the V component is normal to the direction of the first dimensional axis in the data coordinate system at the location of the vector. If TRT is set to 0, and MAP has a value of 0 or 2, the direction of the V component is parallel to the vertical (Y axis) in NDC space.

UVM (REAL, input) Magnitude of the U and V components, SQRT(U*U+V*V). Although this value could be calculated within the routine, it is more efficient for the calling routine to supply the value as an argument, since it is needed for other purposes at a higher level.

XB (REAL, output) Location of the vector starting point along the horizontal (X axis) in NDC space, before adjustment based on the value of the vector positioning parameter, VPO.

YB (REAL, output) Location of the vector starting point along the vertical (Y axis) in NDC space, before adjustment based on the value of the vector positioning parameter, VPO.

XE (REAL, output) Location of the vector ending point along the horizontal (X axis) in NDC space, before adjustment based on the value of the vector positioning parameter, VPO.

YE (REAL, output) Location of the vector ending point along the vertical (Y axis) in NDC space before adjustment based on the value of the vector positioning parameter, VPO.

IST (REAL, output) Status of the vector mapping operation: 0 indicates success, negative values indicate that the mapping failed; positive values are reserved and should not be used by the implementor of a mapping routine.

4.0 OBSOLETE SUBROUTINES

4.1 EZVEC (U,V,M,N)

EZVEC is a simpler front-end to the VELVCT interface. It may be used to plot a vector field in a single call.

4.1.1 Usage

U and V are 2-dimensional vector component arrays, whose first dimensions must be equal to the value of M, and whose second dimensions must equal or exceed the value of N. Given an appropriate setting of the compatibility mode parameter, CPM, many of the VELVCT argument list options are accessible by making calls to VVSETx routines before invoking EZVEC. When creating new code, however, users are strongly encouraged to make use of the VVINIT/VVECTR interface.

4.1.2 Arguments

U (REAL 2-dimensional array, dimensioned M x n: n >= N, input) By default, assumed to contain the first-dimensional Cartesian components of the vector field. However, if PLR is non-zero, it is treated as containing the vector magnitudes.

V (REAL 2-dimensional array, dimensioned M xn: n >= N, input) By default, assumed to contain the second-dimensional Cartesian components of the vector field. However, if PLR is non-zero, it is treated as containing the vector angles.

M (INTEGER, input) Actual size of the first dimension of arrays U and V.

N (INTEGER, input) Assumed size of the second dimension of arrays U and V.

4.2 FX (X,Y)

Given the X and Y coordinates of a point in the grid coordinate system, the function FX returns the X coordinate of the point in user coordinate space.

4.2.1 Usage

The user does not invoke the function, FX, directly. In older versions of NCAR Graphics, the user modified the functions, FX and FY, in order to implement custom mappings from grid coordinates to user coordinates. These functions were used throughout NCAR Graphics, not just in the Vectors utility. For compatibility with existing code, calls to any of the Vectors primary entry points predating Version 3.2 (EZVEC, VELVCT, or VELVEC), by default use FX and FY to map from grid to user coordinates. However, by appropriately setting the compatibility mode parameter, CPM, the user can choose whether the FX and FY functions or the new VVMPXY routine is invoked when using any of the primary entry points supported by Vectors.

Unlike the Version 3.2 mapping routine VVMPXY, whose input coordinates are in the data coordinate system, FX takes input in the grid coordinate system. Therefore, any required conversions into the data coordinate system must be performed within the function prior to the mapping into user coordinates. The common block VVMAP, available for inclusion within the FX routine, supplies the information necessary to perform the conversion into data coordinate space, as well as for the mapping from data to user coordinates. The default version of FX simply performs an identity mapping from grid to user coordinate space.

4.2.2 Arguments

X (REAL, input): The X coordinate of a vector location in the grid coordinate system.

Y (REAL, input) The Y coordinate of a vector location in the grid coordinate system.

4.3 FY (X,Y)

Given the X and Y coordinates of a point in the grid coordinate system, the function FY returns the Y coordinate of the point in user coordinate space.

4.3.1 Usage

The user does not invoke the function, FY, directly. In older versions of NCAR Graphics, the user modified the functions, FX and FY, in order to implement custom mappings from grid coordinates to user coordinates. These functions were used throughout NCAR Graphics, not just in the Vectors utility. For compatibility with existing code, calls to any of the Vectors primary entry points predating Version 3.2 (EZVEC, VELVCT, or VELVEC), by default use FX and FY to map from grid to user coordinates. However, by appropriately setting the compatibility mode parameter, CPM, the user can choose whether the FX and FY functions or the new VVMPXY routine is invoked when using any of the primary entry points supported by Vectors.

Unlike the Version 3.2 mapping routine VVMPXY, whose input coordinates are in the data coordinate system, FY takes input in the grid coordinate system. Therefore, any required conversions into the data coordinate system must be performed within the function prior to the mapping into user coordinates. The common block VVMAP, available for inclusion within the FX routine, supplies the information necessary to perform the conversion into data coordinate space, as well as for the mapping from data to user coordinates. The default version of FX simply performs an identity mapping from grid to user coordinate space.

4.3.2 Arguments

X (REAL, input): The X coordinate of a vector location in the grid coordinate system.

Y (REAL, input): The Y coordinate of a vector location in the grid coordinate system.

4.4 MXF (X,Y,U,V,SFX,SFY,MX,MY)

MXF is a user-modifiable function that, given one endpoint of a vector in both grid and metacode coordinates, returns the X coordinate of the other endpoint in the metacode coordinate system.

4.4.1 Usage

The user does not invoke the function, MXF, directly. However, any time that the compatibility mode parameter CPM is set such that the FX and FY routines are used to map the first endpoint of the vector, the functions MXF and MYF are used to determine the second endpoint. First FX and FY are invoked to determine the vector location in user coordinates, then this point is converted into metacode coordinates; MXF is passed the coordinates of the point both in grid space and in metacode space, along with the vector components and a scale factor used to convert the vector magnitude into a length in the metacode coordinate system.

If the mapping from data to user and from user to metacode coordinates is linear MXF is not hard to use: the default version simply multiplies the U component of the vector (the component parallel to the X grid axis) by the scale factor, SFX, and adds it to the X coordinate of the first point in metacode coordinates, MX. This value is returned as the function value. However, if the mapping is anywhere non-linear, the vector directional angle may change across the transformation, and an iterative differential technique must be employed to map the second endpoint of the vector. If creating a new mapping, the user is strongly urged to use the user-modifiable routine VVUMXY, rather than attempting to work with MXF and MYF.

4.4.2 Arguments

X (REAL, input): The X coordinate of a vector location in the grid coordinate system.

Y (REAL, input) The Y coordinate of a vector location in the grid coordinate system.

U (REAL, input) The U component of the vector at the data point specified by arguments X and Y.

V (REAL, input) The V component of the vector at the data point specified by arguments X and Y.

SFX (REAL, input) Scale factor used to convert the vector magnitude to a length in metacode coordinates.

SFY (REAL, input) Scale factor used to convert the vector magnitude to a length in metacode coordinates. In the current implementation this value is the same as the value of SFX.

MX (INTEGER, input) X coordinate of the vector location in metacode coordinates.

MY (INTEGER, input) Y coordinate of the vector location of the vector in metacode coordinates.

4.5 MYF (X,Y,U,V,SFX,SFY,MX,MY)

MXF is a user-modifiable function that, given one endpoint of a vector in both grid and metacode coordinates, returns the X coordinate of the other endpoint in the metacode coordinate system.

4.5.1 Usage

The user does not invoke the function, MYF, directly. However, any time that the compatibility mode parameter CPM is set such that the FX and FY routines are used to map the first endpoint of the vector, the functions MXF and MYF are used to determine the second endpoint. First FX and FY are invoked to determine the vector location in user coordinates, then this point is converted into metacode coordinates; MYF is passed the coordinates of the point both in grid space and in metacode space, along with the vector components and a scale factor used to convert the vector magnitude into a length in the metacode coordinate system.

If the mapping from data to user and from user to metacode coordinates is linear MYF is not hard to use: the default version simply multiplies the V component of the vector (the component parallel to the Y grid axis) by the scale factor, SFY, and adds it to the Y coordinate of the first point in metacode coordinates, MY. This value is returned as the function value. However, if the mapping is anywhere non-linear, the vector directional angle may change across the transformation, and an iterative differential technique must be employed to map the second endpoint of the vector. If creating a new mapping, the user is strongly urged to use the user-modifiable routine VVUMXY, rather than attempting to work with MXF and MYF.

4.5.2 Arguments

X (REAL, input): The X coordinate of a data point in the grid coordinate system.

Y (REAL, input) The Y coordinate of a data point in the grid coordinate system.

U (REAL, input) The U component of the vector at the data point specified by arguments X and Y.

V (REAL, input) The V component of the vector at the data point specified by arguments X and Y.

SFX (REAL, input) Scale factor used to convert the vector magnitude to a length in metacode coordinates.

SFY (REAL, input) Scale factor used to convert the vector magnitude to a length in metacode coordinates. In the current implementation this value is the same as the value of SFX.

MX (INTEGER, output) X coordinate of the vector location in metacode coordinates.

MY (INTEGER, output) Y coordinate of the vector location in metacode coordinates.

4.6 VELVCT (U,LU,V,LV,M,N,FLO,HI,NSET,LENGTH,ISPV,SPV)

VELVCT plots a vector field, given two 2-dimensional vector component arrays, U and V. Certain characteristics of the plot may be controlled by adjusting the values given to the input arguments. Other less frequently changed characteristics may be affected by modifying VELDAT, the BLOCK DATA routine that initializes members of the common blocks VEC1 and VEC2. In addition, depending on the value given to the compatibility parameter, CPM, many options may be controlled by setting internal parameters using VVSETx routines.

4.6.1 Usage

Beginning with version 3.2 of NCAR Graphics, the VELVCT entry point has been recoded as a front end to the VVINIT/VVECTR interface to Vectors. The compatibility mode parameter, CPM, controls the degree to which a call to the Version 3.2 VELVCT emulates the older call. Appropriate settings of CPM can separately answer each the following three questions regarding the level of emulation:

Given the default value of CPM, all these questions are answered in the affirmative, and a call to VELVCT gives a reasonably faithful emulation of the older version's behavior. However, even in this case, it is possible to use the parameter-setting routines to control the behavior of features that have no counterpart in the older version of VELVCT, as long as the feature is accessible without calling the new interface. For instance, you could control the vector linewidth by setting the LWD parameter, although you could not draw vectors masked to an area map because doing so requires direct invocation of VVECTR with the proper input arguments.

The following two tables show how the VELVCT input arguments and VEC1/VEC2 common block members map into internal parameters currently supported by Vectors:

Input ArgumentInternal Parameter
FLOVLC (VLC is set to -FLO if FLO is positive, 0.0 otherwise)
HIVHC (VHC is set to -HI if HI is positive, 0.0 otherwise)
NSETSET (NSET = 0 is approximately equivalent to SET = 1)
LENGTHVRL (LENGTH in Plotter Address Units is converted to VRL as a fraction of the viewport width)
ISPVSVF
SPV(1)USV
SPV(2)VSV

Common Block MemberInternal Parameter
EXTVPS
ICTRFGVPO
ILABLBL
IOFFDDPF
RMNAMN (RMN in metacode coordinates is converted to AMN as a fraction of the viewport width)
RMXAMX (RMX in metacode coordinates is converted to AMX as a fraction of the viewport width)
SIZELBS (Character size in metacode coordinates is converted to LBS as a fraction of viewport width.)
INCXXIN
INCYYIN
 MNT (When common blocks VEC1 and VEC2 override parameter settings, MNT is always set to ' ', indicating that the minimum vector text block is not to be displayed.)
IOFFMMXT (If IOFFM is non-zero, MXT is set to ' '. indicating that the maximum text block is not to be displayed. Otherwise MXT is set to the string 'MAXIMUM VECTOR'
IOFFMMXX (If IOFFM is 0, MXX is set to a computed value that, as a fraction of the viewport width, specifies a point 0.05 in NDC left of the right hand edge of the plotter frame.)
IOFFMMXY (If IOFFM is 0, MXY is set to a computed value that, as a fraction of the viewport height, specifies a point 0.005 in NDC up from the bottom edge of the plotter frame.)
IOFFMMXP (If IOFFM is 0, MXP is set to -2, indicating that the text block should be lower-right justified.

Note that the emulation of the maximum vector text block differs from the older implementation in that it now uses high-quality text.

4.6.2 Arguments

U (REAL 2-dimensional array, dimensioned LU x n: n >= N, input): By default, assumed to contain the first-dimensional Cartesian components of the vector field. However, if PLR is non-zero, it is treated as containing the vector magnitudes.

LU (INTEGER, input): Actual value of the first dimension of array U.

V (REAL 2-dimensional array, dimensioned LV x n: n >= N, input): By default, assumed to contain the second-dimensional Cartesian components of the vector field. However, if PLR is non-zero, it is treated as containing the vector angles.

LV (INTEGER, input): Actual value of the first dimension of array V.

M (INTEGER, input): Number of contiguous elements along the first dimensional axis containing data to be processed in each of the arrays, U and V.

N (INTEGER, input): Number of contiguous elements along the second dimensional axis containing data to be processed in each of the arrays, U and V.

FLO (REAL, input) Minimum vector magnitude allowed to be displayed in the plot.

HI (REAL, input) Maximum vector magnitude allowed to be displayed in the plot. If set to 0.0 there is no upper limit imposed.

NSET (INTEGER, input) Flag that controls how and when the SET call is invoked. If NSET is 0, VELVCT establishes the viewport and the window to properly scale plotting instructions to the standard configuration. PERIM is called to draw a border. If NSET is greater than zero, VELVCT assumes that the user has established the window and viewport in such a way as to properly scale the plotting instructions generated by VELVCT. PERIM is not called. If NSET is less than zero, VELVCT places the contour plot within the limits of the user's current window and viewport. PERIM is not called.

LENGTH (INTEGER, input) The length in plotter address units (PAUs) used to render the vector with the greatest magnitude that is eligible for plotting. A vector is eligible for plotting if it is less than or equal to the value of HI, unless HI is 0.0 in which case all vectors are eligible. If LENGTH is set to 0.0, the length selected is one half the diagonal length of a grid cell assuming a linear mapping of the grid coordinate space into the viewport.

ISPV (INTEGER, input) Flag to control the special value feature. 0 means that the feature is not in use. 1 means that if the value of U(I,J)=SPV(1) the vector will not be plotted. 2 means that if the value of V(I,J)=SPV(2) the vector will not be plotted. 3 means that if either U(I,J)=SPV(1) or V(I,J)=SPV(2) then the vector will not be plotted. 4 means that if U(I,J)=SPV(1) and V(I,J)=SPV(2), the vector will not be plotted.

SPV (REAL array, dimensioned 2, input) An array of length 2 which gives the value in the U array and the value in the V array which denote special values. This argument is ignored if ISPV=0. The default values are 1.0E12.

4.7 VELVEC (U,LU,V,LV,M,N,FLO,HI,NSET,ISPV,SPV)

The VELVEC call is identical to the VELVCT call except that there is no LENGTH parameter to allow adjustment of the realized length of the maximum vector magnitude.

4.7.1 Usage

VELVEC is used identically to VELVCT except that there is no provision for adjusting the realized length of the maximum vector magnitude.

4.7.2 Arguments

The arguments to VELVEC are identical in use to the corresponding arguments in the VELVCT call.

5.0 PARAMETERS

The behavior of Vectors is controlled by parameters stored in internal common blocks accessible to its routines that require access to them.

5.1 Parameter Names

Each of the parameters of Vectors is identified by a three-character mnemonic name. For example, NLV is the name of the parameter specifying the number of colors and threshold levels used to color the vector field and MSK is the name of a parameter used as a flag to allow the user to specify that the vectors are or are not to be drawn masked to an area map.

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

5.3 Parameter Defaults

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

5.4 Parameter Access

The value of a parameter may be set using one of the three routines VVSETC, VVSETI, and VVSETR. 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 VVGETC, VVGETI, and VVGETR, 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 by the user. However, a number of parameters are read-only to the user meaning that their values may be retrieved by the VVGETx routines but an attempt to set them using the VVSETx routines will result in an error. These parameters are intended to provide the user with useful information about the state of the program that may be helpful in determining how to perform the next operation.

5.5 Parameter-Name Arguments

Only the first three characters of the parameter-name argument in calls to the parameter access routines are examined. The user is encouraged to add additional text in order to make the code more understandable. For example, a call to set the number of color threshold levels might read

      CALL VVSETI ('NLV - Number of Threshold Levels',13)
Note that since the dimension of the parameter name variable is defined as 'CHARACTER*(*)', there is no limit to the number of characters used to comment the call.

5.6 Automatic Type Conversion

Normally, one would use VVSETI to set parameters of type INTEGER and VVSETR 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 VVSETI ('USV - U Array Special Value',-9999)
      CALL VVSETR ('USV - U Array Special Value',-9999.0)
to set the U array special value (which is intrinsically REAL) to -9999.0. The first has the virtue of being two characters shorter. Similarly, one could use either of the two statements

      CALL VVSETI ('CTV - Color Threshold Levels',18)
      CALL VVSETR ('CTV - Color Threshold Levels',18.)
to set the number of contour levels (which is intrinsically INTEGER) to 18. (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 VVSETR must be used, of course. Note that the argument passing rules of FORTRAN must still be respected: an INTEGER argument passed to VVSETR will have the usual "undefined" results.

5.7 Automatic Restriction of Parameter Values

Some parameters may take on any possible value of the proper type. Others are restricted to a certain range. In some cases, out-of-range parameters are simply constrained to some value within the range. In other cases, where it seems dangerous to second-guess what the user has in mind, an error is returned and the program halts.

5.8 Parameter Arrays

Some of the parameters are actually arrays. For example, the parameter CLR, which specifies a color index for each color threshold level, is actually an array dimensioned to the value of the FORTRAN PARAMETER, 'IPLVLS', currently set to a value of 255. 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 creating one parameter, named PAI, to serve as a "parameter array index". Thus, to set the color index of the tenth threshold level to 12, one would use the following code:

      CALL VVSETI ('PAI - Parameter Array Index',10)
      CALL VVSETR ('CLR - Color Index',12)

5.9 Parameters Categorized

This section contains a list of all Vectors parameters categorized by function along with a short descriptive phrase. It also notes which of the categories may safely be set in between the call to VVINIT and VVECTR. The section following is an alphabetical listing of all parameters including a detailed description.

5.9.1 Global Control Parameters

These parameters provide miscellaneous global control of the Vectors utility.

PAI - Parameter Array Index - Integer

CPM - Compatibility Mode - Integer

5.9.2 Coordinate System Control

These parameters (along with the mapping subroutine, VVMPXY or VVUMXY) establish the mapping through a series of coordinate systems starting with the array indices that define the basic grid and ending with the Normalized Device Coordinates. Any non-default values must be set prior to calling VVINIT.

SET - SET Call Flag - Integer

XIN - X Axis Array Increment (Grid) - Integer

YIN - Y Axis Array Increment (Grid) - Integer

XC1 - X Coordinate Value at Array Index 1 (World) - Real

XCM - X Coordinate Value at Array Index M (World) - Real

YC1 - Y Coordinate Value at Array Index 1 (World) - Real

YCN - Y Coordinate Value at Array Index N (World) - Real

WDL - Window Left Boundary (User) - Real

WDR - Window Right Boundary (User) - Real

WDB - Window Bottom Boundary (User) - Real

WDT - Window Top Boundary (User) - Real

VPL - Viewport Left Boundary (NDC or Fractional) - Real

VPR - Viewport Right Boundary (NDC or Fractional) - Real

VPB - Viewport Bottom Boundary (NDC or Fractional) - Real

VPT - Viewport Top Boundary (NDC or Fractional) - Real

VPS - Viewport Shape - Integer

MAP - Map Transformation Code - Integer

TRT - Transformation Type - Integer

5.9.3 Input Data Control

These parameters control the interpretation of the input data, and allow the user to place restrictions on the range of data represented. Any non-default values must be set prior to calling VVINIT.

SVF - Special Value Flag - Integer

USV - U Array Special Value - Real

VSV - V Array Special Value - Real

PSV - P Array Special Value - Real

SPC - Special Color - Integer

PLR - Polar Input Mode - Integer

5.9.4 Color Control

These parameters are used to control the set up of the color threshold array and the color index array. If CTV has a positive value, VVINIT modifies NLV members of the TVL threshold array. Otherwise, these parameters may be set between the call to VVINIT and VVECTR.

CTV - Color Threshold Value Control - Integer

NLV - Number of Color Levels - Integer

CLR - Array of GKS Color Indices - Integer Array

TVL - Array of Threshold Values - Real Array

5.9.5 Rendering Control

These parameters allow the user to make various adjustments to the rendering of the vector field plot. Parameters in this category may be set between the call to VVINIT and VVECTR. A number of parameters have an effect only for a specific arrow style (line-drawn, filled or wind barb).

MSK - Mask To Area Map Flag - Integer

VRL - Vector Reference Length - Real

VFR - Minimum Vector Fractional Length - Real

VRM - Vector Reference Magnitude - Real

VLC - Vector Low Cutoff Value - Real

VHC - Vector High Cutoff Value - Real

LWD - Vector Linewidth - Real

VPO - Vector Positioning Mode - Integer

AST - Arrow Style - Integer

AMN - Arrow Head Minimum Size (line-drawn arrows only) - Real

AMX - Arrow Head Maximum Size (line-drawn arrows only) - Real

ACM - Arrow Color Mode (filled arrows only) - Integer

AFO - Arrow Fill Over Arrow Lines (filled arrows only) - Integer

AIR - Arrow Interior Reference Fraction (filled arrows only) - Real

AWF - Arrow Width Fractional Minimum (filled arrows only) - Real

AWR - Arrow Width Reference Fraction (filled arrows only) - Real

AXF - Arrow X-Coord Fractional Minimum (filled arrows only) - Real

AXR - Arrow X-Coord Reference Fraction (filled arrows only) - Real

AYF - Arrow Y-Coord Fractional Minimum (filled arrows only) - Real

AYR - Arrow Y-Coord Reference Fraction (filled arrows only) - Real

WBA - Wind Barb Angle (wind barbs only) - Real

WBC - Wind Barb Calm Circle Size (wind barbs only) - Real

WBD - Wind Barb Distance Between Ticks (wind barbs only) - Real

WBS - Wind Barb Scale Factor (wind barbs only) - Real

WBT - Wind Barb Tick Size (wind barbs only) - Real

5.9.6 Supplementary Text Control Parameters

These parameters control the placement and appearance of various text elements associated with a vector field plot produced by Vectors. Parameters in this category may be set between the call to VVINIT and VVECTR.

LBL - Vector Label Flag - Integer

DPF - Vector Label Decimal Point Control Flag - Integer

LBS - Vector Label Character Size - Real

LBC - Vector Label Color - Integer

MNS - Minimum Vector Text Block Character Size - Real

MNX - Minimum Vector Text Block X Coordinate - Real

MNY - Minimum Vector Text Block Y Coordinate - Real

MNP - Minimum Vector Text Block Positioning Mode - Integer

MNC - Minimum Vector Text Block Color - Integer

MNT - Minimum Vector Text String - Character* 36

MXS - Maximum Vector Text Block Character Size - Real

MXX - Maximum Vector Text Block X Coordinate - Real

MXY - Maximum Vector Text Block Y Coordinate - Real

MXP - Maximum Vector Text Block Positioning Mode - Integer

MXC - Maximum Vector Text Block Color - Integer

MXT - Maximum Vector Text String - Character* 36

ZFS - Zero Field Text Block Character Size - Real

ZFX - Zero Field Text Block X Coordinate - Real

ZFY - Zero Field Text Block Y Coordinate - Real

ZFP - Zero Field Text Block Positioning Mode - Integer

ZFC - Zero Field Text Block Color - Integer

ZFT - Zero Field Text String - Character* 36

VST - Vector Statistics Output Flag

5.9.7 Read-Only Informational Parameters

These parameters may be used to retrieve information about the state of the Vectors utility. The may be retrieved at any time, but may not contain useful information at all stages of the processing.

VMN - Minimum Displayed Vector Magnitude - Real

VMX - Maximum Displayed Vector Magnitude - Real

DMN - Minimum Vector Size (NDC) - Real

DMX - Maximum Vector Size (NDC) - Real

PMN - Minimum Scalar Array Value - Real

PMX - Maximum Scalar Array Value - Real

5.10 Parameter Description

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.

5.10.1 ACM - Arrow Color Mode - Integer

ACM controls how color is applied to filled vector arrows. It applies only when AST has the value 1. Its behavior also depends on the setting of the parameter CTV. Assuming that CTV is set to a non-zero value, implying that multi-colored vectors are desired, ACM has the following settings:

ValueEffect
-2Multi-colored fill; outline off
-1Fill off; multi-colored outline
0 (default)Multi-colored fill; mono-colored outline
1Mono-colored fill; multi-colored outline
2Multi-colored fill; multi-colored outline

Mono-colored outlines use the current GKS polyline color index. Mono-colored fill uses the current GKS fill color index. When CTV is set to 0, both the fill and the outlines become mono-colored, and therefore only modes -2, -1, and 0 remain distinguishable. The default value is 0.

5.10.2 AFO - Arrow Interior Reference Fraction - Real

If AFO is set to 1, the perimeter outline of a filled vector arrow is drawn first, underneath the fill. In this case, you must set the line thickness parameter (LWD) to a value greater than unity in order for the line to appear completely. The advantage of drawing the line underneath is that the full extent of the fill appears, resulting in a crisper, more sharply defined arrow; when the line is drawn on top of the fill using a different color index, the fill color may be partially or completely obscured, especially for small vector arrows. AFO has an effect only when the parameter AST is set to 1. The default value of AFO is 1.

5.10.3 AIR - Arrow Interior Reference Fraction - Real

AIR specifies the distance from the point of the arrowhead of a filled vector arrow drawn at the reference length to the point where the arrowhead joins with the line extending to the tail of the arrow. Its value represents a fraction of the reference length. This distance is adjusted proportionally to the X component of the arrowhead size for vector arrows whose length differs from the reference length. See VRL for an explanation of how the reference length is determined. AIR has an effect only when AST is set to 1. AIR is allowed to vary between 0.0 and 1.0 and its default value is 0.33.

5.10.4 AMN - Arrow Head Minimum Size - Real

Specifies a minimum length for the two lines representing the point of the vector arrow head, as a fraction of the viewport width. AMN has an effect only for line-drawn vector arrows (parameter AST set to 0). Normally the arrow head size is scaled proportionally to the length of the vector. This parameter allows you to ensure that the arrow head will remain recognizable even for very short vectors. Note that you can cause all the arrowheads in the plot to be drawn at the same size if you set AMN and AMX to the same value. If you set both AMN and AMX to 0.0 the arrowheads will not be drawn at all. The default value is 0.005.

5.10.5 AMX - Arrow Head Maximum Size - Real

Specifies a maximum length for the two lines representing the point of the vector arrow head, as a fraction of the viewport width. AMX has an effect only for line-drawn vector arrows (parameter AST set to 0). Normally the arrow head is scaled proportionally to the length of the vector. This parameter allows you to ensure that the arrow heads do not become excessively large for high magnitude vectors. Note that you can cause all the arrowheads in the plot to be drawn at the same size if you set AMN and AMX to the same value. If you set both AMN and AMX to 0.0 the arrowheads will not be drawn at all. The default value is 0.05.

5.10.6 AST - Arrow Style - Integer

If AST is set to 0, the vector arrows are drawn using lines only. When AST is set to 1, the vectors are plotted using variable width filled arrows, with an optional outline. If AST is set to 2, wind barb glyphs are used to represent the vectors. There are parameters for controlling the appearance of each style. These have an effect only for one value of AST. However, certain parameters apply to all arrow styles. Here is a table of parameters that affect the appearance of vectors and how their behavior is affected by the setting of AST:

ParameterLine-Drawn ArrowsFilled ArrowsWind Barbs
ACM x 
AFO x 
AIR x 
AMNx  
AMXx  
AWF x 
AWR x 
AXF x 
AXR x 
AYF x 
AYR x 
CLRxxx
CTVxxx
LWDxxx
NLVxxx
PAIxxx
TVLxxx
WBA  x
WBC  x
WBD  x
WBS  x
WBT  x

When filled arrows are used, colors associated with the threshold levels may be applied to either or both the fill or the outline of the arrow. When fill is drawn over the outline (AFO set to 1), LWD should be set to a value greater than 1.0 in order for the outline to be fully visible. The default value of AST is 0.

5.10.7 AWF - Arrow Width Fractional Minimum - Real

AWF specifies the width of a filled arrow drawn at the minimum length, as a fraction of the width of an arrow drawn at the reference length. If AWF has the value 0.0, then the ratio of the arrow width to the arrow length will be constant for all arrows in the plot. If given the value 1.0, the width will itself be constant for all arrows in the plot, regardless of length. See VFR for a discussion of how the minimum length is determined. AWF has an effect only when AST is set to 1. AWF is allowed to vary between 0.0 and 1.0 and its default value is 0.25.

5.10.8 AWR - Arrow Width Reference Fraction - Real

AWR specifies the width of a filled vector arrow drawn at the reference length, as a fraction of the reference length. See VRL for an explanation of how the reference length is determined. AWR has an effect only when AST is set to 1. AWR is allowed to vary between 0.0 and 1.0 and its default value is 0.1.

5.10.9 AXF - Arrow X-Coord Fractional Minimum - Real

AXF specifies the X component of the head of a filled vector arrow drawn at the minimum length, as a fraction of the X component of the head of an arrow drawn at the reference length. The X component of the arrowhead is the distance from the point of the arrowhead to a point along the centerline of the arrow perpendicular to the arrowhead's rear tips. If AXF has the value 0.0, then the ratio of the X component of the arrowhead size to the arrow length will be constant for all vectors in the plot. If given the value 1.0, the arrowhead X component will itself be constant for all arrows in the plot, regardless of their length. See VRL for an explanation of how the reference length is determined. AXF has an effect only when AST is set to 1. AXF is is allowed to vary between 0.0 and 1.0 and its default value is 0.25.

5.10.10 AXR - Arrow X-Coord Reference Fraction - Real

AXR specifies the X component of the head of a filled vector arrow drawn at the reference length, as a fraction of reference length. The X component of the arrowhead is the distance from the point of the arrowhead to a point along the centerline of the arrow perpendicular to the arrowhead's rear tips. See VRL for an explanation of how the reference length is determined. AXR has an effect only when AST is set to 1. AXR is allowed to vary between 0.0 and 2.0 and its default value is 0.36.

5.10.11 AYF - Arrow Y-Coord Fractional Minimum - Real

AYF specifies the Y component of the head of a filled vector arrow drawn at the minimum length, as a fraction of the Y component value of an arrow drawn at the reference length. The Y component of the arrowhead is considered to be the perpendicular distance from an edge parallel to the arrow's centerline to one of the arrowhead's rear tips. If AYF has the value 0.0, then the ratio of the Y component of the arrowhead size to the arrow length will be constant for all vectors in the plot. If given the value 1.0, the arrowhead Y component will itself be constant for all arrows in the plot, regardless of length or width. See VFR for a discussion of how the minimum length is determined. AYF has an effect only when AST is set to 1. AYF is allowed to vary between 0.0 and 1.0 and its default value is 0.25.

5.10.12 AYR - Arrow Y-Coord Reference Fraction - Real

AYR specifies the Y component of a filled vector arrow drawn at the reference length, as a fraction of the reference length. The Y component of the arrowhead is considered to be the perpendicular distance from an edge parallel to the arrow's centerline to one of the arrowhead's rear tips. See VRL for an explanation of how the reference length is determined. AYR has an effect only when AST is set to 1. AYR is allowed to vary between 0.0 and 1.0 and its default value is 0.12.

5.10.13 CLR - Array of GKS Color Indices - Integer Array

This parameter represents an array containing the GKS color index to use for coloring the vector when the scalar quantity is less than or equal to the threshold value with the same index in the TVL threshold value array. Depending on the settings of AST and ACM it may specify a set of fill color indexes, a set of line color indexes, or both. In order to access a particular element of the CLR array, you must first set the value of PAI, the parameter array index parameter, to the value of the array element's index. All elements of the array are set to one initially. Note that the Vectors utility makes no calls to set the GKS color representation (GSCR), nor ever modifies the contents of the CLR array; therefore you are responsible for creating a suitably graduated color palette and assigning the color index values into the CLR array, prior to calling VVECTR. Typically, assuming the desired RGB values have been previously stored in a 2-dimensional 3 x n array called RGB, you loop through the calls that set up the color representation and color index as in the following example for a fourteen color palette:

      DO 100 I=1,14,1
        CALL GSCR (1,I,RGB(1,I),RGB(2,I),RGB(3,I))
        CALL VVSETI('PAI -- Parameter Array Index', I)
        CALL VVSETI('CLR -- GKS Color Index', I)
  100 CONTINUE
See the descriptions of CTV, NLV, and TVL for details on configuring the vector coloring scheme.

5.10.14 CPM - Compatibility Mode - Integer

Controls the degree of compatibility between pre-Version 3.2 capabilities of the Vectors utility and later versions. You can independently control three behaviors using the nine settings provided:

Note, however, that when using the Version 3.2 entry points VVINIT and VVECTR, only the third behavior option has any meaning.

When CPM is set to 0, its default value, the Vectors utility's behavior varies depending on whether the utility has been accessed through one of the pre-Version 3.2 entry points (VELVCT, VELVEC, and EZVEC), or through the VVINIT/VVECTR interface. Otherwise, positive values result in invocation of the pre-Version 3.2 mapping routines (FX, FY, MXF, and MYF) for the conversion from data to user coordinates. Negative values cause VVMPXY and perhaps VVUMXY to be used instead. When using the pre-Version 3.2 interface, odd values of CPM cause the data values in the VELDAT block data subroutine to override corresponding values initialized in the Version 3.2 VVDATA block data subroutine, or set by the user calling VVSETx routines. Values of CPM with absolute value greater than two cause some of the input arguments to VELVEC and VELVCT to be ignored. These include FLO, HI, NSET, ISPV, SPV and (for VELVCT only) LENGTH.

Here is a table of the nine settings of CPM and their effect on the operation of the Vectors utility:

ValueUse FX, FY, etc.Use VELDAT dataUse input arguments
-4nonono
-3noyesno
-2nonoyes
-1noyesyes
0old - yes; new - no (*)yesyes
1yesyesyes
2yesnoyes
3yesyesno
4yesnono

(*) Old means EZVEC, VELVEC, VELVCT entry point; new, VVINIT/VVECTR. Only the first column affects the behavior of the VVINIT/VVECTR interface

5.10.15 CTV - Color Threshold Value Control - Integer

In conjunction with NLV, this parameter controls vector coloring and the setting of threshold values. The vectors may be colored based on the vector magnitude or on the contents of a scalar array (VVINIT/VVECTR input argument, P). A table of supported options follows:

ValueAction
-2Color vector arrows based on scalar array data values; the user is responsible for setting up threshold level array, TVL
-1Color vector arrows based on vector magnitude; the user is responsible for setting up values of threshold level array.
0 (default)Color all vectors according to the current GKS polyline color index value. Threshold level array, TVL and GKS color index array, CLR are not used.
1Color vector arrows based on vector magnitude; VVINIT assigns values to the first NLV elements of the threshold level array, TVL.
2Color vector arrows based on scalar array data values; VVINIT assigns values to the first NLV elements of the threshold level array, TVL.

5.10.16 DMN - NDC Minimum Vector Size - Real, Read-Only

This parameter is read-only and has a useful value only following a call to VVECTR (directly or through the compatibility version of VELVCT). It may be retrieved in order to determine the length in NDC space of the smallest vector actually drawn (in other words, the smallest vector within the boundary of the user coordinate space that is greater than or equal in magnitude to the value of the VLC parameter). It is initially set to a value of 0.0.

5.10.17 DMX - NDC Maximum Vector Size - Real, Read-Only

Unlike DMN this read-only parameter has a potentially useful value between calls to VVINIT and VVECTR. However, the value it reports may be different before and after the call to VVECTR. Before the VVECTR call it contains the length in NDC space that would be used to render the maximum size vector assuming the user-settable parameter, VRL is set to its default value of 0.0. After the VVECTR call it contains the NDC length used to render the largest vector actually drawn (in other words, the largest vector within the boundary of the user coordinate space that is less than or equal in magnitude to the value of the VHC parameter). See the section on the VRL parameter for information on using the value of DMX after the VVINIT call in order to adjust proportionally the lengths of all the vectors in the plot. It is initially set to a value of 0.0.

5.10.18 DPF - Vector Label Decimal Point Control Flag - Integer

If DPF is set to a non-zero value, and the optional vector magnitude labels are enabled, the magnitude values are scaled to fit in the range 1 to 999. The labels will contain 1 to 3 digits and no decimal point. Otherwise, the labels will consist of a number up to six characters long, including a decimal point. By default DPF is set to the value 1.

5.10.19 LBC - Vector Label Color - Integer

This parameter specifies the color to use for the optional vector magnitude labels, as follows:

ValueAction
< -1Draw labels using the current GKS text color index
-1 (default)Draw labels using the same color as the corresponding vector arrow
>=0Draw labels using the LBC value as the GKS text color index

5.10.20 LBL - Vector Label Flag - Integer

If set non-zero, Vectors draws labels representing the vector magnitude next to each arrow in the field plot. The vector labels are primarily intended as a debugging aid, since in order to avoid excessive overlap, you must typically set the label text size too small to be readable without magnification. For this reason, as well as for efficiency, unlike the other graphical text elements supported by the Vectors utility, the vector labels are rendered using low quality text.

5.10.21 LBS - Vector Label Character Size - Real

This parameter specifies the size of the characters used for the vector magnitude labels as a fraction of the viewport width. The default value is 0.007.

5.10.22 LWD - Vector Linewidth - Real

LWD controls the linewidth used to draw the lines that form vector arrows and wind barbs. When the arrows are filled (AST is set to 1) LWD controls the width of the arrow's outline. If the fill is drawn over the outline (AFO set to 1) then LWD must be set to a value greater than 1.0 in order for the outline to appear properly. When AST has the value 2, LWD controls the width of the line elements of wind barbs. When AST is set to 0, specifying line-drawn vector arrows, the linewidth applies equally to the body of the vector and the arrowhead. Overly thick lines may cause the arrow heads to appear smudged. This was part of the motivation for developing the option of filled vector arrows. Note that since linewidth in NCAR Graphics is always calculated relative to a unit linewidth that is dependent on the output device, you may need to adjust the linewidth value depending on the intended output device to obtain a pleasing plot. The default is 1.0, specifying a device-dependent minimum linewidth.

5.10.23 MAP - Map Transformation Code - Integer

MAP defines the transformation between the data and user coordinate space. For a complete explanation of the various coordinate systems used by the Vectors utility, see Section 2.3, Coordinate Systems in Vectors. Other relevant information is contained in the discussion of the user-modifiable mapping subroutine, VVUMXY, and in the discussion of parameter TRT, Transformation Type. Three MAP parameter codes are reserved for pre-defined transformations, as follows:

ValueMapping transformation
0 (default)Identity transformation between data and user coordinates: array indices of U, V, and P are linearly related to data coordinates.
1 EZMAP transformation: first dimension indices of U, V, and P are linearly related to longitude; second dimension indices are linearly related to latitude.
2Polar to rectangular transformation: first dimension indices of U, V, and P are linearly related to the radius; second dimension indices are linearly related to the angle in degrees.

If MAP has any other value, the mapping subroutine VVMPXY, passes its parameters on to the user-modifiable subroutine, VVUMXY. The default version of VVUMXY simply performs an identity transformation, without considering the value of the TRT parameter. The effect is the same as if one were to set both MAP and TRT to zero. Note that, while not actually prohibited in the Vectors utility, the user is advised not to use negative integers for user-defined mappings, since a negative value results in an inverse transformation in the CONPACK utility. Inverse transformations are not needed in Vectors but an inconsistent use of negative mapping codes would likely be confusing in the long run.

For all the predefined mappings, the linear relationship between the grid array indices and the data coordinate system is established using the four parameters XC1, XCM, YC1, and YCN. The X parameters define a mapping for the first and last indices of the first dimension of the data arrays, and the Y parameters do the same for the second dimension. If MAP is set to a value of one, the user needs to be careful to ensure that the SET parameter is given a value of zero, since the EZMAP routines call the SET routine to define the user to NDC mapping. Otherwise, the user may choose whether or not to issue a SET call prior to calling VVINIT, modifying the value of SET as required.

5.10.24 MNC - Minimum Vector Text Block Color - Integer

MNC specifies the color of the minimum vector graphical text output block as follows:

ValueAction
<-2Both the vector arrow and the text are colored using the current text color index.
-2If the vectors are colored by magnitude, both the vector arrow and the text use the GKS color index associated with the minimum vector magnitude. Otherwise, the vector arrow uses the current polyline color index and the text uses the current text color index.
-1 (default)If the vectors are colored by magnitude, the vector arrow uses the GKS color index associated with the minimum vector magnitude. Otherwise the vector arrow uses the current polyline color index. The text is colored using the current text color index in either case.
>= 0The value of MNC is used as the color index for both the text and the vector arrow.

See the description of MNT for more information about the minimum vector text block.

5.10.25 MNP - Minimum Vector Text Block Positioning Mode - Integer

This parameter allows you to justify the minimum vector text block, taken as a single unit, relative to the text block position established by the parameters, MNX and MNY. Nine positioning modes are available, as follows:

ModeJustification
-4The lower left corner of the text block is positioned at MNX, MNY.
-3The center of the bottom edge is positioned at MNX, MNY.
-2The lower right corner is positioned at MNX, MNY.
-1The center of the left edge is positioned at MNX, MNY.
0The text block is centered along both axes at MNX, MNY.
1The center of the right edge is positioned at MNX, MNY.
2The top left corner is positioned at MNX, MNY.
3The center of the top edge is positioned at MNX, MNY.
4 (default)The top right corner is positioned at MNX, MNY.

See the description of MNT for more information about the minimum vector text block.

5.10.26 MNS - Minimum Vector Text Block Character Size - Real

MNS specifies the size of the characters used in the minimum vector graphics text block as a fraction of the viewport width. See the description of MNT for more information about the minimum vector text block. The default value is 0.0075.

5.10.27 MNT - Minimum Vector Text String - Character* 36

The minimum vector graphics text block consists of a user-definable text string centered underneath a horizontal arrow. If the parameter VLC is set negative the arrow is rendered at the size of the reference minimum magnitude vector (which may be smaller than any vector that actually appears in the plot). Otherwise, the arrow is the size of the smallest vector in the plot. Directly above the arrow is a numeric string in exponential format that represents the vector's magnitude.

Use MNT to modify the text appearing below the vector in the minimum vector graphics text block. Currently the string length is limited to 36 characters. Set MNT to a single space (' ') to remove the text block, including the vector arrow and the numeric magnitude string, from the plot. The default value is 'Minimum Vector'

5.10.28 MNX - Minimum Vector Text Block X Coordinate - Real

MNX establishes the X coordinate of the minimum vector graphics text block as a fraction of the viewport width. Values less than 0.0 or greater than 1.0 are permissible and respectively represent regions to the left or right of the viewport. The actual position of the block relative to MNX depends on the value assigned to MNP. See the descriptions of MNT and MNP for more information about the minimum vector text block. The default value of MNX is 0.475.

5.10.29 MNY - Minimum Vector Text Block Y Coordinate - Real

MNY establishes the Y coordinate of the minimum vector graphics text block as a fraction of the viewport height. Values less than 0.0 or greater than 1.0 are permissible and respectively represent regions below or above the viewport. The actual position of the block relative to MNY depends on the value assigned to MNP. The default value is -0.01.

5.10.30 MSK - Mask To Area Map Flag - Integer

Use this parameter to control masking of vectors to an existing area map created by routines in the Areas utility. When MSK is greater than 0, masking is enabled and an the area map must be set up prior to the call to VVECTR. The area map array and, in addition, the name of a user-definable masked drawing routine, must be passed as input parameters to VVECTR. Various values of the MSK parameter have the following effects:

ValueEffect
<= 0 (default)No masking of vectors.
1The subroutine ARDRLN is called internally to decompose the vectors into segments contained entirely within a single area. ARDRLN calls the user-definable masked drawing subroutine.
>1Low precision masking. ARGTAI is called internally to get the area identifiers for the vector base position point. Then the user-definable masked drawing subroutine is called to draw the vector. Vectors with nearby base points may encroach into the intended mask area.

See the discussion of the default version of the user-definable subroutine, VVUDMV, for further explanation of masked drawing of vectors

5.10.31 MXC - Maximum Vector Text Block Color - Integer

MXC specifies the color of the maximum vector graphical text output block as follows:

ValueAction
<-2Both the vector arrow and the text are colored using the current text color index.
-2If the vectors are colored by magnitude, both the vector arrow and the text use the GKS color index associated with the minimum vector magnitude. Otherwise, the vector arrow uses the current polyline color index and the text uses the current text color index.
-1 (default)If the vectors are colored by magnitude, the vector arrow uses the GKS color index associated with the minimum vector magnitude. Otherwise the vector arrow uses the current polyline color index. The text is colored using the current text color index in either case.
>= 0The value of MXC is used as the color index for both the text and the vector arrow

See the description of MXT for more information about the maximum vector text block.

5.10.32 MXP - Maximum Vector Text Block Positioning Mode - Integer

This parameter allows you to justify the maximum vector text block, taken as a single unit, relative to the text block position established by the parameters, MXX and MXY. Nine positioning modes are available, as follows:

ModeJustification
-4The lower left corner of the text block is positioned at MXX, MXY.
-3The center of the bottom edge is positioned at MXX, MXY.
-2The lower right corner is positioned at MXX, MXY.
-1The center of the left edge is positioned at MXX, MXY.
0The text block is centered along both axes at MXX, MXY.
1The center of the right edge is positioned at MXX, MXY.
2 (default)The top left corner is positioned at MXX, MXY.
3The center of the top edge is positioned at MXX, MXY.
4 The top right corner is positioned at MXX, MXY.

See the description of MXT for more information about the maximum vector text block.

5.10.33 MXS - Maximum Vector Text Block Character Size - Real

MXS specifies the size of the characters used in the maximum vector graphics text block as a fraction of the viewport width. See the description of MXT for more information about the maximum vector text block. The default value is 0.0075.

5.10.34 MXT - Maximum Vector Text String - Character* 36

The maximum vector graphics text block consists of a user-definable text string centered underneath a horizontal arrow. If the parameter VHC is set negative the arrow is rendered at the size of the reference maximum magnitude vector (which may be larger than any vector that actually appears in the plot). Otherwise, the arrow is the size of the largest vector in the plot. Directly above the arrow is a numeric string in exponential format that represents the magnitude of this vector.

Use MXT to modify the text appearing below the vector in the maximum vector graphics text block. Currently the string length is limited to 36 characters. Set MXT to a single space (' ') to completely remove the text block, including the vector arrow and the numeric magnitude string, from the plot. Note that the name "Maximum Vector Text Block" is no longer accurate, since using the parameter VRM it is now possible to establish a reference magnitude that is smaller than the maximum magnitude in the data set. A more accurate name would be "Reference Vector Text Block". The default value of MXT is 'Maximum Vector'.

5.10.35 MXX - Maximum Vector Text Block X Coordinate - Real

MXX establishes the X coordinate of the maximum vector graphics text block as a fraction of the viewport width. Values less than 0.0 or greater than 1.0 are permissible and respectively represent regions left or right of the viewport. The actual position of the block relative to MXX depends on the value assigned to MXP. See the descriptions of MXT and MXP for more information about the maximum vector text block. The default value is 0.525.

5.10.36 MXY - Maximum Vector Text Block Y Coordinate - Real

MXY establishes the Y coordinate of the maximum vector graphics text block as a fraction of the viewport width. Values less than 0.0 or greater than 1.0 are permissible and respectively represent regions below or above the viewport. The actual position of the block relative to MXY depends on the value assigned to MXP. See the descriptions of MXT and MXP for more information about the maximum vector text block. The default value is -0.01.

5.10.37 NLV - Number of Color Levels - Integer

NLV specifies the number of color levels to use when coloring the vectors according to data in a scalar array or by vector magnitude. Any time CTV has a non-zero value, you must set up the first NLV elements of the color index array CLR. Give each element the value of a GKS color index that must be defined by a call to the GKS subroutine, GSCR, prior to calling VVECTR. If CTV is less than 0, in addition to setting up the CLR array, you are also responsible for setting the first NLV elements of the threshold values array TVL to appropriate values. Currently NLV is constrained to a maximum value of 255. The default value of NLV is 0, specifying that vectors are colored according to the value of the GKS polyline color index currently in effect, regardless of the value of CTV. If CTV is greater than 0, you must initialize Vectors with a call to VVINIT after modifying this parameter.

5.10.38 PAI - Parameter Array Index - Integer

The value of PAI must be set before calling VVGETC, VVGETI, VVGETR, VVSETC, VVSETI, or VVSETR to access any parameter which is an array; it acts as a subscript to identify the intended array element. For example, to set the 10th color threshold array element to 7, use code like this:

      CALL VVSETI ('PAI - PARAMETER ARRAY INDEX',10)
      CALL VVSETI ('CLR - Color Index',7)
The default value of PAI is one.

5.10.39 PLR - Polar Input Mode - Integer

When PLR is greater than zero, the vector component arrays are considered to contain the field data in polar coordinate form: the U array is treated as containing the vector magnitude and the V array as containing the vector angle. Be careful not to confuse the PLR parameter with the MAP parameter set to polar coordinate mode (2). The MAP parameter relates to the location of the vector, not its value. Here is a table of values for PLR:

ValueMeaning
0 (default)U and V arrays contain data in cartesian component form.
1U array contains vector magnitudes; V array contains vector angles in degrees.
2U array contain vector magnitudes; V array contains vector angles in radians.

5.10.40 PMN - Minimum Scalar Array Value - Real, Read-Only

You may retrieve the value specified by PMN at any time after a call to VVINIT. It will contain a copy of the minimum value encountered in the scalar data array. If no scalar data array has been passed into VVINIT it will have a value of 0.0.

5.10.41 PMX - Maximum Scalar Array Value - Real

You may retrieve the value specified by PMX at any time after a call to VVINIT. It contains a copy of the maximum value encountered in the scalar data array. If no scalar data array has been passed into VVINIT it will have a value of 0.0.

5.10.42 PSV - P Array Special Value - Real

Use PSV to indicate the special value that flags an unknown data value in the P scalar data array. This value will not be considered in the determination of the dataset maximum and minimum values. Also, depending on the setting of the SPC parameter, the vector may be specially colored to flag the unknown data point, or even eliminated from the plot.

5.10.43 SET - SET Call Flag - Integer

Give SET the value 0 to inhibit the SET call otherwise performed by VVINIT. Arguments 5-8 of a SET call done by the user must be consistent with the ranges of the user coordinates expected by Vectors. This is determined by the mapping from grid to data coordinates as specified by the values of the parameters XC1, XCM, YC1, YCN, and also by the mapping from data to user coordinates established by the MAP parameter. See the descriptions of these parameters and the section, Coordinate Systems in Vectors. The default value of SET is 1.

5.10.44 SPC - Special Color - Integer

SPC controls special value processing for the optional scalar data array used to color the vectors, as follows:

ValueEffect
< 0 (default)The P scalar data array is not examined for special values.
0Vectors at P scalar array special value locations are not drawn.
> 0Vectors at P scalar array special value locations are drawn using color index SPC.

5.10.45 SVF - Special Value Flag - Integer

The special value flag controls special value processing for the U and V vector component data arrays. Special values may appear in either the U or V array or in both of them. Five different options are available (although the usefulness of some of the choices is debatable):

ValueEffect
0 (default)Neither the U nor the V array is examined for special values
1Vectors with special values in the U array are not drawn
2Vectors with special values in the V array are not drawn
3Vectors with special values in either the U or V array are not drawn
4Vectors with special values in both the U and V arrays are not drawn

The U and V special values are defined by setting parameters USV and VSV.

5.10.46 TRT - Transformation Type - Integer

As currently implemented, TRT further qualifies the mapping transformation specified by the MAP parameter, as follows:

ValueEffect
-1Direction, magnitude, and location are all transformed. This option is not currently supported by any of the pre-defined coordinate system mappings.
0Only location is transformed
1 (default)Direction and location are transformed

This parameter allows you to distinguish between a system that provides a mapping of location only into an essentially cartesian space, and one in which the space itself is mapped. To understand the difference, using polar coordinates as an example, imagine a set of wind speed monitoring units located on a radial grid around some central point such as an airport control tower. Each unit's position is defined in terms of its distance from the tower and its angular direction from due east. However, the data collected by each monitoring unit is represented as conventional eastward and northward wind components. Assuming the towers' location is at a moderate latitude, and the monitoring units are reasonably 'local', this is an example of mapping a radially defined location into a nearly cartesian space (i.e. the eastward components taken alone all point in a single direction on the plot, outlining a series of parallel straight lines). One would set MAP to two (for the polar transformation) and TRT to zero to model this data on a plot generated by the Vectors utility.

On the other hand, picture a set of wind data, again given as eastward and northward wind components, but this time the center of the polar map is actually the south pole. In this case, the eastward components do not point in a single direction; instead they outline a series of circles around the pole. This is a space mapping transformation: one would again set MAP to two, but TRT would be set to one to transform both direction and location.

Changing the setting of this parameter affects the end results only when a non-uniform non-linear mapping occurs at some point in the transformation pipeline. For this discussion a uniform linear transformation is defined as one which satisfies the following equations:

      Xout = Xoffset + Scaleconstant * Xin
      Yout = Yoffset + Scaleconstant * Yin
If Scaleconstant is not the same for both the X axis and the Y axis then the mapping is non-uniform.

This option is currently implemented only for the pre-defined MAP parameter codes, 0 and 2, the identity mapping and the polar coordinate mapping. However, it operates on a different stage of the transformation pipeline in each case. The polar mapping is non-linear from data to user coordinates. The identity mapping, even though necessarily linear over the data to user space mapping, can have a non-uniform mapping from user to NDC space, depending on the values given to the input parameters of the SET call. This will be the case whenever the LL input parameter is other than one, or when LL equals one, but the viewport and the user coordinate boundaries do not have the same aspect ratio. Thus for a MAP value of 2, TRT affects the mapping between data and user space, whereas for MAP set to 0, TRT influences the mapping between user and NDC space.

5.10.47 TVL - Array of Threshold Values - Real Array

TVL is an array of threshold values that is used to determine the individual vector color, when CTV and NLV are both non-zero. For each vector the TVL array is searched for the smallest value greater than or equal to the scalar value associated with the vector. The array subscript of this element is used as an index into the CLR array. Vectors uses the GKS color index found at this element of the CLR array to set the color for the vector. Note that Vectors assumes that the threshold values are monotonically increasing.

When CTV is less than 0, you are responsible for assigning values to the elements of TVL yourself. To do this, first set the PAI parameter to the index of the threshold level element you want to define, then call VVSETR to set TVL to the appropriate threshold value for this element. Assuming the desired values have previously been stored in a array named TVALS, you could assign the threshold values for a fourteen level color palette using the following loop:

      DO 100 I=1,14,1
        CALL VVSETI(PAI -- Parameter Array Index, I)
        CALL VVSETR(TVL -- Threshold Value, TVALS(I))
  100 CONTINUE
When CTV is greater than 0, Vectors assigns values into TVL itself. Each succeeding element value is greater than the preceding value by the value of the expression:

      (maximum_data_value - minimum_data_value) / NLV
where the data values are either from the scalar data array or are the magnitudes of the vectors in the vector component arrays. The first value is equal to the minimum value plus the expression; the final value (indexed by the value of NLV) is equal to the maximum value. If Vectors encounters a value greater than the maximum value in the TVL array while processing the field data, it gives the affected vector the color associated with the maximum TVL value.

5.10.48 USV - U Array Special Value - Real

USV is the U vector component array special value. It is a value outside the range of the normal data and is used to indicate that there is no valid data for this grid location. When SVF is set to 1 or 3, Vectors will not draw a vector whose U component has the special value. It has a default value of 1.0 E12.

5.10.49 VFR - Minimum Vector Fractional Length - Real

Use this parameter to adjust the realized size of the reference minimum magnitude vector relative to the reference maximum magnitude vector in order to improve the appearance or perhaps the information content of the plot. Specify VFR as a value between 0.0 and 1.0, where 0.0 represents an unmodified linear scaling of the realized vector length, in proportion to magnitude, and 1.0 specifies that the smallest vector be represented at 1.0 times the length of the largest vector, resulting in all vectors, regardless of magnitude, having the same length on the plot. A value of 0.5 means that the smallest magnitude vector appears half as long as the largest magnitude vector; intermediate sizes are proportionally scaled to lengths between these extremes. Where there is a wide variation in magnitude within the vector field, you can use this parameter to increase the size of the smallest vectors to a usefully visible level. Where the variation is small, you can use the parameter to exaggerate the differences that do exist. See also the descriptions of VRL, VLC, VHC, and VRM. The default value is 0.0.

5.10.50 VHC - Vector High Cutoff Value - Real

If the parameter VRM is set to a value greater than 0.0, it supercedes the use of VHC to specify the reference magnitude. VRM allows greater flexibility in that it can be used to specify an arbitrary reference magnitude that need not be the maximum magnitude contained in the data set. VHC can still be used to set a high cutoff value -- no vectors with magnitude greater than the cutoff value will be displayed in the plot.

If VRM has its default value, 0.0, VHC specifies the reference maximum magnitude represented by an arrow of length VRL (as a fraction of the viewport width). The realized length of each individual vector in the plot is based on its magnitude relative to the reference maximum magnitude and, if VFR is non-zero, the reference minimum magnitude (as specified by VLC). Note that the reference maximum magnitude may be greater than the magnitude of any vector in the dataset. The effect of this parameter varies depending on its value, as follows:

ValueEffect
< 0.0The absolute value of VHC unconditionally determines the reference maximum magnitude. Vectors in the dataset with magnitude greater than VHC are not displayed.
0.0 (default)The vector with the greatest magnitude in the dataset determines the reference maximum magnitude.
>0.0The minimum of VHC and the vector with the greatest magnitude in the data set determines the reference maximum magnitude. Vectors in the dataset with magnitude greater than VHC are not displayed.

Typically, for direct comparison of the output of a series of plots, you would set VHC to a negative number, the absolute value of which is greater than any expected vector magnitude in the series. You can turn on Vectors statistics reporting using the parameter VST in order to see if any vectors in the datasets do exceed the maximum magnitude you have specified. See also the descriptions of the parameters VRM, VRL, DMX, VLC, and VFR.

5.10.51 VLC - Vector Low Cutoff Value - Real

Use this parameter to prevent vectors smaller than the specified magnitude from appearing in the output plot. VLC also specifies the reference minimum magnitude that is rendered at the size specified by the product of VRL and VFR (as a fraction of the viewport width), when VFR is greater than 0.0. Note that the reference minimum magnitude may be smaller than the magnitude of any vector in the dataset. The effect of this parameter varies depending on its value, as follows:

ValueEffect
< 0.0The absolute value of VLC unconditionally determines the reference minimum magnitude. Vectors in the dataset with magnitude less than VLC are not displayed.
0.0 (default)The vector with the least magnitude in the dataset determines the reference minimum magnitude.
>0.0The maximum of VLC and the vector with the least magnitude in the data set determines the reference minimum magnitude. Vectors in the dataset with magnitude less than VLC are not displayed.

The initialization subroutine, VVINIT, calculates the magnitude of all the vectors in the vector field, and stores the maximum and minimum values. The user may access these values by retrieving the read-only parameters, VMX and VMN. Thus it is possible to remove the small vectors without prior knowledge of the data domain. The following code fragment illustrates how the smallest 10% of the vectors could be removed:

      CALL VVINIT(...
      CALL VVGETR('VMX - Vector Maximum Magnitude', VMX)
      CALL VVGETR('VMN - Vector Minimum Magnitude', VMN)
      CALL VVSETR('VLC - Vector Low Cutoff Value', VMN+0.1*(VMX-VMN))
      CALL VVECTR(...
On the other hand, when creating a series of plots that you would like to compare directly and you are using VFR to set a minimum realized size for the vectors, you can ensure that all vectors of a particular length represent the same magnitude on all the plots by setting both VHC and VLC to negative values. If you do not actually want to remove any vectors from the plot, make VLC smaller in absolute value than any expected magnitude. You can turn on Vectors statistics reporting using the parameter VST in order to see if any vectors in the datasets are less the minimum magnitude you have specified. See also the descriptions of parameters VFR, VRL, VRM, VHC and DMN.

5.10.52 VMD - Vector Minimum Distance - Real

If VMD is set to a value greater than 0.0, it specifies, as a fraction of the viewport width, a minimum distance between adjacent vectors in the plot. The distribution of vectors is analyzed and then vectors are selectively removed in order to ensure that the remaining vectors are separated by at least the specified distance. The thinning algorithm requires that you supply Vectors with a work array twice the size of the VVINIT arguments N and M multiplied together. Use of this capability adds some processing time to the execution of Vectors. If VMD is set to a value greater than 0.0 and no work array is provided, an error condition results.

If the data grid is transformed in such a way that adjacent grid cells become very close in NDC space, as for instance in many map projections near the poles, you can use this parameter to reduce the otherwise cluttered appearance of these regions of the plot. The default value of VMD is 0.0.

5.10.53 VMN - Minimum Vector Magnitude - Real, Read-Only

After a call to VVINIT, VMN contains the value of the minimum vector magnitude in the U and V vector component arrays. Later, after VVECTR is called, it is modified to contain the magnitude of the smallest vector actually displayed in the plot. This is the vector with the smallest magnitude greater than or equal to the value specified by VLC, the vector low cutoff parameter, (0.0 if VLC has its default value) that falls within the user coordinate window boundaries. The value contained in VMN is the same as that reported as the 'Minimum plotted vector magnitude' when Vectors statistics reporting is enabled. It may be larger than the reference minimum magnitude reported by the minimum vector text block if you specify the VLC parameter as a negative value. VMN is initially set to a value of 0.0.

5.10.54 VMX - Maximum Vector Magnitude - Real, Read-Only

After a call to VVINIT, VMX contains the value of the maximum vector magnitude in the U and V vector component arrays. Later, after VVECTR is called, it is modified to contain the magnitude of the largest vector actually displayed in the plot. This is the vector with the largest magnitude less than or equal to the value specified by VHC, the vector high cutoff parameter, (the largest floating point value available on the machine if VHC has its default value, 0.0) that falls within the user coordinate window boundaries. The value contained in VMX is the same as that reported as the 'Maximum plotted vector magnitude' when Vectors statistics reporting is enabled. It may be smaller than the reference maximum magnitude reported by the maximum vector text block if you specify the VHC parameter as a negative value. VMX is initially set to a value of 0.0.

5.10.55 VPB - Viewport Bottom - Real

The parameter VPB has an effect only when SET is non-zero, specifying that Vectors should do the call to SET. It specifies a minimum boundary value for the bottom edge of the viewport in NDC space, and is constrained to a value between 0.0 and 1.0. It must be less than the value of the Viewport Top parameter, VPT. The actual value of the viewport bottom edge used in the plot may be greater than the value of VPB, depending on the setting of the Viewport Shape parameter, VPS. The default value of VPB is 0.05.

5.10.56 VPL - Viewport Left - Real

The parameter VPL has an effect only when SET is non-zero, specifying that Vectors should do the call to SET. It specifies a minimum boundary value for the left edge of the viewport in NDC space, and is constrained to a value between 0.0 and 1.0. It must be less than the value of the Viewport Right parameter, VPR. The actual value of the viewport left edge used in the plot may be greater than the value of VPL, depending on the setting of the Viewport Shape parameter, VPS. The default value of VPL is 0.05.

5.10.57 VPO - Vector Positioning Mode - Integer

VPO specifies the position of the vector arrow in relation to the grid point location of the vector component data. Three settings are available, as follows:

ValueEffect
<0The head of the vector arrow is placed at the grid point location
0 (default)The center of the vector arrow is placed at the grid point location
>0The tail of the vector arrow is placed at the grid point location

5.10.58 VPR- Viewport Right - Real

The parameter VPR has an effect only when SET is non-zero, specifying that Vectors should do the call to SET. It specifies a maximum boundary value for the right edge of the viewport in NDC space, and is constrained to a value between 0.0 and 1.0. It must be greater than the value of the Viewport Left parameter, VPL. The actual value of the viewport right edge used in the plot may be less than the value of VPR, depending on the setting of the Viewport Shape parameter, VPS. The default value of VPR is 0.95.

5.10.59 VPS - Viewport Shape - Real

The parameter VPS has an effect only when SET is non-zero, specifying that Vectors should do the call to SET; it specifies the desired viewport shape, as follows:

ValueEffect
<0.0The absolute value of VPS specifies the viewport shape as a ratio of the viewport width to its height.
0.0The viewport completely fills the area defined by the boundaries specifiers, VPL, VPR, VPB, VPT
>0.0, <1.0

(0.25, default)

Use R = (XCM-XC1)/(YCN-YC1) as the viewport shape if MIN(R, 1.0/R) is greater than VPS. Otherwise determine the shape as when VPS is equal to 0.0.
>= 1.0Use R = (XCM-XC1)/(YCN-YC1) as the viewport shape if MAX(R, 1.0/R) is less than VPS. Otherwise make the viewport a square.

The viewport, whatever its final shape, is centered in, and made as large as possible in, the area specified by the parameters VPB, VPL, VPR, and VPT. The default value of VPS is 25.

5.10.60 VPT - Viewport Top - Real

The parameter VPT has an effect only when SET is non-zero, specifying that Vectors should do the call to SET. It specifies a maximum boundary value for the top edge of the viewport in NDC space, and is constrained to a value between 0.0 and 1.0. It must be greater than the value of the Viewport Bottom parameter, VPB. The actual value of the viewport top edge used in the plot may be less than the value of VPT, depending on the setting of the Viewport Shape parameter, VPS. The default value of VPT is 0.95.

5.10.61 VRL - Vector Reference Length - Real

Use this parameter to specify the realized length of the reference magnitude vector as a fraction of the viewport width. Based on this value a reference length in NDC units is established, from which the lengths of all vectors in the plot are derived. The relationship between magnitude and length also depends on the setting of the minimum vector magnitude fraction parameter, VFR, but, given the default value of VFR (0.0), the length of each vector is simply proportional to its relative magnitude. Note that the arrow size parameters, AMN and AMX, allow independent control over the minimum and maximum size of the vector arrowheads.

Given a reference length, Vectors calculates a maximum length based on the ratio of the reference magnitude to the larger of the maximum magnitude in the data set and the reference magnitude itself. This length is accessible in units of NDC via the read-only parameter, DMX. If VRL is set less than or equal to 0.0, VVINIT calculates a default value for DMX, based on the size of a grid box assuming a linear mapping from grid coordinates to NDC space. The value chosen is one half the diagonal length of a grid box. By retrieving the value of DMX and calling GETSET to retrieve the viewport boundaries after the call to VVINIT, you can make relative adjustments to the vector length, as shown by the following example, where the maximum vector length is set to 1.5 times its default value:

      CALL VVINIT(...
      CALL VVGETR('DMX - NDC Maximum Vector Size', DMX)
      CALL GETSET(VL,VR,VB,VT,UL,UR,UB,UT,LL)
      VRL = 1.5 * DMX / (VR - VL)
      CALL VVSETR('VRL - Vector Reference Length', VRL)
      CALL VVECTR(...
When VVECTR sees that VRL is greater than 0.0, it will calculate a new value for DMX. If VRL is never set, the initially calculated value of DMX is used as the reference length. Do not rely on the internal parameters used for setting the viewport, VPL, VPR, VPB and VPT to retrieve information about viewport in lieu of using the GETSET call. These values are ignored entirely if the SET parameter is zero, and even if used, the viewport may be adjusted from the specified values depending on the setting of the viewport shape parameter, VPS. See also the descriptions of VFR, VRM and VHC. The default value of VRL is 0.0.

5.10.62 VRM - Vector Reference Magnitude - Real

The introduction of the parameter VRM means that it is now possible to specify an arbitrary vector magnitude as the reference magnitude appearing in the "Maximum Vector Text Block" annotation. The reference magnitude no longer needs to be greater than or equal to the largest magnitude in the data set. When VRM has a value greater than 0.0, it specifies the magnitude of the vector arrow drawn at the reference length. See VRL for an explanation of how the reference length is determined. If VRM is less than or equal to 0.0, the reference magnitude is determined by the value of VHC, the vector high cutoff value. If, in turn, VHC is equal to 0.0 the maximum magnitude in the vector field data set becomes the reference magnitude. The default value of VRM is 0.0.

5.10.63 VST - Vector Statistics Output Flag -Integer

If VST is set to one, VVECTR writes a summary of its operation to the default logical output unit, including the number of vectors plotted, number of vectors rejected, minimum and maximum vector magnitudes, and if coloring the vectors according to data in the scalar array, the maximum and minimum scalar array values encountered. Here is a sample of the output:

VVECTR Statistics
                        Vectors plotted: 906
    Vectors rejected by mapping routine: 0
        Vectors under minimum magnitude: 121
         Vectors over maximum magnitude: 0
              Other zero length vectors: 0
                Rejected special values: 62
       Minimum plotted vector magnitude: 9.94109E-02
       Maximum plotted vector magnitude: 1.96367
                   Minimum scalar value: -1.00000
                   Maximum scalar value: 1.00000

5.10.64 VSV - V Array Special Value - Real

VSV is the V vector component array special value. It is a value outside the range of the normal data and is used to indicate that there is no valid data for this grid location. When SVF is set to 2 or 3, Vectors will not draw a vector whose V component has the special value. It has a default value of 1.0 E12.

5.10.65 WBA - Wind Barb Angle - Real

WBA sets the angle of the wind barb ticks in degrees as measured clockwise from the vector direction. It also sets the angle between the hypotenuse of the triangle defining the pennant polygon and the vector direction. You can render southern hemisphere wind barbs, which by convention, have their ticks and pennants on the other side of the shaft, by setting WBA to a negative value. WBA has an effect only when AST has the value 2.

5.10.65 WBC - Wind Barb Calm Circle Size - Real

WBC sets the diameter of the circle used to represent small vector magnitudes (less than 2.5) as a fraction of the overall wind barb length (the value of the VRL parameter). WBC has an effect only when AST has the value 2.

5.10.65 WBD - Wind Barb Distance Between Ticks - Real

WBD sets the distance between adjacent wind barbs ticks along the wind barb shaft as a fraction of the overall wind barb length (the value of the VRL parameter). Half this distance is used as the spacing between adjacent wind barb pennants. Note that there is nothing to to prevent ticks and/or pennants from continuing off the end of the shaft if a vector of high enough magnitude is encountered. You are responsible for adjusting the parameters appropriately for the range of magnitudes you need to handle. WBD has an effect only when AST has the value 2.

5.10.65 WBS - Wind Barb Scale Factor - Real

WBS specifies a factor by which magnitudes passed to the wind barb drawing routines are to be scaled. It can be used to convert vector data given in other units into the conventional units used with wind barbs, which is knots. For instance, if the data are in meters per second, you could set WBS to 1.8974 to create a plot with conventional knot-based wind barbs. Note that setting WBS does not currently have any effect on the magnitude values written into the maximum or minimum vector legends. WBS has an effect only when AST has the value 2.

5.10.65 WBT - Wind Barb Tick Size - Real

WBT the length of the wind barb ticks as a fraction of the overall length of a wind barb (the value of the VRL parameter). The wind barb length is defined as the length of the wind barb shaft plus the projection of a full wind barb tick along the axis of the shaft. Therefore, increasing the value of WBT, for a given value of VRL has the effect of reducing the length of the shaft itself somewhat. You may need to increase VRL itself to compensate. WBT also sets the hypotenuse length of the triangle defining the pennant polygon. WBT has an effect only when AST has the value 2.

5.10.65 WDB - Window Bottom - Real

When VVINIT does the call to SET, the parameter 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, but YC1 is not equal to YCN, then YC1 is used. Otherwise, the value 1.0 is used. The default value of WDB is 0.0.

5.10.66 WDL - Window Left - Real

When VVINIT does the call to SET, the parameter 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, but XC1 is not equal to XCM, then XC1 is used. Otherwise, the value 1.0 is used. The default value of WDL is 0.0.

5.10.67 WDR - Window Right - Real

When VVINIT does the call to SET, the parameter 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, but XCM is not equal to XC1, then XCM is used. Otherwise, the value of the VVINIT input parameter, M, converted to a real, is used. The default value of WDR is 0.0.

5.10.68 WDT - Window Top - Real

When VVINIT does the call to SET, the parameter 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, but YCN is not equal to YC1 then YCN is used. Otherwise, the value of the VVINIT input parameter, N, converted to a real, is used. The default value of WDT is 0.0.

5.10.69 XC1 - X Coordinate at Index 1 - Real

The parameter XC1 specifies the X coordinate value that corresponds to a value of 1 for the first subscript of the U, V, vector component arrays as well as for the P scalar data array, if used. Together with XCM, YC1, and YCN it establishes the mapping from grid coordinate space to data coordinate space. If XC1 is equal to XCM, 1.0 will be used. The default value of XC1 is 0.0.

5.10.70 XCM - X Coordinate at Index M - Real

The parameter XCM specifies the X coordinate value that corresponds to the value of the VVINIT input parameter, M, for the first subscript of the U and V vector component arrays as well as for the P scalar data array, if used. Together with XC1, YC1, and YCN it establishes the mapping from grid coordinate space to data coordinate space. If XC1 is equal to XCM, the value of M, converted to a real, will be used. The default value of XCM is 0.0.

5.10.71 XIN - X Axis Array Increment (Grid) - Integer

XIN controls the step size through first dimensional subscripts of the U,V vector component arrays and also through the P scalar data array if it is used. For dense arrays plotted at a small scale, you could set this parameter to a value greater than one to reduce the crowding of the vectors and hopefully improve the intelligibility of the plot. The grid point with subscripts (1,1) is always included in the plot, so if XIN has a value of three, for example, only grid points with first dimension subscripts 1, 4, 7... (and so on) will be plotted. See also YIN. The default value of XIN is 1.

5.10.72 YC1 - Y Coordinate at Index 1 - Real

The parameter YC1 specifies the Y coordinate value that corresponds to a value of 1 for the first subscript of the U, V, vector component arrays as well as for the P scalar data array, if used. Together with YCN, XC1, and XCM it establishes the mapping from grid coordinate space to data coordinate space. If YC1 is equal to YCN, 1.0 will be used. The default value of YC1 is 0.0.

5.10.73 YCN - Y Coordinate at Index N - Real

The parameter YCN specifies the Y coordinate value that corresponds to the value of the VVINIT input parameter, N, for the second subscript of the U and V vector component arrays as well as the P scalar data array, if used. Together with YC1, XC1, and XCM it establishes the mapping from grid coordinate space to data coordinate space. If YC1 is equal to YCN, the value of N, converted to a real, will be used. The default value of YCN is 0.0

5.10.74 YIN - Y Axis Array Increment (Grid) - Integer

YIN controls the step size through the second dimension subscripts of the U and V vector component arrays and also through the P scalar data array if it is used. For dense arrays plotted at a small scale, you could set this parameter to a value greater than one to reduce the crowding of the vectors and hopefully improve the intelligibility of the plot. The grid point with subscripts (1,1) is always included in the plot, so if YIN has a value of three, for example, only grid points with second dimension subscripts 1, 4, 7... (and so on) will be plotted. See also XIN. The default value of YIN is 1.

5.10.75 ZFC - Zero Field Text Block Color - Integer

If ZFC is greater or equal to zero, it specifies the GKS color index to use to color the Zero Field text block. Otherwise the Zero Field text block is colored using the current GKS text color index. The default value of ZFC is -1.

5.10.76 ZFP - Zero Field Text Block Positioning Mode - Integer

The ZFP parameter allows you to justify, using any of the 9 standard justification modes, the Zero Field text block unit with respect to the position established by the parameters, ZFX and ZFY. The position modes are supported as follows:

ModeJustification
-4The lower left corner of the text block is positioned at ZFX, ZFY.
-3The center of the bottom edge is positioned at ZFX, ZFY.
-2The lower right corner is positioned at ZFX, ZFY.
-1The center of the left edge is positioned at ZFX, ZFY.
0 (default)The text block is centered along both axes at ZFX, ZFY.
1The center of the right edge is positioned at ZFX, ZFY.
2The top left corner is positioned at ZFX, ZFY.
3The center of the top edge is positioned at ZFX, ZFY.
4The top right corner is positioned at ZFX, ZFY.

5.10.77 ZFS - Zero Field Text Block Character Size - Real

ZFS specifies the size of the characters used in the Zero Field graphics text block as a fraction of the viewport width. The default value is 0.033.

5.10.78 ZFT - Zero Field Text String - Character* 36

Use ZFT to modify the text of the Zero Field text block. The Zero Field text block may appear whenever the U and V vector component arrays contain data such that all the grid points otherwise eligible for plotting contain zero magnitude vectors. Currently the string length is limited to 36 characters. Set ZFT to a single space (' ') to prevent the text from being displayed. The default value for the text is 'Zero Field'.

5.10.79 ZFX - Zero Field Text Block X Coordinate - Real

ZFX establishes the X coordinate of the Zero Field graphics text block as a fraction of the viewport width. Values less than 0.0 or greater than 1.0 are permissible and respectively represent regions to the left or right of the viewport. The actual position of the block relative to ZFX depends on the value assigned to the Zero Field Positioning Mode parameter, ZFP. The default value is 0.5.

5.10.80 ZFY - Zero Field Text Block Y Coordinate - Real

ZFY establishes the Y coordinate of the Zero Field graphics text block as a fraction of the viewport height. Values less than 0.0 or greater than 1.0 are permissible and respectively represent regions below and above the viewport. The actual position of the block relative to ZFY depends on the value assigned to the Zero Field Positioning Mode parameter, ZFP. The default value is 0.5.

6.0 ERROR MESSAGES

In this section are listed, in alphabetical order, all the error messages that may be written by Vectors. Each error message begins with the name of the Vectors routine in which an error has been detected, followed by a dash, followed by the error message itself. These error messages are written by a call to the error-handling support routine SETER, with a final argument indicating that the error is recoverable; by default, an error message is printed and execution is terminated, but, if you turn on error recovery (as described in the documentation for SETER, you can get control back.

VVECTR - TOO MANY AREA GROUPS
The area map passed as the argument, IAM, to VVECTR contains more area groups than allowed by the Vectors utility, currently 64. This error can occur only if the Mask to Area Map parameter, MSK, has a value greater than 0, specifying that vectors are to be drawn masked to an area map.

VVECTR - INVALID AREA MAP
The area map passed as the argument, IAM, to VVECTR is judged to be invalid because it contains a negative value for the number of area groups. This error can occur only if the Mask to Area Map parameter, MSK, has a value greater than 0, specifying that vectors are to be drawn masked to an area map.

VVGETC - PARAMETER NAME NOT KNOWN - x
The given parameter name ('x') is not a legal parameter name known to Vectors.

VVGETC - PARAMETER NAME TOO SHORT - x
The parameter name ("x") is less than three characters long.

VVGETI OR VVGETR - GETTING x - PAI INCORRECT
An attempt has been made to get an element of the parameter array named 'x' and the current value of PAI (the "parameter array index") is inappropriate for that parameter array.

VVGETI OR VVGETR - PARAMETER NAME NOT KNOWN - x
The given parameter name ('x') is not a legal parameter name known to Vectors.

VVGETI OR VVGETR - PARAMETER NAME TOO SHORT - x
The parameter name ("x") is less than three characters long.

VVINIT - U AND/OR V ARRAY DIMENSIONS EXCEEDED
The VVINIT input argument, M, specifying the number of array elements to use along the first dimension of the U and V (and possibly P) arrays, exceeds the actual first dimension of U and/or V, as specified by the input arguments LU and LV. 

VVINIT - SCALAR ARRAY TOO SMALL
The value given to LP, the VVINIT input argument specifying the actual first dimension of the scalar data array, P, is less than M, the input argument specifying the number of array elements to use along the first dimension for all of the input arrays. This error can only occur when the absolute value of the Color Threshold Level control parameter, CTV, is set to 2, indicating that coloring is to be performed according to values contained in the scalar data array, P.

VVSETC - PARAMETER NAME NOT KNOWN - x
The given parameter name ('x') is not a legal parameter name known to Vectors.

VVSETC - PARAMETER NAME TOO SHORT - x
The parameter name ("x") is less than three characters long.

VVSETI OR VVSETR - PARAMETER NAME NOT KNOWN - x
The given parameter name ('x') is not a legal parameter name known to Vectors.

VVSETI OR VVSETR - PARAMETER NAME TOO SHORT - x
The parameter name ("x") is less than three characters long.

VVSETI OR VVSETR - PARAMETER VALUE OUT OF RANGE - x
An attempt has been made to set the parameter named 'x' to a value outside the range allowed by the Vectors utility.

VVSETI OR VVSETR - SETTING x - PAI INCORRECT
An attempt has been made to set an element of the parameter array named 'x' and the current value of PAI (the "parameter array index") is inappropriate for that parameter array.

7.0 EXAMPLES

On a Unix system on which NCAR Graphics has been installed you may retrieve, compile, and execute all examples involving the Vectors utility by executing the command

    ncargex -vectors
Alternatively, you can obtain and run a specific example by giving the command

  ncargex example_name
To obtain the code without compiling or executing it, use the command

    ncargex -n example_name
If, after examining the code and perhaps modifying it, you wish to compile and execute the program, use the commands

    ncargf77 -o example_name *.f
    ./example_name
(Note that the form of the above command assumes you have the source for only one example in the current directory.) The metafile created by executing an example can be viewed using the command

    ctrans metafile_name

7.1 tvelvc

The example "tvelvc" demonstrates compatibility of the Vectors utility with the pre-Version 3.2 interface, and also points out some of the minor differences. Two frames are produced, as follows:

7.2 vvex01

The example "vvex01" also produces 2 frames, illustrating a vector field overlaid on a polar soft-filled contour plot. Many capabilities of the Vectors utility are illustrated in this example. First an area map is created and the contour map is drawn. Then the vectors are drawn masked to the area map. The Vectors mapping parameter is set to 2 specifying a polar mapping; and the data coordinate boundaries are defined appropriately. The special color flag is set to indicate that the P array will contain special values; next the P array special value parameter is set to the value used for special values in the data. Various parameters are set to control the size and spacing of the vectors.

7.3 vvex02

The example "vvex02" produces 10 frames, one for each of the supported EZMAP projections. Except for the Lambert conformal conic projection, all the frames show the maximum possible area of the globe visible with that projection. The same randomly generated vector component data, treated as a globe-covering grid, is applied to each projection. Alternate frames are colored either according to the data contained in a randomly generated scalar array, or according to magnitude. The fifth through the tenth frames use additional parameter-setting calls to modify the size of the maximum and minimum vectors, as well as to eliminate the vectors with magnitudes in the bottom 20 percentile range.

Note that while for some of the projections the whole surface of the globe is visible, others show only a portion of the globe. The grid boundaries can remain the same in either case: vectors that map to areas outside the visible boundaries of the projection are simply discarded. The vector statistics flag parameter, VST, is set on, allowing you to see at a glance (among other things) the number of vectors thrown away.

7.4 vvex03

The example "vvex03" demonstrates how to create user-defined mappings of vector data using the user-modifiable mapping routine, VVUMXY. Its three frames illustrate three potentially useful mappings:

Given these examples the user should not have much difficulty producing other permutations such as projecting an irregularly gridded dataset through Ezmap.

7.5 Other Examples

See the section, Field flows, in NCAR Graphics Fundamentals, UNIX Version, for descriptions of more examples involving the Vectors utility.

INDEX

A

C

D

E

L

M

N

P

S

T

U

V

W

X

Y

Z