Ubuntu Manpage: VVUMXY - The user may modify this routine to define a custom mapping of vectors from a data coordinate

NAME

       VVUMXY - The user may modify this routine to define a custom mapping of vectors from a data coordinate
       system aligned with the natural boundaries of the vector field to the uniform normalized device
       coordinate (NDC) system suitable for generating a plot on an output device. It has same parameters as the
       internal Vectors routine, VVMPXY, used for the predefined mappings employed when the MAP parameter has a
       value between 0 and 2.

SYNOPSIS

       CALL VVUMXY (X,Y,U,V,UVM,XB,YB,XE,YE,IST)

DESCRIPTION

X (REAL, input) Location of the vector along the first dimensional axis in the data coordinate
system. When MAP is 0, this is the X Axis. If MAP is 1, it is the longitudinal axis, and if
MAP is 2, it is the radial axis. For other values of MAP, those that cause VVUMXY to be
invoked, the interpretation is up to the author of the mapping routine.

Y (REAL, input) Location of the vector along the second dimensional axis in the data coordinate
system. When MAP is 0, this is the Y Axis. If MAP is 1, it is the latitudinal axis, and if
MAP is 2, it is the angular axis. For other values of MAP, those that cause VVUMXY to be
invoked, the interpretation is up to the author of the mapping routine.

U (REAL, input) U component of the vector. If TRT is set to 1, the direction of the U component
is tangent to the direction of the first dimensional axis in the data coordinate system at
the location of the vector. If TRT is set to 0, and MAP has a value of 0 or 2, the direction
of the U component is parallel to the horizontal (X axis) in NDC space.

V (REAL, input) V component of the vector. If TRT is set to 1, the direction of the V component
is normal to the direction of the first dimensional axis in the data coordinate system at the
location of the vector. If TRT is set to 0, and MAP has a value of 0 or 2, the direction of
the V component is parallel to the vertical (Y axis) in NDC space.

UVM (REAL, input) Magnitude of the U and V components, SQRT(U*U+V*V). Although this value could
be calculated within the routine, it is more efficient for the calling routine to supply the
value as an argument, since it is needed for other purposes at a higher level.

XB (REAL, output) Location of the vector starting point along the horizontal (X axis) in NDC
space, before adjustment based on the value of the vector positioning parameter, VPO.

YB (REAL, output) Location of the vector starting point along the vertical (Y axis) in NDC
space, before adjustment based on the value of the vector positioning parameter, VPO

XE (REAL, output) Location of the vector ending point along the horizontal (X axis) in NDC
space, before adjustment based on the value of the vector positioning parameter, VPO

YE (REAL, output) Location of the vector ending point along the vertical (Y axis) in NDC space
before adjustment based on the value of the vector positioning parameter, VPO

IST (REAL, output) Status of the vector mapping operation: 0 indicates success, negative values
indicate that the mapping failed; positive values are reserved and should not be used by the
implementor of a mapping routine.

USAGE

The user does not call VVUMXY. Vectors calls it only when the parameter MAP has a value other than 0, 1,
or 2, the mappings handled by Vectors internally. Note that unlike other user-modifiable mapping routines
in NCAR Graphics, such as CPMPXY, that map a single point into the user coordinate system, this routine
returns two points, representing both ends of the vector, scaled for magnitude, in the normalized device
coordinate (NDC) system. The NDC system is used for output because, as a coordinate system guaranteed to
be rectangular and uniform, it serves as a convenient reference system to help map both vector magnitude
and direction correctly. The term uniform, as used in this discussion, means that an arbitrary numerical
increment along either the X or Y axis has the same length given any offset from the coordinate system
origin. The user coordinate system does not qualify, because it may be log-scaled, or the X units may
have a different size from the Y units.

In order to implement a custom mapping, you must pick a unique mapping code (a positive integer greater
than 2), and then modify VVUMXY to recognize and respond to the chosen code. In the standard distribution
of NCAR Graphics, this routine resides in the file, ´vvumxy.f´. VVUMXY has access to a common block
called VVMAP that contains a number of variables used to record the current transformation state. In
order to accommodate a variety of mapping implementations, VVMAP provides more information than normally
required. Consider the values stored in VVMAP as strictly read-only. One essential member of this common
block is IMAP, which contains the value currently assigned to the MAP parameter.

When implementing a non-linear mapping, an iterative differential technique will most likely be required.
Look at the routine, VVMPXY, in ´vvmpxy.f´, which handles the pre-defined mappings, for examples of the
method. Both the default transformation (MAP set to 0), in order to account for possible log scaling of
the user coordinate axes, and also the Ezmap projection (MAP set to 1) use such a technique. Basically
the idea is that the vector components must be proportionally reduced in size enough that an effectively
"instantaneous" angle can be calculated, although they must not become so small that the calculation is
adversely affected by the floating point precision available for the machine. Additionally, checks must
be put in place to prevent the increment from stepping off the edge of the coordinate system space. The
pre-defined mappings step in the opposite direction to find the angle whenever an increment in the
original direction would fall off the edge.

ACCESS

       To use VVUMXY, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order.

COPYRIGHT