STUMXY(3NCARG)

💫 STUMXY 💫 — the streamline point-mapper (from the NCAR Graphics manual, bestie)

okay so picture this: you've got a point chillin' on a streamline in data coordinate space, and it needs a lil glow-up into user coordinate space. That's literally the whole job. STUMXY maps a single point on the streamline from data to user coordinate space. that's it, that's the vibe. 🦋

✨ SYNOPSIS ✨

CALL STUMXY(XDA,YDA,XUS,YUS,IST)

🌸 DESCRIPTION 🌸

here's the roster of arguments, no skips, no cuts:

• XDA (REAL, input) — the X coordinate of a point on the streamline, in data coordinate space.
• YDA (REAL, input) — the Y coordinate of that same point, also in data coordinate space.
• XUS (REAL, output) — the X coordinate of the point once it's in user coordinate space.
• YUS (REAL, output) — the Y coordinate of the point once it's in user coordinate space.
• IST (REAL, output) — the status of the mapping operation. 0 means slay, it worked. Negative values mean the mapping failed 😭. Positive values are reserved and should not be used by the implementor of a mapping routine — hands off those, bestie.

🎀 USAGE 🎀

so STUMXY is a user-modifiable routine, provided to support custom mappings of the data coordinate space. The thing is, you don't call it yourself. Ever. Instead, whenever the parameter MAP specifies a mapping that Streamlines doesn't handle internally — i.e., whenever MAP is set to a value other than 0, 1, or 2 — Streamlines calls STUMXY as needed while it's out here creating a streamline. 💅

The default version of STUMXY? It just does an identity mapping. Simple. Iconic. Does nothing, beautifully.

Now, if you wanna implement a custom mapping, here's the tea:

1. Pick a unique mapping code — a positive integer greater than 2.
2. Modify each of the three routines — STUMXY, STUIXY, and STUMTA — so they recognize that code and respond to it consistently with each other.

In the standard distribution of NCAR Graphics, those three routines all live in a single file, stumxy.f. And here's who does what:

• STUMXY maps a point from data to user coordinate space.
• STUIXY inversely maps a point from user to data coordinate space.
• STUMTA finds the tangent angle of the streamline at a point in NDC space — and ngl, that one's probably gonna be the hardest to implement. 😭

STUMXY also has access to a common block called STMAP, which holds a bunch of variables used to record the current transformation state. To accommodate a whole variety of mapping implementations, STMAP provides more information than is normally required — generous of it, honestly. But consider the values stored in STMAP as strictly read-only. Do not touch. Do not breathe on them. One essential member of this common block is IMAP, which contains the value currently assigned to the MAP parameter. 👑

In STUMXY, if you're implementing a custom mapping, you need to add code of this form:

IF (IMAP .EQ. <chosen_map_code>) THEN

    ...map XDA to XUS

    ...map YDA to YUS

    ...if error, set IST to a negative value

    RETURN

ENDIF

heads up: after the return from STUMXY, Streamlines checks to make sure that XUS and YUS are within the current boundaries of the user coordinate system. so don't be sending it out-of-bounds coords, fr fr.

When you're implementing a custom mapping, you might wanna peek at how the pre-defined mappings are coded — that's 0 for identity mapping, 1 for Ezmap projections, and 2 for polar coordinate mapping — all sitting in the file stmpxy.f. For those mappings, the subroutine STMPXY is the equivalent of STUMXY. It has an identical interface and may totally serve as a model for your implementation. steal like an artist, bestie. 🎨

🔥 ACCESS 🔥

To use STUMXY, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c — preferably in that order. order matters, don't fight it. ✨

🌈 SEE ALSO 🌈

Online: stgetc, stgeti, stgetr, stinit, stream, streamlines, streamlines_params, strset, stsetc, stseti, stsetr, stuixy, stumsl, stumta, stumxy, 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.

okay that's the whole page, we ate and left no crumbs 💖 this was STUMXY(3NCARG) from the UNIX manual, dated April 1993 — mwah, periodt. 🫶