Ubuntu Manpage: CPCLDM - Draws contour lines masked by an existing area map. The object of this may be simply to avoid

Provided by: libncarg-dev_6.6.2.dfsg.1-10build2_amd64

NAME

       CPCLDM - Draws contour lines masked by an existing area map. The object of this may be simply to avoid
       drawing contour lines through label boxes, but the routine may be used for more complicated tasks, like
       limiting the drawing of contour lines to the ocean areas on an Ezmap background.

SYNOPSIS

       CALL CPCLDM (ZDAT, RWRK, IWRK, IAMA, RTPL)

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_cpcldm (float *zdat, float *rwrk, int *iwrk,
       int *iama, int (*rtpl)(float *xcs, float *ycs, int *ncs,
       int *iai, int *iag, int *nai))

DESCRIPTION

The first three arguments are arrays used in the last call to CPRECT, CPSPS1, or CPSPS2, the contents of
which must not have been changed since that call.

ZDAT (REAL array, dimensioned as specified in the last call to CPRECT, CPSPS1, or CPSPS2, input)
is the data array.

RWRK (REAL array, dimensioned as specified in the last call to CPRECT, CPSPS1, or CPSPS2,
input/output) is the real workspace array.

IWRK (INTEGER array, dimensioned as specified in the last call to CPRECT, CPSPS1, or CPSPS2,
input/output) is the integer workspace array.

IAMA (INTEGER array, dimensioned as specified in a call to ARINAM, in the package Areas,
input/output) is the array containing the area map which is to be used to mask the contour
lines as they are drawn.

RTPL (EXTERNAL subroutine) is the user subroutine which is to process the polylines which result
from masking the generated contour lines and other edges against the area map. It must be
declared EXTERNAL in the routine which calls CPCLDM. It will be called repeatedly and must
have the following form:

SUBROUTINE RTPL (XCS,YCS,NCS,IAI,IAG,NAI)
DIMENSION XCS(*),YCS(*),IAI(*),IAG(*)
...
(CODE TO PROCESS POLYLINE DEFINED BY ARGUMENTS)
...
RETURN
END

The real arrays XCS and YCS hold the X and Y coordinates of NCS points defining a polyline
which is to be considered for drawing. For each I greater than or equal to 1 and less than or
equal to NAI, IAI(I) is the area identifier for the area in which the polyline lies, relative
to the area-identifier group IAG(I). The X and Y coordinates are all normalized device
coordinates and it may be assumed that the appropriate SET call has been done. If it is
decided to draw the line, it may be done with a call to the SPPS routine CURVE, to the
Dashline routine CURVED, or to the GKS routine GPL. The value of 'PAI' will have been set to
the appropriate value (1 through 'NCL', -1, -2, or -3) for the line of which the polyline is
a part. The color and line width will have been set as implied by the values of the
appropriate elements of the parameter arrays 'CLC' and 'CLL'. The dash pattern will have been
defined as implied by the value of the appropriate elements of the parameter arrays 'CLD' and
'CLU' and the value of the parameter 'DPU'. If a dash pattern is defined, it may be retrieved
by a "CALL CPGETC ('CTM',CVAL)".

If the only object of using CPCLDM is to avoid drawing contour lines through label boxes,
then the Conpack routine CPDRPL may be used for RTPL. In the routine that calls CPCLDM,
insert the declaration

EXTERNAL CPDRPL

and then use CPDRPL for the last argument.

C-BINDING DESCRIPTION

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

USAGE

The routine CPCLDM may be called at any time after the initialization call to CPRECT, CPSPS1, or CPSPS2
to draw contour lines masked by an existing area map. Actually, CPCLDM does not draw the lines; it
generates them, masks them against a user-specified area map, and generates calls, one for each polyline
resulting from the masking process, to the user specified routine RTPL. Each such polyline lies entirely
within precisely one of the areas defined by the area map. The routine RTPL may use the information
provided by its arguments, describing the area the polyline is in, to decide whether or not to draw the
polyline.

The contour lines generated are those specified by the first 'NCL' elements of the parameter arrays 'CLV'
and 'CLU'. If 'NCL' is zero, CPPKCL is called to generate these values. Each element of 'CLV' specifies
a contour level and the corresponding element of 'CLU' specifies whether or not contour lines are to be
generated at that level. If the parameter 'T2D' has a non-zero value, the contour lines are smoothed,
using cubic splines under tension.

If the element of the parameter array 'CLU' corresponding to 'PAI' = -1 is non-zero, the edge of the grid
is also generated. If the element of 'CLU' corresponding to 'PAI' = -2 is non-zero, the edges of
special-value areas, if any, are generated. If the element of 'CLU' corresponding to 'PAI' = -3 is non-
zero, the edges of out-of-range areas, if any, are generated. The default values are such that none of
these edges is generated.

Groups of lines are generated in the following order:

• contour lines for each of the specified levels, in ascending numeric order,

• the edges of special-value areas, if any,

• the edges of out-of-range areas, if any, and

• the edge of the grid.

The color, dash pattern, and line width to be used for the lines drawn may be specified by elements of
the parameter arrays 'CLC', 'CLD', and 'CLL', respectively. Each of these contains elements
corresponding to values of 'PAI' from 1 to 'NCL' and three special elements, corresponding to 'PAI' = -1,
-2, and -3. Before and after each group of lines is generated, the routine CPCHCL is called; a user-
supplied version of this routine may override the settings of color, dash pattern, and line width. Also,
of course, the routine RTPL, which actually does the drawing, may override the settings of these
quantities.

You can use the dash-pattern-usage parameter ('DPU') to affect the pattern used to draw the lines. Set
the value of 'DPU' as follows:

Value Description

< 0 or = 0 Lines are drawn by calling the SPPS routine CURVE. Lines are all solid and unlabeled;
specified dash patterns are not used.

> 0 Lines are drawn by calling the Dashline routine CURVED. Lines are solid or dashed, depending
on the dash pattern specified by the appropriate element of 'CLD'.

If ABS('LLP') = 1, then the dash pattern for those lines that are to be labeled is
constructed by replicating, 'DPU' times, the dash pattern specified by the appropriate
element of 'CLD', and then appending to it the characters specified by the appropriate
element of 'LLT'.

If, during the last call to CPRECT, CPSPS1, or CPSPS2, the data being contoured were found to be
essentially constant, then no contour lines are generated; instead, the constant-field label is written.
Other lines are still generated.

EXAMPLES

       Use  the ncargex command to see the following relevant examples: ccpcldm, ccpllc, ccpllo, ccpllp, ccpllt,
       ccppc, ccppc1, ccppc2, ccppc3, ccppc4, ccppole, ccprc, ccpscam, colcon, cpex01, cpex02,  cpex03,  cpex04,
       cpex06, cpex08, cbex01, vvex01, fcover, ffex03, ffex05.

ACCESS

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

MESSAGES

       See the conpack man page for a description of all Conpack error messages and/or informational messages.

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research

       The use of this Software is governed by a License Agreement.

UNIX                                               March 1993                                     CPCLDM(3NCARG)