1CPCLDM(3NCARG) NCAR GRAPHICS CPCLDM(3NCARG)
2
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
13 CALL CPCLDM (ZDAT, RWRK, IWRK, IAMA, RTPL)
14
16 #include <ncarg/ncargC.h>
17 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
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 ZDAT (REAL array, dimensioned as specified in the last call to
28 CPRECT, CPSPS1, or CPSPS2, input) is the data array.
29 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 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 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 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 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 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 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 EXTERNAL CPDRPL
85 and then use CPDRPL for the last argument.
87
89 The C-binding argument descriptions are the same as the FORTRAN
90 argument descriptions.
91
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 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 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 Groups of lines are generated in the following order:
121 · contour lines for each of the specified levels, in ascending numeric
123 order,
124 · the edges of special-value areas, if any,
126 · the edges of out-of-range areas, if any, and
128 · the edge of the grid.
130 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 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 Value Description
146 < 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 > 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 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 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
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
173 To use CPCLDM or c_cpcldm, load the NCAR Graphics libraries ncarg,
174 ncarg_gks, and ncarg_c, preferably in that order.
175
177 See the conpack man page for a description of all Conpack error
178 messages and/or informational messages.
179
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 Hardcopy: NCAR Graphics Contouring and Mapping Tutorial
187
189 Copyright (C) 1987-2007
190 University Corporation for Atmospheric Research
191 This documentation is free software; you can redistribute it and/or
193 modify it under the terms of the GNU General Public License as
194 published by the Free Software Foundation; either version 2 of the
195 License, or (at your option) any later version.
196 This software is distributed in the hope that it will be useful, but
198 WITHOUT ANY WARRANTY; without even the implied warranty of
199 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
200 General Public License for more details.
201 You should have received a copy of the GNU General Public License along
203 with this software; if not, write to the Free Software Foundation,
204 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
205UNIX March 1993 CPCLDM(3NCARG)