PPINTR(3NCARG)

💖 NAME 💖

PPINTR — okay bestie, this is the one from NCAR GRAPHICS (yes, the 3NCARG manual, we're fancy) that generates and returns a whole set of trapezoids representing the interior of the "intersection" polygon. And what's the intersection polygon, you ask? It's literally every single point that is inside both the clip polygon and the subject polygon. Overlap city. The overlap is the moment. 👑

---

🦋 SYNOPSIS 🦋

CALL PPINTR (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPT,IERR)

✨ C-BINDING SYNOPSIS ✨

#include <ncarg/ncargC.h>

void c_ppintr(
     float *xccp,
     float *yccp,
     int nccp,
     float *xcsp,
     float *ycsp,
     int ncsp,
     float *rwrk,
     int *iwrk,
     int nwrk,
     int (*urpt_)(float *xcbl,
                  float *xcbr,
                  float *ycob,
                  float *dxle,
                  float *dxre,
                  float *ycot),
     int *ierr)

---

🌸 DESCRIPTION 🌸

Sit down, hydrate, we're going through every single argument. No skipping. Not even the workspace ones. 💅

• XCCP — (an input array of type REAL) the X coordinate array for the clip polygon. It's giving scissors. ✂️
• YCCP — (an input array of type REAL) the Y coordinate array for the clip polygon. Bestie pairing with the one above.
• NCCP — (an input expression of type INTEGER) how many points define the clip polygon.
• XCSP — (an input array of type REAL) the X coordinate array for the subject polygon.
• YCSP — (an input array of type REAL) the Y coordinate array for the subject polygon.
• NCSP — (an input expression of type INTEGER) how many points define the subject polygon.
• RWRK — (a scratch array, dimensioned NWRK, of type REAL) a real workspace array. And here's the tea: because of the way in which they are used, RWRK and IWRK may be EQUIVALENCEd — and, to save space, they should be. 👯‍♀️
• IWRK — (a scratch array, dimensioned NWRK, of type INTEGER) an integer workspace array. Same deal: because of the way in which they are used, RWRK and IWRK may be EQUIVALENCEd — and, to save space, they should be. Yes I'm repeating myself, it's important. 🙈
• NWRK — (an input expression of type INTEGER) the length of the workspace array(s). Now, the routines that produce trapezoids use a lot less workspace than the ones that produce polygons. The amount of space used at a particular time during the execution of one of these routines is roughly ten or eleven times the number of intersections of a horizontal "scan line" with the edge segments making up the input polygons, plus about three times the number of points above the current scan line that are "local minima". And what is a "local minimum"? It's a point on one of the polygons that is connected to two other points on the polygon having larger Y coordinates than its own. So the author has not yet developed a rule of thumb for setting the value of NWRK. Ultimately, they would like to at least put in an internal parameter that will tell one how much space was actually used on a given call, but they have not yet done so. 🫠 (relatable, we've all got a to-do list)
• URPT — the name of a user-provided routine to process the trapezoids. This name must appear in an EXTERNAL statement in the routine that calls PPINTR, and the routine itself must have the following form:

     SUBROUTINE URPP (XCBL,XCBR,YCOB,DXLE,DXRE,YCOT)
       ...(code to process a trapezoid)...
       RETURN
     END

The bottom and top of the trapezoid are horizontal (parallel to the X axis); the arguments XCBL and XCBR define the X coordinates of its bottom left and bottom right corners, YCOB is the Y coordinate of its bottom edge, DXLE and DXRE are the inverses (dx/dy) of the slopes of its left and right edges, and YCOT is the Y coordinate of its top edge. So the corners of the trapezoid are therefore as follows: (XCBL,YCOB), (XCBR,YCOB), (XCBL+DXLE*(YCOT-YCOB),YCOT), and (XCBR+DXRE*(YCOT-YCOB),YCOT). Four corners, all accounted for, geometry slay. 📐

• IERR — (an output variable of type INTEGER) comes back with the value zero if no errors occurred in the execution of PPINTR, or with a small positive value if an error did occur. Let's decode the drama:
  • value 1 → a degenerate clip polygon was detected
  • value 2 → a degenerate subject polygon was detected
  • value 3 → the workspace provided was too small
  • values greater than 3 → should be reported to the author, since they probably indicate some problem with the algorithm. 👀

⚠️ Okay important caveat, listen up: if IERR is returned non-zero, one can be sure that there have been no calls to URPT only if IERR = 1 or 2; otherwise, some trapezoids probably have been generated and delivered to URPT. So don't assume nothing happened. 🙅‍♀️

---

🎀 C-BINDING DESCRIPTION 🎀

The C-binding argument descriptions are the same as the FORTRAN argument descriptions. Copy-paste energy, but make it official. ✨

---

💜 USAGE 💜

The FORTRAN statement

CALL PPINTR (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPT,IERR)

causes the formation of an intersection polygon (of the subject and clip clip polygons — yes, the original says it like that, and we respect the original 💖) and the delivery of trapezoids representing the interior of that polygon, one at a time, to the user-specified trapezoid-processing routine URPT. One. At. A. Time. The suspense. The pacing. The main character energy. 🌈

---

🌟 EXAMPLES 🌟

Use the ncargex command to see the following relevant examples: ppex01, tppack, c_ppex01. Go look, bestie, it's free education. 🍓

---

👑 ACCESS 👑

To use PPINTR or c_ppintr, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order. Order matters, iykyk. 💅

---

🧚 SEE ALSO 🧚

• Online: polypack, ppdipo, ppditr, ppinpo, ppplcl, ppppap, ppunpo, ppuntr, ncarg_cbind.
• Hardcopy: None. (the hardcopy said nothing, iconic of it)

---

💖 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, you made it, I'm so proud of you 🥹✨ This was the UNIX version of PPINTR(3NCARG), dated March 1995 — go forth and intersect your polygons, bestie, mwah 💋