1CPCLDM(3NCARG)                   NCAR GRAPHICS                  CPCLDM(3NCARG)
2
3
4

NAME

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

SYNOPSIS

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

C-BINDING SYNOPSIS

16       #include <ncarg/ncargC.h>
17
18       void c_cpcldm (float *zdat, float *rwrk, int *iwrk,
19       int *iama, int (*rtpl)(float *xcs, float *ycs, int *ncs,
20       int *iai, int *iag, int *nai))
21

DESCRIPTION

23       The first three arguments are arrays used in the last call to CPRECT,
24       CPSPS1, or CPSPS2, the contents of which must not have been changed
25       since that call.
26
27       ZDAT        (REAL array, dimensioned as specified in the last call to
28                   CPRECT, CPSPS1, or CPSPS2, input) is the data array.
29
30       RWRK        (REAL array, dimensioned as specified in the last call to
31                   CPRECT, CPSPS1, or CPSPS2, input/output) is the real
32                   workspace array.
33
34       IWRK        (INTEGER array, dimensioned as specified in the last call
35                   to CPRECT, CPSPS1, or CPSPS2, input/output) is the integer
36                   workspace array.
37
38       IAMA        (INTEGER array, dimensioned as specified in a call to
39                   ARINAM, in the package Areas, input/output) is the array
40                   containing the area map which is to be used to mask the
41                   contour lines as they are drawn.
42
43       RTPL        (EXTERNAL subroutine) is the user subroutine which is to
44                   process the polylines which result from masking the
45                   generated contour lines and other edges against the area
46                   map. It must be declared EXTERNAL in the routine which
47                   calls CPCLDM. It will be called repeatedly and must have
48                   the following form:
49
50                        SUBROUTINE RTPL (XCS,YCS,NCS,IAI,IAG,NAI)
51                          DIMENSION XCS(*),YCS(*),IAI(*),IAG(*)
52                          ...
53                          (CODE TO PROCESS POLYLINE DEFINED BY ARGUMENTS)
54                          ...
55                          RETURN
56                        END
57
58                   The real arrays XCS and YCS hold the X and Y coordinates of
59                   NCS points defining a polyline which is to be considered
60                   for drawing. For each I greater than or equal to 1 and less
61                   than or equal to NAI, IAI(I) is the area identifier for the
62                   area in which the polyline lies, relative to the area-
63                   identifier group IAG(I). The X and Y coordinates are all
64                   normalized device coordinates and it may be assumed that
65                   the appropriate SET call has been done. If it is decided to
66                   draw the line, it may be done with a call to the SPPS
67                   routine CURVE, to the Dashline routine CURVED, or to the
68                   GKS routine GPL. The value of 'PAI' will have been set to
69                   the appropriate value (1 through 'NCL', -1, -2, or -3) for
70                   the line of which the polyline is a part. The color and
71                   line width will have been set as implied by the values of
72                   the appropriate elements of the parameter arrays 'CLC' and
73                   'CLL'. The dash pattern will have been defined as implied
74                   by the value of the appropriate elements of the parameter
75                   arrays 'CLD' and 'CLU' and the value of the parameter
76                   'DPU'. If a dash pattern is defined, it may be retrieved by
77                   a "CALL CPGETC ('CTM',CVAL)".
78
79                   If the only object of using CPCLDM is to avoid drawing
80                   contour lines through label boxes, then the Conpack routine
81                   CPDRPL may be used for RTPL. In the routine that calls
82                   CPCLDM, insert the declaration
83
84                        EXTERNAL CPDRPL
85
86                   and then use CPDRPL for the last argument.
87

C-BINDING DESCRIPTION

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

USAGE

93       The routine CPCLDM may be called at any time after the initialization
94       call to CPRECT, CPSPS1, or CPSPS2 to draw contour lines masked by an
95       existing area map.  Actually, CPCLDM does not draw the lines; it
96       generates them, masks them against a user-specified area map, and
97       generates calls, one for each polyline resulting from the masking
98       process, to the user specified routine RTPL.  Each such polyline lies
99       entirely within precisely one of the areas defined by the area map.
100       The routine RTPL may use the information provided by its arguments,
101       describing the area the polyline is in, to decide whether or not to
102       draw the polyline.
103
104       The contour lines generated are those specified by the first 'NCL'
105       elements of the parameter arrays 'CLV' and 'CLU'.  If 'NCL' is zero,
106       CPPKCL is called to generate these values.  Each element of 'CLV'
107       specifies a contour level and the corresponding element of 'CLU'
108       specifies whether or not contour lines are to be generated at that
109       level.  If the parameter 'T2D' has a non-zero value, the contour lines
110       are smoothed, using cubic splines under tension.
111
112       If the element of the parameter array 'CLU' corresponding to 'PAI' = -1
113       is non-zero, the edge of the grid is also generated.  If the element of
114       'CLU' corresponding to 'PAI' = -2 is non-zero, the edges of special-
115       value areas, if any, are generated.  If the element of 'CLU'
116       corresponding to 'PAI' = -3 is non-zero, the edges of out-of-range
117       areas, if any, are generated.  The default values are such that none of
118       these edges is generated.
119
120       Groups of lines are generated in the following order:
121
122       ·  contour lines for each of the specified levels, in ascending numeric
123          order,
124
125       ·  the edges of special-value areas, if any,
126
127       ·  the edges of out-of-range areas, if any, and
128
129       ·  the edge of the grid.
130
131       The color, dash pattern, and line width to be used for the lines drawn
132       may be specified by elements of the parameter arrays 'CLC', 'CLD', and
133       'CLL', respectively.  Each of these contains elements corresponding to
134       values of 'PAI' from 1 to 'NCL' and three special elements,
135       corresponding to 'PAI' = -1, -2, and -3.   Before and after each group
136       of lines is generated, the routine CPCHCL is called; a user-supplied
137       version of this routine may override the settings of color, dash
138       pattern, and line width.  Also, of course, the routine RTPL, which
139       actually does the drawing, may override the settings of these
140       quantities.
141
142       You can use the dash-pattern-usage parameter ('DPU') to affect the
143       pattern used to draw the lines.  Set the value of 'DPU' as follows:
144
145       Value       Description
146
147       < 0 or = 0  Lines are drawn by calling the SPPS routine CURVE.  Lines
148                   are all solid and unlabeled; specified dash patterns are
149                   not used.
150
151       > 0         Lines are drawn by calling the Dashline routine CURVED.
152                   Lines are solid or dashed, depending on the dash pattern
153                   specified by the appropriate element of 'CLD'.
154
155                   If ABS('LLP') = 1, then the dash pattern for those lines
156                   that are to be labeled is constructed by replicating, 'DPU'
157                   times, the dash pattern specified by the appropriate
158                   element of 'CLD', and then appending to it the characters
159                   specified by the appropriate element of 'LLT'.
160
161       If, during the last call to CPRECT, CPSPS1, or CPSPS2, the data being
162       contoured were found to be essentially constant, then no contour lines
163       are generated; instead, the constant-field label is written.  Other
164       lines are still generated.
165

EXAMPLES

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

ACCESS

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

MESSAGES

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

SEE ALSO

181       Online: conpack, cpback, cpchcf, cpchcl, cpchhl, cpchil, cpchll,
182       cpcica, cpclam, cpcldr, cpcltr, cpcnrc, cpdrpl, cpezct, cpgetc, cpgeti,
183       cpgetr, cplbam, cplbdr, cpmpxy, cpmviw, cpmvrw, cppkcl, cppklb, cprect,
184       cprset, cpscae, cpsetc, cpseti, cpsetr, cpsps1, cpsps2, ncarg_cbind
185
186       Hardcopy: NCAR Graphics Contouring and Mapping Tutorial
187
189       Copyright (C) 1987-2009
190       University Corporation for Atmospheric Research
191
192       The use of this Software is governed by a License Agreement.
193
194
195
196UNIX                              March 1993                    CPCLDM(3NCARG)
Impressum