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.
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.
- 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.
- VVECTR
- Following a required call to VVINIT, draws a vector field plot.
- 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.
- 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.
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.
- STINIT
- Sets up the array space and establishes the basic mapping from grid coordinate space to NDC space.
- STREAM
- Following a required call to STINIT, draws a streamline field flow representation of a vector field on the plotting surface.
- STGETI
- Gets integer parameters.
- STGETR
- Gets real parameters.
- STRSET
- Restores all parameters to default values.
- STSETI
- Sets integer parameters.
- STSETR
- Sets real parameters.
- 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.
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
----------------------------------------------------------------------
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
-----------------------------------------------------
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.
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
- 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.
- 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.
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.
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.
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
CALL VVINIT (U, LU, V, LV, P, LP, M, N, WRK, LW)
CALL VVECTR (U, V, P, IAM, VVUDMV, WRK)
- 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.
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.
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.
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
CALL STINIT (U, LU, V, LV, P, LP, M, N, WRK, LW)
CALL STREAM (U, V, P, IAM, STUMSL, WRK)
- 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.
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.
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.
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.
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)
CALL VVSETI ('MAP', imap)
CALL VVSETI ('SET', iset)
CALL VVSETR ('XCM', rxcm)
CALL VVSETI ('SVF', rsvf)
CALL VVSETR ('USV', rusv)
CALL VVSETI ('SPC', ispc)
- 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.
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.
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.
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
CALL VVSETR ('AMN', ramn)
CALL VVSETR ('LWD', rlwd)
CALL VVGETR ('VMN', rvmn)
CALL VVSETR ('VLC', rvlc)
CALL VVGETR ('DMX', rdmx)
- 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.
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.
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.
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)
CALL VVSETI ('CTV', ictv)
CALL VVSETI ('NLV', inlv)
CALL VVSETI ('PAI', ipai)
CALL VVSETI ('CLR', iclr)
CALL VVSETI ('TVL', itvl)
- 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.
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.
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.
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)
CALL STSETI ('MSK', imsk)
CALL STSETR ('SSP', rssp)
CALL STSETR ('DFM', rdfm)
CALL STSETI ('SST', isst)
- 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.
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.
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.
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)
CALL STSETI ('MAP', imap)
CALL STSETR ('WDL', rwdl)
CALL STSETR ('XC1', rsc1)
CALL STSETI ('TRT', itrt)
- 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).
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.
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.
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
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