1VVUMXY(3NCARG)                   NCAR GRAPHICS                  VVUMXY(3NCARG)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

18       X           (REAL, input) Location of the vector along the first
19                   dimensional axis in the data coordinate system. When MAP is
20                   0, this is the X Axis. If MAP is 1, it is the longitudinal
21                   axis, and if MAP is 2, it is the radial axis. For other
22                   values of MAP, those that cause VVUMXY to be invoked, the
23                   interpretation is up to the author of the mapping routine.
24
25       Y           (REAL, input) Location of the vector along the second
26                   dimensional axis in the data coordinate system. When MAP is
27                   0, this is the Y Axis. If MAP is 1, it is the latitudinal
28                   axis, and if MAP is 2, it is the angular axis. For other
29                   values of MAP, those that cause VVUMXY to be invoked, the
30                   interpretation is up to the author of the mapping routine.
31
32       U           (REAL, input) U component of the vector. If TRT is set to
33                   1, the direction of the U component is tangent to the
34                   direction of the first dimensional axis in the data
35                   coordinate system at the location of the vector. If TRT is
36                   set to 0, and MAP has a value of 0 or 2, the direction of
37                   the U component is parallel to the horizontal (X axis) in
38                   NDC space.
39
40       V           (REAL, input) V component of the vector. If TRT is set to
41                   1, the direction of the V component is normal to the
42                   direction of the first dimensional axis in the data
43                   coordinate system at the location of the vector. If TRT is
44                   set to 0, and MAP has a value of 0 or 2, the direction of
45                   the V component is parallel to the vertical (Y axis) in NDC
46                   space.
47
48       UVM         (REAL, input) Magnitude of the U and V components,
49                   SQRT(U*U+V*V). Although this value could be calculated
50                   within the routine, it is more efficient for the calling
51                   routine to supply the value as an argument, since it is
52                   needed for other purposes at a higher level.
53
54       XB          (REAL, output) Location of the vector starting point along
55                   the horizontal (X axis) in NDC space, before adjustment
56                   based on the value of the vector positioning parameter,
57                   VPO.
58
59       YB          (REAL, output) Location of the vector starting point along
60                   the vertical (Y axis) in NDC space, before adjustment based
61                   on the value of the vector positioning parameter, VPO
62
63       XE          (REAL, output) Location of the vector ending point along
64                   the horizontal (X axis) in NDC space, before adjustment
65                   based on the value of the vector positioning parameter, VPO
66
67       YE          (REAL, output) Location of the vector ending point along
68                   the vertical (Y axis) in NDC space before adjustment based
69                   on the value of the vector positioning parameter, VPO
70
71       IST         (REAL, output) Status of the vector mapping operation: 0
72                   indicates success, negative values indicate that the
73                   mapping failed; positive values are reserved and should not
74                   be used by the implementor of a mapping routine.
75

USAGE

77       The user does not call VVUMXY. Vectors calls it only when the parameter
78       MAP has a value other than 0, 1, or 2, the mappings handled by Vectors
79       internally. Note that unlike other user-modifiable mapping routines in
80       NCAR Graphics, such as CPMPXY, that map a single point into the user
81       coordinate system, this routine returns two points, representing both
82       ends of the vector, scaled for magnitude, in the normalized device
83       coordinate (NDC) system. The NDC system is used for output because, as
84       a coordinate system guaranteed to be rectangular and uniform, it serves
85       as a convenient reference system to help map both vector magnitude and
86       direction correctly. The term uniform, as used in this discussion,
87       means that an arbitrary numerical increment along either the X or Y
88       axis has the same length given any offset from the coordinate system
89       origin. The user coordinate system does not qualify, because it may be
90       log-scaled, or the X units may have a different size from the Y units.
91
92       In order to implement a custom mapping, you must pick a unique mapping
93       code (a positive integer greater than 2), and then modify VVUMXY to
94       recognize and respond to the chosen code. In the standard distribution
95       of NCAR Graphics, this routine resides in the file, ´vvumxy.f´.  VVUMXY
96       has access to a common block called VVMAP that contains a number of
97       variables used to record the current transformation state.  In order to
98       accommodate a variety of mapping implementations, VVMAP provides more
99       information than normally required. Consider the values stored in VVMAP
100       as strictly read-only.  One essential member of this common block is
101       IMAP, which contains the value currently assigned to the MAP parameter.
102
103       When implementing a non-linear mapping, an iterative differential
104       technique will most likely be required. Look at the routine, VVMPXY, in
105       ´vvmpxy.f´, which handles the pre-defined mappings, for examples of the
106       method. Both the default transformation (MAP set to 0), in order to
107       account for possible log scaling of the user coordinate axes, and also
108       the Ezmap projection (MAP set to 1) use such a technique.  Basically
109       the idea is that the vector components must be proportionally reduced
110       in size enough that an effectively "instantaneous" angle can be
111       calculated, although they must not become so small that the calculation
112       is adversely affected by the floating point precision available for the
113       machine. Additionally, checks must be put in place to prevent the
114       increment from stepping off the edge of the coordinate system space.
115       The pre-defined mappings step in the opposite direction to find the
116       angle whenever an increment in the original direction would fall off
117       the edge.
118

ACCESS

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

SEE ALSO

124       Online: vectors, vectors_params, vvectr, vvgetc, vvgeti, vvgetr,
125       vvinit, vvrset, vvsetc, vvseti, vvsetr, vvudmv, ncarg_cbind.
126
127       Hardcopy: NCAR Graphics Fundamentals, UNIX Version
128
130       Copyright (C) 1987-2009
131       University Corporation for Atmospheric Research
132       The use of this Software is governed by a License Agreement.
133
134
135
136UNIX                              April 1993                    VVUMXY(3NCARG)
Impressum