NAME:
       VARIANCE

 PURPOSE:
       This function computes the statistical variance of an
       N-element vector. 

 CATEGORY:
       Statistics.

 CALLING SEQUENCE:
       Result = variance(X)

 INPUTS:
       X:      An N-element vector of type integer, float or double.

 KEYWORD PARAMETERS:
       DOUBLE: IF set to a non-zero value, computations are done in
               double precision arithmetic.

       NAN:    If set, treat NaN data as missing.

 CALLS: ***
	MOMENT
 EXAMPLE:
       Define the N-element vector of sample data.
         x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
       Compute the mean.
         result = variance(x)
       The result should be:
       7.06667

 PROCEDURE:
       VARIANCE calls the IDL function MOMENT.

 REFERENCE:
       APPLIED STATISTICS (third edition)
       J. Neter, W. Wasserman, G.A. Whitmore
       ISBN 0-205-10328-6

 MODIFICATION HISTORY:
       Written by:  GSL, RSI, August 1997

 NAME:
	VECTOR_FIELD

 PURPOSE:

	This procedure is used to place colored, orientated vectors of
	specified length at each vertex in an input vertex array.  The output
	can be sent directly to an IDLgrPolyline object.  The generated
	display is generally referred to as a hedgehog display and is used to
	convey various aspects of a vector field.


 CATEGORY:
	3D Toolkit

 CALLING SEQUENCE:

	VECTOR_FIELD, field, outverts, outcolors [,ANISOTROPY = a] [,SCALE=sc]
	    [,VERTICES=verts]


 INPUTS:

 Field:	Input vector field array. This can be a [3,x,y,z] array or a
		[2,x,y] array.  The leading dimension is the vector quantity 
		to be displayed.

 OUTPUTS:


 Outverts:	Output vertex array ([3,N] or [2,N] array of floats).  Useful 
		if the routine is to be used with Direct Graphics or the user 
		wants to manipulate the data directly.
 Outcolors:	Output color array.  Useful if the routine is to be used with 
		Direct Graphics or the user wants to manipulate the data 
		directly.


 OPTIONAL KEYWORD PARAMETERS:


 VERTICES:	Set this input keyword to a [3,n] or [3n] ([2,n]
               or[2n] if 2D) array of points. If this keyword is set, the
               vector field is interpolated at these points. The resulting
               interpolated vectors are displayed as line segments at these
               locations.  If the keyword is not set, each spatial sample
               point in the input Field grid is used as the base point for a
               line segment.
 ANISOTROPY:	Set this input keyword to a two or three element array 
		describing the distance between grid points in each dimension.
  		The default value is [1.0, 1.0, 1.0]
 SCALE:	Set this keyword to a scalar scaling factor.  All vector 
		lengths are multiplied by this value.  The default is 1.0.


 PROCEDURE/EXAMPLES: 


 VECTOR_FIELD, field, outverts, outconn, ANISOTROPY=anisotropy,
     SCALE=2.0, VERTICES=vertices

 oHedgeHog = OBJ_NEW('IDLgrPolyline',outverts,POLYLINES=outconn)


 MODIFICATION HISTORY: 
 	KB, 	written Feb 1999.  

 NAME:
	VEL

 PURPOSE:
	Draw a velocity (flow) field with arrows following the field
	proportional in length to the field strength.  Arrows are composed
	of a number of small segments that follow the streamlines.

 CATEGORY:
	Graphics, two-dimensional.

 CALLING SEQUENCE:
	VEL, U, V

 INPUTS:
	U:	The X component at each point of the vector field.  This
		parameter must be a 2D array.

	V:	The Y component at each point of the vector field.  This
		parameter must have the same dimensions as U.

 KEYWORD PARAMETERS:
	NVECS:	The number of vectors (arrows) to draw.  If this keyword is
		omitted, 200 vectors are drawn.

	XMAX:	X axis size as a fraction of Y axis size.  The default is 1.0.
		This argument is ignored when !p.multi is set.

	LENGTH:	The length of each arrow line segment expressed as a fraction
		of the longest vector divided by the number of steps.  The
		default is 0.1.

	NSTEPS:	The number of shoots or line segments for each arrow.  The
		default is 10.

	TITLE:	A string containing the title for the plot.

 OUTPUTS:
	No explicit outputs.  A velocity field graph is drawn on the current
	graphics device.

 CALLS: ***
	VEL__ARRHEAD, VEL__ARROWS, VEL__MYBI
 COMMON BLOCKS:
	None.

 SIDE EFFECTS:
	A plot is drawn on the current graphics device.

 RESTRICTIONS:
	none

 PROCEDURE:
	NVECS random points within the (u,v) arrays are selected.
	For each "shot" the field (as bilinearly interpolated) at each
	point is followed using a vector of LENGTH length, tracing
	a line with NSTEPS segments.  An arrow head is drawn at the end.

 MODIFICATION HISTORY:
	Neal Hurlburt, April, 1988.
	12/2/92	- modified to handle !p.multi (jiy-RSI)
       7/12/94 HJM - Fixed error in weighting factors in function
                     vel_mybi() which produced incorrect velocity vectors.
	2/18/99 - SJL - Added check of input array dims

 NAME:
   VELOVECT

 PURPOSE:
   Produce a two-dimensional velocity field plot.

   A directed arrow is drawn at each point showing the direction and
   magnitude of the field.

 CATEGORY:
   Plotting, two-dimensional.

 CALLING SEQUENCE:
   VELOVECT, U, V [, X, Y]

 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.  Y must have
       the same dimensions as X.  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]).

 OPTIONAL INPUT PARAMETERS:
   X:  Optional abcissae values.  X must be a vector with a length
       equal to the first dimension of U and V.

   Y:  Optional ordinate values.  Y must be a vector with a length
       equal to the first dimension of U and V.

 KEYWORD INPUT PARAMETERS:
   COLOR:  The color index used for the plot.

   DOTS:   Set this keyword to 1 to place a dot at each missing point.
       Set this keyword to 0 or omit it to draw nothing for missing
       points.  Has effect only if MISSING is specified.

   LENGTH: Length factor.  The default of 1.0 makes the longest (U,V)
       vector the length of a cell.

       MISSING: Missing data value.  Vectors with a LENGTH greater
       than MISSING are ignored.

       OVERPLOT: Set this keyword to make VELOVECT "overplot".  That is, the
               current graphics screen is not erased, no axes are drawn, and
               the previously established scaling remains in effect.


   Note:   All other keywords are passed directly to the PLOT procedure
       and may be used to set option such as TITLE, POSITION,
       NOERASE, etc.
 OUTPUTS:
   None.

 COMMON BLOCKS:
   None.

 SIDE EFFECTS:
   Plotting on the selected device is performed.  System
   variables concerning plotting are changed.

 RESTRICTIONS:
   None.

 PROCEDURE:
   Straightforward.  Unrecognized keywords are passed to the PLOT
   procedure.

 MODIFICATION HISTORY:
   DMS, RSI, Oct., 1983.
   For Sun, DMS, RSI, April, 1989.
   Added TITLE, Oct, 1990.
   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.
   January, 1994, KDB. Fixed integer math which produced 0 and caused
                   divide by zero errors.
   December, 1994, MWR. Added _EXTRA inheritance for PLOTS and OPLOT.
   June, 1995, MWR. Removed _EXTRA inheritance for PLOTS and changed
            OPLOT to PLOTS.
       September, 1996, GGS. Changed denominator of x_step and y_step vars.
       February, 1998, DLD.  Add support for CLIP and NO_CLIP keywords.
       June, 1998, DLD.  Add support for OVERPLOT keyword.
   June, 2002, CT, RSI: Added the _EXTRA back into PLOTS, since it will
       now (as of Nov 1995!) quietly ignore unknown keywords.

 NAME:
       VERT_T3D

 PURPOSE:
       This function tranforms 3-D points by a 4x4 transformation matrix.
       The 3-D points are typically an array of polygon vertices that were
       generated by SHADE_VOLUME or MESH_OBJ.

 CATEGORY:
       Graphics.

 CALLING SEQUENCE:
       result = VERT_T3D(vertex_list)

 INPUTS:
       Vertex_List:
               A 3 x n array of 3D coordinates to transform.

 KEYWORD PARAMETERS:

	Double:
		Set this keyword to a nonzero value to indicate that the
		returned coordinates should be double precision.  If this
		keyword is not set, the default is to return single
		precision coordinates (unless double precision coordinates
		are input, in which case the DOUBLE keyword is implied to
		be non-zero).

       Matrix:
               The 4x4 transformation matrix to use. The default is to use
               the system viewing matrix (!P.T). (See the "T3D" procedure). 

       No_Copy:
               Normally, a COPY of Vertex_List is transformed and the
               original vertex_list is preserved. If No_Copy is set, however,
               then the original Vertex_List will be undefined AFTER the call
               to VERT_T3D. Using the No_Copy mode will require less memory.

       No_Divide:
               Normally, when a [x, y, z, 1] vector is transformed by a 4x4
               matrix, the final homogeneous coordinates are obtained by
               dividing the x, y, and z components of the result vector by
               the fourth element in the result vector. Setting the No_Divide
               keyword will prevent VERT_T3D from performing this division.
               In some cases (usually when a perspective transformation is
               involved) the fourth element in the result vector can be very
               close to (or equal to) zero.

       Save_Divide:
               Set this keyword to a named variable to receive the fourth
               element of the transformed vector(s). If Vertex_List is a
               vector then Save_Divide is a scalar. If Vertex_List is a
               [3, n] array then Save_Divide is an array of n elements.
               This keyword only has effect when the No_Divide keyword is set.

 OUTPUTS:
       This function returns the transformed coordinate(s). The returned
       array has the same size and dimensions as Vertex_List.

 CALLED BY:
	MESH_OBJ, SLICER3
 PROCEDURE:
       Before performing the transformation, the [3, n] Vertex_List is padded
       to produce a [4, n] array with 1's in the last column. After the
       transformation, the first three columns of the array are divided by
       the fourth column (unless the No_Divide keyword is set). The fourth
       column is then stripped off (or saved in the Save_Divide keyword)
       before returning.

 EXAMPLE:
       Transform four points representing a square in the x-y plane by first
       translating +2.0 in the positive X direction, and then rotating 60.0
       degrees about the Y axis.

               points = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], $
                         [1.0, 1.0, 0.0], [0.0, 1.0, 0.0]]
               T3d, /Reset
               T3d, Translate=[2.0, 0.0, 0.0]
               T3d, Rotate=[0.0, 60.0, 0.0]
               points = VERT_T3D(points)

 MODIFICATION HISTORY:
       Written by:     Daniel Carr, Thu Mar 31 15:58:07 MST 1994
	DLD, April, 2000.  Update for double precision; add DOUBLE keyword.

 NAME:
   VORONOI

 PURPOSE:
   This procedure computes the Voronoi polygon of a point within
   an irregular grid of points, given the Delaunay triangulation.
   The Voronoi polygon of a point contains the region closer to
   that point than to any other point.

 CATEGORY:
   Gridding.

 CALLING SEQUENCE:
   VORONOI, X, Y, I0, C, Xp, Yp, Rect

 INPUTS:
   X:  An array containing the X locations of the points.
   Y:  An array containing the Y locations of the points.
   I0: Index of the point of which to obtain the Voronoi polygon.
   C:  A connectivity list from the Delaunay triangulation.
       This list is produced with the CONNECTIVITY keyword
       of the TRIANGULATE procedure.
   Rect    the bounding rectangle:  [Xmin, Ymin, Xmax, Ymax].
       Because the Voronoi polygon (VP) for points on the convex hull
       extends to infinity, a clipping rectangle must be supplied to
       close the polygon.  This rectangle has no effect on the VP of
       interior points.  If this rectangle does not enclose all the
       Voronoi vertices, the results will be incorrect.  If this
       parameter, which must be a named variable, is undefined or
       set to a scalar value, it will be calculated.

 OUTPUTS:
   Xp, Yp: The vertices of voroni polygon, VP.

 CALLS: ***
	CIR_3PNT, ISRIGHT, TEK_COLOR, VORONOI_GET_INTERSECT, VORONOI_SHOW
 RESTRICTIONS:
   The polygons only cover the convex hull of the set of points.

 PROCEDURE:
   For interior points, the polygon is constructed by connecting
   the midpoints of the lines connecting the point with its Delaunay
   neighbors. Polygons are traversed in a counterclockwise direction.

   For exterior points, the set described by the midpoints of the
   connecting lines, plus the circumcenters of the two triangles
   that connect the point to the two adjacent exterior points.

 EXAMPLE:
   See the example procedure, VORONOI_SHOW, contained in this file.
   To illustrate Voronoi polygons, after compiling this file (voronoi):
       VORONOI_SHOW, Npoints  (try anywhere from 3 to 1000, default=12)

   To draw the voroni polygons of each point of an irregular
   grid:
     x = randomu(seed, n)           ;Random grid of N points
     y = randomu(seed, n)
     triangulate, x, y, tr, CONN=c           ;Triangulate it
     rect = 0
     for i=0, n-1 do begin
       voronoi, x, y, i, c, xp, yp, rect     ;Get the ith polygon
       polyfill, xp, yp, color = (i mod 10) + 2  ;Draw it
       endfor

 MODIFICATION HISTORY:
   DMS, RSI.   Dec, 1992. Original version.
   DMS, RSI    Feb, 1995. Added bounding rectangle which simplified
                  logic and better illustrated VPs for points
                  on the convex hull.