Previous Chapter LLUs Home Next Chapter IndexThe 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.

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

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

----------------------------------------------------------------------ParameterBrief descriptionFortran 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 ----------------------------------------------------------------------

-----------------------------------------------------ParameterBrief descriptionFortran 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 -----------------------------------------------------

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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

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