Ubuntu Manpage: PPUNPO - generates and returns the boundary of the "union" polygon, which consists of all points that are

NAME

       PPUNPO - generates and returns the boundary of the "union" polygon, which consists of all points that are
       inside either or both of the clip polygon and the subject polygon.

SYNOPSIS

       CALL PPUNPO (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPP,IERR)

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_ppunpo(
            float *xccp,
            float *yccp,
            int nccp,
            float *xcsp,
            float *ycsp,
            int ncsp,
            float *rwrk,
            int *iwrk,
            int nwrk,
            int (*urpp_)( float *xcra, float *ycra, int *ncra),
            int *ierr)

DESCRIPTION

XCCP (an input array of type REAL) is the X coordinate array for the clip polygon.

YCCP (an input array of type REAL) is the Y coordinate array for the clip polygon.

NCCP (an input expression of type INTEGER) is the number of points defining the clip polygon.

XCSP (an input array of type REAL) is the X coordinate array for the subject polygon.

YCSP (an input array of type REAL) is the Y coordinate array for the subject polygon.

NCSP (an input expression of type INTEGER) is the number of points defining the subject polygon.

RWRK (a scratch array, dimensioned NWRK, of type REAL) is a real workspace array. 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) is an integer workspace array. Because
of the way in which they are used, RWRK and IWRK may be EQUIVALENCEd (and, to save space,
they should be).

NWRK (an input expression of type INTEGER) is the length of the workspace array(s). It is a bit
difficult to describe how much space might be required. At the moment, I would recommend
using NWRK equal to about ten times the total of the number of points in the input polygons
and the number of intersection points. This situation will change with time; at the very
least, I would like to put in an internal parameter that will tell one how much space was
actually used on a given call, but I have not yet done so.

URPP is the name of a user-provided routine to process the polygon-boundary pieces. This name
must appear in an EXTERNAL statement in the routine that calls PPUNPO and the routine itself
must have the following form:

SUBROUTINE URPP (XCRA,YCRA,NCRA)
DIMENSION XCRA(NCRA),YCRA(NCRA)
...(code to process a polygon boundary piece)...
RETURN
END

Each of the arguments XCRA and YCRA is a real array, dimensioned NCRA; the former holds the X
coordinates, and the latter the Y coordinates, of a piece of the polygon boundary. It will be
the case that XCRA(NCRA)=XCRA(1) and YCRA(NCRA)=YCRA(1).

IERR (an output variable of type INTEGER) is returned with the value zero if no errors occurred in
the execution of PPUNPO or with a small positive value if an error did occur. The value 1
indicates that a degenerate clip polygon was detected, the value 2 that a degenerate subject
polygon was detected, and the value 3 that the workspace provided was too small; values
greater than 3 should be reported to the author, as they indicate some problem with the
algorithm. Currently, if IERR is returned non-zero, one can be sure that no calls to URPP
were executed; in the future, this could change, but, in that case, there will be an internal
parameter allowing one to request the current behavior.

C-BINDING DESCRIPTION

       The C-binding argument descriptions are the same as the FORTRAN argument descriptions.

USAGE

       The FORTRAN statement

       CALL PPUNPO (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPP,IERR)

       causes the formation of a union polygon (of the subject and clip polygons) and the delivery of that
       polygon's boundary, piece by piece, to the user-specified polygon-processing routine URPP.

EXAMPLES

       Use the ncargex command to see the following relevant examples: ppex01, tppack, c_ppex01.

ACCESS

       To use PPUNPO or c_ppunpo, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c, preferably in
       that order.

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research
       The use of this Software is governed by a License Agreement.