# V routines

All GAMAP Routines

List routines by alphabetical order:
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

# Routine Descriptions

## VELOCITY_FIELD

[List of Routines]
``` NAME:
VELOCITY_FIELD

PURPOSE:
Overplots a 2-D velocity field atop a map or plot window.

CATEGORY:
Plotting

CALLING SEQUENCE:
VELOCITY_FIELD, U, V, X, Y [, keywords ]

INPUTS:
U -> The X component of the two-dimensional field.
U must be a two-dimensional array.

V -> The Y component of the two dimensional field.  V must have
the same dimensions as U.  The vector at point (i,j) has a
magnitude of:

[ U(i,j)^2 + V(i,j)^2 ]^0.5

and a direction of:

ATAN2( V(i,j), U(i,j) ).

X -> Abcissae values.  X must be a vector with a length
equal to the first dimension of U and V.

Y -> Ordinate values.  Y must be a vector with a length
equal to the second dimension of U and V.

KEYWORD PARAMETERS:
MISSING -> Missing data high-cutoff value.  Vectors with a
magnitude greater than MISSING are ignored.

/DOTS -> If set, will place a dot at each missing data point.
Otherwise, will draw nothing for missing data points.
/DOTS only has effect if MISSING is specified.

X_STEP -> The X-extent of a cell in data coordinates.  If
X_STEP is not specified, then a VELOCITY_FIELD will
compute it as:

X_STEP = ( Max(X) - Min(X) ) / ( N_Elements(X) - 1 )

Where X is the array of abscissae as described above.

Y_STEP -> The X-extent of a cell in data coordinates.  If
X_STEP is not specified, then a VELOCITY_FIELD will
compute it as:

Y_STEP = ( Max(Y) - Min(Y) ) / ( N_Elements(Y) - 1 )

Where X is the array of ordinates as described above.

COLOR -> Specifies the color of the arrows.  Default is black.

/DATELINE -> Will skip points for which an arrow cannot
be drawn (usually across the date line).

HSIZE -> The length of the lines used to draw the arrowhead.
If HSIZE is positive, then the arrow head will be the
same regardless of the length of each vector.  (Default
size is !D.X_SIZE / 100).  If HSIZE is negative, then
the arrowhead will be 1/HSIZEth of the total arrow
length.

LEGENDLEN -> Specify an arrow of a given length in DATA
coordinates displayed as a legend in the calling
routine.  Default is LONGEST.

LEGENDNORM -> Returns to the calling program the length of
LEGENDLEN in NORMAL coordinates.  This is needed in
order to plot a legend arrow in the calling program.

LEGENDMAG -> Returns to the calling program the magnitude of
the vector of size LEGENDLEN.  Default is LONGEST.

_EXTRA=e -> Picks up all other keywords for PLOT, PLOTS, etc.

OUTPUTS:
None.

SUBROUTINES:
Internal Subroutines:
=====================
VF_MAGNITUDE (function)

NOTES:
(1) You need to call MAP_SET or PLOT first, to establish the
coordinate system.  VELOCITY_FIELD can only overplot
vectors atop of an existing map or plot window.

(2) If you are calling VELOCITY_FIELD to overplot vectors
atop a world map, then in the calling program you must
make sure that the longitude values contained in the X
vector are in the range 0 - 360.

(3) If you do not explicitly specify Y_STEP, and your grid
has half-size boxes at the poles, then the value of
Y_STEP computed by VELOCITY_FIELD might be different from
the actual latitude interval.

(4) VELOCITY_FIELD assumes that U, V, X, and Y are on a
regularly-spaced grid (e.g. longitude & latitude).

(5) Now uses the IDL ARROW command to draw the arrow heads.

RESTRICTIONS:
None.

CALLING SEQUENCE:
VELOCITY_FIELD, U, V, X, Y, Thick=3, HSize=0.1

; produces a velocity field plot with an arrow
; thickness of 3 and a arrow head size of 10% of
; the arrow body size.

MODIFICATION HISTORY:
DMS, RSI, Oct., 1983.
For Sun, DMS, RSI, April, 1989.
Added POSITION, NOERASE, COLOR, Feb 91, RES.
August, 1993.  Vince Patrick, Adv. Visualization Lab, U. of Maryland,
fixed errors in math.
August, 1993. DMS, Added _EXTRA keyword inheritance.

bmy, 03 Dec 1999: GAMAP VERSION 1.44
- renamed to VELOCITY_FIELD
- added ARRLEN, HSIZE, HANGLE, THICK keywords
- cleaned up some things
bmy, 26 May 2000: GAMAP VERSION 1.45
bey, bmy, 24 Jul 2000: GAMAP VERSION 1.46
- several bug fixes
- added X_STEP, Y_STEP, MAXMAG keywords
sjg, bmy, 01 Aug 2000: - added error check on index array GOOD
- now compare magnitudes to abs( MISSING )
- now error check for MAXLEN: prevent div by 0
bmy, 23 Jul 2002: GAMAP VERSION 1.51
- now use IDL ARROW procedure to draw arrows
- HSIZE is now defaulted to device coordinates
- removed HANGLE keyword -- it's obsolete
- now specify legend vector w/ LEGENDLEN
- renamed ARRLEN to LEGENDNORM
bmy, 02 Jun 2005: GAMAP VERSION 2.04
- Added /DATELINE keyword to perform a quick
test to skip over points which will choke
at the date line
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 20 Mar 2008: GAMAP VERSION 2.12
- Now test if the vector position is in
the plot window