VVUMXY(3NCARG)

💖 VVUMXY — the glow-up-your-own-vector-mapping routine 💖

okay bestie, so this is a page from the NCAR GRAPHICS manual, and it's about VVUMXY from the 3NCARG section. no cap, this one is a choose-your-own-adventure routine. 🦋

---

✨ NAME ✨

VVUMXY — the routine you get to modify so you can define a custom mapping of vectors from a data coordinate system (one that's aligned with the natural boundaries of the vector field, obviously 💅) over to the uniform normalized device coordinate (NDC) system that's suitable for generating a plot on an output device.

it has the same parameters as the internal Vectors routine, VVMPXY, which is the one used for the predefined mappings — y'know, the ones that kick in 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 ✨

okay so here's the whole cast of characters, one by one, no skips 🫶

• X — (REAL, input) where the vector sits along the first dimensional axis in the data coordinate system. when MAP is 0, this is the X Axis. if MAP is 1, it's the longitudinal axis, and if MAP is 2, it's the radial axis. for any other values of MAP — the ones that actually cause VVUMXY to get invoked — the interpretation is up to the author of the mapping routine. you're the main character here, bestie. 👑
• Y — (REAL, input) where the vector sits along the second dimensional axis in the data coordinate system. when MAP is 0, this is the Y Axis. if MAP is 1, it's the latitudinal axis, and if MAP is 2, it's the angular axis. for other values of MAP — again, the ones that make VVUMXY get called — the interpretation is up to the author of the mapping routine. ✨
• U — (REAL, input) the 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, then the direction of the U component is parallel to the horizontal (X axis) in NDC space. slay.
• V — (REAL, input) the 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, then the direction of the V component is parallel to the vertical (Y axis) in NDC space. iconic behavior honestly.
• UVM — (REAL, input) the magnitude of the U and V components, SQRT(U*U+V*V). like yes, technically this could be calculated inside the routine, but it's more efficient for the calling routine to supply the value as an argument, because it's needed for other purposes at a higher level. bestie is doing the math so you don't have to. 🧚
• 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) the status of the vector mapping operation:
  • 0 means success 🎉
  • negative values mean the mapping failed 😭
  • positive values are reserved and should not be used by the implementor of a mapping routine. hands off, bestie. 🙈

---

✨ USAGE ✨

so here's the tea: the user does not call VVUMXY. 🫢 Vectors calls it, and only when the parameter MAP has a value other than 0, 1, or 2 — those three mappings are handled by Vectors internally. iykyk.

also, heads up: unlike the other user-modifiable mapping routines in NCAR Graphics, like CPMPXY, which 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.

and why NDC for output? because NDC is a coordinate system that's guaranteed to be rectangular and uniform, so it's a super convenient reference system for mapping both vector magnitude and direction correctly. 💅

now, "uniform" here means: 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. not uniform, not invited. 💀

🎀 implementing your own custom mapping 🎀

to implement a custom mapping, you gotta:

1. pick a unique mapping code — a positive integer greater than 2
2. 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. 👑

🦋 the non-linear mapping situation 🦋

when implementing a non-linear mapping, an iterative differential technique will most likely be required. go look at the routine, VVMPXY, in vvmpxy.f — it handles the pre-defined mappings, and it's full of examples of the method. 📖✨

both the default transformation (MAP set to 0) — which exists to account for possible log scaling of the user coordinate axes — and also the Ezmap projection (MAP set to 1) use such a technique. so you're in good company.

basically the idea is:

• the vector components must be proportionally reduced in size enough that an effectively "instantaneous" angle can be calculated,
• but 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.

and the pre-defined mappings? they step in the opposite direction to find the angle whenever an increment in the original direction would fall off the edge. iconic problem-solving, honestly. 👑

---

✨ ACCESS ✨

to use VVUMXY, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c — preferably in that order. don't fight the order, bestie. 🫶

---

✨ SEE ALSO ✨

Online: vectors, vectors_params, vvectr, vvgetc, vvgeti, vvgetr, vvinit, vvrset, vvsetc, vvseti, vvsetr, vvudmv, 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.

---

and that's the whole page, bestie!! 🎀✨ this was VVUMXY(3NCARG) from the UNIX manual, dated April 1993 — yeah, she's vintage, she's timeless, she ate. 💅 go forth and write your custom mapping, you absolute icon. 🌈💖🦋