Vectors(3NCARG)

💫 Vectors 💫 (that's the NCAR Graphics one, bestie)

okay so listen. Vectors is the utility for making a vector field plot when you've got two arrays holding the vector components on a uniform grid. 🦋

And here's the cute part: you can also hand it a third array of scalar data defined over that same grid space — independent of the vector data, but presumably related to it somehow, iykyk. Then the utility will color each vector based on the scalar value at that grid point. OR, if that's not your vibe, you can color the vectors based on vector magnitude instead. Choices!! ✨

---

🌸 SYNOPSIS 🌸

These two calls are the bare minimum to make a vector field plot with the current interface, no cap:

• VVINIT — does all the initialization so that VVECTR can interpret your input array data properly. It stores the data array sizes, sets up various coordinate system mappings, and processes the input arrays to find the max and min values. And if vector coloring is enabled and you haven't explicitly taken control, it establishes a linearly scaled color threshold array. 💅
• VVECTR — renders the vectors, based on the conditions set up by VVINIT plus whatever the current values of the user-modifiable internal parameters are. That's the moment.

Every user-modifiable internal parameter has a default value, so you only need to set the ones that are gonna be different from the default. The routines that set Vectors parameters are:

• VVRSET — resets ALL internal parameters back to their default values. Factory reset energy.
• 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 gets a value from one of these routines, it keeps that value until a similar call resets it. 💀 And to read a parameter's value back, you call one of these:

• 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 also supports three obsolete routines for compatibility with old NCAR Graphics codes. The compatibility mode parameter, CPM, offers a bunch of options that give you considerable flexibility while transitioning to the new version of the utility. But when you're writing new code, please please please don't use these entry points — they provide less capability than the standard Vectors interface, and they may eventually be phased out. 🙈

• VELVCT — the principal entry point before Version 3.2, now a front end to the VVINIT/VVECTR interface.
• EZVEC — front end to VELVCT: a simpler interface for standard situations, for when you don't need detailed control of the plot.
• 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 👑

⚠️ These routines are not to be called directly. But you may modify them to customize the behavior of Vectors. VVUMXY is there to support user-defined mapping transformations, and VVUDMV lets you 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, bestie. 🫶

---

💖 MESSAGES 💖

Here, in alphabetical order, are all the error messages Vectors may write. Each one starts with the name of the Vectors routine where the error was detected, then a dash, then the message itself. These get written by a call to the error-handling support routine SETER, with a final argument saying the error is fatal and execution should be terminated. 😭

VVECTR - TOO MANY AREA GROUPS

The area map passed as the argument, IAM, to VVECTR contains more area groups than the Vectors utility allows — currently 64. This error can only occur if the Mask to Area Map parameter, MSK, has a value greater than 0, meaning 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 invalid because it contains a negative value for the number of area groups. This error can only occur if the Mask to Area Map parameter, MSK, has a value greater than 0, meaning 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, meaning 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.

---

and that's the whole page, bestie, go slay your vector field 🧚💅

NCAR Graphics · UNIX · April 1993 · Vectors(3NCARG) — mwah, thanks for reading, ily, periodt. 💖