NAME¶
Vectors - Utility for creating a vector field plot given two arrays containing
the vector components on a uniform grid. In addition, the user may pass in
another array of scalar data defined over the same grid space independent of
but presumably related in some fashion to the vector data. The utility will
then color each vector based on the scalar value at the grid point.
Alternatively, the user can choose to color the vectors based on vector
magnitude.
SYNOPSIS¶
The following two calls are the minimum required to create a vector field plot
using the current interface:
- •
- VVINIT - Performs the initialization required for VVECTR to interpret the
input array data properly. VVINIT stores the data array sizes, sets up
various coordinate system mappings, and processes the input arrays to find
the maximum and minimum values. If vector coloring is enabled and the user
has not explicitly taken control, the routine establishes a linearly
scaled color threshold array.
- •
- VVECTR - Renders the vectors based on conditions established by VVINIT and
the current values of a set of user-modifiable internal parameters
associated with the Vectors utility.
All user-modifiable internal parameters have default values; only those which
are to have values different from the default need to be set. The routines
used to set Vectors parameters are as follows:
- •
- VVRSET - Resets all internal parameters to their default values.
- •
- VVSETC - Assigns a value of type CHARACTER to a parameter.
- •
- VVSETI - Assigns a value of type INTEGER to a parameter.
- •
- VVSETR - Assigns a value of type REAL to a parameter.
In general, once a parameter is given a value by a call to one of these
routines, it retains that value until a similar call resets it. Retrieve the
value of an internal parameter by calling one of the following routines:
- •
- VVGETC - Returns a parameter value of type CHARACTER.
- •
- VVGETI - Returns a parameter value of type INTEGER.
- •
- VVGETR - Returns a parameter value of type REAL.
- •
Vectors supports three obsolete routines for compatibility with old NCAR
Graphics codes. The compatibility mode parameter, CPM, offers a number of
options that allow considerable flexibility in making the transition to the
new version of the utility. When writing new code you are encouraged not to
use these entry points, since they provide less capability than the standard
Vectors interface, and may eventually be phased out.
- •
- VELVCT - The principal entry point prior to Version 3.2, now a front end
to the VVINIT/VVECTR interface.
- •
- EZVEC - Front end to VELVCT: a simpler interface for standard situations,
when detailed control of the plot is not required.
- •
- VELVEC - Older version of VELVCT and now also a front end to it. It
differs from the VELVCT call only in that it contains one less input
argument in its calling sequence.
C-BINDING SYNOPSIS¶
c_vvinit
c_vvectr
c_vvrset
c_vvsetc
c_vvseti
c_vvsetr
c_vvgetc
c_vvgeti
c_vvgetr
c_velvct
c_ezvec
c_velvec
USER-MODIFIABLE INTERNAL ROUTINES¶
The following routines are not to be called directly. However, you may modify
them in order to customize the behavior of Vectors. VVUMXY is provided to
support user-defined mapping transformations. VVUDMV allows you to tailor
vector masking to your requirements.
- •
- VVUMXY - Performs a user-definable mapping of vector position and
direction from data coordinate space to normalized device coordinate
space.
- •
- VVUDMV - The default name of a routine used to draw vectors masked to an
area map. VVUDMV decides which segments of a vector to draw depending on
the area group and group identifier arrays passed to it.
ACCESS¶
To use Vectors, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c,
preferably in that order.
MESSAGES¶
In this section are listed, in alphabetical order, all the error messages that
may be written by Vectors. Each error message begins with the name of the
Vectors routine in which an error has been detected, followed by a dash,
followed by the error message itself. These error messages are written by a
call to the error-handling support routine SETER, with a final argument
indicating that the error is fatal and that execution should be terminated.
- VVECTR - TOO MANY AREA GROUPS
- The area map passed as the argument, IAM, to VVECTR contains more area
groups than allowed by the Vectors utility, currently 64. This error can
occur only if the Mask to Area Map parameter, MSK, has a value greater
than 0, specifying that vectors are to be drawn masked to an area
map.
- VVECTR - INVALID AREA MAP
- The area map passed as the argument, IAM, to VVECTR is judged to be
invalid because it contains a negative value for the number of area
groups. This error can occur only if the Mask to Area Map parameter, MSK,
has a value greater than 0, specifying that vectors are to be drawn masked
to an area map.
- VVGETC - PARAMETER NAME NOT KNOWN - x
- The given parameter name (´x´) is not a legal parameter name
known to Vectors.
- VVGETC - PARAMETER NAME TOO SHORT - x
- The parameter name ("x") is less than three characters
long.
- VVGETI OR VVGETR - GETTING x - PAI INCORRECT
- An attempt has been made to get an element of the parameter array named
´x´ and the current value of PAI (the "parameter array
index") is inappropriate for that parameter array.
- VVGETI OR VVGETR - PARAMETER NAME NOT KNOWN - x
- The given parameter name (´x´) is not a legal parameter name
known to Vectors.
- VVGETI OR VVGETR - PARAMETER NAME TOO SHORT - x
- The parameter name ("x") is less than three characters
long.
- VVINIT - U AND/OR V ARRAY DIMENSIONS EXCEEDED
- The VVINIT input argument, M, specifying the number of array elements to
use along the first dimension of the U and V (and possibly P) arrays,
exceeds the actual first dimension of U and/or V, as specified by the
input arguments LU and LV.
- VVINIT - SCALAR ARRAY TOO SMALL
- The value given to LP, the VVINIT input argument specifying the actual
first dimension of the scalar data array, P, is less than M, the input
argument specifying the number of array elements to use along the first
dimension for all of the input arrays. This error can only occur when the
absolute value of the Color Threshold Level control parameter, CTV, is set
to 2, indicating that coloring is to be performed according to values
contained in the scalar data array, P.
- VVSETC - PARAMETER NAME NOT KNOWN - x
- The given parameter name (´x´) is not a legal parameter name
known to Vectors.
- VVSETC - PARAMETER NAME TOO SHORT - x
- The parameter name ("x") is less than three characters
long.
- VVSETI OR VVSETR - PARAMETER NAME NOT KNOWN - x
- The given parameter name (´x´) is not a legal parameter name
known to Vectors.
- VVSETI OR VVSETR - PARAMETER NAME TOO SHORT - x
- The parameter name ("x") is less than three characters
long.
- VVSETI OR VVSETR - PARAMETER VALUE OUT OF RANGE - x
- An attempt has been made to set the parameter named ´x´ to a
value outside the range allowed by the Vectors utility.
- VVSETI OR VVSETR - SETTING x - PAI INCORRECT
- An attempt has been made to set an element of the parameter array named
´x´ and the current value of PAI (the "parameter array
index") is inappropriate for that parameter array.
SEE ALSO¶
Online: vectors_params, ezvec, velvec, velvct, fx, fy, vvectr, vvgetc, vvgeti,
vvgetr, vvinit, vvrset, vvsetc, vvseti, vvsetr, vvudmv, vvumxy, ncarg_cbind.
Hardcopy: NCAR Graphics Fundamentals, UNIX Version
COPYRIGHT¶
Copyright (C) 1987-2009
University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.