VVECTR(3NCARG)

VVECTR 💖 (the NCAR GRAPHICS era, bestie)

okay so. welcome to VVECTR, a function from the NCAR Graphics cinematic universe 🌈. she's the one who handles the coordinate system mapping, the color setting, the auxiliary text output, and the actual drawing of the vector field plot — all according to the specs you already set up with the parameter-setting routines and the init routine, VVINIT. she does not freestyle. she executes the vision. 💅

---

✨ NAME ✨

VVECTR — manages the coordinate system mapping, color setting, auxiliary text output, and drawing of the vector field plot, according to the specifications established by the parameter setting routines and the initialization routine, VVINIT. 🦋

---

✨ SYNOPSIS ✨

CALL VVECTR (U,V,P,IAM,VVUDMV,WRK)

---

✨ C-BINDING SYNOPSIS ✨

#include <ncarg/ncargC.h>

void c_vvectr(float *u, float *v, float *p, int *iam,
              int (*vvudmv_)(float *xcs, float *ycs,
              int *ncs, int *iai, int *iag, int *nai),
              float *wrk)

---

✨ DESCRIPTION ✨

the glow-up tour of every argument, one by one, no skips, we're being thorough here 🫶

• U — (REAL 2 dimensional array, dimensioned as specified in last call to VVINIT, input): by default, she's assumed to contain the first dimensional axis components of the vector field. BUT — and this is the plot twist — if PLR is non-zero, she gets treated as containing the vector magnitudes. two jobs, one array, main character energy fr.
• V — (REAL 2 dimensional array, dimensioned as specified in last call to VVINIT, input): by default, assumed to contain the second dimensional axis components of the vector field. however, if PLR is non-zero, she's treated as containing the vector angles. same deal, same duality ✨
• P — (REAL 2 dimensional array, dimensioned as specified in last call to VVINIT, input): an array of scalar data that may be used to color the vectors. the grid points are assumed to coincide with the grid points of the U and V arrays. only required if CTV has an absolute value of 2; otherwise this argument is ignored and you can just hand her a dummy value, no thoughts, head empty 🙈
• IAM — (INTEGER array, unknown dimension, input): an area map array previously established by calls to routines in the Areas utility. lowkey important: it is not examined or modified by Vectors. only required if MSK is set to a non-zero value; otherwise she's ignored and may be assigned a dummy value 💜
• VVUDMV — (EXTERNAL subroutine, input): the user-definable masked drawing subroutine. go read the vvudmv man page for a discussion of the usage and the argument list this subroutine requires. only required if MSK is set to a non-zero value; otherwise ignored, dummy value, we move on 🎀
• WRK — (REAL array, dimensioned as specified in last call to VVINIT, input/output): the work array, required only if the parameter VMD is set to a value greater than 0.0. otherwise? you guessed it — she may be set to a dummy value. iconic consistency 💅

💫 C-BINDING DESCRIPTION 💫

the C-binding argument descriptions are the same as the FORTRAN argument descriptions. that's it, that's the whole section, they're twins, they match, slay 🦋

---

✨ USAGE ✨

okay so here's the actual tea ☕

a call to VVINIT must precede the first call to VVECTR. and it's required again any time:

• the vector or scalar array data changes,
• any of the coordinate control parameters are modified, or
• the number of color threshold levels is modified when Vectors is given the responsibility of setting up the color threshold value array.

BUT 🫶 — and this is the part that's actually giving flexibility — the user may modify text elements or any of the rendering control parameters between multiple invocations of VVECTR. and if you're assuming responsibility for setting up the color threshold array, you may also modify the color array parameters in between. so you're not locked in, you're just... coordinated. ✨

arguments to VVINIT establish the sizes of the two or three data arrays, as well as the possible work array. VVINIT places these values into common block variables where they become available to VVECTR. therefore no size arguments need appear in the VVECTR argument list — she already knows, iykyk 💅

so when there is no scalar data array, area masking is not enabled, and VMD is less than or equal to 0.0, then all but the first two arguments to VVECTR may have dummy values, and the invocation would be something like:

CALL VVECTR(U,V,IDM,IDM,IDM,IDM)

where IDM is an arbitrary variable, INTEGER or REAL, that need not have been initialized. literally just vibes, uninitialized vibes 🌸

however — heads up bestie — any time the color threshold control parameter, CTV, has an absolute value of 2, the auxiliary scalar data array is expected, and the P scalar array variable needs to be specified. no dummies allowed in that scenario, periodt.

masking capability talk, buckle up 🧚

the masking capability supported by Vectors lets the user overlay vector fields on top of graphics produced by other utilities — think Conpack contour plots — without encroaching on areas, like label boxes, that should appear in the foreground. so your labels stay on top, where they belong, as they should 👑

normally the area map should be generated and used in the normal way (as described in the Areas and Conpack documentation) before calling any routines in the Vectors utility. when the parameter MSK has a non-zero value, masking is enabled and a previously created area map must be passed to VVECTR.

VVECTR examines the map, and she'll return an error if she determines that it's an invalid map or that it contains more area maps than she can handle — currently 64. that's the limit, she said what she said 💀

otherwise, her only use of the map is as a member of the argument list when invoking one of the Areas routines, ARDRLN or ARGTAI.

the user must also pass in a user-definable masked drawing subroutine. a simple version of this subroutine, named VVUDMV, is supplied with the Vectors utility, and may suffice for basic masked drawing operations. see the vvudmv man page for more information 🎀

now, the last argument in the calling sequence, WRK, is used only when the parameter VMD (Vector Minimum Distance) is given a value greater than 0.0. in that case, Vectors uses the array to keep track of the location of each vector in NDC space so that the distances between vectors can be compared. based on these comparisons, Vectors eliminates some vectors such that the remaining vectors are separated by at least the specified distance. ✨ (yes, she's doing crowd control on your vectors. it's a look.)

otherwise the WRK argument is ignored, and may be passed a dummy argument value. again. dummy value. it's a whole theme 🦋

---

✨ EXAMPLES ✨

use the ncargex command to see the following relevant examples: bnchmk, fcover, ffex00, ffex01, ffex02, ffex05, stex02, stex03, vvex01, vvex02. go run them, they're free, they're cute, they're educational 🍓

---

✨ ACCESS ✨

to use VVECTR or c_vvectr, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order. the order matters bestie, don't be chaotic about it 💅

---

✨ MESSAGES ✨

see the vectors man page for a description of all Vectors error messages and/or informational messages. she will tell you what went wrong, she's not mysterious 🌈

---

✨ SEE ALSO ✨

Online: vectors, vectors_params, 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 🫶 this was the VVECTR(3NCARG) manual page from the UNIX corner of the docs, dated April 1993 — yes she's vintage, yes she still ate, no cap. go draw some vectors. 💖✨🎀