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

Provided by: libncarg-dev_6.6.2.dfsg.1-1_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.