This section is intended to give an overall view of CONPACK and selected aspects of its design; it covers some details, but, in general, one should refer to the sections "SUBROUTINES" and "PARAMETERS" for detailed descriptions of subroutines and parameters mentioned. (Parameters are mentioned by name; all the names are of the form 'XXX', where XXX is a three-character mnemonic.) The section "ERROR MESSAGES" describes error messages written by CONPACK. The section "EXAMPLES" describes the examples available for CONPACK.
It is assumed that the reader is familiar with NCAR Graphics in general and has some knowledge of the packages AREAS and EZMAP/EZMAPA.
After all required parameters have been set, the process of drawing a contour plot begins with a call to one of three initialization routines. Which one is called depends on the type of data to be contoured. The three possibilities so far are as follows:
Each of the routines CPRECT, CPSPS1, and CPSPS2 performs initialization required for subsequent calls to work properly. The dimensions of the data array and of real and integer workspace arrays are copied to internal variables. Pointers used to manage the real and integer workspaces are initialized. It is decided how the indices of the data array are to be mapped into X and Y coordinates used to define contour lines and how those X and Y coordinates are to be mapped to the plotter frame. If the user has not called the SPPS routine SET (or done the equivalent GKS calls), that call is done. The minimum and maximum values in the data array are found and it is decided whether or not the data field is essentially constant. If contour levels are to be chosen automatically, the parameter arrays specifying the contour levels are cleared, so that automatic selection will take place when these levels are required.
Among the internal parameters are arrays completely specifying contour levels of interest and what is to be done at each of those levels. These arrays may be used to take complete control of the contouring process; most users will probably elect not to do this, but to let CONPACK choose the levels. At this point, then, as a rule, none of these parameter arrays will have been filled. No calls need be done to fill them; if they are empty when they are needed, the required values will be chosen at that point. For certain applications, however, it is desirable to force the selection of contour levels and perhaps the character strings which are to be used as contour labels. This may be done by means of calls to one or both of the following routines:
At this point, various other routines may be called:
At any time, it is possible to retrieve the value of an internal parameter by calling one of the three following routines:
Two additional routines are provided for use in error-recovery situations:
If the intent is to draw the contour plot using relatively few computer resources, the following sequence of calls will suffice:
To produce a better-positioned set of labels, step 1 above should include a call to CPSETI setting the parameter 'LLP', which says how line labels are to be positioned, to one of the values 3 or -3; this turns off the generation of line labels by a dashed-line package called by CPCLDR and causes them to be positioned and written by the routine CPLBDR instead, using a penalty scheme which produces quite pleasing results. Contour lines will still pass through line labels positioned in this way.
Contour lines may be prevented from passing through labels drawn by CPLBDR in one of two ways, depending on the nature of the plotting device. If the device allows for the use of the GKS fill area primitive and if the result of drawing one object on top of another is that the pixels affected by drawing the second object simply change color (as happens on most terminals, but not usually on a device which exposes film, for example), then one may insert calls changing the values of the parameters 'ILB', 'HLB', and 'LLB' in such a way as to force boxes surrounding the informational label, the high and low labels, and the line labels to be filled with the background color prior to the drawing of the labels. This has the effect of preventing the contour lines from passing through the labels.
If filling the label boxes will not work, then a software technique, using routines in the utility AREAS, may be used instead. The sequence of calls will then be as follows:
The packages AREAS, CONPACK, and EZMAP/EZMAPA may be used cooperatively to achieve other desired effects. For example, if the contour plot being drawn represents output from an ocean model, it may be desirable to draw contours (or to fill contour bands) only over the oceans on a background drawn by EZMAP. See example 8 in the section "EXAMPLES".
As of release 3.1.3 of NCAR Graphics, a solid-filled contour plot may be drawn in another way, using the GKS primitive "cell array". The steps required are as follows:
Other values of 'CLS' may be used to change the way in which CONPACK chooses contour levels. See the detailed descriptions of 'CLS' and of the other parameters 'CIS', 'CIT', 'CIU', 'CMN', 'CMX', 'LIS', 'LIT', and 'LIU'.
The user may elect to set all of the contour levels and associated quantities. Suppose, for example, that it is desired to draw labelled solid lines for each of the values .1, .2, .3, ..., .9 and unlabelled dashed lines for each of the values .05, .15, .25, ... .95. The following code, inserted before the call to CPRECT, CPSPS1, or CPSPS2, will set the required parameters:
CALL CPSETI ('CLS - CONTOUR LEVEL SELECTION',0)
CALL CPSETI ('NCL - NUMBER OF CONTOUR LEVELS',19)
DO 101 I=1,19
CALL CPSETI ('PAI - PARAMETER ARRAY INDEX',I)
CALL CPSETR ('CLV - CONTOUR LEVEL VALUE',REAL(I)/20.)
IF (MOD(I,2).EQ.1) THEN
CALL CPSETI ('CLU - CONTOUR LEVEL USE',1)
CALL CPSETI ('CLD - CONTOUR LINE DASH PATTERN',21845)
ELSE
CALL CPSETI ('CLU - CONTOUR LEVEL USE',3)
CALL CPSETI ('CLD - CONTOUR LINE DASH PATTERN',65535)
END IF
101 CONTINUE
In the above code, 'CLS' is zeroed to suspend the selection of contour
levels by CONPACK itself. Then, 'NCL' is set to say how many contour
levels are to be defined. Then, in a loop on I from 1 to 19, 'PAI' is
set to tell CONPACK which element of each parameter array is to be set,
the Ith element of 'CLV' is set to REAL(I)/20., which, for each I, gives
one of the desired contour levels, the Ith element of 'CLU' is set to a
1 if just the line is to be drawn or to a 3 if both the line and the
labels for the line are to be drawn, and the Ith element of 'CLD' is set
to 21845 (octal 52525) if a dashed line is to be used or to 65535 (octal
177777) if a solid line is to be used. Note that 'NCL' must be set prior to setting any element of 'CLV' or the associated arrays.
Note also that, when an element of 'CLV' is set, all of the associated elements of the associated arrays receive a default value. (In fact,the default element of 'CLU' is 1, and the default element of 'CLD' is a pattern specifying a solid line, so two of the calls in the code above are redundant.)
Note also that the use of CPSETI to specify the value of 'CLD' will work only if 'DPU' is positive, implying the use of DASHCHAR routines; if 'DPU' is negative, DASHPACK routines will be used and, by default, they will expect underscores, rather than apostrophes, to represent gaps, so that CPSETC calls will be needed to define the dash patterns.
In some cases, the user will want to let CONPACK choose a set of contour levels and then either add other levels of interest, modify elements of the associated parameter arrays, or both. Suppose, for example, that it is desired to have CONPACK pick the levels, that contour lines at positive levels are to be drawn in red, that contour lines at negative levels are to be drawn in blue, and that contour lines at the zero level are to be drawn in white. The following code, inserted after the call to CPRECT, CPSPS1, or CPSPS2, would do the job:
... CALLS TO DEFINE COLOR INDICES IBLU, IRED, AND IWHI ...
CALL CPPKCL (...)
CALL CPGETI ('NCL - NUMBER OF CONTOUR LINES',NOCL)
DO 101 I=1,NOCL
CALL CPSETI ('PAI - PARAMETER ARRAY INDEX',I)
CALL CPGETR ('CLV - CONTOUR LEVEL VALUE',CLEV)
IF (CLEV.LT.0.) THEN
CALL CPSETI ('CLC - CONTOUR LINE COLOR INDEX',IBLU)
ELSE IF (CLEV.GT.0.) THEN
CALL CPSETI ('CLC - CONTOUR LINE COLOR INDEX',IRED)
ELSE
CALL CPSETI ('CLC - CONTOUR LINE COLOR INDEX',IWHI)
END IF
101 CONTINUE
In the code above, the routine CPPKCL is called to force CONPACK to pick
a set of contour levels. Then, the value of 'NCL' that it chose is
retrieved, and a loop is run from 1 to that value. On each pass through
the loop, the parameter array index 'PAI' is set to tell CONPACK what
element of the parameter arrays is being accessed and then one of the
contour levels chosen is retrieved to the variable CLEV. Depending on
the value of CLEV, the associated element of the parameter array which
specifies the color index of the contour lines at that level is set to
produce a blue line, a red line, or a white line.
By default, to describe contour lines and other objects on the contour plot, CONPACK generates X coordinates in the same range as the first subscript of the array of data being contoured and Y coordinates in the same range as the second subscript of that array. Thus, X coordinates range from 1. to REAL(M) and Y coordinates from 1. to REAL(N), where "M" and "N" are the dimensions of the data array. (The parameters 'ZDM' and 'ZDN' have the values "M" and "N", respectively, after the call to CPRECT, CPSPS1, or CPSPS2.) Thus, the lower left corner of the plot is at (1.,1.), the upper right corner of the plot is at (REAL(M),REAL(N)), and, assuming the array to be indexed by (I,J), the center of the grid box bounded by I = 3, I = 4, J = 6, and J = 7 is (3.5,6.5).
The parameters 'XC1', 'XCM', 'YC1', and 'YCN' may be used to cause X and Y coordinates to be generated in arbitrary user ranges. For example, one could set 'XC1' = -2, 'XCM' = 2, 'YC1' = -1, and 'YCN' = 1 to generate X coordinates between -2 (at I = 1) and 2 (at I = M), and Y coordinates between -1 (at J = 1) and 1 (at J = N). Similarly, one could set 'XC1' = LON1, 'XCM' = LON2, 'YC1' = LAT1, and 'YCN' = LAT2 to generate X coordinates between longitudes LON1 and LON2 and Y coordinates between latitudes LAT1 and LAT2.
If the parameter 'MAP' is given a non-zero value, each pair of X and Y coordinates is mapped, prior to use, by a statement of the form
CALL CPMPXY (IMAP,XINP,YINP,XOTP,YOTP)
IMAP is the non-zero value of 'MAP', XINP and YINP are the unmapped (input)
coordinates and XOTP and YOTP are the mapped (output) coordinates.The default version of CPMPXY does the following mappings:
XOTP=XINP*COS(.017453292519943*YINP)
YOTP=XINP*SIN(.017453292519943*YINP)
Similarly, if the data array being contoured is such that rho is a linear function of its first subscript and theta a linear function of its second subscript, then to map CONPACK output onto a polar coordinate background (which one would have to draw for oneself), one need only set 'MAP' to 2, set 'XC1' and 'XCM' to the values of rho at I = 1 and I = M, set 'YC1' and 'YCN' to the values of theta at J = 1 and J = M, and, again, arrange for the proper SET call to be done.
The subroutine CPMPXY may be replaced by a version which does other desired mappings. If the CONPACK routines are loaded from a binary library, this can usually be done by just compiling one's own version of the routine, so that it replaces the one from the library.
A call to the SPPS routine SET has the form
CALL SET (XVPL,XVPR,YVPB,YVPT,XWDL,XWDR,YWDB,YWDT,LNLG)
All arguments are REALs except for LNLG, which is an INTEGER. The first
four arguments must all be between 0 and 1, inclusive; they define a
rectangular area on the plotter frame known as the "viewport". The next
four arguments define a rectangular area in "user" coordinate space known
as the "window". The final argument indicates whether the mapping of user
coordinates into the viewport is to be linear or logarithmic in X and Y.
See the documentation of the package SPPS for further details.By default, CONPACK (specifically, one of the routines CPRECT, CPSPS1, or CPSPS2) calls SET. One may, by setting the parameter 'SET' to zero, prevent CONPACK from doing this; in that case, one must do the call for oneself or depend on some other utility (such as EZMAP) to have done it.
If CONPACK calls SET, it always uses LNLG = 1, requesting a linear-linear mapping from the window to the viewport, and it positions the viewport and window as follows: The viewport is positioned as specified by the current values of the parameters 'VPL', 'VPR', 'VPB', 'VPT', and 'VPS'. The first four of these specify the position of a "viewport area", in which the viewport is to be centered and made as large as possible; the final one says how the shape of the viewport is to be chosen. By default, the window is defined by the values XAT1, XATM, YAT1, and YATN, where XAT1 is the X coordinate corresponding to I = 1, XATM is the X coordinate corresponding to I = M, YAT1 is the Y coordinate corresponding to J = 1, and YATN is the Y coordinate corresponding to J = N. The parameters 'WDL', 'WDR', 'WDB', and 'WDT' may be used to override this default behavior and specify the exact values to be used in the SET call to define the window. This is principally useful when the parameter 'MAP' is given a non-zero value to specify that X and Y coordinates are to be mapped by calling the subroutine CPMPXY.
When the default version of CPMPXY is used and 'MAP' is set to 1, one should just set 'SET' to zero; the proper call to SET will have been done already by EZMAP.
When the default version of CPMPXY is used and 'MAP' is set to 2, one may either set 'SET' to zero and do an appropriate call to SET or leave 'SET' non-zero and set the parameters 'WDL', 'WDR', 'WDB', and 'WDT' appropriately.
Note that, as long as the parameter 'MAP' is zero, a SET call done by CONPACK will define the window in such a way as to be consistent with the ranges of the X and Y coordinates it generates. If 'MAP' is set non-zero, then 'XC1', 'XCM', 'YC1', and 'YCN' will probably have to be set to cause the unmapped X and Y coordinates to be generated in the ranges expected by CPMPXY. The call to SET must specify window limits commensurate with the mapped X and Y coordinates; if CONPACK is to do the call, then 'WDL', 'WDR', 'WDB', and 'WDT' will probably have to be set to accomplish this.
The union of all grid boxes having a special value at one or more of the four corners constitutes a set of special-value areas. The routine CPCLAM will add the edges of such areas to the area map. The routines CPCLDM and CPCLDR may be made to draw the edges of such areas (by giving a non-zero value to element "-2" of the parameter array 'CLU').
A possible value for 'ORV', if it is to be set non-zero, is 1.E12, which has historically been returned by the EZMAP routine MAPTRN (and, now, MAPTRA) to indicate a point which is outside the area depicted by a given map projection.
The union of all points for which CPMPXY returns the out-of-range value constitutes a set of out-of-range areas. Contour lines are not traced in out-of-range areas (indeed, they cannot be). A binary-halving technique is used to extend contour lines to the very edge of such areas. The routine CPCLAM will attempt to generate and add to the area map a set of edges for such areas, and the routines CPCLDM and CPCLDR may be made to attempt to draw the edges of such areas (by giving a non-zero value to element "-3" of the parameter array 'CLU'). Currently, the edges can only be traced successfully if they are defined by continuous curves having continuous first derivatives and no points of inflection or (as of version 3.1.3) if the version of CPMPXY in use is capable of doing the inverse transformations (as is true of the default version of CPMPXY).
When contour lines are traced, if two consecutive points are out of range (in range), then the entire line segment connecting those two points is assumed to be out of range (in range). If the detail of the out-of-range areas is small enough, this assumption may cause errors. Giving the parameter 'PIC' a non-zero value will cause more points to be examined along each such line segment, thus curing the problem. For similar reasons, the algorithms used to trace the edge of the grid, the edges of special-value areas, and the edges of out-of-range areas may fail. Giving the parameter 'PIE' a non-zero value will cause these algorithms to use a finer grid, thus, again, curing the problem.
Note that, since each contour line is smoothed separately, there is no way to absolutely ensure that it will not cause adjacent contour lines to cross each other; one must experiment with the tension to reduce the probability of that to a minimum. A reasonable value to start with is 2.5.
If 'T2D' is negative, smoothing is done prior to the coordinate mapping, if any, implied by the setting of the parameter 'MAP'. If 'T2D' is positive, smoothing is done after the mapping.
The parameter 'PIC' says how many points are to be interpolated between each pair of points defining the contour line, before smoothing. If 'PIC' is given a non-zero value when the 2D smoother is turned on, the effect is to constrain the smoothed curves to more closely approximate the original polygonal lines.
The parameter 'SSL' specifies the distance between points used to draw the smoothed contour lines. It is expressed as a fraction of the width of the window in the coordinate system in which the smoothing is being done.
The data in the dense array returned by CPSPS1 or CPSPS2 may have a larger range than the original data in the sparse array (the lows may be lower and the highs higher). If the data represent a physical quantity whose value must fall inside a fixed range, the use of CPSPS1 or CPSPS2 may be inappropriate. In this case, the user should either do his/her own interpolation to a dense grid or take action to modify the contents of the dense array before continuing to draw the contour plot. If the latter is done, CPRECT must be the first routine called after the array is modified.
As of version 4 of NCAR Graphics, one can tell CONPACK to use routines from a new dash package, called DASHPACK, which is intended to replace all of the older packages. One does this by giving the internal parameter 'DPU' a negative value in place of the default positive value. The new dash package offers many advantages over the older ones; for a full description of it, see the programmer document called "DASHPACK, A SOFTWARE PACKAGE FOR DRAWING DASHED LINES".
When DASHPACK is used, the following considerations apply:
Note: When hachuring is activated, it may be necessary to increase the value of the internal parameter named 'RWC'. See the descriptions of the parameters 'HCF' and 'RWC' for more information.
When a constant field was detected by the initial call to CPRECT, CPSPS1, or CPSPS2, a fourth type of label may be written by CONPACK routines. In this case, a call to CPLBDR will write a constant-field label, warning of the situation, in place of the labels it would normally write. A call to CPLBAM will add the label box for the constant-field label to the area map, instead of the label boxes for the other labels. Calls to CPCLDR and CPCLDM which would normally draw contour lines will write the constant-field label instead.
The appearance of all of these labels may be determined in detail by setting parameters:
All labels are written by means of calls to the character-plotting routine PLCHHQ, in the package PLOTCHAR. The angle, in degrees, at which a label is written is determined by the value of the parameter 'xxA' (and, if it is a contour-line label, by the value of the parameter 'LLO'). The box flag 'xxB' determines whether or not, prior to writing the label, a box surrounding it is filled, and whether or not, after writing the label, the edge of the box is drawn. If the box is filled, it is done using the color index specified by the parameter 'LBC'; if the edge of the box is drawn, it is done using the color index, if any, chosen for the label itself, which is determined by the value of the parameter 'xxC'. The line width to be used in drawing the box is determined by the value of the parameter 'xxL'. The size (width) of the characters is determined by the value of the parameter 'xxS'. The text of the label is determined by the value of the parameter 'xxT'; usually, this string may contain embedded substrings of the form '$xxx$', which are to be replaced by the value of the quantity specified by the three-character mnemonic 'xxx'. The width of the "white space" to be left around the label (which defines the dimensions of the box around it) is determined by the value of the parameter 'xxW'.
A point P on a contour line will be rejected as the center point of a label under any of the following conditions:
PFUN = PW1 * GRAD / (GRAV+PC1*GRSD) GRADIENT TERM
+ PW2 * ENCB / PC2 NUMBER-OF-CONTOURS TERM
+ PW3 * CDIR / PC3 CHANGE-IN-DIRECTION TERM
+ PW4 * MIN (1-EXP(-((D(I)-PC4)/PC5)**2)) OPTIMUM-DISTANCE TERM
The first term of the penalty function becomes larger in high-gradient
regions. GRAD is the estimated gradient at the point P, GRAV is the
average gradient over the whole field being contoured, and GRSD is the
standard deviation of the estimated gradients over the whole field. The
parameter 'PC1' specifies how far from the norm gradients are allowed
to wander, as a multiple of the standard deviation. Condition 5 above
implies that, for points at which the penalty function is computed,
either 'PW1' is zero or GRAD is less than or equal to GRAV+PC1*GRSD.The second term of the penalty function becomes larger as ENCB, the estimated number of contour bands crossing a label at the point P, increases. The parameter 'PC2' specifies the largest number of crossing bands allowed. Condition 6 above implies that, for points at which the penalty function is computed, either 'PW2' is zero or ENCB is less than or equal to 'PC2'.
The third term of the penalty function becomes larger as CDIR, the cumulative change in direction of the contour line in a circular region centered at the point P and with a radius equal to half the larger dimension of the label, increases. The parameter 'PC3' specifies the largest such cumulative change allowed, in degrees. Condition 7 above implies that, for points at which the penalty function is computed, either 'PW3' is zero or CDIR is less than or equal to 'PC3'.
The fourth term of the penalty function becomes larger as the distance of the point P from the centers of all labels previously placed on other contour lines deviates from an optimum value specified by the user. D(I) represents the distance to the Ith such label center. The minimum is taken over all values of I. The parameter 'PC4' is the user-specified optimum distance, specified as a fraction of the width of the current viewport. If the point P is exactly 'PC4' units away from some previous label, then "MIN(1-EXP(...))" will have the value 0; otherwise, it will be non-zero. The parameter 'PC5' is the "folding distance", specified as a fraction of the width of the current viewport; as its value decreases, the function "1-EXP(...)" develops a sharper spike at D(I) = 'PC4'.
Thumbnail descriptions and default values of all the user-settable parameters are given below:
'PC1'=1. MULTIPLIER OF THE STANDARD DEVIATION OF THE GRADIENTS
'PC2'=5. MAXIMUM NUMBER OF CROSSING CONTOUR BANDS
'PC3'=60. MAXIMUM CUMULATIVE CHANGE IN DIRECTION OF THE CONTOUR LINE
'PC4'=.05 OPTIMUM DISTANCE, AS A FRACTION OF THE WIDTH OF THE VIEWPORT
'PC5'=.15 FOLDING DISTANCE, AS A FRACTION OF THE WIDTH OF THE VIEWPORT
'PC6'=.30 MINIMUM DISTANCE BETWEEN LABELS ON THE SAME CONTOUR LINE, AS
A FRACTION OF THE WIDTH OF THE VIEWPORT
'PW1'=2. WEIGHT OF THE GRADIENT TERM
'PW2'=0. WEIGHT OF THE NUMBER-OF-CONTOURS TERM
'PW3'=1. WEIGHT OF THE CHANGE-IN-DIRECTION TERM
'PW4'=1. WEIGHT OF THE OPTIMUM-DISTANCE TERM
Seven CONPACK parameters have to do with the generation of pleasing numeric labels: 'NEL', 'NET', 'NEU', 'NLS', 'NLZ', 'NOF', and 'NSD'. These are described in detail in the section "PARAMETERS".
The interaction between the parameters 'NLS' and 'NSD' can be confusing. I was asked the following question:
PROGRAM TESTIT
DIMENSION ZDAT(101,101),RWRK(10000),IWRK(10000)
CALL OPNGKS
CALL GSCLIP (0)
CALL CPSETI ('DPU - DASH PATTERN USE FLAG',1)
CALL CPSETI ('CLS - CONTOUR LEVEL SELECTION FLAG',100)
CALL CPSETI ('CIS - CONTOUR INTERVAL SPECIFIER',1)
CALL CPSETI ('LIS - LABEL INTERVAL SPECIFIER',1)
CALL CPSETI ('CMN - CONTOUR LEVEL MINIMUM',1)
CALL CPSETI ('CMX - CONTOUR LEVEL MAXIMUM',100)
C------>CALL CPSETI ('NLS - NUMERIC LEFTMOST SIGNIFICANT DIGIT',0)
CALL CPSETI ('NSD - NUMBER OF SIGNIFICANT DIGITS',-2)
C------>CALL CPSETI ('NSD - NUMBER OF SIGNIFICANT DIGITS',-6)
DO 102 I=1,101
DO 101 J=1,101
ZDAT(I,J)=(REAL(I)+REAL(J))/2.-.5
101 CONTINUE
102 CONTINUE
CALL CPRECT (ZDAT,101,101,101,RWRK,10000,IWRK,10000)
CALL CPCLDR (ZDAT,RWRK,IWRK)
CALL CPLBDR (ZDAT,RWRK,IWRK)
CALL FRAME
CALL CLSGKS
STOP
END
The parameter 'SFS' says how the scale factor is to be chosen. If it is given a value greater than zero, that value is the desired scale factor. If 'SFS' is given a value less than or equal to zero, CONPACK is directed to choose a scale factor to use, in one of five different ways. The value of the parameter 'SFU' may be retrieved by the user; it specifies the scale factor which has been selected for use.
The value of the scale factor may be displayed as a part of the informational label. This is done by embedding the substring '$SFU$' in the string which gives the value of the parameter 'ILT'.
The default value of 'SFS' is 1, which essentially specifies that no scale factor is to be used.
When 'CFF' is non-zero, a call to one of the routines CPCLDM or CPCLDR will not cause any contour lines to be drawn; instead, the constant-field label will be written. The edge of the grid, the edges of special-value areas, and the edges of out-of-range areas may still be drawn.
Similarly, when 'CFF' is non-zero, a call to the routine CPLBDR will write the constant-field label instead of the labels which would normally be written, and a call to the routine CPLBAM will put the label box for the constant-field label into the area map instead of the label boxes for the normal set of labels.
The workspace management scheme used in CONPACK is as follows: The user defines one workspace array of type REAL and another of type INTEGER. In the call to CPRECT, CPSPS1, or CPSPS2, which initializes the drawing of a contour plot, these arrays appear as arguments (called RWRK and IWRK), together with arguments specifying their lengths (LRWK and LIWK). In subsequent calls to other CONPACK routines which require workspaces, the same arrays appear as arguments, but the lengths do not. The CONPACK routines cooperate in using these arrays in such a way as not to interfere with one another. Dynamic enlargement of one workspace at the expense of another becomes possible and the probability of running out of space is reduced.
In general, it is safest not to use the workspace arrays for other purposes between one call to a CONPACK routine and the next (unless the next is to one of the routines CPRECT, CPSPS1, or CPSPS2, which initialize the workspace pointers). At the moment, there is only one case in which the contents of the arrays are assumed to be preserved intact: If labels are being positioned using either the "regular" scheme or the "penalty" scheme, the list of label positions is created in the workspace arrays when it is first required and is assumed untouched thereafter. Other cases may arise as a result of further development of the package, however.
It is possible to find out how much space has been used in each of the workspace arrays. The parameters 'IWU' and 'RWU' are zeroed by a call to CPRECT, CPSPS1, or CPSPS2 and are updated thereafter to reflect maximum usage of space in the arrays. Thus, one might give the arrays large dimensions, create a typical contour plot, retrieve the values of 'IWU' and 'RWU' to see how much space was actually used, and then reduce the dimensions to more reasonable values.
Workspace usage by some routines cannot be predicted exactly. Upper bounds can be computed, but they may be rather large. For this reason, it may not be possible to absolutely ensure that enough workspace will be available for a given call. Therefore, there is a parameter, called 'WSO', which says what to do when a workspace overflow occurs. The four possibilities are as follows: to terminate after printing an error message, to continue running after printing an error message (this is the default), to just continue running without printing anything, or to do a recoverable-error call to SETER and then continue running without printing anything. Of course, in the latter two cases, incomplete plots may result. It is possible to find out whether or not a workspace overflow has occurred during a given call to a CONPACK routine; this is done by retrieving the values of the parameters 'IWU' and 'RWU' and comparing them with the dimensions of the workspace arrays IWRK and RWRK.
The following information may be of value in attempting to estimate how much real and integer workspace will be required by each of the user-callable routines of CONPACK. First, define the following quantities:
Note: As of February, 1996, CPLBAM and CPLBDR have been changed a little. It is now the case that, even when contour-line labels are not being positioned using the regular scheme or the penalty scheme, some real workspace will be required. This space is used for a list of labels, including the informational label and the high/low labels.
Note that, on 02/06/2002, this definition was changed slightly to allow for the placement of highs and lows closer to special values. In essence, the change caused the special-value boundary to be treated just like the grid boundary with respect to the positioning of highs and lows: no high or low will be positioned right on such a boundary, but may be positioned within one grid unit of it (that is to say, within two grid units of a grid position at which there is a special value).
Accordingly, as the "normal" search for highs and lows is executed, CONPACK now checks for evidence of equal values at adjacent grid points. If any such are seen and if the user has set the value of the internal parameter 'HLE' (which see) non-zero, an additional search is performed, looking for connected regions in which the field value is constant. Each such region is then tested to see if it ought to be considered a high or a low (or neither).
Setting 'HLE' equal to 1 allows each small connected region A to be of any size. If 'HLE' is set larger than 1, it sets an upper limit on the size of each such region; for example, if 'HLE' = 4, then any such region containing more than 4 grid points will be ignored.
The region B within which the field values must be smaller than or equal to (for a high) or greater than or equal to (for a low) the value at the grid points of A is just the union of the neighborhoods defined by the values of 'HLX' and 'HLY' (as described in the fourth condition of the normal definition, above) for all of the grid points in A.
The additional search is not outrageously expensive (it may take from 1 to 2 times as long as the normal search), but it can be significant, so it should probably not be performed unless the user has evidence that highs and lows such as it finds are being omitted and it is thought to be important that those highs and lows be shown. One peculiarity: The timing of the new algorithm is influenced by the dimensioning of the field being contoured. In particular, if the first dimension of the field ('ZDM') is less than the first dimension of the FORTRAN array in which it is stored ('ZD1'), the new algorithm will run more slowly than it would if these values were the same. Also, using the algorithm on fields in which there are large regions within which the field values are constant may be quite expensive and should be avoided.
An additional note: one may be able to construct pathological cases in which the additional search for highs and lows would find things a human would reject, but such cases will probably be rare in actual practice. One such pathological case has already been found and protected against: If a large enough fraction of the field contained the same high or low value, the code would appear to have gone into an infinite loop; this can no longer happen.
This structure allows the use of a tiered approach to color setting. If no color setting whatsoever is done, contour plots are drawn entirely in the colors specified by the applicable default values of the GKS color indices. If, on the other hand, prior to calling CONPACK, one defines the color index "IC" (see the next section, "GKS Considerations") and then uses
CALL GSPLCI (IC)
to change the GKS polyline color index, then all polylines drawn by
CONPACK change color. Similarly, one may use the statement
CALL GSTXCI (IC)
to change the GKS text color index and the statement
CALL GSFACI (IC)
to change the GKS fill area color index; the first will cause labels
drawn by CONPACK to change color and the second will cause label boxes
filled by CONPACK to change color.If, in addition or instead, CONPACK color-setting parameters are given values greater than or equal to zero, the objects or classes of objects to which those parameters apply are colored accordingly; these colors are used in preference to values preset by calls to GSPLCI, GSTXCI, or GSFACI.
A final opportunity to set color is provided by the user-supplied versions of the "change" routines, with names of the form CPCHxx; calls to GSPLCI, GSTXCI, and GSFACI may occur in such a routine and take precedence over color setting by any other means. Note that, if color is being set for drawing a label, then either or both of the polyline color index and the text color index may need to be set, depending on whether the labels are being drawn by calls to the GKS routine GPL (to draw polylines stroking out the characters) or by calls to the GKS routine GTX (to draw text). In particular, the routine PLCHHQ, in the package PLOTCHAR, which is called by CONPACK to draw labels, may be directed by the user to draw high-quality characters, which are stroked, medium-quality characters, which are also stroked, or low-quality characters, which are drawn by GTX.
CGDL=AGFL+AGDL*(AGFR-AGFL)
CGDR=AGFL+AGDR*(AGFR-AGFL)
CGDB=AGFB+AGDB*(AGFT-AGFB)
CGDT=AGFB+AGDT*(AGFT-AGFB)
Note what happens when AGFL and AGFB are 0's and AGFR and AGFT are 1's,
which is the default situation; in that case CGDL=AGDL, CGDR=AGDR,
CGDB=AGDB, and CGDT=AGDT.
(1) Like all the utilities in the NCAR graphics package, CONPACK assumes that GKS has been opened and that the desired workstations have been opened and activated. The statement
CALL OPNGKS
calls the SPPS routine OPNGKS, the GKS equivalent of which is
CALL GOPKS (6,0)
CALL GOPWK (1,2,1)
CALL GACWK (1)
creating a single metacode workstation associated with FORTRAN unit 2.Similarly, at the end of one's program, the workstations must be deactivated and closed and then GKS must be closed. The statement
CALL CLSGKS
calls the SPPS routine CLSGKS, the GKS equivalent of which is
CALL GDAWK (1)
CALL GCLWK (1)
CALL GCLKS
(2) In versions of CONPACK prior to 3.1.3, it was more or less assumed
that clipping was turned off. To turn clipping off yourself, use the
statement
CALL GSCLIP (0)
If this is not done, and if you are using a pre-3.1.3 version of CONPACK
to draw the informational label in its default position, which is outside
the viewport, it will be clipped and fail to appear on the plot.(3) It is assumed that the aspect source flags for various quantities are set to "individual". (The NCAR GKS package does this by default, but other packages may not.) To make sure that all the aspect source flags are set correctly, use the following code:
DIMENSION IASF(13)
...
DATA IASF / 13*1 /
...
CALL GSASF (IASF)
(4) Color fill of label boxes is done by CONPACK using calls to the GKS
routine GFA; color fill of contour bands by the user will be done using
similar calls. To get solid fill, rather than hollow fill, one must call
a GKS routine to set the "fill area interior style":
CALL GSFAIS (1)
(This is because the default "fill area interior style", as mandated by
the GKS standard, is "hollow", rather than "solid".)(5) Color-setting by CONPACK is done by executing calls to the GKS routines GSPLCI, GSTXCI, and GSFACI, with user-defined color indices as arguments. The association of these color indices with colors on the workstations must have been defined previously by the user. This should be done by calling the GKS routine GSCR. The statement
CALL GSCR (IW,IC,RC,GC,BC)
defines, for workstation IW, color index IC, with RGB components RC, GC,
and BC. To be consistent with the SPPS routines OPNGKS and CLSGKS, use
IW = 1. The value of IC may be any non-negative integer. By default, color
index 0 is associated with the color black, which is defined by (RC,GC,BC)
= (0.,0.,0.) and is used as the background color, while color index 1 is
associated with the color white, which is defined by (RC,GC,BC) =
(1.,1.,1.).
The initial version of CPBACK does very little. User feedback will be useful in determining what this routine is eventually made to do.
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, CPSPS2, or CPMVRW, input/output) is the current real workspace array.
IWRK (INTEGER array, dimensioned as specified in the last call to CPRECT, CPSPS1, CPSPS2, or CPMVIW, input/output) is the current integer workspace array.
The text of the label being written may be retrieved by means of a "CALL CPGETC ('CTM',CVAL)". The text of the label may be changed by means of a "CALL CPSETC ('CTM',CVAL)"; this should only be done during a call with IFLG = 1 or 3 and, if it is done for one of those two values, it should also be done for the other.
When CPCHCF is called, the parameter 'ZDV' will have been set to the value of the field; its value may be retrieved and used by CPCHCF.
If the element of the parameter array 'CLU' corresponding to 'PAI' = -1 has been set non-zero to request the drawing of the edge of the grid, then CPCHCL will be called before and after that is done. Similarly, if the element of 'CLU' corresponding to 'PAI' = -2 has been set non-zero, then CPCHCL will be called before and after the drawing of the edges of the special-value areas, and, if the element of 'CLU' corresponding to 'PAI' = -3 has been set non-zero, then CPCHCL will be called before and after the drawing of the edges of the out-of-range areas.
When CPCHCL is called, the parameter 'PAI' will have been set to the index of the appropriate contour level (between 1 and 'NCL') or to one of the values -1, -2, or -3. By retrieving the value of 'PAI', CPCHCL can find out what line is being drawn; also, a CPGETx call to retrieve an element of a parameter array like 'CLD' will automatically get the correct one for the line being drawn.
The text of the label may be retrieved by means of a "CALL CPGETC ('CTM',CVAL)". The text of the label may be changed by means of a "CALL CPSETC ('CTM',CVAL)"; this should only be done during a call with IFLG = 1, 3, 5, or 7; if it is done for one of the two values 1 and 3, it should also be done for the other; if it is done for one of the two values 5 and 7, it should also be done for the other.
When CPCHHL is called, the parameter 'ZDV' will have been set to the value of the high or low being labelled; its value may be retrieved and used by CPCHHL. Also, the internal parameters 'LBX' and 'LBY' will have been set to the X and Y coordinates of the center point of the label, in the current user coordinate system.
The text of the label may be retrieved by means of a "CALL CPGETC ('CTM',CVAL)". The text of the label may be changed by means of a "CALL CPSETC ('CTM',CVAL)"; this should only be done during a call with IFLG = 1 or IFLG = 3, and, if it is done for one of those values, it should be done for the other.
The internal parameters 'LBX' and 'LBY' will have been set to the X and Y coordinates of the center point of the label, in the current user coordinate system.
The text of the label may be retrieved by means of a "CALL CPGETC ('CTM',CVAL)". The text of the label may be changed by means of a "CALL CPSETC ('CTM',CVAL)"; this should only be done during a call with IFLG = 1 or 3 and, if it is done for one of those values, it should be done for the other.
When CPCHLL is called, the parameter 'PAI' will have been set to the index of the appropriate contour level. Thus, parameters associated with that level may easily be retrieved by calls to CPGETx. Also, the parameter 'ZDV' will have been set to the contour level value and the internal parameters 'LBX' and 'LBY' will have been set to the X and Y coordinates of the center point of the label, in the current user coordinate system.
This routine incorporates into a user's cell array color indices determined by examining where the user's contours lie relative to the cell array.
Special Note: If the internal parameter 'MAP' is non-zero, CPCICA requires that the routine CPMPXY be capable of doing the inverse transformation associated with that non-zero value of 'MAP'. As of release 3.1.3 of NCAR Graphics, the default version of CPMPXY does the inverses for the built-in mappings; users who supply their own versions of CPMPXY may need to upgrade them. See the description of the routine CPMPXY, below.
Once an area identifier has been associated with a particular cell, that area identifier must be mapped into a color index that can be stored as the value of the corresponding element of the cell array. The internal parameter 'CAF' determines how area identifiers are mapped into color indices, as follows:
Note that, if element -1 of 'AIA' has the value -1, and if element -2 of 'AIA' has the value -2, and if element -3 of 'AIA' has the value -3, and if, for I = 1 through 'NCL', element I of 'AIA' has the value I+1 and element I of 'AIB' has the value I, and if 'CAF' has the value 4, then the color indices stored in the cell array will have values from 1 through 'NCL'+5, where the value 1 implies an out-of-range area, the value 2 implies a special-value area, the value 3 implies an area outside the grid, the value 4 implies an area inside the grid for which no color index has been unambiguously specified (which should not occur, in this case) and each of the values 5 through 'NCL'+5 implies a particular contour band.
Note that, if cells lying outside the data grid, in special-value areas of the data grid, or in out-of-range areas are not to have their color indices reset, elements -1, -2, and -3 in the parameter array 'AIA' should be made large and negative; if, on the other hand, it is desired that such cells should be marked, they must be given values which will result in the generation (by whichever scheme is selected by the value of 'CAF') of color indices greater than or equal to zero.
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, CPSPS2, or CPMVRW, input/output) is the current real workspace array.
IWRK (INTEGER array, dimensioned as specified in the last call to CPRECT, CPSPS1, CPSPS2, or CPMVIW, input/output) is the current integer workspace array.
ICRA (INTEGER array, dimensioned ICA1 by "n", where "n" is greater than or equal to the value of the argument ICAN, input/output) is the user's cell array.
ICA1 (INTEGER, input) is the first dimension of the FORTRAN array ICRA, which contains the user's cell array.
ICAM (INTEGER, input) is the first dimension of the user's cell array.
ICAN (INTEGER, input) is the second dimension of the user's cell array.
XCPF and YCPF (REAL, input) are the coordinates, in the fractional coordinate system, of a point P. P is the point at that corner of the rectangular area into which the cell array maps that corresponds to the cell (1,1).
XCQF and YCQF (REAL, input) are the coordinates, in the fractional coordinate system, of a point Q. Q is the point at that corner of the rectangular area into which the cell array maps that corresponds to the cell (ICAM,ICAN).
The contour lines added to the area map are as specified by the first 'NCL' elements of the parameter arrays 'CLV', 'AIA', and 'AIB'. If 'NCL' is zero, CPPKCL is called to generate these values. The contour levels defined by the first 'NCL' elements of the parameter array 'CLV' are then examined. If a given contour level is associated with a non-zero value of 'AIA' and/or a non-zero value of 'AIB', the contour lines at that contour level are added to the area map. If there is an associated non-zero value of 'AIA', it is used as the area identifier for the area "above" the line (where field values are greater than they are along the line); otherwise, a zero is used. If there is an associated non-zero value of 'AIB', it is used as the area identifier for the area "below" the line (where field values are less than they are along the line); otherwise, a zero is used. Note that a given contour level may occur more than once in the internal parameter array 'CLV', but there must be at most one non-zero value of 'AIA' and at most one non-zero value of 'AIB' associated with it; otherwise, an error exit occurs.
Other types of lines are also added to the area map by CPCLAM: the edge of the current viewport and possibly a set of vertical lines within the viewport; the edge of the grid; the edges of special-value areas, if any; and the edges of out-of-range areas, if any. The area identifier for the outside of the viewport is always -1. Elements of the parameter array 'AIA' for 'PAI' = -1, -2, and -3 may be used to specify the area identifiers to be used for the outside of the grid, the inside of a special-value area, and the inside of an out-of-range area, respectively; the default values of all three are -1's. (Except for the first, which, as of version 3.1.3, has been changed to "0".) Area identifiers for all other sides of these edges are determined from the area-identifier information given for the contour levels.
The lines added to the area map are put into two edge groups, one with group identifier 'GIC' and another with group identifier 'GIS'. (The edge of the viewport may actually be added twice, once to each group.) The edge group 'GIC' is the more important of the two; it really defines the division of the plane into contour bands, special-value areas, out-of-range areas, outside-the-grid areas, and so on. The edge group 'GIS' only receives the edge of the viewport and a collection of vertical lines; its object is to break up the areas defined by the other edge group into vertical pieces, creating simpler polygons on devices that might not handle more complicated ones. Whether or not edge group 'GIS' is created is under control of the user; for more information, see the descriptions of the parameters 'GIS' and 'NVS'.
Lines are added to the area map in the following order: the edge of the viewport and the vertical lines within it, edges of the out-of-range areas, if any; the edge of the grid; edges of the special-value areas, if any; and the contour lines, in order of increasing contour level.
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 added to the area map; the other lines are added, however.
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, CPSPS2, or CPMVRW, input/output) is the current real workspace array.
IWRK (INTEGER array, dimensioned as specified in the last call to CPRECT, CPSPS1, CPSPS2, or CPMVIW, input/output) is the current integer workspace array.
IAMA (INTEGER array, dimensioned as specified in a call to ARINAM, in the package AREAS) is the array containing the area map to which contour lines are to be added.
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; the value 1 directs CPCLDM to draw only parts of the special-value edges that do not overlap the grid edge; a value of 2 or greater says that all parts of the special-value edges are to be 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; 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 user routine which actually does the drawing may override the settings of these quantities.)
If the dash-pattern-usage parameter 'DPU' is zero, it is assumed that lines are to be drawn by calling the SPPS routine CURVE; specified dash patterns are not used. If 'DPU' is greater than zero, it is assumed that lines are to be drawn by calling the DASHCHAR routine CURVED, while if 'DPU' is less than zero, it is assumed that lines are to be drawn by calling the DASHPACK routine DPCURV; in either case, specified dash patterns are used. If 'DPU' is non-zero and ABS('LLP') = 1, then, for those lines which are to be labelled, the dash pattern is constructed by replicating the dash pattern specified by the appropriate element of 'CLD' 'DPU' times and then adding to that the numeric label 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.
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, CPSPS2, or CPMVRW, input/output) is the current real workspace array.
IWRK (INTEGER array, dimensioned as specified in the last call to CPRECT, CPSPS1, CPSPS2, or CPMVIW, input/output) is the current 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 DASHCHAR routine CURVED, to the
DASHPACK routine DPCURV, 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.For more information, see the description of the argument LPR of the subroutine ARDRLN, in the documentation of the package AREAS.
The contour lines drawn 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 drawn at that level and whether or not the lines are to be labelled. 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 drawn.
If the element of 'CLU' corresponding to 'PAI' = -2 is non-zero, the edges of special-value areas areas (if any) are drawn; the value 1 directs CPCLDR to draw only those parts of the special-value edges that do not overlap the grid edge; a value of 2 or greater says that all parts of the special-value edges are to be drawn.
If the element of 'CLU' corresponding to 'PAI' = -3 is non-zero, the edges of out-of-range areas (if any) are drawn. The default values are such that none of these edges are drawn.
Groups of lines are drawn 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; 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 drawn, the routine CPCHCL is called; a user-supplied version of this routine may override the settings of color, dash pattern, and line width.
If the dash-pattern-usage parameter 'DPU' is zero, lines are drawn by calling the SPPS routine CURVE; they are all solid and unlabelled. If 'DPU' is greater than zero, lines are drawn by calling the DASHCHAR routine CURVED, while if 'DPU' is less than zero, lines are drawn by calling the DASHPACK routine DPCURV; in either case, they are solid or dashed, depending on the dash pattern specified by the appropriate element of 'CLD'. If 'DPU' is non-zero and ABS('LLP') = 1, the dash pattern for those lines which are to be labelled is constructed by replicating the dash pattern specified by the appropriate element of 'CLD' 'DPU' times and then adding to it the characters specified by the apppropriate element of 'LLT'. If 'DPU' is non-zero and ABS('LLP') is greater than 1, the lines drawn will pass through any labels drawn by CPLBDR; if this is undesirable, CPLBAM can be used to put the label boxes into an area map and CPCLDM can be used to draw only those portions of the contour lines which do not lie inside the label boxes.
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 drawn; instead, the constant-field label is written. Other lines are still drawn.
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, CPSPS2, or CPMVRW, input/output) is the current real workspace array.
IWRK (INTEGER array, dimensioned as specified in the last call to CPRECT, CPSPS1, CPSPS2, or CPMVIW, input/output) is the current integer workspace array.
This routine traces the contour lines at a given level and retrieves them for some sort of user-defined processing. The contour lines are traced in such a way that lower field values (less than CLVL) are to the left and higher field values (greater than CLVL) are to the right (where "left" and "right" are defined from the standpoint of someone standing at one point of the contour line, looking toward the next).
IJMP=0
101 CALL CPCLTR (ZDAT,RWRK,IWRK,CLEV,IJMP,IRW1,IRW2,NRWK)
IF (IJMP.NE.0) THEN
(PROCESS SEGMENT OF CONTOUR LINE THAT HAS BEEN PUT IN RWRK.)
GO TO 101
END IF