1VVUMXY(3NCARG) NCAR GRAPHICS VVUMXY(3NCARG)
2
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
15 CALL VVUMXY (X,Y,U,V,UVM,XB,YB,XE,YE,IST)
16
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 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 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 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 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 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 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 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 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 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
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 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 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
120 To use VVUMXY, load the NCAR Graphics libraries ncarg, ncarg_gks, and
121 ncarg_c, preferably in that order.
122
124 Online: vectors, vectors_params, vvectr, vvgetc, vvgeti, vvgetr,
125 vvinit, vvrset, vvsetc, vvseti, vvsetr, vvudmv, ncarg_cbind.
126 Hardcopy: NCAR Graphics Fundamentals, UNIX Version
128
130 Copyright (C) 1987-2007
131 University Corporation for Atmospheric Research
132 This documentation is free software; you can redistribute it and/or
134 modify it under the terms of the GNU General Public License as
135 published by the Free Software Foundation; either version 2 of the
136 License, or (at your option) any later version.
137 This software is distributed in the hope that it will be useful, but
139 WITHOUT ANY WARRANTY; without even the implied warranty of
140 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
141 General Public License for more details.
142 You should have received a copy of the GNU General Public License along
144 with this software; if not, write to the Free Software Foundation,
145 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
146UNIX April 1993 VVUMXY(3NCARG)