SPPS_converters(3NCARG)

💖 SPPS_converters — the NCAR Graphics coordinate glow-up station 💖

okay so bestie, welcome to spps_converters (that's the 3NCARG manual, she's an icon, she's been here since forever). This is literally a whole set of functions, and every single one of them takes a coordinate from one NCAR Graphics coordinate system and transforms it into another one. That's it. That's the job. Coordinate metamorphosis. 🦋

The complete lineup, no gatekeeping, all 24 of them:

CFUX, CFUY, CMFX, CMFY, CMUX, CMUY, CPFX, CPFY, CPUX, CPUY, CUFX, CUFY, KFMX, KFMY, KFPX, KFPY, KMPX, KMPY, KPMX, KPMY, KUMX, KUMY, KUPX, KUPY.

---

🌈 STATUS 🌈

Plotter Address Units (PAUs) and Metacode Units (MUs) are no longer used in NCAR Graphics; thus, all functions with either an M or a P as the second or third letter of the function name are considered obsolete.

not me having to say this but — PAUs and MUs? girl they're done. Retired. ✨Obsolete✨. So literally any function rocking an M or a P as its second or third letter? Yeah, that's a legacy queen, we still love her, but she is not the moment anymore. 💀

The coordinate systems that are currently recognized (the main characters, the it-girls):

• GKS world coordinates
• GKS normalized device coordinates
• NCAR Graphics fractional coordinates
• NCAR Graphics user coordinates

if you want the full lore on those, go read the NCAR Graphics document "NCAR Graphics Fundamentals, UNIX Version". it's giving required reading, fr fr. 📚

Now, because some of y'all are still out here interpreting and converting codes that use PAUs or MUs, here are the official definitions. We're doing this for the archive, bestie:

The plotter coordinate system: the plotter coordinates of a point are integers IPX and IPY, where IPX is between 1 and 2**MX and IPY is between 1 and 2**MY. MX and MY are internal parameters of SPPS, and each one has a default value of 10. You can set values of MX and MY by calling the routines SETI or SETUSV, and you can get them back by calling the routines GETSI or GETUSV. 🎀

The metacode coordinate system: the metacode coordinates of a point are integers IMX and IMY between 0 and 32767 inclusive. The area addressed is a square in a "metacode space" that is usually mapped into a square subset of the addressable area of the plotting device. Metacode coordinates were used in calls to the routine PLOTIT and are returned in calls to FL2INT. 👑

---

✨ SYNOPSIS ✨

Current (the ones that still eat):

X = CFUX (RX),  Y = CFUY(RY)
X = CUFX (RX),  Y = CUFY(RY)

Obsolete (the throwbacks, still documented for the culture):

X = CMUX (IX),  Y = CMUY(IY)
X = CPUX (IX),  Y = CPUY(IY)
X = CMFX (IX),  Y = CMFY(IY)
X = CPFX (IX),  Y = CPFY(IY)
I = KFMX (RX),  J = KFMY(RY)
I = KUMX (RX),  J = KUMY(RY)
I = KFPX (RX),  J = KFPY(RY)
I = KUPX (RX),  J = KUPY(RY)
I = KPMX (IX),  J = KPMY(IY)
I = KMPX (IX),  J = KMPY(IY)

---

🫶 C-BINDING SYNOPSIS 🫶

#include <ncarg/ncargC.h>

float c_cfux (float rx)

float c_cfuy (float ry)

float c_cufx (float rx)

float c_cufy (float ry)

---

💅 DESCRIPTION 💅

okay so here's how to read these function names, because the names are the documentation and honestly? iconic design. no cap.

• RX — an input expression of type REAL, and it's an X coordinate in whichever coordinate system the second letter of the function name says. So in a reference to CFUX, RX is a fractional X coordinate; in a reference to CUFX, RX is a user X coordinate. 💜
• RY — an input expression of type REAL, and it's a Y coordinate in whichever coordinate system the second letter of the function name says. So in a reference to CFUY, RY is a fractional Y coordinate; in a reference to CUFY, RY is a user Y coordinate. 💜
• IX and IY — these only show up as arguments in references to some of the obsolete functions. They're input expressions of type INTEGER, specifying the X and Y coordinates of a point in either PAUs or MUs (which one depends on the second letter of the function name). 🙈

And now the letter-by-letter decoder ring, because this naming scheme is honestly genius once you see it:

• The first letter is a C if the result is of type REAL, and a K if the result is of type INTEGER (the K situation only happens for some of the obsolete ones). This conforms to the usual FORTRAN convention for implicit typing. ⭐
• The second letter specifies the coordinate system of the argument.
• The third letter specifies the coordinate system of the functional result. So in references to CFUX and CFUY, the result is in the user system; in references to CUFX and CUFY, the result is in the fractional system. 🔥
• The fourth letter is an X or a Y, depending on whether an X or a Y coordinate is being converted. periodt.

C-BINDING DESCRIPTION

The C-binding argument description is the same as the FORTRAN argument description. literally identical, she said "same energy." 💖

---

🌸 EXAMPLES 🌸

Use the ncargex command to see the following relevant examples which use coordinate converters: mpex10, cbex01, sfex02, epltch.

And here's the trick, bestie: the command

ncargex -n mpex10

will load the driver mpex10.f into your current working directory, where you can examine the file using a local editor, or the UNIX more command. go look at it. touch the code. understand the code. 🧚

---

🎀 ACCESS 🎀

There were 24 conversion functions in the original set. Twenty-four. These functions (12 for the X coordinate of a point, and 12 for the Y coordinate), allowed one to convert between any combination of PAUs, MUs, fractional coordinates, and user coordinates. A whole grid of possibilities. 😭

But PAUs and MUs are now obsolete, so only four of the conversion functions are still pertinent:

• CFUX and CFUY — convert the X and Y coordinates of a point from the fractional system to the user system
• CUFX and CUFY — do the opposite

that's it. four queens left standing. 👑

To use one of these conversion routines, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c — preferably in that order. preferably in that order!! don't be chaotic about the linking, i'm begging. 🙏

---

💀 SEE ALSO 💀

Online: cfux, cfuy, cmfx, cmfy, cmux, cmuy, cpfx, cpfy, cpux, cpuy, cufx, cufy, kfmx, kfmy, kfpx, kfpy, kmpx, kmpy, kpmx, kpmy, kumx, kumy, kupx, kupy, spps, ncarg_cbind

Hardcopy: NCAR Graphics Fundamentals, UNIX Version; User's Guide for NCAR GKS-0A Graphics

---

🌈 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 little time capsule came out of the UNIX manual, March 1993 edition, filed under SPPS_converters(3NCARG) — go forth and convert those coordinates responsibly. mwah. 💖✨🎀