Chapter 18: Field flows

Previous Chapter          LLUs Home          Next Chapter          Index
The field flow utilities, Vectors and Streamlines, allow you to create plots representing two-dimensional field flows in a variety of styles, given arrays containing the components of the field vectors on a uniform grid. Vectors additionally provides the capability of representing a third associated scalar dataset, using a graded-color palette to color the vectors. A variety of options also exist in both utilities that allow you to control coordinate system mapping, overlay masking, and other features.

Uniform field over an azimuthal equidistant projection of the globe plotted using Vectors and Streamlines

Table of Vectors user entry points

The Vectors utility has nine user entry points. In addition there are two routines not called directly from an application, but which you may modify in order to control coordinate system mapping and vector masking. This module organizes these routines by function.

Initialization routine

VVINIT
Sets up the array space and establishes the basic mapping from grid coordinate space to NDC space. Also sets up color threshold array and determines maximum and minimum vector magnitudes and scalar array values.

Drawing routine

VVECTR
Following a required call to VVINIT, draws a vector field plot.

Parameter routines

VVGETC
Gets character parameters.

VVGETI
Gets integer parameters.

VVGETR
Gets real parameters.

VVRSET
Restores all parameters to default values.

VVSETC
Sets character parameters.

VVSETI
Sets integer parameters.

VVSETR
Sets real parameters.

User-modifiable routines

VVUDMV
Decides whether to draw a vector segment based on the values of its area group identifiers.

VVUMXY
Maps the location and direction of a vector from data coordinate space to NDC space.

Table of Streamlines user entry points

The Streamlines utility has seven user entry point routines. In addition, there are four routines you do not call directly from an application, but that you may modify in order to control coordinate system mapping and streamline masking. This module lists these routines by function.

Initialization routine

STINIT
Sets up the array space and establishes the basic mapping from grid coordinate space to NDC space.

Drawing routine

STREAM
Following a required call to STINIT, draws a streamline field flow representation of a vector field on the plotting surface.

Parameter routines

STGETI
Gets integer parameters.

STGETR
Gets real parameters.

STRSET
Restores all parameters to default values.

STSETI
Sets integer parameters.

STSETR
Sets real parameters.

User-modifiable routines

STUMSL
Draws part of a streamline based on the area group identifiers of the segment.

STUMXY
Maps a point on the streamline from data coordinates to user coordinates.

STUIXY
Maps a point on the streamline from user coordinates to data coordinates.

STUMTA
Returns the directional angle of the streamline at a point with respect to NDC space.

Table of Vectors parameters

For a complete description of the Vectors parameters, see the vectors_params man page or the Vectors programmer document.

----------------------------------------------------------------------
Parameter  Brief description                           Fortran type     
----------------------------------------------------------------------
AMN        Arrow head MiNimum size                     Real             
AMX        Arrow head MaXimum size                     Real             
CLR        Array of GKS CoLoR indices                  Integer array    
CPM        ComPatibility Mode                          Integer          
CTV        Color Threshold Value control               Integer          
DMN        NDC MiNimum vector size                     Real, read-only  
DMX        NDC MaXimum vector size                     Real, read-only  
DPF        Vector label Decimal Point control Flag     Integer          
LBC        Vector LaBel Color                          Integer          
LBL        Vector LaBeL flag                           Integer          
LBS        Vector LaBel character Size                 Real             
LWD        Vector Line WiDth                           Real             
MAP        MAP transformation code                     Integer          
MNC        MiNimum vector text block Color             Integer          
MNP        MiNimum vector text block Positioning mode  Integer          
MNS        MiNimum vector text block character Size    Real             
MNT        MiNimum vector Text string                  Character*36     
MNX        MiNimum vector text block X coordinate      Real             
MNY        MiNimum vector text block Y coordinate      Real             
MSK        MaSK to area map flag                       Integer          
MXC        MaXimum vector text block Color             Integer          
MXP        MaXimum vector text block Positioning mode  Integer          
MXS        MaXimum vector text block character Size    Real             
MXT        MaXimum vector Text string                  Character*36     
MXX        MaXimum vector text block X coordinate      Real             
MXY        MaXimum vector text block Y coordinate      Real             
NLV        Number of colors LeVels                     Integer          
PAI        Parameter Array Index                       Integer          
PLR        PoLaR input mode                            Integer          
PMN        MiNimum scalar array value                  Real, read-only  
PMX        MaXimum scalar array value                  Real             
PSV        P array Special Value                       Real             
SET        SET call flag                               Integer          
SPC        SPecial Color                               Integer          
SVF        Special Value Flag                          Integer          
TRT        TRansformation Type                         Integer          
TVL        Array of Threshold VaLues                   Real array       
USV        U array Special Value                       Real             
VFR        Minimum Vector FRactional length            Real             
VHC        Vector High Cutoff value                    Real             
VLC        Vector Low Cutoff value                     Real             
VRL        Maximum Vector Realized Length              Real             
VMN        MiNimum Vector magnitude                    Real, read-only  
VMX        MaXimum Vector magnitude                    Real, read-only  
VPB        ViewPort Bottom                             Real             
VPL        ViewPort Left                               Real             
VPO        Vector POsitioning mode                     Integer          
VPR        ViewPort Right                              Real             
VPS        ViewPort Shape                              Real             
VPT        ViewPort Top                                Real             
VST        Vector STatistics output flag               Integer          
VSV        V array Special Value                       Real             
WDB        WinDow Bottom                               Real             
WDL        WinDow Left                                 Real             
WDR        WinDow Right                                Real             
WDT        WinDow Top                                  Real             
XC1        X Coordinate at index 1                     Real             
XCM        X Coordinate at index M                     Real             
XIN        X-axis array INcrement (grid)               Integer          
YC1        Y Coordinate at index 1                     Real             
YCN        Y Coordinate at index N                     Real             
YIN        Y-axis array INcrement (grid)               Integer          
ZFC        Zero Field text block Color                 Integer          
ZFP        Zero Field text block Positioning mode      Integer          
ZFS        Zero Field text block character Size        Real             
ZFT        Zero Field Text string                      Character*36     
ZFX        Zero Field text block X coordinate          Real             
ZFY        Zero Field text block Y coordinate          Real             
----------------------------------------------------------------------

Table of Streamlines parameters

For a complete description of the Streamlines parameters, see the streamlines_params man page or the Streamlines programmer document.

-----------------------------------------------------
Parameter  Brief description             Fortran type  
-----------------------------------------------------
AGD        Arrow GriD increment          Integer       
ARL        ARrow head Length             Real          
CDS        Critical DiSplacement         Real          
CKP        ChecK Progress count          Integer       
CKX        ChecK (X) crossover count     Integer       
CYK        CYclical data flag            Integer       
CPM        ComPatibility Mode            Integer       
DFM        DiFferential Magnitude        Real          
LWD        Streamline Line WiDth         Real          
MAP        MAP transformation code       Integer       
MSK        MaSK to area map flag         Integer       
PLR        PoLaR input mode              Integer       
SET        SET call flag                 Integer       
SGD        Stream starting GriD          Integer       
SSP        Streamline SPacing value      Real          
SST        Streamline STatistics output  Integer       
SVF        Special Value Flag            Integer       
TRP        InTeRPolation method          Integer       
TRT        TRansformation Type           Integer       
USV        U array Special Value         Real          
VNL        Vector NormaLization value    Real          
VPB        ViewPort Bottom               Real          
VPL        ViewPort Left                 Real          
VPR        ViewPort Right                Real          
VPS        ViewPort Shape                Real          
VPT        ViewPort Top                  Real          
VSV        V array Special Value         Real          
WDB        WinDow Bottom                 Real          
WDL        WinDow Left                   Real          
WDR        WinDow Right                  Real          
WDT        WinDow Top                    Real          
XC1        X Coordinate at index 1       Real          
XCM        X Coordinate at index M       Real          
YC1        Y Coordinate at index 1       Real          
YCN        Y Coordinate at index N       Real          
-----------------------------------------------------

Using parameters in Vectors and Streamlines

The parameter access routines give you control of many aspects of the field flow utilities' behavior, including coordinate mapping, masked drawing, rendering precision, special value processing, and vector coloring. This module lists the calls you have at your disposal.

Synopsis

      CALL VVSETC (CNM, CVL)
      CALL VVSETI (CNM, IVL)
      CALL VVSETR (CNM, RVL)
      CALL VVSETC (CNM, CVL)
      CALL VVGETI (CNM, IVL)
      CALL VVGETR (CNM, RVL)
      CALL VVRSET
      CALL STSETI (CNM, IVL)
      CALL STSETR (CNM, RVL)
      CALL STGETI (CNM, IVL)
      CALL STGETR (CNM, RVL)
      CALL STRSET

Routines

VVSETC
Gives a character value to a parameter.

VVSETI / STSETI
Gives an integer value to a parameter.

VVSETR / STSETR
Gives a real value to a parameter.

VVGETC
Retrieves a character value for a parameter.

VVGETI / STGETI
Retrieves integer parameter information.

VVGETR / STGETR
Retrieves real parameter information.

VVRSET / STRSET
Resets all parameters to default values.

Arguments

CNM
Character, Input---A character expression that represents a parameter name. The field flow utilities use only the first three characters in the string. Many users include additional characters that describe the parameter to make their code easier to maintain.

CVL
Character, Input or Output---A character value or character variable. Note that Vectors has character type parameters and character getting and setting routines, but Streamlines does not.

IVL
Integer, Input or Output---An integer value or integer variable.

RVL
Real, Input or Output---A real value or real variable.
The field flow parameter access routines follow the model established by other NCAR Graphics utilities. You should be aware that Vectors has two parameters that are actually arrays. You access a particular element of the array by first setting the parameter array index, PAI, (itself a parameter) to the index of the element you want to access.

Note: To avoid a common user problem, be sure to double-check your GET and SET calls to ensure that you use the correct routine with the correct variable type. For example, do not use STSETI to set a real parameter value.

Creating simple field flow plots

The minimum requirements for creating a plot using either Vectors or Streamlines are much the same. First you must set up the vector field component arrays, then you call the appropriate initialization routine, and finally you call VVECTR or STREAM to draw the plot. Streamlines also requires an uninitialized work array. Using a mathematically generated flow field as an example, this section steps through the code required to render the plot, first with Vectors and then with Streamlines. The image below shows both representations, with streamlines overlaid on vectors.

A simple field flow plot: Streamlines over Vectors

A simple plot using Vectors

Once the data arrays have been set up, call VVINIT (initialize Vectors) followed by VVECTR (draw vectors) to draw a vector field plot. By default, the plot will be shaped according to the ratio of the number of array elements along each axis. The default maximum viewport fills the plotting area, less 5% around each edge for margins. If you can dimension the component arrays exactly to the size of the field you want to plot, the VVINIT call becomes even simpler. To draw a border around your plot simply call PERIM(1,0,1,0) any time after VVINIT.

A simple Vector field plot

Code segment from ffex01.f

1       IDM=0
2       RDM=0.0
3       CALL VVINIT(U,M,V,M,RDM,IDM,M,N,RDM,IDM)
4       CALL VVECTR(U,V,RDM,IDM,IDM,RDM)
5       CALL PERIM(1,0,1,0)
6       CALL FRAME

Synopsis

      CALL VVINIT (U, LU, V, LV, P, LP, M, N, WRK, LW)
      CALL VVECTR (U, V, P, IAM, VVUDMV, WRK)

Arguments

U (LU, N)
Real 2-D array, Input---By default, assumed to contain the first dimensional Cartesian components of the vector field. However, if the PLR parameter is nonzero, it is treated as containing the vector magnitudes.

LU
Integer, Input---The first dimension of array U.

V (LV,N)
Real 2-D array, Input---By default, assumed to contain the second dimensional Cartesian components of the vector field. However, if the PLR parameter is nonzero, it is treated as containing the vector angles.

LV
Integer, Input---The first dimension of array V.

P (LP,N)
Real 2-D array, 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. This argument is used only if the CTV parameter has an absolute value of 2; otherwise, it is ignored and may be assigned a dummy value.

LP
Integer, Input---The first dimension of array P.

M
Integer, Input---Number of 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 elements along the second dimensional axis containing data to be processed in each of the arrays, U, V, and P (if used).

IAM(*)
Integer array, Input---Area map array previously established by calls to routines in the Areas utility. Required only if the MSK parameter is set to a nonzero value; otherwise, it is ignored and may be assigned a dummy value.

VVUDMV
External subroutine, Input---User-definable masked drawing subroutine. Required only if MSK is set to a nonzero value; otherwise, it is ignored and may be assigned a dummy value. When used, it must be declared external.

WRK(LW)
Real array, Workspace---For future enhancement. It is currently ignored and may be assigned a dummy value.

LW
Integer, Input---Assumed size of the array WRK. Not currently used, this argument should be assigned the integer value 0.

Discussion

Line 1 of the ffex01.f code segment sets the integer dummy variable IDM to 0. Line 2 sets the real dummy variable RDM to 0.0. You could use an integer variable for all arguments given dummy values, since Vectors never examines them when they are not used, but it is probably wise to remain aware of the variable types. Lines 3 and 4, calls to VVINIT and VVECTR, do the work of the Vectors utility. Line 5 draws an outline around the plot, and line 6 advances the frame.

The arguments U, V, P, and WRK refer to the same entities in both VVINIT and VVECTR. Although there are a total of 12 arguments to both routines, if the desired field grid size matches the dimensions of the U and V arrays and you are not drawing masked vectors or using the P scalar array to color the vectors, you can ignore all but six. Of these six remaining arguments, three get the same value---the number of grid elements along the first dimension. Effectively, therefore, you need worry about only four.

A simple plot using Streamlines

The code required to create a simple Streamlines plot is very similar to what you need for a Vectors plot. Just remember than in addition to the data arrays, Streamlines also always requires the work array. Dimension the work array so that there is at least one element for each element used in both the field component arrays, or in other words, two times the input parameter M times the input parameter N. Then call STINIT (initialize Streamlines), followed by a call to STREAM to render the streamlines.

A simple Streamlines field flow plot

Code segment from ffex01.f

1       IDM=0
2       RDM=0.0
3       CALL STINIT(U,M,V,M,RDM,IDM,M,N,WRK,IWSIZE)
4       CALL STREAM(U,V,RDM,IDM,IDM,WRK)
5       CALL PERIM(1,0,1,0)
6       CALL FRAME

Synopsis

      CALL STINIT (U, LU, V, LV, P, LP, M, N, WRK, LW)
      CALL STREAM (U, V, P, IAM, STUMSL, WRK)

Arguments

U (LU,N)
Real 2-D array, Input---By default, assumed to contain the first dimensional Cartesian components of the flow field. However, if the PLR parameter is nonzero, it is treated as containing the vector magnitudes.

LU
Integer, Input---The first dimension of array U.

V (LV,N)
Real 2-D array, Input---By default, assumed to contain the second dimensional Cartesian components of the flow field. However, if the PLR parameter is nonzero, it is treated as containing the vector angles.

LV
Integer, Input---The first dimension of array V.

P (LP,N)
Real 2-D array, Input---For future enhancement. It is currently ignored and may be assigned a dummy value.

LP
Integer, Input---The first dimension of array P. Not currently used, this argument should be assigned the integer value 0.

M
Integer, Input---Number of elements along the first dimensional axis containing data to be processed in each of the arrays, U and V.

N
Integer, Input---Number of elements along the second dimensional axis containing data to be processed in each of the arrays, U and V.

IAM(*)
Integer array, Input---Area map array previously established by calls to routines in the Areas utility. Required only if the MSK parameter is set to a nonzero value; otherwise, it is ignored and may be assigned a dummy value.

STUMSL
External subroutine, Input---User-definable masked drawing subroutine. Required only if MSK is set to a nonzero value; otherwise, it is ignored and may be assigned a dummy value. When used, you must declare the name of the routine as external in the routine that calls STREAM.

WRK(LW)
Real array, Workspace---Work array used to store normalized values of the U and V vector components while the streamlines are calculated. It also holds bit flags indicating whether a grid location is eligible for starting a streamline or placing a directional arrowhead.

LW
Integer, Input---Assumed size of the array WRK. Currently, it must be greater than or equal to 2*M*N.

Discussion

Lines 1 and 2 of the ffex01.f code segment assign values to the dummy variables. The calls to STINIT and STREAM in lines 3 and 4 render the streamlines. Line 5 creates a border, and line 6 advances the frame.

Again, note the similarities between Streamlines and Vectors. With the exception of the work array (ignored by Vectors, but required by Streamlines), both plots use the same declarations and field arrays. When drawing a basic plot with Streamlines, you can assign dummy values to four of the parameters.

Exploring the field flow utilities

This section looks at some of the options available to Vectors and Streamlines. Using appropriate parameter settings, you can adjust the appearance of the plot, either to enhance depiction of underlying patterns contained in the data or purely for aesthetic reasons. Other facilities exist to help you combine field flow output with other utilities in NCAR Graphics.The first four modules in this section demonstrate some of the variations obtainable by successively applying options to the same basic plot of actual U.S. National Meteorological Center forecast data displayed over an Ezmap projection. The next module demonstrates polar coordinate mapping, and the final one shows Vectors plotted over a polar stereographic map projection. For information about drawing map backgrounds, please see the NCAR Graphics Contouring and Mapping Tutorial.

Eastern North America using lambert conical projection

Displaying vectors overlaying an Ezmap projection

In all but the simplest situations, you must know certain basic information about your field data in order to display it correctly. For this example, it is necessary to determine what special values are used to flag grid points with non-valid data. You also need to know the coordinate boundaries of the dataset to map the field correctly into the Ezmap projection. This module shows the parameter-setting calls you must make to display the example National Meteorological Center dataset.

NMC early domestic product set: Severe snowstorm, March 13, 1993

Code segment from ffex02.f

1       CALL VVSETI('MAP -- Mapping Flag', 1)
2       CALL VVSETI('SET -- Set Call Flag', 0)
3       CALL VVSETR('XC1 -- Lower X Bound', -140.0)
4       CALL VVSETR('XCM -- Upper X Bound', -52.5)
5       CALL VVSETR('YC1 -- Lower X Bound', 20.0)
6       CALL VVSETR('YCN -- Upper Y Bound', 60.0)
7       CALL VVSETR('USV -- U Special Value', -9999.0)
8       CALL VVSETR('VSV -- V Special Value', -9999.0)
9       CALL VVSETR('PSV -- P Special Value', -9999.0)
10      CALL VVSETI('SVF -- Special Value Flag', 3)
11      CALL VVSETI('SPC -- P Special Color', 1)

Synopsis

      CALL VVSETI ('MAP', imap)
      CALL VVSETI ('SET', iset)
      CALL VVSETR ('XCM', rxcm)
      CALL VVSETI ('SVF', rsvf)
      CALL VVSETR ('USV', rusv)
      CALL VVSETI ('SPC', ispc)

Description

MAP
Integer---Specifies the mapping from data coordinates into user coordinate space. There are three pre-defined mappings:

0
Identity mapping (default).
1
Ezmap projections.
2
Polar coordinate mapping.
Any other value greater than 0 implies a user-defined mapping that must be implemented by modifying the source code of VVUMXY. Values less than 0 are reserved.

SET
Integer---Flag specifying whether Vectors should perform its own call to the SET routine.

0
Vectors should not perform SET call.
1
Vectors should perform SET call (default).

XC1, XCM, YC1, YCN
Real---These four parameters define the boundaries of the data coordinate system. XC1 and YC1 specify the location of element (1,1) of each of the input data arrays, while XCM and YCN specify the location of element (M,N) of the same arrays (where M and N are the arguments to VVINIT).

SVF
Integer---The special value flag specifies how to handle special values in the U and V input data arrays.

0
No special value processing (default).
1
Do not draw the vector at grid points containing a special value in the U array.
2
Do not draw the vector at grid points containing a special value in the V array.
3
Do not draw the vector at grid points containing a special value in either the U or the V array (most generally useful).
4
Do not draw the vector at grid points containing special values in both the U and the V array (least generally useful).

USV, VSV, PSV
Real ---Special values for the input data arrays, U, V, and P respectively (default: 1.0E12).

SPC
Integer---Controls special value processing for the P scalar data array.

<0
No special value processing (default).
0
Do not draw vectors at grid points containing a special value in the P array.
>0
Draw vectors at grid points containing a special value in the P array, using as the special color the GKS color index SPC.

Discussion

To display a vector field using an Ezmap projection, you must always set the MAP and SET parameters as in lines 1 and 2 of the ffex02.f code segment. You must also make calls similar to lines 3 through 6 to inform Vectors of the boundaries of your data. Note that the values you give these parameters depend on the dataset, but not on the particular Ezmap projection you use. Once you have set them correctly, you can vary the Ezmap projection parameters any way you like.

If the data include invalid data flagged by special values, you need to find out what the special values are. Line 7 through 9 set each of the special value parameters USV, VSV, and PSV to -9999.0, the value the NMC data uses to flag invalid data. Line 10 sets up special-value processing for the U and V vector component arrays. The area at the bottom right corner of the plot where no vectors appear is in fact a region where the input arrays contain special values. Special value processing for the P array is also enabled, anticipating use of the P array later.

Modifying the appearance of a Vector plot

The third frame in this example illustrates some of the facilities in the Vectors utility for adjusting the rendering of a vector field plot. The intent is to enhance the depiction of the overall flow characteristics of the field, possibly at the expense of some of the detailed information about flow speeds. Among other things, the plot eliminates low-velocity vectors, magnifies the overall vector length, and adjusts the minimum vector length to one-third the maximum.

Vector field with rendering modifications

Code segment from ffex02.f

1       CALL VVINIT (U,M,V,M,P,M,M,N,IDM,IDM)
2       IF (IFRMNO .EQ. 3) THEN
3          CALL VVSETR('AMN -- Arrow Minimum Size',0.025)
4          CALL VVSETR('LWD -- Vector Line Width',1.75)
5          CALL VVGETR('VMN -- Minimum Vector', VMN)
6          CALL VVGETR('VMX -- Maximum Vector', VMX)
7          CALL VVSETR('VLC -- Vector Low Cutoff', VMN+(VMX-VMN)/8.0)
8          CALL VVGETR('DMX -- Device Maximum Vector Length', DMX)
9          CALL GETSET(VL,VR,VB,VT,UL,UR,UB,UT,LL)
10         CALL VVSETR('VRL - Vector Realized Length',1.8*DMX/(VR-VL))
11         CALL VVSETR('VFR - Vector Fractional Length',0.33)
12      END IF

Synopsis

      CALL VVSETR ('AMN', ramn)
      CALL VVSETR ('LWD', rlwd)
      CALL VVGETR ('VMN', rvmn)
      CALL VVSETR ('VLC', rvlc)
      CALL VVGETR ('DMX', rdmx)

Description

AMN, AMX
Real---Normally the size of the arrowhead on a vector is proportional to the length of the vector; this parameter lets you specify, as a fraction of the viewport width, a minimum size for the arrowhead. The default value of AMN is 0.01. A corresponding parameter, AMX, specifies a maximum size and has a default value of 0.2.

LWD
Real---Specifies the line width used to render the vector arrows. Since the appearance on the plot of a particular line width setting depends on the output device, you may need to adjust the value for different devices.

VMN, VMX
Real---After a call to VVINIT, these read-only parameters allow you to find the lowest and highest magnitude values in the vector field. Calling VVECTR causes them to be modified to contain the lowest and highest magnitudes of the vectors that actually appear in the plot.

VLC, VHC
Real---VLC, the vector low cutoff parameter, allows you to specify the minimum magnitude a vector must have to qualify for plotting. You can also specify a maximum magnitude with VHC, the corresponding vector high cutoff parameter.

DMX, DMN
Real---After calling VVINIT, you can use the read-only parameter DMX to determine the length, in NDCs, that Vectors would use by default to render the maximum magnitude vector. It is calculated as half the diagonal length of a grid box, assuming a linear mapping into user coordinates. After the call to VVECTR, DMX contains the NDC length of the longest vector actually plotted. The corresponding parameter, DMN, is only useful after the VVECTR call, when it contains the NDC length of the shortest vector actually plotted. These are the lengths in NDC space of the arrows you see in the maximum and minimum vector text blocks.

VRL
Real---VRL specifies the length (as a fraction of viewport width) you want Vectors to use for rendering the vector with the greatest magnitude. When VRL has its default value of 0.0, Vectors uses the value of DMX to determine the longest vector length. But note that VRL uses different units from DMX.

VFR
Real---Use this parameter to specify the length of the smallest vector arrow as a fraction of the length of the largest. Vectors then scales all remaining vectors proportionally. Its default value is 0.0, specifying that vector length is strictly proportional to the size of the vector.

Discussion

The calls discussed here modify attributes of the vector field rendering. Note that they appear in the code after the VVINIT initialization call. Many of the Vectors utility's parameters should not be modified at this stage of the processing. When in doubt, set parameters before the VVINIT call. However, for certain field attribute parameters, in particular VLC and VRL, the advantage of delaying the call is that you can first inquire certain characteristics of the datasets. Then you can use the dynamically obtained results to create more general code.

Lines 3 and 4 of the ffex02.f code segment modestly increase the minimum arrowhead size and the vector line width. You may notice that the effect of these changes varies depending on the plot scale and the device resolution. Lines 5 and 6 retrieve the maximum and minimum vector magnitudes from the field data. Then, based on a simple calculation using these values, the code in line 7 sets the vector low cutoff parameter, VLC, to eliminate the smallest 12.5% of the vectors from the plot.

Line 8 retrieves DMX, the default maximum vector length, and line 9 calls GETSET to find the current viewport width. Line 10 increases the vector realized length by a factor of 1.8, using a calculation that includes conversion of the default length, DMX, from NDCs to a fraction of the viewport width. Finally, line 11 sets the minimum displayed vector length to one-third the maximum length. The end result is a plot that more obviously displays the directional characteristics of the flow.

Coloring a Vector plot based on scalar array data

You can add another dimension to the information you convey through the use of the field coloring facilities provided by Vectors. The fourth frame of this example shows the same vector field data, but now surface pressure data for the same time period and grid locations is used to determine the color of each vector individually. The online example, displayed on a color workstation, shows cyan for the lowest pressure, progressing to red for the highest. In the grayscale version presented here, lows are black and highs are a light gray.

Vector field colored according to surface pressure data

Code segment from ffex02.f

1       DATA ICLRIX / 2,16,30,44,59,73,87,102,116,130,144,159,173,187 /
2       IF (IFRMNO .EQ. 4) THEN
3          CALL VVSETI('CTV -- Color Thresholds Value Control', 2)
4          CALL VVSETI('NLV -- Number Of Levels', NCLRS)
5          DO 100 I=1,NCLRS,1
6             CALL GSCR(1,ICLRIX(I),RGBV(1,I),RGBV(2,I),RGBV(3,I))
7             CALL VVSETI('PAI -- Parameter Array Index', I)
8             CALL VVSETI('CLR -- GKS Color Index', ICLRIX(I))
9  100     CONTINUE
10      END IF
11      CALL VVINIT (U,MSIZE,V,MSIZE,P,MSIZE,MSIZE,NSIZE,IDM,IDM)

Synopsis

      CALL VVSETI ('CTV', ictv)
      CALL VVSETI ('NLV', inlv)
      CALL VVSETI ('PAI', ipai)
      CALL VVSETI ('CLR', iclr)
      CALL VVSETI ('TVL', itvl)

Description

CTV
Integer---Use the color threshold value control parameter to enable vector coloring.

-2
Color vectors based on scalar array data. The Vectors utility will not alter threshold value data in the TVL parameter array.
-1
Color vectors based on vector magnitude. Vectors will not alter threshold value data.
0
No individual coloring of vectors. All vectors are given the color specified by the current GKS polyline color index (default).
1
Color vectors based on vector magnitude. VVINIT assigns values to the first NLV elements of the threshold array TVL.
2
Color vectors based on scalar array data. VVINIT assigns values to the first NLV elements of the threshold array TVL.

NLV
Integer---Specifies the number of levels used to color the vectors. Whenever the CTV parameter has a nonzero value enabling vector coloring, you need to define NLV elements of the CLR parameter array to appropriate GKS color index values. In addition, if CTV is negative, you are responsible for ensuring that the threshold value array, TVL, contains valid values. The maximum value you can give to NLV currently is 64.

PAI
Integer---Before setting or retrieving a parameter array element, you must first set PAI, the parameter array index parameter, to the array index of the element you want to access. In Vectors, there are currently two parameter arrays, CLR and TVL.

CLR
Integer array---Parameter array containing valid GKS color index values. Unless your output device has a fixed non-writable color table, you are also responsible for calling GSCR to set the GKS color representation for each color index you use. See the "Color tables and color mapping" chapter for more information on setting up color tables.

TVL
Integer array---Contains the threshold values that determine which color is assigned to a particular vector. Vectors looks for the first element of TVL greater than or equal to the vector's associated value (either from the scalar array or a magnitude). It then determines the GKS color index to use from the value stored in the CLR array element with the same index. When CTV is less than zero, you are responsible for setting up the TVL array with NLV values in ascending order starting from the first element of the array.

Discussion

You must set parameters CTV, the color threshold value control, and NLV, the number of levels, as a prerequisite for coloring the vector field. When CTV has a positive value, VVINIT sets up the threshold value array to contain a number (specified by NLV) of linearly spaced values. If CTV is negative, VVINIT does not touch the contents of TVL. If you want to look at more than one set of data using the same color scale, you can choose one dataset, preferably the one with the widest domain, as a reference. You allow VVINIT to choose the threshold values for this set only; then you set CTV negative to tell Vectors to use the same scaling for subsequent datasets. On the other hand, if the default linear threshold value setup is inadequate for your purposes, you can set CTV negative immediately to take complete control of the threshold array values.

However you handle the threshold array, you are always responsible for defining the colors you want to use and setting up the color parameter array, CLR. The DATA statement in line 1 of the ffex02.f code segment uses a trick of spacing out the color indices between the values 2 and 187 to allow the same code to work for a workstation with settable colors as well as for the fixed color table grayscale PostScript device. This device has a color range from index 1 for black and 255 for white. The GKS GSCR call for setting the RGB color representation is simply ignored for such a device.

Masked Streamlines over contour lines and Ezmap

This module uses the same data as the previous plots, but presents a different picture. The map projection is identical, but now surface pressure is represented as a contour plot using the Conpack utility and Streamlines draws the flow field. On a color workstation, the plot uses color to distinguish the various kinds of lines. In the gray scale version shown here, shades of gray and line thickness are used. To illustrate the masked drawing capabilities of Streamlines, the example masks the streamlines to the contour line and high/low labels drawn by Conpack.

Streamlines representing wind flow over contour plot of surface pressure

Code segment from ffex03.f

1       EXTERNAL STUMSL
2       CALL CPRECT (P,MSIZE,MSIZE,NSIZE,RWRK,ICPRWL,IWRK,ICPIWL)
3       CALL ARINAM (IAM,IAREAL)
4       CALL CPLBAM (P,RWRK,IWRK,IAM)
5       CALL STSETI ('MSK -- Streamline Masking',1)
6       CALL STSETR ('SSP -- Stream Spacing', 0.012)
7       CALL STSETR ('DFM -- Differential Magnitude', 0.012)
8       CALL STSETI ('SST -- Streamline Statistics', 1)
9       CALL STINIT (U,MSIZE,V,MSIZE,IDM,IDM,MSIZE,NSIZE,WRK,ISTWKL)
10      CALL STREAM (U,V,IDM,IAM,STUMSL,WRK)

Synopsis

      CALL STSETI ('MSK', imsk)
      CALL STSETR ('SSP', rssp)
      CALL STSETR ('DFM', rdfm)
      CALL STSETI ('SST', isst)

Description

MSK
Integer--- Flag indicating whether streamlines should be drawn masked to an area map established by the Areas utility.

0
Do not draw streamlines masked (default).
1
Draw streamlines masked to area map.

SSP
Real---The streamline spacing parameter establishes the minimum distance (as a fraction of the viewport width) a streamline in progress is allowed to approach existing streamlines before being terminated. In general, giving this value a larger number increases the distance between streamlines, and has a tendency to create more, but shorter streamlines. The spacing is only checked at intervals, so streamlines sometimes approach closer than the specified distance. The checking frequency is adjustable using the streamline crossover checking parameter, CKX. The streamline starting grid increment parameter, SGD, also affects the overall streamline density. The default value of SSP is 0.015.

DFM
Real---The streamline differential magnitude parameter specifies, as a fraction of the viewport width, the step size used to calculate each incremental piece of the streamline. As DFM becomes smaller, the resolution of the plot increases, but so does the amount of time Streamlines uses to process the field data. Memory requirements do not change. The default value of DFM is 0.02.

SST
Integer---Flag specifying whether Streamlines should output to the default output unit a message summarizing the streamline statistics. (Vectors has a similar facility accessed through the parameter VST.)

0
Do not output Streamlines statistics (default).
1
Output Streamlines statistics.

Discussion

Line 1 of the ffex03.f code segment declares as external the user-definable routine called eventually from an Areas utility routine to do the streamline drawing. Streamlines provides a basic default version of this routine that is adequate for this example. For more complicated masking, you would use identical techniques for modifying the routine as for the analogous routines required by the Ezmap masked grid routine, MAPGRM, or the Conpack masked contour routine, CPCLDM, both of which are discussed in the NCAR Graphics Contouring and Mapping Tutorial. Lines 2 through 4 call the Areas and Conpack routines required to create an area map containing information about the contour labels. After these calls, even if the code that draws the labels were omitted, Streamlines would leave holes where the labels belong.

Line 5 sets the parameter MSK to 1, telling Streamlines to perform masking. This call has the effect of causing STREAM to inspect the contents of its IAM area map array argument and return an error if it is judged invalid.

Lines 6, 7, and 8 are not required for this plot, but you should be aware of the effect of these parameters. If the streamlines seem to be broken into too many pieces, a smaller value of SSP, the streamline spacing parameter, may help. If the rendering is not smooth enough, try a smaller value for the differential magnitude, DFM. Turning on the statistics output parameter, SST, results in output showing the total number of differential steps used to compute all the streamlines in the plot. This number may help you determine the best compromise between plot quality and computing time used.

Note that the masking capabilities of Vectors parallel those of Streamlines. Study the Ezmap and Conpack sections of the NCAR Graphics Contouring and Mapping Tutorial to learn about area maps and masked drawing of contour plots. The initial parameter-setting calls for this example---MAP, SET, data coordinate boundary parameters, and special values---are very similar to the setup calls for Vectors described in the preceding module "Displaying Vectors overlaying an Ezmap projection," except that the special value flag, SVF, for Streamlines has only two values, off and on. If you look at the online example, compare also the code that performs the equivalent duties for Conpack. Note that you must be sure to set the Conpack out-of-range parameter, ORV, when overlaying using an Ezmap projection.

Mapping to polar coordinates in Streamlines

The graphic presented in this module illustrates how Streamlines performs polar coordinate mapping. Vectors uses the same model. The code calls STREAM twice. The first time the U array components are all set to 1.0, while the V array has all zero values. The second call reverses the situation. The straight radial lines with arrows pointing outwards from the center comprise the first field; the concentric circles with arrows pointing counterclockwise, the second. Therefore, the U array contains components parallel to the radius, while the V array components are perpendicular to the radius.

Uniform orthogonal polar fields plotted using Streamlines

Code segment from ffex04.f

1       CALL STSETI('MAP -- Mapping Mode', 2)
2       CALL STSETR('WDL -- Window Left', -20.0)
3       CALL STSETR('WDR -- Window Right', 20.0)
4       CALL STSETR('WDB -- Window Bottom', -20.0)
5       CALL STSETR('WDT -- Window Top', 20.0)
6       CALL STSETR('XC1 -- Lower X Bound', 1.0)
7       CALL STSETR('XCM -- Upper X Bound', 20.0)
8       CALL STSETR('YC1 -- Lower Y Bound', 0.0)
9       CALL STSETR('YCN -- Upper Y Bound', 360.0)
10      DO 1000 K=1,0,-1
11         CALL STSETI('TRT -- Transform Type', K)

Synopsis

      CALL STSETI ('MAP', imap)
      CALL STSETR ('WDL', rwdl)
      CALL STSETR ('XC1', rsc1)
      CALL STSETI ('TRT', itrt)

Description

MAP
Integer---Specifies the mapping from data coordinates into user coordinate space. There are three pre-defined mappings:

0
Identity mapping (default).
1
Ezmap projections.
2
Polar coordinate mapping.
Any other value greater than 0 implies a user-defined mapping that must be implemented by modifying the source code of VVUMXY. Values less than 0 are reserved.

WDL, WDR, WDB, WDT
Real---These four parameters define the boundaries of the window (or user coordinate system). WDL and WDR specify the left and right edges of the window, while WDB and WDT specify the bottom and top edges of the window. They refer to the same entities as arguments 5, 6, 7, and 8 of the SET call.

XC1, XCM, YC1, YCN
Real---These parameters define the boundaries of the data coordinate system. In other words, XC1 and YC1 specify the location of element (1,1) of each of the input data arrays, while XCM and YCN specify the location of element (M,N) of the same arrays (where M and N are the arguments to VVINIT). When the MAP parameter specifies an Ezmap projection, the X values are treated as longitude and the Y values as latitude. For the polar mapping, the X values are treated as radius, and the Y values as angle.

TRT
Integer---If the MAP parameter has a value of 0 or 2, the transformation type parameter qualifies the mapping, as follows:

0
Only the location of the each grid point is mapped. The directional component of the field arrays is calculated relative to an underlying rectangular coordinate system.
1
Both the location and the directional component are mapped (default).

Discussion

Line l of the ffex04.f code segment sets the mapping mode to 2, specifying polar coordinate mapping. Be sure not to confuse the polar coordinate mapping mode with the polar input mode parameter, PLR.

Lines 2 through 5 define the window (that is, the boundaries of the user coordinate space) by setting each of the four window boundary parameters. For this example, the SET parameter has been left in its default state, with the result that STINIT will do a call to the SET routine. As an alternative, you could accomplish the same goal by calling SET yourself, using the values given to the window boundary parameters as arguments 5 through 8 of the SET call.

The values you use for the window boundary need to be based on some understanding of the mapping from data coordinates to the user coordinate system. When polar coordinate mapping is in effect, the outer extent of the radius combined with the angle it sweeps determines the amount of user coordinate space required. From looking at lines 6 through 9, you can see that the outer extent of the radius, defined by the parameter XCM, is 20; the angle going from YC1 to YCN is 360.0 to 0.0---in other words a complete circle. Therefore, the user space must extend a minimum of 20 units in every direction from the origin for all the data to be visible. The conclusion is that the window boundaries should go from -20 to 20 along both axes.

The effect of the non-default setting of the TRT parameter is not shown in the graphic displayed here, but you can see what it does by looking at the second frame of the online example. When TRT has a value of 0, only the location of the grid points are mapped into the polar coordinate system. The vector components themselves are processed relative to an underlying rectangular coordinate system. For the uniform fields in the example, the resulting streamlines are series of horizontal and vertical straight lines.

A polar plot using Vectors, Conpack, and Ezmap

The final field flow example shows a vector field overlaying a contour plot on an Ezmap polar stereographic projection. In the lower right corner of the plot appears the same storm system as in previous examples. Here it is seen in the context of higher latitude northern weather around the globe. Although most of the code is very similar to previous examples, there is one new difficulty to resolve--- with this kind of projection, the data become very crowded near the poles. Although neither Vectors nor Streamlines has yet implemented a general solution to the problem, the code presented here is a relatively easy workaround for plots like this.

Polar stereographic plot using NMC global product set data, March 13, 1993

Code segment from ffex05.f

1       PARAMETER (NROWS = 11)
2       DIMENSION ITHIN(NROWS)
3       DATA ITHIN /90,15,5,5,4,4,3,3,2,2,2/
4       DO 50 J=NSIZE,NSIZE-NROWS+1,-1
5          DO 49 I=1,MSIZE
6              IF (MOD(I,ITHIN(NSIZE-J+1)).NE.0) THEN
7                  U(I,J) = -9999.0
8              ENDIF
9   49     CONTINUE
10  50  CONTINUE

Discussion

The code used to generate the ffex05 example was created for the most part by combining pieces of examples ffex02 (the Vectors and Ezmap plot) and ffex03 (the Streamlines, Conpack, and Ezmap plot). Only a few changes are required to place the data properly within the projection. You must set up the map projection and modify the data array sizes and the data coordinate boundaries to accommodate the global dataset. The remaining changes are only to improve the clarity and appearance of the plot. However, note that when a plot has as many levels of overlay as this example, you may need to experiment for a while to avoid obscuring important details, especially when rendering to a grayscale device.

In a polar projection such as this one, the data grid becomes progressively more crowded as the pole is approached. However, unlike some other projections, the crowding is uniform for each latitudinal row of the grid. This fact makes possible a relatively simple method of removing the excess vectors.

Line 1 of the ffex05.f code segment sets the parameter, NROWS, to the number of rows in the plot determined by inspection to be too crowded. Line 2 dimensions an array called ITHIN to the value of this parameter, and then line 3 initializes this array with empirically determined data that are later used in the MOD function of line 6 to weed out all but a fraction of the vectors in the row. Knowing that the last row of this array represents 90 degrees north, line 4 begins a backwards loop through the top NROWS rows of the data. The inner loop of lines 5 through 9 sets each component of the U array whose column index is not evenly divisible by the appropriate value from the ITHIN array to the special value associated with this dataset: -9999.0. The result, for the affected rows, is that only a fraction of the vectors appear: if the ITHIN element is 3, for example, only a third of the vectors, evenly spaced along the row, will show up.

Of course this is an ad hoc approach, and will not work for situations where the crowding is not uniform within a row of the grid. You should also be aware that it is not suitable for use with the Streamlines utility. However, in the situations where it can be used, it is easy to implement and only requires a modest amount of experimentation to adjust the thinning array data suitably.

Previous Chapter          LLUs Home          Next Chapter          Index