Using Conpack
Previous Chapter Tutorial Home Next Chapter
- Cp 1. What is Conpack?
- Cp 1.1 Table of Conpack user entry points
- Conpack initialization and data support routines
- Background routine
- Labeling routines
- Contour line drawing routines
- Parameter access routines
- Cp 1.2 Table of Conpack parameters
- Cp 1.3 Producing a "quick and dirty" plot
- Cp 1.4 More complex black and white plots
- Cp 1.5 What calls do I need to get my Conpack plot?
- Cp 1.6 Conpack parameters: What they do and how to use them
- Cp 2. Backgrounds for your plots
- Cp 2.1 Generating a background
- Cp 2.2 Drawing a contour perimeter
- Cp 2.3 Setting X/Y axis values for a contour background
- Cp 2.4 Changing perimeter options
- Cp 2.5 Labeling X/Y axis values for a contour background
- Cp 2.6 Contour perimeter: Size, shape, and location using Conpack
- Cp 2.7 Contour perimeter: Size, shape, and location using SET
- Cp 3. Initializing Conpack
- Cp 3.1 Data types
- Dense gridded data
- Sparse gridded data
- Irregularly spaced gridded data
- Nongridded data
- Missing data
- Non-Cartesian data
- Cp 3.2 Dense gridded data
- Cp 3.3 Sparse gridded data
- Cp 3.4 Irregularly spaced gridded data
- Cp 3.5 Nongridded data
- Cp 3.6 Missing or special data
- Cp 3.7 Non-Cartesian data
- Cp 3.8 Non-Cartesian data: Latitude/longitude data
- Cp 3.9 Non-Cartesian data: Polar coordinates
- Cp 3.10 Non-Cartesian data: Other data types
- Cp 3.11 Contouring non-rectangular domains
- Cp 3.12 Setting minimal workspace
- Cp 4. Contour line basics
- Cp 4.1 Contour line basics
- Cp 4.2 Drawing contour lines
- Cp 4.3 Four methods of contour level selection
- Cp 4.4 Default contour level selection
- Cp 4.5 Default contour level selection: Default intervals and labels
- Cp 4.6 Default contour level selection: Fixed contour intervals and labels
- Cp 4.7 Modifying Conpack-chosen levels: Picking levels
- Cp 4.8 Modifying Conpack-chosen levels: Changing the levels
- Cp 4.9 Setting n equally spaced contour levels
- Cp 4.10 Choosing your own contour levels
- Cp 4.11 Line attributes: Line dash patterns
- Cp 4.12 Line attributes: Line thickness
- Cp 4.13 Line attributes: Line color
- Cp 4.14 Line attributes: Turning contour line drawing off and on
- Cp 5. Filling contour levels
- Cp 5.1 Area identifiers in Conpack
- Cp 5.2 Group identifiers in Conpack
- Cp 5.3 Initialize Conpack with Areas
- Cp 5.4 Adding label boxes to the area map
- Cp 5.5 Masking areas: Label boxes
- Cp 5.6 Masking areas: Box masking routines
- Cp 5.7 Filling contour levels
- Cp 5.8 Filling contour levels: Writing a fill routine
- Cp 6. Contour line labels
- Cp 6.1 Annotating your plots
- Cp 6.2 Forcing labels to be chosen
- Cp 6.3 Selecting lines for labels: Default method
- Cp 6.4 Selecting lines for labels: Labeling every nth line
- Cp 6.5 Selecting lines for labels: Labeling specific lines
- Cp 6.6 Three methods of label placement
- Cp 6.7 Label placement: Default method
- Cp 6.8 Label placement: Regular scheme
- Cp 6.9 Label placement: Penalty scheme
- Cp 6.9.1 Label placement: Penalty scheme---Gradient term
- Cp 6.9.2 Label placement: Penalty scheme---Crossing contours
- Cp 6.9.3 Label placement: Penalty scheme---Tight curves
- Cp 6.9.4 Label placement: Penalty scheme---Label spacing
- Cp 6.10 Label attributes: Angle and orientation
- Cp 6.11 Label attributes: Color
- Cp 6.12 Label attributes: Label text options
- Cp 7. General labels
- Cp 7.1 Overview of labeling in Conpack
- Cp 7.2 Titles
- Cp 7.3 Numeric control: Significant digits
- Cp 7.4 Numeric control: Formatting
- Cp 7.5 Numeric control: Exponents
- Cp 7.6 Label attributes: Angles
- Cp 7.7 Label attributes: Size
- Cp 7.8 Label attributes: Constant field and information text
- Cp 7.9 Label attributes: High/low text
- Cp 7.10 Label attributes: Color
- Cp 7.11 Label box attributes: Outline and fill
- Cp 7.12 Label box attributes: Line width
- Cp 7.13 Label box attributes: Size
- Cp 7.14 Label placement: Constant field and information labels
- Cp 7.15 Label placement: High/low
- Cp 7.16 Constant field found flag
- Cp 8. Overlaying filled contours on a map
- Cp 8.1 Initialization
- Cp 8.2 Masking areas: Label boxes and land masses
- Cp 8.3 Filling specific contour and geographic areas
- Cp 8.4 Filling areas: Polar projection
- Cp 9. Advanced topics
- Cp 9.1 Smoothing contours
- Cp 9.2 Hachuring: Indicating slope on a contour plot
- Cp 9.3 Cell arrays
- Cp 9.4 Making a movie
- Cp 10. Conpack parameter descriptions
Conpack is a color contouring utility. Conpack can be used to generate contour plots of almost any rectangular array of data; it has an extensive variety of options.
Because of the flexibility of Conpack, the process of generating a plot usually requires calling several routines. This module organizes the routines according to their functions.
These routines draw contour plots using a single call.
- CPCNRC
- Draws black-and-white contours with a single call. Simulates old routine CONREC. See module Cp 1.4.
- CPEZCT
- Draws black-and-white contours with a single call. Simulates old routine EZCNTR (in the old CONREC utility). See module Cp 1.3.
These routines aid in converting data to a form Conpack can use, initialize Conpack to handle specific kinds of data, or add features to an area map for filled or masked contours.
- CPRECT
- Initializes contouring of data on a dense rectangular array of data. See module Cp 3.2.
- CPSPS1
- Initializes contouring of data on a sparse rectangular grid. See module Cp 3.3.
- CPSPS2
- Initializes contouring of data on an irregularly spaced rectangular grid. See module Cp 3.4.
- IDSFFT
- A Bivar routine that interpolates randomly spaced data onto a dense regular grid. See module Cp 3.5.
- CPCLAM
- Adds contour lines to area map. See module Cp 5.3.
- CPLBAM
- Adds label boxes to an area map, so that lines aren't drawn through labels. See module Cp 5.4.
- CPMPXY
- Maps from a rectangular coordinate system to some other coordinate
system. See module Cp 3.10; also see module Cp 3.7.
Most people want a perimeter drawn around their contour plot.
- CPBACK
- Draws a perimeter. See module Cp 2.2.
Labeling is controlled by several routines, depending on which label you want to modify.
- CPLBDR
- Draws labels. See module Cp 6.1.
- CPPKLB
- Picks a set of labels for labeled contour levels. See module Cp 6.2.
- CPCHLL
- Changes drawing of line labels.
- CPCHIL
- Changes drawing of information labels.
- CPCHHL
- Changes drawing of high and low labels.
- CPCHCF
- Changes drawing of constant field message.
Contour lines are drawn as a separate step.
- CPCLDR
- Draws contour lines. See module Cp 4.2.
- CPCLDM
- Draws contour lines masked by existing area map. See module Cp 5.5.
- CPDRPL
- Provides polyline drawing for CPCLDM. See module Cp 5.6.
- CPCICA
- Incorporates, into a user's cell array, color indices determined by examining where the user's contours lie relative to the cell array. See module Cp 9.3.
- CPCHCL
- Changes drawing of contour lines.
- CPCLTR
- Traces the contour lines at a given level and retrieves them for some sort of user-defined processing.
- CPPKCL
- Picks a set of contour levels. See module Cp 4.7.
There are seven calls that aid in changing and retrieving parameter values.
- CPSETC
- Sets character values. See module Cp 1.6.
- CPSETI
- Sets integer values. See module Cp 1.6.
- CPSETR
- Sets real values. See module Cp 1.6.
- CPRSET
- Resets default values. See module Cp 1.6.
- CPGETC
- Retrieves current character values. See module Cp 1.6.
- CPGETI
- Retrieves current integer values. See module Cp 1.6.
- CPGETR
- Retrieves current real values. See module Cp 1.6.
This table is a quick reference guide to the examples in which Conpack parameters are used and the modules in which Conpack parameters are described. More complete descriptions appear in section "Cp 10. Conpack parameter descriptions."
The behavior of a typical routine in an NCAR Graphics utility is sometimes determined entirely by the routine's arguments, but frequently it is also affected by the value of one or more of the utility's parameters. A "parameter" is a variable that controls the behavior of a utility; parameters are accessed via parameter-access routines that can set or retrieve the parameter value.
Instructions for setting and retrieving Conpack parameters are provided in module "Cp 1.6 Conpack parameters:What they do and how to use them."
----------------------------------------------------------------------------------
Parameter Brief description Fortran type Examples Module
----------------------------------------------------------------------------------
AIA Area Identifier Above Integer array --- Cp 5.1
ccpscam ---
AIB Area Identifier Below Integer array --- Cp 5.1
ccpscam ---
CAF Cell Array Flag Integer --- Cp 10.
CFA Constant Field label Angle Real ccpila Cp 7.6
CFB Constant Field label Box flag Integer ccpllb Cp 7.11
CFC Constant Field label Color Integer ccplbdr Cp 7.10
index
CFF Constant Field Found flag Integer ccpcff Cp 7.16
CFL Constant Field label Line Real ccplll Cp 7.12
width
CFP Constant Field label Integer ccpcfx Cp 7.14
Positioning flag
CFS Constant Field label Size Real ccpils Cp 7.7
CFT Constant Field label Text Character ccpilt Cp 7.8
string
CFW Constant Field label White Real ccpllw Cp 7.13
space width
CFX Constant Field label X Real ccpcfx Cp 7.14
coordinate
CFY Constant Field label Y Real ccpcfx Cp 7.14
coordinate
CIS Contour Interval Specifier Real ccpcis, Cp 4.6,
ccpcis Cp 6.4
CIT Contour Interval Table Real array ccpcit, Cp 4.5,
ccpcit Cp 6.3
CIU Contour Interval Used Real --- Cp 10.
CLC Contour Line Color index Integer array ccpclc Cp 4.13
CLD Contour Line Dash pattern Character array or ccpcld Cp 4.11
Integer array
CLL Contour Line Line width Real array ccpcll Cp 4.12
CLS Contour Level Selection flag Integer --- Cp 4.4,
ccpncls, Cp 4.9,
ccphand Cp 4.10
CLU Contour Level Use flags Integer array ccpspv, Cp 3.6,
ccpclu, Cp 4.14,
ccpclu Cp 6.5
CLV Contour Level Values Real array ccppkcl, Cp 4.8,
ccphand Cp 4.10
CMN Contour MiNimum Real ccpcis Cp 4.6
CMX Contour MaXimum Real ccpcis Cp 4.6
CTM Character TeMporary Character --- Cp 10.
CWM Character Width Multiplier Real ccpllt, Cp 6.12,
ccpils Cp 7.7,
ccpllw Cp 7.13
DPS Dash Pattern Size Real --- Cp 10.
DPU Dash Pattern Use flag Integer --- Cp 10.
DPV Dash Pattern Vector length Real --- Cp 10.
GIC Group Identifier for Contour Integer ccpvs Cp 5.2
lines
GIL Group Identifier for Label Integer ccpvs Cp 5.2
boxes
GIS Group Identifier for Strips Integer ccpvs Cp 5.2
HIC HIgh label Color index Integer ccplbdr Cp 7.10
HIT HIgh label Text string Character --- Cp 10.
HCF HaChure Flag Integer ccphcf Cp 9.2
HCL HaChure Length Real ccphcf Cp 9.2
HCS HaChure Spacing Real ccphcf Cp 9.2
HLA High/Low label Angle Real ccpila Cp 7.6
HLB High/Low label Box flag Integer ccpllb Cp 7.11
HLC High/Low label Color index Integer ccplbdr Cp 7.10
HLL High/Low label Line width Real ccplll Cp 7.12
HLO High/Low label Overlap flag Integer ccphl Cp 7.15
HLS High/Low label Size Real ccpils Cp 7.7
HLT High/Low label Text strings Character ccphlt Cp 7.9
HLW High/Low label White space Real ccpllw Cp 7.13
width
HLX High/Low search radius in X Integer ccphl Cp 7.15
HLY High/Low search radius in Y Integer ccphl Cp 7.15
ILA Information Label Angle Real ccpila Cp 7.6
ILB Information Label Box flag Integer ccpllb Cp 7.11
ILC Information Label Color Integer ccplbdr Cp 7.10
index
ILL Information Label Line width Real ccplll Cp 7.12
ILP Information Label Positioning Integer ccpcfx Cp 7.14
flag
ILS Information Label Size Real ccpils Cp 7.7
ILT Information Label Text string Character ccpilt Cp 7.8
ILW Information Label White space Real ccpllw Cp 7.13
width
ILX Information Label X Real ccpcfx Cp 7.14
coordinate
ILY Information Label Y Real ccpcfx Cp 7.14
coordinate
IWM Integer Workspace for Integer --- Cp 10.
Masking
IWU Integer Workspace Usage Integer ccprwu Cp 3.12
LBC Label Box Color index Integer ccpllb Cp 7.11
LBX Label Box X coordinate Real --- Cp 10.
LBY Label Box Y coordinate Real --- Cp 10.
LIS Label Interval Specifier Integer ccpcis, Cp 4.6,
ccpcis Cp 6.4
LIT Label Interval Table Integer array ccpcit, Cp 4.5,
ccpcit Cp 6.3
LIU Label Interval Used Integer ccpcit Cp 6.3
LLA Line Label Angle Real ccpllo Cp 6.10
LLB Line Label Box flag Integer ccpllb Cp 7.11
LLC Line Label Color index Integer array ccpllc Cp 6.11
LLL Line Label Line width Real ccplll Cp 7.12
LLO Line Label Orientation Integer ccpllo Cp 6.10
LLP Line Label Positioning Integer --- Cp 6.6
LLS Line Label Size Real ccpllt Cp 6.12
LLT Line Label Text string Character array ccpllt Cp 6.12
LLW Line Label White space Real ccpllw Cp 7.13
LOC LOw label Color index Integer ccplbdr Cp 7.10
LOT LOw label Text string Character --- Cp 10.
MAP MAPping flag Integer ccpmap, Cp 3.8,
ccpcir Cp 3.9
NCL Number of Contour Levels Integer ccppkcl, Cp 4.8,
ccphand Cp 4.10
NEL Numeric Exponent Length Integer ccpnet Cp 7.5
NET Numeric Exponent Type Integer ccpnet Cp 7.5
NEU Numeric Exponent Use flag Integer ccpnet Cp 7.5
NLS Numeric Leftmost Significant Integer ccpnsd Cp 7.3
digit flag
NLZ Numeric Leading Zero flag Integer ccpnof Cp 7.4
NOF Numeric Omission Flags Integer ccpnof Cp 7.4
NSD Number of Significant Digits Integer ccpnsd Cp 7.3
NVS Number of Vertical Strips Integer ccpvs Cp 5.2
ORV Out-of-Range Value Real ccpmap Cp 3.8
PAI Parameter Array Index Integer --- Cp 1.6,
ccpspv, Cp 3.6,
ccpcit, Cp 4.5,
ccppkcl, Cp 4.8,
ccphand, Cp 4.10,
ccpcit Cp 6.3
PC1 Penalty scheme Constant 1 Real ccppc1 Cp 6.9.1
PC2 Penalty scheme Constant 2 Real ccppc2 Cp 6.9.2
PC3 Penalty scheme Constant 3 Real ccppc3 Cp 6.9.3
PC4 Penalty scheme Constant 4 Real ccppc4 Cp 6.9.4
PC5 Penalty scheme Constant 5 Real ccppc4 Cp 6.9.4
PC6 Penalty scheme Constant 6 Real ccppc4 Cp 6.9.4
PIC Point Interpolation flag for Integer ccpt2d Cp 9.1
Contours
PIE Point Interpolation flag for Integer --- Cp 10.
Edges
PW1 Penalty scheme Weight 1 Real ccppc1 Cp 6.9.1
PW2 Penalty scheme Weight 2 Real ccppc2 Cp 6.9.2
PW3 Penalty scheme Weight 3 Real ccppc3 Cp 6.9.3
PW4 Penalty scheme Weight 4 Real ccppc4 Cp 6.9.4
RC1 Regular scheme Constant 1 Real ccprc Cp 6.8
RC2 Regular scheme Constant 2 Real ccprc Cp 6.8
RC3 Regular scheme Constant 3 Real ccprc Cp 6.8
RWC Real Workspace for Contours Integer ccprwc Cp 6.7
RWG Real Workspace for Gradients Integer --- Cp 10.
RWM Real Workspace for Masking Integer --- Cp 10.
RWU Real Workspace Usage Integer ccprwu Cp 3.12
SET do-SET-call flag Integer ccpset Cp 2.7
SFS Scale Factor Selector Real ccpklb Cp 10.
SFU Scale Factor Used Real ccpklb Cp 10.
SPV SPecial Value Real ccpspv Cp 3.6
SSL Smoothed Segment Length Real ccpt2d Cp 9.1
T2D Tension on 2-Dimensional Real ccpt2d Cp 9.1
splines
T3D Tension on 3-Dimensional Real --- Cp 10.
splines
VPB ViewPort Bottom Real ccpvp Cp 2.6
VPL ViewPort Left Real ccpvp Cp 2.6
VPR ViewPort Right Real ccpvp Cp 2.6
VPS ViewPort Shape Real ccpvp Cp 2.6
VPT ViewPort Top Real ccpvp Cp 2.6
WDB WinDow Bottom Real --- Cp 10.
WDL WinDow Left Real --- Cp 10.
WDR WinDow Right Real --- Cp 10.
WDT WinDow Top Real --- Cp 10.
WSO WorkSpace Overflow flag Integer --- Cp 10.
XC1 X Coordinate at index 1 Real ccpga, ---
ccpset, ---
--- Cp 2.3,
ccpmap, Cp 3.8,
ccpcir Cp 3.9
XCM X Coordinate at index M Real ccpga, ---
ccpset, ---
--- Cp 2.3,
ccpmap, Cp 3.8,
ccpcir Cp 3.9
YC1 Y Coordinate at index 1 Real ccpga, ---
ccpset, ---
--- Cp 2.3,
ccpmap, Cp 3.8,
ccpcir Cp 3.9
YCN Y Coordinate at index N Real ccpga, ---
ccpset, ---
--- Cp 2.3,
ccpmap, Cp 3.8,
ccpcir Cp 3.9
ZD1 Z data array Dimension 1 Integer --- Cp 10.
ZDM Z data array Dimension M Integer --- Cp 10.
ZDN Z data array Dimension N Integer --- Cp 10.
ZDS Z data array Dimension Integer --- Cp 10.
Selector
ZDU Z Data value, Unscaled Real --- Cp 10.
ZDV Z Data Value Real --- Cp 10.
ZMN Z MiNimum value Real --- Cp 10.
ZMX Z MaXimum value Real --- Cp 10.
----------------------------------------------------------------------------------
If all you want to do is get a quick look at some data that are arrayed on a regular rectangular grid, you may want to try using the CPEZCT routine. CPEZCT often provides good way to preview your data.
1 CALL CPEZCT (ZREG, M, N)
CALL CPEZCT (ZREG, M, N)
- ZREG(M,N)
- Real, Input---A filled M by N data array holding values to be contoured.
- M
- Integer, Input---The first dimension of ZREG.
- N
- Integer, Input---The second dimension of ZREG.
CPEZCT is one of the two Conpack routines that draw contours with a single call. CPEZCT also calls FRAME, the SPPS routine for separating pictures in your CGM. To generate a plot, you only have to call CPEZCT.
CPEZCT makes several assumptions:
- All of the array will be contoured.
- The data are regularly spaced.
- You don't want specific contour levels.
- You don't care too much about the scale factors.
- You want highs and lows marked.
- Contour lines with negative values will be drawn with a dashed-line pattern.
- Call CPEZCT with some of your own data.
You may need more control over drawing black-and-white contour plots than CPEZCT offers, but you probably still want to obtain initial results quickly. CPCNRC offers basic control over labels, contour line patterns, choosing contour levels, and other functions.
1 CALL CPCNRC (ZREG, M, M, N, -40., 50., 10., 0, 0, -366)
CALL CPCNRC (ZREG, K, M, N, FLOW, FHGH, FINC, NSET, NHGH, NDSH)
- ZREG(K,n)
- Real Array, Input---The array of data to be contoured. Dimensioned K by n, where n>=N.
- K
- Integer, Input---The first dimension of the declared Fortran array ZREG.
- M
- Integer, Input---The first dimension of the data in the array.
- N
- Integer, Input---The second dimension of the data array. N<=n, where n is the declared second dimension of ZREG.
- FLOW
- Real, Input---The desired lowest contour level. If FLOW>=FHGH, Conpack chooses the set of contour levels.
- FHGH
- Real, Input---The desired highest contour level. If FHGH<=FLOW, Conpack chooses the set of contour levels.
- FINC
- Real, Input---Determines how contour levels are chosen, as follows:
- >0 FINC is the desired contour interval to be used. If FINC>0 and FLOW<FHGH, the intervals used will be FLOW, FLOW+FINC, FLOW+2*FINC, ... FLOW+n*FINC, where n is the largest integer such that FLOW+n*FINC<=FHGH. If FLOW>=FHGH, then the contour levels will be those integer multiples of FINC that fall between the minimum value in ZREG and the maximum value in ZREG.
- <=0 Conpack chooses the contour interval to give at least 16 contour levels (if FINC=0), or MAX(1,INT(-FINC)) contour levels (if FINC<0) between the minimum and maximum values in ZREG. All the contour levels will be integer multiples of the chosen interval. If FLOW<FHGH, then no contour lines will be drawn outside the range (FLOW, FHGH).
- NSET
- Integer, Input---Determines how the plot is mapped into the plotter frame as follows:
- 0 The default configuration is used. Conpack calls SET with:
CALL SET (.05, .95, .05, .95, WDL, WDR, WDB, WDT, 1)
- where WDL, WDR, WDB, and WDT are the left, right, bottom, and top window boundaries. CPBACK is called to draw a perimeter.
- <0 The contour plot fills the current viewport. First, Conpack calls GETSET, then SET:
CALL GETSET (VPL, VPR, VPB, VPT, ...)
CALL SET (VPL, VPR, VPB, VPT, WDL, WDR, WDB, WDT, 1)
- where VPL, VPR, VPB, and VPT are the left, right, bottom, and top viewport boundaries and where WDL, WDR, WDB, and WDT are the left, right, bottom, and top window boundaries. CPBACK is not called to draw a perimeter.
- >0 Conpack does not call SET. It is assumed that you have either called SET directly, or that you have called a utility that calls SET (such as Ezmap). CPBACK is not called to draw a perimeter. This option should be used to overlay contours on an existing background.
- NHGH
- Integer, Input---Determines whether highs, lows, and data points are to be labeled as follows:
- 0 Each high is marked with an "H", and each low is marked with an "L". The value of the point is written as a subscript to the "H" or the "L".
- >0 Each data point is marked with the value at that point. No attempt is made to deal with overlapping labels, so this option results in a mess on very dense data. Parameters HLA and HLS affect label angle and size.
- <0 No high, low, or data points are labeled.
- NDSH
- Integer, Input---Specifies the dash pattern(s) to be used for drawing contour lines. ABS(NDSH) is the decimal value for the 10-bit dash pattern to be used. Conpack makes this dash pattern into a 16bit pattern by appending a copy of the high-order six bits.
- 0 or 1 or 1023
Solid lines are used for all contour lines.
- >0 The specified dash pattern is used for all contour lines (except for special values 1 and 1023).
- <0 The dash pattern is used only for contour lines with negative values.
The ccpcnrc.f code segment and its plot show that a single call to CPCNRC gives you a considerable amount of control over black-and-white plots.
The first four arguments for CPCNRC are the data array and its dimensions. The fifth and sixth arguments limit the contour lines to be drawn between -40. and 50, and the seventh argument sets the contour interval to 10.
The eighth argument gives NSET the value of zero to produce the default background. The ninth argument sets NHGH to zero, causing highs and lows to be labeled in the style shown.
The final argument sets a negative value for NDSH; this plots contour lines with negative values using dashed lines, and it plots contour lines with a zero or a positive value using solid lines. To set NDSH, first create the dash pattern of your choice using a ten-bit binary string where 0 represents a space and 1 represents a dash. The ccpcnrc example started with the number 01011011102; this was then converted to 36610 and used as a negative value for NDSH. This NDSH value specifies the string 01011011100101102 because the first six bits of the 10-bit binary string are copied and added to the end to create a 16-bit string.
- Use CPCNRC to contour your data. Use the default line type and label highs and lows.
- Using ccpcnrc.f, try changing the dash pattern a few times.
Conpack programs usually have a very similar structure. Parameters are usually set first, Conpack must be initialized, labels drawn, contours drawn, and a background added.
Important note: The sequence of calls presented in this Conpack functional outline and shown throughout this Conpack tutorial is commonly used. This approach speeds new users' learning of this sometimes complex material; it does not specify the only way you can use Conpack. As you gain experience using Conpack, you will probably have creative insights that will allow you to achieve a wide variety of results.
This is one of the strengths of Conpack: the order of the calls can be varied to achieve different results in your output plots. When you fill contours with solid colors (called solid fill), you need to draw the background after the fill so the background grid overwrites the fill colors and not vice versa. In other cases, it may be useful to call the background-drawing routine CPBACK before making other drawing calls.
----------------------------------------------------------
* 1. Open GKS
2. Set window and viewport
3. Put in titles and other labels
4. Set up general parameters
5. Set up area maps
* 6. Initialize Conpack
7. Force Conpack to choose contour levels if necessary
8. Modify Conpack-chosen parameters
9. Draw labels
* 10. Draw background
* 11. Draw contour lines
* 12. Call FRAME
* 13. Close GKS
----------------------------------------------------------
* Steps needed to produce a contour plot.
One of the most common user problems is making Conpack calls in an incorrect order. Since Conpack requires information in a nonintuitive order, this tutorial discusses Conpack routines in an order designed to help you learn them.
For example, Conpack usually uses the dimensions of your data to determine what shape to draw the rectangle around your contours (the contour rectangle). So you can't ask Conpack to draw a perimeter around your contours until it has your data. However, most of us think about drawing the boundary of a plot before drawing contours in it. Therefore, this tutorial first discusses drawing contour rectangles and other backgrounds for Conpack before it discusses Conpack initialization, which is typically the first Conpack call in a program.
The following lines are highlighted in the Conpack functional outline:
- Open GKS
- Initialize Conpack
- Draw background
- Draw contour lines
- Call FRAME
- Close GKS
These lines show the absolute minimum calls that must be made to draw a plot with Conpack. Both CPEZCT and CPCNRC make the Conpack calls for you. The lines without asterisks in the functional outline show proper placement of frequently desired calls that are not required.
Because opening GKS, closing GKS, and clipping are discussed in the NCAR Graphics Fundamentals guide, they are discussed only very briefly here. GKS must be opened and closed for every CGM file---these calls are included in the Conpack functional outline as a reminder that graphics code does not run without them.
Conpack can be initialized with one of the three routines CPRECT,
CPSPS1, or CPSPS2, depending on the type of data to be contoured.
Section "Cp 3. Initializing Conpack"
describes each type of data and the appropriate method for
initializing Conpack in each case.
Contour lines are drawn with either a call to CPCLDR or CPCLDM. If you just want to draw contour lines, use CPCLDR. If you want to protect your labels from being drawn over by contour lines, or if you need to use Areas for some other reason, use CPCLDM.
As discussed in the NCAR Graphics Fundamentals guide, FRAME is an SPPS routine that flushes all the buffers and closes a frame so that you can either quit NCAR Graphics or draw another picture. FRAME must be called to finish a Conpack plot, and it is included in the Conpack functional outline as a reminder that you must always call it.
Conpack relies heavily on parameters and parameter-setting routines. Parameter-setting options allow you to specify all aspects of your contour plot. Seven routines help you set and retrieve parameter values, and the Parameter Array Index (PAI) helps you access individual elements in parameter arrays. The illustration shows how PAI accesses the sixth element in the Conpack parameter arrays.
The first argument in a call to CPGETI, CPSETI, CPGETR, CPSETR, CPGETC, or CPSETC is the parameter name. The second argument is either a variable in which the value of the named parameter is to be returned (via CPGETx) or an expression specifying the desired new value of the parameter (via CPSETx).
CALL CPGETC (PNAM, CVAL)
CALL CPGETI (PNAM, IVAL)
CALL CPGETR (PNAM, RVAL)
CALL CPSETC (PNAM, CVAL)
CALL CPSETI (PNAM, IVAL)
CALL CPSETR (PNAM, RVAL)
CALL CPRSET
- CPGETC
- Retrieves character parameter information.
- CPGETI
- Retrieves integer parameter information.
- CPGETR
- Retrieves real parameter information.
- CPSETC
- Sets character parameters.
- CPSETI
- Sets integer parameters.
- CPSETR
- Sets real parameters.
- CPRSET
- Resets all parameters to their initial default values.
- PNAM
- Character expression, Input---The name of the parameter that you want to set or retrieve. Three-character parameter names appear in examples and discussions in place of PNAM. The parameter names and their meanings are enclosed in single quotation marks in the Fortran code to ensure that they are treated as character expressions rather than real or integer variables. Only the first three characters within the quotation marks are examined.
- CVAL
- Character expression, Input or Output---A character string or character variable.
- IVAL
- Integer, Input or Output---An integer value or integer variable.
- RVAL
- Real, Input or Output---A real value or real variable.
In the Conpack functional outline, note that Conpack parameters are set before Conpack is initialized. Unless you are modifying Conpack-chosen parameters, it is always best to set your parameters before the initialization subroutine is called.
The CPRSET subroutine allows you to quickly reset all of the Conpack parameters to their default values between contour plots.
Some of the parameters are not simple integers or reals, but arrays. To access an individual element of a specific parameter array, you can specify individual elements using PAI (Parameter Array Index). For example, to set the ith element of the CLV array, first set PAI=I, then set CLV to the desired value, let's say 0.25:
CALL CPSETI ('PAI', I)
CALL CPSETR ('CLV', .25)
These calls set the ith contour level value to 1/4.
As individual parameters are described, examples of the CPSETx and CPGETx routines are shown, and the parameters that require CPSETx or CPGETx routine calls are clearly indicated.
Some parameters are described as Fortran type integer, or as integer arrays. These values can be set using:
CALL CPSETI ('PAR', ipar)
or
CALL CPSETR ('PAR', REAL(ipar))
where PAR is some integer parameter and ipar represents its integer value.
You can also set a real parameter using:
CALL CPSETI ('XXX', ival)
if the desired value is REAL(ival).
Caution: To avoid a common user problem, be sure to double-check your GET and SET calls to ensure that you don't mix integer and real parameters.
Conceptually, the first thing that you want to do with your plot is to set up a background, so drawing backgrounds is discussed first. Because backgrounds are rarely drawn first when using Conpack, the functional outline below provides you with a suggested location in your code for background drawing. In later sections, the background drawing occurs in different places in the code. Later sections also demonstrate some techniques for producing the results you want.
Note: The Gridall or Autograph utilities are often used to draw backgrounds for Conpack; these calls can be made before you initialize Conpack.
----------------------------------------------------------
1. Open GKS
2. Set window and viewport
3. Put in titles and other labels
* 4. Set up general parameters
5. Set up area maps
6. Initialize Conpack
7. Force Conpack to choose contour levels if necessary
8. Modify Conpack-chosen parameters
9. Draw labels
* 10. Draw background
11. Draw contour lines
12. Call FRAME
13. Close GKS
----------------------------------------------------------
* Steps discussed in this section.
Conpack offers an option for drawing a simple perimeter. You can also use Ezmap to draw maps with geographical and/or political outlines, Gridall to draw perimeters, axes, and grids, or Autograph for alternative backgrounds.
Conpack is designed to allow you to use most other utilities to draw backgrounds for your contour plot. This flexibility requires you to understand the SPPS routine SET, the Conpack parameter SET, and how other Conpack parameters affect the SET call.
The illustration shows how the coordinate system of your data (the user coordinate system) is mapped first into a window, then into the viewport (a portion of your display screen). Before any graphics can be drawn, the window, viewport, and the transformation between them must be set up so that everything can be drawn correctly.
The best way to set up the window, the viewport, and the transformation in NCAR Graphics is to call the SPPS routine SET. SET sets up the normalization transformation between the user coordinate system and the normalized device coordinate (NDC) system of the viewport. In other words, you call the SPPS routine SET to tell the graphics package the limits of your data space and where on the screen or paper you want your plot to be drawn.
Conpack has 15 different internal parameters that directly affect how Conpack makes a SET call: VPL, VPR, VPB, VPT, VPS, WDL, WDR, WDB, WDT, XC1, XCM, YC1, YCN, SET, and MAP.
The simplest background you can make is to draw a perimeter around
your plot using the Conpack routine CPBACK. This does not require you
to use any of the above parameters. By default, CPBACK calls the SPPS
routine SET for you. This option is covered in module "Cp 2.2 Drawing a contour perimeter."
The next easiest background you can make is to use XC1, XCM, YC1, and
YCN to define the X and Y coordinates of your data in the user
coordinate system. In this case, you probably want to let Conpack call
the SPPS routine SET for you. This option is covered in module "Cp 2.3 Setting X/Y axis values for a contour
background."
If you are drawing a map background with Ezmap, you need to follow the
Ezmap chapter to set up your map. After the map background is
initialized, you can tell Conpack to overlay your data on a map by
setting the MAP parameter, then by setting your minimum and maximum
latitude and longitude data locations using XC1, XCM, YC1, and YCN. In
this case, Ezmap calls the SPPS routine SET for you, so you must tell
Conpack that SET has already been called; you do this by setting the
Conpack parameter SET. This option is covered in detail in module "Cp 3.8 Non-Cartesian data: Latitude/longitude
data."
One of the most complex things that you can do with these options is to use a transformation to map your data to some other place on the plane by setting the Conpack parameter MAP. Then you might set XC1, YC1, XCM, YCN, WDB, WDT, WDL, and WDR to direct the drawing of contours in the window that you define. Setting the window parameters is very similar to setting the viewport parameters; see module "Cp 2.6 Contour perimeter: Size, shape, and location using Conpack."
Occasionally, you may want to use another utility with Conpack, or you may want to call SET yourself. In this case, you simply set the Conpack parameter SET to zero, then make your call to the SPPS routine SET. This option is covered in module "Cp 2.7 Contour perimeter: Size, shape, and location using SET."
In all of the above situations where Conpack calls SET, you can set VPL, VPR, VPB, and VPT to move the plot around on the plotter frame, and you can use VPS to define the desired proportions of your contour plot. Moving your plot around on the plotter frame and changing its proportions is covered in module "Cp 2.6 Contour perimeter: Size, shape, and location using Conpack."
The Conpack routine CPBACK draws a perimeter around your plot only if you want the simple default rectangle. By default, CPBACK calls the SPPS routine SET for you. If you are using any mapping functions by setting the MAP parameter, or if you want labels for your tick marks, you need to draw your own perimeter using another NCAR Graphics utility such as Gridall.
1 CALL CPRECT (Z, K, M, N, RWRK, LRWK, IWRK, LIWK)
2 CALL CPBACK (Z, RWRK, IWRK)
CALL CPBACK (Z, RWRK, IWRK)
All three arguments to the CPBACK call are the arrays used in the last call to CPRECT, CPSPS1, or CPSPS2, the contents of which must not have been changed since that call.
- Z
- Real array, Input---The data array.
- RWRK
- Real array, Workspace---The real workspace array. The dimensions of RWRK are set by CPRECT, CPSPS1, or CPSPS2.
- IWRK
- Integer array, Workspace---The integer workspace array. The dimensions of IWRK are set by CPRECT, CPSPS1, or CPSPS2.
By default, CPBACK calls the SPPS routine SET. Then it calls the Gridall routine PERIM to draw the perimeter. Modules "Cp 2.4 Changing perimeter options" and "Cp 2.5 Labeling X/Y axis values for a contour background" demonstrate how you can call Gridall directly to draw a perimeter and label tick marks.
Line 1 of the ccpback.f code segment initializes Conpack with a call to CPRECT. This call is thoroughly discussed in module "Cp 3.2 Dense gridded data" and is mentioned here as a reminder that CPBACK must not be called before initializing Conpack. Line 2 calls CPBACK to draw a perimeter around the contours (contours are not drawn in this example).
Perimeter attributes such as line width, line pattern, line color, and so forth can be changed with the same parameters you use with contour lines. Please see the line attributes modules Cp 4.11 through Cp 4.14.
If you have non-Cartesian data, you need to set the MAP parameter to some nonzero value by using the CPSETI routine. Setting the MAP parameter has the side effect of causing CPBACK to do nothing. Hence, if you have non-Cartesian data, and you want a perimeter around your plot, you need to draw it with the GKS routine GPL, the Dashline routine CURVED, the Gridall utility, or the Autograph utility.
When plotting real data, it is often necessary to know what portion of the X/Y plane your data cover. Conpack has four parameters that set minimum and maximum values for X and Y. The following illustrations show the relationship between the Cartesian plane and data array indices.
CALL CPSETR ('XC1', XMIN)
CALL CPSETR ('XCM', XMAX)
CALL CPSETR ('YC1', YMIN)
CALL CPSETR ('YCN', YMAX)
- XC1
- Real---The X Coordinate at index 1 parameter is the X coordinate value that corresponds to a value of 1 for the first subscript of the data array. Alternatively, you can think of XC1 as being the leftmost X data location. If XC1=XCM, then XC1 gets the value 1.0.
- XCM
- Real---The X Coordinate at index M parameter is the X coordinate value that corresponds to a value of 'ZDM' for the first subscript of the data array. Alternatively, you can think of XCM as the rightmost X data location. If XC1=XCM, then XCM gets the value REAL(ZDM), where ZDM is the first dimension of the array of dense gridded or interpolated data to be contoured.
- YC1
- Real---The Y Coordinate at index 1 parameter is the Y coordinate value that corresponds to a value of 1 for the second subscript of the data array. Alternatively, you can think of YC1 as being the bottom Y data location. If YC1=YCN, then YC1 gets the value 1.0.
- YCN
- Real---The Y Coordinate at index N parameter is the Y coordinate value that corresponds to a value of 'ZDN' for the second subscript of the data array. Alternatively, you can think of YCN as the top Y data location. If YC1=YCN, then YCN gets the value REAL(ZDN), where ZDN is the second dimension of the array of dense gridded or interpolated data to be contoured.
The preceding parameters associate X and Y data locations with the subscripts of your Z data array. By default, the lower left corner of the plot is at (1.0, 1.0), and the upper right corner of the plot is at (REAL(ZDM), REAL(ZDN)), where ZDM and ZDN represent the X and Y dimensions of the data array respectively.
In the default mapping illustration, note that XC1=1.0, XCM=REAL(m), YC1=1.0, and YCN=REAL(n). Also notice how the usual drawing of the Z array is rotated into the Cartesian plane.
In the user mapping illustration, the user sets XC1=0.25, XCM=m/4.0, YC1=50, and YCN=50*n. In this case, the data are both translated on the X/Y plane and stretched to fit. Any real values for XC1, XCM, YC1, and YCN are allowable, making any translation from a data array to the Cartesian plane possible.
In cases where XC1>XCM, the mapping will be mirror imaged in the X direction.
In cases where YC1>YCN, the mapping will be mirror imaged in the Y direction.
You can label tick marks or change the sizes and spacing of the tick marks on your perimeter, but these functions are not available from Conpack. You must use the Gridall utility to change the appearance of perimeter tick marks.
1 CALL CPSETR ('XC1 - X COORDINATE AT INDEX 1', 2.0)
2 CALL CPSETR ('XCM - X COORDINATE AT INDEX M', 20.0)
3 CALL CPSETR ('YC1 - Y COORDINATE AT INDEX 1', 0.0)
4 CALL CPSETR ('YCN - Y COORDINATE AT INDEX N', .01)
5 CALL CPRECT (Z, K, M, N, RWRK, LRWK, IWRK, LIWK)
6 CALL LABMOD ('(E7.2)', '(E7.2)', 0, 0, 10, 10, 0, 0, 1)
7 CALL GRIDAL (K-1, 0, N-1, 0, 1, 1, 5, 0., 0.)
CALL GRIDAL (MJRX, MNRX, MJRY, MNRY,IXLB, IYLB, IGPH, XINT, YINT)
- MJRX
- Integer, Input---The number of major divisions (spaces between tick marks) in the X axes.
- MNRX
- Integer, Input---Determines the number of minor divisions in the X axes.
- MJRY
- Integer, Input---The number of major divisions in the Y axes.
- MNRY
- Integer, Input---Determines the number of minor divisions in the Y axes.
The meanings of these arguments depend on the current setting of the linear/log flag in SPPS. This flag is set by the final argument in the SET call.
If the axis is linear, MJRX specifies the number of major divisions of the X/Y axis, and MNRX specifies the number of minor divisions within each major division. These values specify the number of spaces between GRIDAL lines or ticks, not the number of lines or ticks. Counting those at the ends, there is always one more major tick than the number of major divisions specified by MJRX. There is always one less minor tick than the number of minor divisions specified by MNRX.
If the axis is logarithmic, major division points occur at a value 10MJRX times the previous point. So if the minimum and maximum X-axis values are 3. and 3000., and MJRX is 1, then the major division points are 3., 30., 300., and 3000. If MNRX<=10, nine minor divisions occur between major divisions. For example, between 3. and 30., there would be minor division points at 6., 9., 12., 15., 18., 21., 24., and 27. If MNRX>10., minor divisions are omitted.
- IXLB
- Integer, Input---Specifies X-axis appearance.
- -1 No X axis is drawn. No X-axis labels.
- 0 X axis is drawn. No X-axis labels.
- 1 X axis and X-axis labels are drawn.
- IYLB
- Integer, Input---Specifies Y-axis appearance.
- -1 No Y axis is drawn. No Y-axis labels.
- 0 Y axis is drawn. No Y-axis labels.
- 1 Y axis and Y-axis labels are drawn.
- IGPH
- Integer, Input---Specifies the background type as indicated by one of the following integers:
--------------------------
IGPH X axis Y axis
--------------------------
0 grid grid
1 grid perimeter
2 grid axis
4 perimeter grid
5 perimeter perimeter
6 perimeter axis
8 axis grid
9 axis perimeter
10 axis axis
--------------------------
- XINT,YINT
- Real, Input---The user "world" coordinates of the point of intersection of the two axes when IGPH equals 10. For other values of IGPH for which one of the axes is the axis type, XINT and/or YINT specifies the position of that axis.
Lines 1 through 4 of the ccpga.f code segment set the minimum and maximum X and Y locations for the data using Conpack routine CPSETR. In line 5, CPRECT takes these data locations and uses them to make a SET call that can be used by GRIDAL. The GRIDAL call in line 7 sets the number of major tick marks to one less than the number of rows and columns in the data array to simulate the results of CPBACK and to denote locations of data values. MNRX and MNRY are set to zero to turn off the minor tick mark option and mimic CPBACK. IXLB and IYLB are set to 1 to draw and label X and Y axes, and IGPH is set to 5 to draw a perimeter around the contours. Since we are drawing a perimeter, XINT and YINT are dummy parameters. The next module discusses the effect of line 6.
If you are drawing a contour plot in Cartesian space, there are several ways to label your X/Y axes, and to change options on your tick marks, none of which involve Conpack. The easiest method is to use the two Gridall routines GRIDAL and LABMOD to draw and label your perimeter.
1 CALL CPSETR ('XC1 - X COORDINATE AT INDEX 1', 2.0)
2 CALL CPSETR ('XCM - X COORDINATE AT INDEX M', 20.0)
3 CALL CPSETR ('YC1 - Y COORDINATE AT INDEX 1', 0.0)
4 CALL CPSETR ('YCN - Y COORDINATE AT INDEX N', .01)
5 CALL CPRECT (Z, K, M, N, RWRK, LRWK, IWRK, LIWK)
6 CALL LABMOD ('(E7.2)', '(E7.2)', 0, 0, 10, 10, 0, 0, 1)
7 CALL GRIDAL (K-1, 0, N-1, 0, 1, 1, 5, 0., 0.)
CALL LABMOD (FMTX, FMTY, NUMX, NUMY, ISZX, ISZY, IXDC, IYDC, IXOR)
- FMTX
- Character expression, Input---Contains format specifications for the X-axis numerical labels produced by the Gridall routine GRIDAL. The specification must begin with a left parenthesis and end with a right parenthesis, and it must not be more than ten characters long. Conversions of types E, F, G, and I are allowed; for example, you might use (F8.2). The default is (E10.3).
- FMTY
- Character expression, Input---Contains format specifications for the Y-axis numerical labels produced by GRIDAL. The specification must begin with a left parenthesis and end with a right parenthesis, and it must not be more than ten characters long. Conversions of types E, F, G, and I are allowed; for example, you might use (E10.0). The default is (E10.3).
- NUMX
- Integer, Input---The number of characters in each X-axis numeric label.
- 0 The label is the substring LBLX(m:n), where LBLX(m:m) is the first nonblank character in LBLX, and LBLX(n:n) is the last nonblank character following LBLX(m:m). This is the default.
- <>0 The number of characters in each X-axis numeric label; if LBLX is a string produced by the format FMTX, then the label is the substring LBLX(1:NUMX). This causes the labels to be centered differently than if a zero value is used.
- NUMY
- Integer, Input---Same as NUMX, except it is used for Y-axis labels.
- ISZX, ISZY
- Integer, Input---Character sizes for the labels, specified in 1024ths of a screen width, just as for the SPPS routine WTSTR. The special values of 0, 1, 2, and 3 produce very small, small, medium, and large character sizes. The default value for both is 10, which means 10/1024ths of a screen width.
- If you have called SETI, ISZX and ISZY are not 1024ths of a screen width, they are some other fraction of a screen width as determined by the arguments of SETI.
- IXDC
- Integer, Input---The distance, in 1024ths of a screen width, from the left edge of the current viewport to the label specified by FMTY, NUMY, and ISZY. There are two special values for IXDC:
- 0 The Y-axis labels end 20/1024ths of a screen width from the left of the viewport. This is equivalent to setting IXDC=20.
- 1 Y-axis labels begin 20/1024ths of a screen width from the right of the viewport. This is equivalent to setting IXDC=20w, where w/1024 is the width of the viewport in NDCs.
- The default value is 20.
- Negative values of IXDC specify the distance from the right edge of the viewport.
- When GRIDAL is called with IGPH=2, 6, or 10, IXDC is the distance from the Y axis, rather than from the minimum viewport coordinate, and the special values 0 and 1 are equivalent to 20 and 20.
- IYDC
- Integer, Input---The distance, in 1024ths of a screen width, from the bottom edge of the current viewport to the label specified by FMTX, NUMX, and ISZX. There are two special values for IYDC:
- 0 The X-axis labels end 20/1024ths of a screen width (0.02 NDCs) below the viewport. This is equivalent to setting IYDC=20.
- 1 The X-axis labels begin 0.02 NDCs above the viewport. This is equivalent to setting IYDC=20h, where h/1024 is the height of the viewport in NDCs.
- The default value is 20.
- Negative values of IYDC specify the distance from the top edge of the viewport.
- When GRIDAL is called with IGPH=8, 9, or 10, IYDC is the distance from the X axis, rather than from the minimum viewport coordinate, and the special values 0 and 1 are equivalent to 20 and 20.
- IXOR
- Integer, Input---Specifies the orientation of the X-axis labels.
- 0 Horizontal. This is the default.
- 1 Vertical.
Line 6 of the ccpga.f code segment sets FMTX and FMTY using a good numerical format for the X and Y axis values. NUMX and NUMY are set to 0 to produce a simple numeric label. ISZX and ISZY are set to 10 to show off the labels. IXDC and IYDC are set to the default 0 because label location is not critical here, and IXOR is set to 1 so that X-axis labels don't overlap. Further discussion of the LABMOD routine appears in Chapter 15 "Drawing axes, perimeters, and grids" of the NCAR Graphics Fundamentals guide.
It is often desirable to put more than one contour plot on a page, or to change the size of a contour plot so that it can fit into a publication. Conpack offers four parameters, VPL, VPR, VPB, and VPT, to allow you to place the contour plot anywhere on the plotter frame. A fifth parameter, VPS, allows you to specify the shape of your contour rectangle.
1 CALL CPSETR ('VPL - VIEWPORT LEFT', 0.02)
2 CALL CPSETR ('VPR - VIEWPORT RIGHT', 0.48)
3 CALL CPSETR ('VPB - VIEWPORT BOTTOM', 0.52)
4 CALL CPSETR ('VPT - VIEWPORT TOP', 0.98)
5 CALL CPSETR ('VPL - VIEWPORT LEFT', 0.52)
6 CALL CPSETR ('VPR - VIEWPORT RIGHT', 0.98)
7 CALL CPSETR ('VPB - VIEWPORT BOTTOM', 0.52)
8 CALL CPSETR ('VPT - VIEWPORT TOP', 0.98)
9 CALL CPSETR ('VPS - VIEWPORT SHAPE', -0.33)
10 CALL CPSETR ('VPL - VIEWPORT LEFT', 0.02)
11 CALL CPSETR ('VPR - VIEWPORT RIGHT', 0.48)
12 CALL CPSETR ('VPB - VIEWPORT BOTTOM', 0.02)
13 CALL CPSETR ('VPT - VIEWPORT TOP', 0.48)
14 CALL CPSETR ('VPS - VIEWPORT SHAPE', -1.5)
CALL CPSETR ('VPL', vpl)
CALL CPSETR ('VPR', vpr)
CALL CPSETR ('VPB', vpb)
CALL CPSETR ('VPT', vpt)
CALL CPSETR ('VPS', vps)
- VPL, VPR, VPB, VPT
- Real---The ViewPort Left, ViewPort Right, ViewPort Bottom, and ViewPort Top parameters, respectively. These parameters specify a rectangle within which the viewport is to be placed. They are always in Normalized Device Coordinate (NDC) units. In other words: 0.0<=VPL, VPR, VPB, VPT<=1.0. By default, VPL=VPB=.05, and VPR=VPT=.95.
- VPS
- Real---The ViewPort Shape parameter is used only when Conpack calls the SPPS routine SET (that is, when the Conpack parameter SET<>0). VPS specifies viewport shape as follows:
- <0.0
Specifies the exact shape of the contour rectangle. ABS(VPS) = width / height, where width is the desired width of the rectangle and height is the desired height of the rectangle.
- 0.0
Specifies a contour rectangle completely filling VPL, VPR, VPB, and VPT.
- 0<VPS<1
Specifies a plot of the shape determined by XC1, XCM, YC1, and YCN, reverting to the shape specified by VPL, VPR, VPB, and VPT if the ratio of the shorter side to the longer side would be less than the value specified. By default, VPS=0.25.
- >=1.0
Specifies a plot of the shape determined by XC1, XCM, YC1, and YCN, reverting to a square if the ratio of the longer side to the shorter side would be greater than VPS.
- Whatever its shape, the contour rectangle is made as large as possible and centered in the viewport specified by VPL, VPR, VPB, and VPT.
The viewport parameters are only used when the Conpack parameter SET<>0, so that Conpack calls the SPPS routine SET.
In the ccpvp.f program, there are calls to Conpack routines that draw contours between lines 4 and 5, lines 9 and 10, and lines 14 and 15 of the code segment. Lines 1 through 4 of the ccpvp.f code segment set up the viewport so that the first plot is drawn in the upper left corner. Lines 5 through 8 put the second plot in the upper right corner. Line 9 specifies a contour rectangle three times as high as it is wide.
Lines 10 through 13 tell Conpack to draw contours in the lower left corner, and line 14 specifies a contour rectangle wider than it is tall. This contour drawing uses rho/theta data; this is why it draws contours in a wedge rather than a square.
Contours in the lower right corner are drawn without setting VPR, VPL, VPB, or VPT because the viewport is set up by Ezmap.
- Give each contour rectangle in the ccpvp example a different shape using each of the different range values of VPS.
- Change the viewports so that the contour rectangles overlap by a small amount in the center of the plot.
- Make each plot display full size on a different frame.
The second way to adjust contour perimeter size, shape, and location is to use the SPPS routine SET. By default, Conpack uses a rectangle of the shape implied by the dimensions of your data array, and makes that rectangle as large as possible within the viewport. Occasionally, when your data array defines a long, narrow rectangle, Conpack will use the entire viewport as the contour rectangle. You can call the SPPS routine SET directly to define the location, shape, and size of the contour rectangle.
1 CALL SET (0.5, 0.98, 0.125, 0.375, 0., 2., 0., 1., 1)
2 CALL CPSETI ('SET - DO-SET-CALL FLAG', 0)
3 CALL CPSETR ('XC1 - X COORDINATE AT INDEX 1', 0.)
4 CALL CPSETR ('XCM - X COORDINATE AT INDEX M', 2.)
5 CALL CPSETR ('YC1 - Y COORDINATE AT INDEX 1', 0.)
6 CALL CPSETR ('YCN - Y COORDINATE AT INDEX N', 1.)
7 CALL CPRECT (Z, K, M, N, RWRK, LRWK, IWRK, LIWK)
8 CALL CPBACK (Z, RWRK, IWRK)
9 CALL CPCLDR (Z, RWRK, IWRK)
CALL CPSETI ('SET', iset)
CALL SET (VL, VR, VB, VT, WL, WR, WB, WT, LS)
- SET
- Integer---The doSETcall flag is a Conpack parameter that determines whether you call the SPPS routine SET or Conpack calls SET for you.
- 0 Conpack does not call SET. When you call SET, arguments 5 through 8 (the window coordinates) must be consistent with the range of coordinates specified by MAP, XC1, XCM, YC1, and YCN.
- 1 A Conpack initialization routine calls SET. This is the default.
- VL, VR, VB, VT
- Real, Input---These arguments for the SPPS routine SET are values that define the left, right, bottom, and top edges of the viewport or a rectangle in NDC units. These coordinates determine where the plot is placed on your output device. These are values between 0.0 and 1.0, inclusive.
- WL, WR, WB, WT
- Real, Input---These arguments for the SPPS routine SET are values that define the left, right, bottom, and top edges of a window or rectangle in the user coordinate system. These coordinates determine what part of your data is visible in the plot.
- LS
- Integer, Input---This argument for the SPPS routine SET specifies linear/logarithmic mapping options for the X and Y axes:
- 1 X linear, Y linear
- 2 X linear, Y logarithmic
- 3 X logarithmic, Y linear
- 4 X logarithmic, Y logarithmic
The SPPS routine SET is described more thoroughly in the NCAR Graphics Fundamentals guide. SET allows for logarithmic scaling with the LS argument, and mirror imaging by swapping the values for the bottom and top or the left and right window arguments. If you want to use log scaling in your contour plot, or if you want to use some other utility before drawing your contours, then you may need to call SET directly. Before calling SET yourself, you should study the section "Cp 2. Backgrounds for your plots" to gain a clear understanding of how Conpack interacts with the SET routine.
The call to SET in line 1 of the ccpset.f code segment defines the portion of the plotter frame used for the plot. Line 2 uses the Conpack parameter SET to tell Conpack that subroutine SET has already been called. Lines 3 through 6 place the contour rectangle in the X/Y plane. XC1, XCM, YC1, and YCN are the same as WL, WR, WB, and WT in the SET call because this is where user coordinates are defined for Conpack and SET. Contours are then initialized and drawn normally. Because CPRECT, CPSPS1, and CPSPS2 all use information specified in the CPSETx calls, it is best to set general parameters before calling the Conpack initialization routines.
- Run the ccpset example to produce a copy of ccpset.f, then modify it to move the contour rectangle into the upper left corner of the frame.
- Modify ccpset.f so that the plot fills the whole frame, and have Conpack draw in a square contour rectangle.
- In ccpset.f, comment out the line:
CALL CPSETI ('SET', 0)
and explain the results.
The way you initialize Conpack is highly dependent on the type of data you have. Fortunately, after determining your data type, you can initialize Conpack with a single subroutine call as one of the first steps to produce your contour plot.
----------------------------------------------------------
1. Open GKS
2. Set window and viewport
3. Put in titles and other labels
4. Set up general parameters
5. Set up area maps
* 6. Initialize Conpack
7. Force Conpack to choose contour levels if necessary
8. Modify Conpack-chosen parameters
9. Draw labels
10. Draw background
11. Draw contour lines
12. Call FRAME
13. Close GKS
----------------------------------------------------------
* Steps discussed in this section.
Before Conpack can draw anything, it must know what kind of data you have. In some cases you must do some preprocessing to get your data into an acceptable form. The next several modules discuss initializing Conpack with the following data types. Decide what kind or kinds of data you have, then turn to the relevant modules.
Dense gridded data Sparse gridded data
Irregularly spaced gridded data Missing data
Nongridded data
Non-Cartesian data Non-Cartesian data
Dense gridded data implies that you have data points at regular intervals on a rectangular grid. If you have dense gridded data, you should use CPRECT to initialize Conpack.
Sparse gridded data implies that you have data points on a rectangular grid, but that the grid has large spacing between gridlines. This is the effect of having a tick-tack-toe grid versus 1/4-inch graph paper. If you were to contour your data using CPRECT, you would find that the contours were long straight line segments that join with sharp corners at data points. CPSPS1 is a smoother that interpolates your data onto a dense grid, and initializes Conpack.
Generally, if your data set has less than 35 data points in either direction, it is better to use CPSPS1. However, this distinction is very subjective. Most modelers define "sparse" for global datasets as a spacing of 2 degrees or more between data points.
Irregularly spaced gridded data is frequently gathered by satellites, or generated by large models. In essence, the data lie on a grid, but the grid may have very wide spacing in some places and very narrow spacing in others. Because CPSPS2 interpolates from the irregular grid onto a regular grid, it doesn't matter if your data are sparse or dense.
Nongridded data, or randomly spaced data, has no relationship to a grid at all. The effect is as if you took a handful of rice and tossed it down on a piece of paper, then used the locations of the rice grains as your data points. Before Conpack can use this kind of data, you must interpolate the data onto a grid.
Bivar, an interpolation package that works with Conpack, is distributed with NCAR Graphics. Bivar can be used on data that do not have abrupt changes (like ridges or cliffs on a topographic map). In other words, Bivar assumes that the function describing the data has a continuous first derivative. If your data do not fit this description, or if you have an interpolation package that fits your data better, don't use Bivar.
Missing data points can occur in any gridded data; this has no bearing on which of the initialization routines are used. All that is necessary is to use the SPV parameter to tell Conpack what data value signals a missing data point.
Non-Cartesian data are data that do not lie on an X/Y coordinate plane. Conpack has transformations for latitude/longitude data, and for polar coordinate data. Conpack also has a mechanism for dealing with other kinds of data.
Latitude/longitude data is fairly common, and Conpack is designed so that it is easy to overlay lat/lon data over a map.
Conpack can also easily be used to display polar coordinate data, using a method similar to the lat/lon display method.
Almost any data that can be transformed into data on a rectangular grid can be contoured by Conpack by writing a transformation, and adding it to the CPMPXY subroutine provided by Conpack.
Dense gridded data implies that you have data points at regular intervals on a rectangular grid. If you have dense gridded data, you should use CPRECT to initialize Conpack. CPRECT initializes the internal pointers that are used to manage workspace; it decides appropriate ranges for X and Y coordinates used to draw contour lines.
1 CALL CPRECT (Z, M, M, N, RWRK, LRWK, IWRK, LIWK)
2 CALL CPBACK (Z, RWRK, IWRK)
3 CALL CPCLDR (Z, RWRK, IWRK)
4 CALL MARK (M, N)
CALL CPRECT (Z, K, M, N, RWRK, LRWK, IWRK, LIWK)
- Z(K,n)
- Real array, Input---The array of data values to be contoured. Z is dimensioned K by n, where n>=N.
- K
- Integer, Input---The first dimension of the array Z.
- M
- Integer, Input---The first dimension of the array of data in Z. M<=K.
- N
- Integer, Input---The second dimension of the array of data in Z. N<=n, where n is the declared second dimension of the array Z.
- RWRK(LRWK)
- Real array, Workspace---A real work array of length LRWK.
- LRWK
- Integer, Input---The length of RWRK. Generally, a good value to start with is 2500.
- IWRK(LIWK)
- Integer array, Workspace---An integer work array of length LIWK.
- LIWK
- Integer, Input---The length of IWRK. Generally, a good value to start with is 1000.
Line 1 of the ccprect.f code segment initializes Conpack with a call to CPRECT. Notice that the call to CPRECT comes before the call to draw the background with CPBACK in line 2. As discussed in module "Cp 2.2 Drawing a contour perimeter," this is necessary because Conpack uses the data information to decide how to shape the contour rectangle. Line 3 draws contours with CPCLDR. Line 4 marks the data locations with example subroutine MARK.
Occasionally you may see error messages similar to this:
CPGRWS 200 WORDS REQUESTED, 100
WORDS AVAILABLE
CPGIWS 200 WORDS REQUESTED, 100
WORDS AVAILABLE
CPGRWS tells you that your real workspace is too small, and CPGIWS tells you that your integer workspace is too small. Increase LRWK or LIWK to the number of words requested in the error message, and repeat until the error message goes away.
The size of LRWK and LIWK depends on the complexity of your contour plot, so plots with lots of small, tight contour levels require more space than large, loose contour plots like ccprect. If you are running a job with lots of similar plots, and need to minimize workspace, see module "Cp 3.12 Setting minimal workspace" for the most reliable method of optimizing these array sizes.
- Try running the ccprect example using the function:
Z(I,J) = sin(1./real(i*j)) * sin(real(i*j)) *
cos(real(i)/real(j)) + cos(real(i*j))
in subroutine GETDAT instead.
Sparse gridded data implies that you have data points on a rectangular grid, but that the grid has large spacing between gridlines. This is like having a tick-tack-toe grid versus 1/4-inch graph paper. If you contour sparse data with CPRECT, the contours would be long and straight with sharp corners at data points. CPSPS1 is a smoother that interpolates your data onto a dense grid, then initializes Conpack.
1 CALL CPSPS1 (Z, K, M, N, RWRK, LRWK, IWRK, LIWK, ZDAT, LZDT)
2 CALL CPBACK (ZDAT, RWRK, IWRK)
3 CALL CPCLDR (ZDAT, RWRK, IWRK)
4 CALL MARK (X, Y, M, N)
CALL CPSPS1 (ZSPS, K, M, N, RWRK, LRWK, IWRK, LIWK, ZREG, LZRG)
- ZSPS(K,n)
- Real array, Input---The sparse array of data from which the dense array is to be generated. Dimensioned K by n, where n>=N.
- K
- Integer, Input---The first dimension of the array ZSPS.
- M
- Integer, Input---The first dimension of the sparse array of data in ZSPS. M<=K.
- N
- Integer, Input---The second dimension of the sparse array of data in ZSPS. N<=n, where n is the declared second dimension of the array ZSPS.
- RWRK(LRWK)
- Real array, Workspace---The real work array.
- LRWK
- Integer, Input---The length of RWRK. Should be at least
100 * ((NSPV+99)/100) + 3 * M * N + MAX (M + N + N, 4 * IZDM)
- where NSPV is the number of special or missing values in the sparse array, and IZDM is the first dimension of the dense array.
- IWRK(LIWK)
- Integer array, Workspace---Integer work array.
- LIWK
- Integer, Input---The length of IWRK. Should be at least
100 * ((NSPV+99)/100)
- ZREG(LZRG)
- Real array, Output---The densely gridded array to which the interpolated data are returned.
- LZRG
- Integer, Input---The length of ZREG.
Line 1 of the ccpsps1.f code segment initializes Conpack with a call to CPSPS1. Note that this call comes before the call to draw the background with CPBACK in line 2. As discussed in module "Cp 2.2 Drawing a contour perimeter," this is necessary because Conpack uses the data information to decide how to shape the contour rectangle. Line 3 calls CPCLDR with ZDAT, the interpolated data, rather than with the uninterpolated data. Line 4 marks the data locations with example subroutine MARK.
If your sparse array defines a long, narrow rectangle, Conpack chooses a roughly square rectangle of contours for you. It is possible to change this by specifying the dimensions of the interpolated array ZREG, using the parameters ZDS, ZDM, and ZDN. For more information on changing the shape of your contour rectangle, see the contour perimeter modules Cp 2.6 and Cp 2.7.
By default, both CPSPS1 and CPSPS2 use bicubic splines under tension to fit the sparse array data values. The routines used are from Fitpack, by Alan Cline. Spline tension can be changed with the T2D parameter. More information appears in module "Cp 9.1 Smoothing contours."
Occasionally you may see error messages like this:
CPGRWS 200 WORDS REQUESTED, 100
WORDS AVAILABLE
CPGIWS 200 WORDS REQUESTED, 100
WORDS AVAILABLE
CPGRWS tells you that your real workspace is too small, and CPGIWS tells you that your integer workspace is too small. Increase LRWK or LIWK to the number of words requested in the error message, and repeat until the error message goes away.
CPSPS1 cannot extrapolate data beyond the boundaries of the data field.
- Modify the ccpsps1 example so that it calls CPRECT instead of CPSPS1. Notice the differences in the two plots.
Irregularly spaced gridded data is the kind of data most frequently gathered by satellites, or generated by large models. In essence, the data lie on a grid, but the grid may have very wide spacing in some places and very narrow spacing in others. CPSPS2 interpolates from a sparse rectangular grid which is spaced irregularly in X and Y to a dense rectangular grid; it then initializes contouring of the data in the dense grid. CPSPS2 may be viewed as a data-smoothing routine.
1 CALL CPSPS2 (X, Y, Z, M, M, N, RWRK, LRWK, IWRK, LIWK, ZREG, LZRG)
2 CALL CPBACK (ZREG, RWRK, IWRK)
3 CALL CPCLDR (ZREG, RWRK, IWRK)
4 CALL MARK (X, Y, M, N)
CALL CPSPS2 (X, Y, Z, K, M, N, RWRK, LRWK, IWRK, LIWK, ZREG, LZRG)
- X(M)
- Real array, Input---The array of X coordinates of the irregular rectangular grid. These must be in strictly increasing numerical order.
- Y(N)
- Real array, Input---The array of Y coordinates of the irregular rectangular grid. These must be in strictly increasing numerical order.
- Z(K,n)
- Real array, Input---The sparse array of data, from which the dense array is to be generated. Dimensioned K by n, where n>=N.
- K
- Integer, Input---The first dimension of the array Z.
- M
- Integer, Input---The first dimension of the sparse array of data in Z. M<=K.
- N
- Integer, Input---The second dimension of the sparse array of data in Z. N<=n, the declared second dimension of the array Z.
- RWRK(LRWK)
- Real array, Workspace---The real work array.
- LRWK
- Integer, Input---The length of RWRK.
LRWK \xb3 100 * ((NSPV+99)/100) + 3 * M * N + M + N + N)
- where NSPV is the number of special values or missing data points in the sparse array, as determined by the SPV parameter.
- IWRK(LIWK)
- Integer array, Workspace---The integer work array.
- LIWK
- Integer, Input---The length of IWRK.
LIWK >= 100 * ((NSPV+99) / 100)
- ZREG(LZRG)
- Real array, Output---The densely gridded array to which the interpolated data are returned.
- LZRG
- Integer, Input---The length of ZREG. The larger you dimension ZREG, the more interpolated data points will be generated, giving smoother curves.
LZRG = MAX (1600, M * N)
- is a good size to start with.
Line 1 of the ccpsps2.f code segment initializes Conpack with a call to CPSPS2. Notice that the call to CPSPS2 comes before the call to draw the background with CPBACK in line 2. This is necessary because Conpack uses the data information to decide how to shape the contour rectangle. Note that line 3 calls CPCLDR with ZREG, the interpolated data, rather than with the uninterpolated data. Line 4 marks the data locations with example subroutine MARK.
If your sparse array defines a long, narrow rectangle, Conpack chooses a roughly square rectangle of contours for you. It is possible to change this by specifying the dimensions of the interpolated array ZREG, using the parameters ZDS, ZDM, and ZDN. For more information on changing the shape of your contour rectangle, see the contour perimeter modules Cp 2.6 and Cp 2.7.
By default, both CPSPS1 and CPSPS2 use bicubic splines under tension to fit the sparse array data values. The routines used are from Fitpack, by Alan Cline. Spline tension can be changed with the T2D parameter. More information appears in module "Cp 9.1 Smoothing contours."
Occasionally you may see error messages similar to this:
CPGRWS 200 WORDS REQUESTED, 100
WORDS AVAILABLE
CPGIWS 200 WORDS REQUESTED, 100
WORDS AVAILABLE
CPGRWS tells you that your real workspace is too small, and CPGIWS tells you that your integer workspace is too small. Increase LRWK or LIWK to the number of words requested in the error message, and repeat until the error message goes away.
CPSPS2 cannot extrapolate data beyond the boundaries of the data field.
Another common error is the failure to specify the arrays X and Y in strictly increasing order. When this happens, you see this error message:
ERROR 6 IN CPSPS2 - ERROR IN CALL TO MSSRF1
- Choose different values for the arrays X and Y in the ccpsps2 example, then compile and run ccpsps2.f again. Did the shape of the contour rectangle change?
- Try setting XC1, XCM, YC1, and YCN in ccpsps2.f to agree with X(1), X(M), Y(1), and Y(N). Note how the contour rectangle shape changes.
Nongridded data, or randomly spaced data, are data that have no relationship to a grid at all. The effect is as if you took a handful of rice and tossed it down on a piece of paper, then used the locations of the rice grains as your data points. Before Conpack can use this kind of data, you must preprocess it with an interpolation package such as Bivar. IDSFFT is a Bivar subroutine that returns an array of dense gridded data for use with CPRECT, but it has some limitations.
1 DO 101, I=2, MREG
2 XREG(I) = XMIN + (XMAX-XMIN) * REAL(I-1)/(MREG-1)
3 101 CONTINUE
4 DO 102, I=2, NREG
5 YREG(I) = YMIN + (YMAX-YMIN) * REAL(I-1)/(NREG-1)
6 102 CONTINUE
7 CALL IDSFFT (1, NRAN, XRAN, YRAN, ZRAN, MREG, NREG, MREG, XREG, YREG,
+ ZREG, IWRK, RWRK)
8 CALL CPRECT (ZREG, MREG, MREG, NREG, RWRK, LRWK, IWRK, LIWK)
9 CALL CPCLDR (ZREG, RWRK, IWRK)
10 CALL MARK (XRAN, YRAN, NRAN)
CALL IDSFFT (MD, NRAN, XRAN, YRAN, ZRAN, MREG, NREG, KREG, XREG,
+ YREG, ZREG, IWK, WK)
- MD
- Integer, Input---Mode of computation (must be 1, 2, or 3).
- 1 Used if this is the first call to this subroutine, or if the value of NRAN has been changed from the previous call, or if the contents of the XRAN or YRAN arrays have been changed from the previous call.
- 2 Used if the values of NRAN, the XRAN array, and the YRAN array are unchanged from the previous call, but new values for XREG, YREG are being used. If MD=2 and NRAN has been changed since the previous call to IDSFFT, an error return occurs.
- 3 Used if the values of NRAN, MREG, NREG, XRAN, YRAN, XREG, and YREG are unchanged from the previous call, that is, if the only change on input to IDSFFT is in the ZRAN array. If MD=3 and NRAN, MREG, or NREG has been changed since the previous call to IDSFFT, an error return occurs.
- Between the call with MD=2 or MD=3 and the preceding call, the IWK and WK work arrays should not be disturbed.
- NRAN
- Integer, Input---Number of random data points (must be 4 or greater).
- XRAN(NRAN)
- Real array, Input---Array of dimension NRAN containing the X coordinates of the data points.
- YRAN(NRAN)
- Real array, Input---Array of dimension NRAN containing the Y coordinates of the data points.
- ZRAN(NRAN)
- Real array, Input---Array of dimension NRAN containing the Z coordinates of the data points.
- MREG
- Integer, Input---Number of output grid points in the X direction (must be 1 or greater).
- NREG
- Integer, Input---Number of output grid points in the Y direction (must be 1 or greater).
- KREG
- Integer, Input---First dimension of ZREG as declared in the calling program. KREG>=MREG, else an error return occurs.
- XREG(MREG)
- Real array, Input---Array of dimension MREG containing the X coordinates of the output grid points.
- YREG(NREG)
- Real array, Input---Array of dimension NREG containing the Y coordinates of the output grid points.
- ZREG(KREG,NREG)
- Real array, Output---Real, densely gridded two-dimensional array of dimension (KREG, NREG), storing the interpolated Z values at the output grid points.
- IWK(*)
- Integer array, Workspace---Integer work array that must be dimensioned at least 31 * NRAN + MREG * NREG.
- WK(*)
- Real array, Workspace---Real work array of dimension at least 6 * NRAN.
Lines 1 through 6 of the cidsfft.f code segment set up the grid locations XREG and YREG for the interpolated data values, ZREG. Without these points, the call to IDSFFT in line 7 is unable to produce a set of interpolated data values. Line 8 uses CPRECT with the interpolated data to initialize Conpack, and line 9 calls CPCLDR to draw the contours. Once again, subroutine MARK is used to show approximate locations for the nongridded data values.
Bivar requires that nongridded data points must be distinct and their projections in the X/Y plane must not be collinear. In other words, you can't have two Z values for the same X,Y pair, and your X,Y values can't all lie on the same line.
Inadequate work space in IWK and WK may cause incorrect results. If you decide to share the work arrays with Conpack work arrays, make sure that your integer work space is large enough. In general, IDSFFT needs more integer space than Conpack, and Conpack needs more real work space than IDSFFT. Also, Conpack relies on the fact that workspace arrays are not modified between calls to Conpack routines, so IDSFFT must be called before calls to Conpack.
In versions of NCAR Graphics prior to Version 3.2, you must load your own copy of Bivar for use with nongridded data. First, execute:
- ncargex cbex01
This places several files in your directory. Edit cbex01.f, and remove all lines that precede the line:
C PACKAGE BIVAR
The remainder of the file is the Bivar package. In NCAR Graphics Version 3.2, Bivar resides in libncarg.a, so you only need to load the NCAR Graphics library to use Bivar.
- Modify cidsfft.f so that XREG and YREG are not initialized, and see what happens when you run it.
- Think about what kind of an interpolation package would be best for your data. If you decide that a bivariate interpolation package is not optimal, try running the cidsfft example with another interpolation package.
Because any set of data can have missing or special data, Conpack has a parameter option that allows you to tag special data points. Once the special value parameter is set, initialize Conpack with CPRECT, CPSPS1, or CPSPS2, depending on what kind of data you have.
1 CALL CPSETR ('SPV - SPECIAL VALUE', -1.0)
2 CALL CPSETI ('PAI - PARAMETER ARRAY INDEX', -2)
3 CALL CPSETI ('CLU - CONTOUR LEVEL USE FLAGS', 1)
4 CALL CPRECT (Z, K, M, N, RWRK, LRWK, IWRK, LIWK)
5 CALL CPBACK (Z, RWRK, IWRK)
6 CALL CPCLDR (Z, RWRK, IWRK)
CALL CPSETR ('SPV', spv)
CALL CPSETI ('PAI', ipai)
CALL CPSETI ('CLU', iclu)
- SPV
- Real---The SPecial Value parameter specifies a special value for certain types of data.
- 0 No data are treated as a special value. This is the default.
- <>0 This value is a special value that can be used in data fields to mark missing, suspect, or undesired data locations.
- PAI
- Integer---The Parameter Array Index is used when the parameter to be accessed is a parameter array (rather than that of a single-value parameter). When the parameter is an array, the current value of PAI is used as the index of the element in the array whose value is to be set or retrieved. In this module, PAI is used to specify the contour level use flags parameter (CLU). PAI can specify three special elements in CLU that refer to three lines which are not technically contours:
- -1 The edge of the contour plot.
- -2 The edge of any area filled with special values.
- -3 The edge of any area in which the mapping routine CPMPXY returns an out-of-range value.
- CLU(NCL)
- Integer array---The Contour Level Use flags parameter determines how the associated contour level in the internal parameter array CLV is used. NCL is the Number of Contour Levels. The value of CLU determines how a line is drawn:
- 0 No contour line is drawn.
- 1 Contour line is drawn without labels.
- 2 Contour labels are drawn without line.
- 3 Contour labels and line are both drawn.
- When drawing lines that are not contour lines, any nonzero value for CLU draws the line with no labels.
In the ccpspv example, the special value flag is set so that any data point with a value of -1.0 is tagged as missing data. This is all that is necessary to specify missing data. Lines 2 and 3 of the ccpspv.f code segment set the parameter array index to point to the element of CLU that determines whether or not the special-value edge is drawn; lines 2 and 3 then set that element nonzero so the edge will be drawn. Conpack is then initialized and contours are drawn normally.
- Modify ccpspv.f so that the missing data region is not a rectangle, and make a second special value region.
- Modify ccpspv.f so that an outline is not drawn around the special value region.
- What would you have to do to draw contours through a region where data do not exist?
Conpack recognizes two kinds of non-Cartesian data: latitude/longitude data and polar coordinate data. Conpack maps these kinds of data from an array or a rectangle in the Cartesian plane to the desired Ezmap projection or polar coordinate space. Translation is done between these spaces using the subroutine CPMPXY. You can modify CPMPXY to produce other mappings.
Non-Cartesian data Non-Cartesian data
Conpack treats non-Cartesian data in the same way that it treats Cartesian data, except that it requires a mapping function between the non-Cartesian space and the Cartesian plane. What this means is that you need to choose or write a transformation from the Cartesian plane to your non-Cartesian space. This step is done by setting the MAP parameter nonzero, and in some cases, modifying the Conpack routine CPMPXY.
Then decide what kind of data you have in the Cartesian space (for example dense gridded, sparse gridded, irregularly spaced gridded, or nongridded), and initialize for that type of data. After these steps are done, contours are drawn normally. The next few modules discuss examples of how to use your data in various non-Cartesian spaces.
When plotting latitude/longitude data, you need to know what portion of the globe your data cover, and what kind of data you will have after projection onto the Cartesian plane. Conpack has four parameters to set the corners of your plot, a mapping parameter to specify lat/lon data, and an out-of-range parameter to specify points that don't map into your space or viewport.
CPSETI ('MAP', 1)
CPSETR ('XC1', xmin)
CPSETR ('XCM', xmax)
CPSETR ('YC1', ymin)
CPSETR ('YCN', ymax)
CPSETR ('ORV', val)
- MAP
- Integer---The MAPping flag for subroutine CPMPXY.
- 0 Cartesian data. This is the default.
- 1 Latitude/longitude data.
- 2 Rho/theta data.
- XC1
- Real---The X Coordinate at index 1 parameter is the longitude, in degrees, that corresponds to a value of 1 for the first subscript of the data array. Alternatively, you can think of XC1 as being the minimum value of your longitude data locations.
- XCM
- Real---The X Coordinate at index M parameter is the longitude, in degrees, that corresponds to a value of M for the first subscript of the data array, where M is the first dimension of your data. Alternatively, you can think of XCM as being the maximum value of your longitude data locations.
- YC1
- Real---The Y Coordinate at index 1 parameter is the latitude, in degrees, that corresponds to a value of 1 for the second subscript of the data array. Alternatively, you can think of YC1 as being the minimum value of your latitude data locations.
- YCN
- Real---The Y Coordinate at index N parameter is the latitude, in degrees, that corresponds to a value of N for the second subscript of the data array, where N is the second dimension of your data. Alternatively, you can think of YCN as being the maximum value of your latitude data locations.
- ORV
- Real---When the Out-of-Range Value parameter is set nonzero, ORV is used as the value of X and Y coordinates expected to be returned by the mapping subroutine CPMPXY to say that a point is out of range under the current mapping. If you are plotting points over an Ezmap projection, you should set ORV=1.E12 so that contours that don't project onto the map are not drawn.
1 PARAMETER (RMNLON=-190., RMXLON=20., RMNLAT=-20., RMXLAT=50.)
2 DATA RLAT1 /RMNLAT, 0.0/
3 DATA RLAT2 /RMXLAT, 0.0/
4 DATA RLON1 /RMNLON, 0.0/
5 DATA RLON2 /RMXLON, 0.0/
6 CALL MAPSTI ('GR - GRID', 10)
7 CALL MAPSTC ('OU - OUTLINE DATASET', 'PO')
8 CALL MAPROJ ('SV - SATELLITE-VIEW', 35., -100., 0.)
9 CALL MAPSET ('MA', RLAT1, RLON1, RLAT2, RLON2)
10 CALL MAPDRW
11 CALL CPSETI ('SET - DO-SET-CALL FLAG', 0)
12 CALL CPSETR ('XC1 - X COORDINATE AT INDEX 1', RMNLON)
13 CALL CPSETR ('XCM - X COORDINATE AT INDEX M', RMXLON)
14 CALL CPSETR ('YC1 - Y COORDINATE AT INDEX 1', RMNLAT)
15 CALL CPSETR ('YCN - Y COORDINATE AT INDEX N', RMXLAT)
16 CALL CPSETI ('MAP - MAPPING FLAG', 1)
17 CALL CPSETR ('ORV - OUT-OF-RANGE VALUE', 1.E12)
18 CALL CPRECT (Z, M, M, N, RWRK, LRWK, IWRK, LIWK)
19 CALL CPCLDR (ZREG, RWRK, IWRK)
The ccpmap example shows how XC1, XCM, YC1, and YCN associate longitude and latitude data locations with the subscripts of your Z data array. The MAP parameter is used to specify the map transformation you want, and the ORV parameter is set to tell Conpack what value CPMPXY returns for a point on the globe that has no valid projection on your map. If ORV is not set, your program may core dump in cases like the example where contours extend beyond the edges of the projection. You must use the above parameters to set ranges for longitude and latitude before you can overlay your contour plot onto a map drawn by Ezmap.
Lines 1 through 5 of the ccpmap.f code segment set the minimum and maximum latitude and longitude values for both the geographic and contour mappings. Lines 6 through 10 draw a black-and-white map of the globe using routines discussed in the Ezmap chapter. Line 6 specifies that latitude and longitude lines should be drawn at 10-degree intervals. Line 7 forces drawing of political and continental boundary lines. Lines 8 and 9 specify a satellite view of the globe. Line 10 draws the map. Up to this point, everything is just as it would be if no contours were to be drawn.
Lines 11 through 19 overlay contours on the Ezmap projection. As discussed in module "Cp 2.7 Contour perimeter: Size, shape, and location using SET," the Conpack parameter SET in line 11 tells Conpack that subroutine SET has been called by Ezmap. XC1, XCM, YC1, and YCN fix the corners of the array on the globe. Line 16 sets the Conpack parameter MAP so that Conpack knows that lat/lon data is being used. Line 12 sets ORV to "1.E12" so that contours will be terminated at the edge of the visible portion of the globe. Notice that all of the parameter-setting routines are called before the CPRECT call to initialize Conpack for drawing.
Lines 18 and 19 initialize Conpack and draw contours in the same way as for a simple Cartesian plot.
In some cases, you may want to draw contours across the international date line. To do this, you must make sure that XC1<XCN, even if it means making XCN>180. Notice that contours are drawn across the date line in the example.
- Using what you learned in this module, convert ccprect.f to overlay contours on a black-and-white satellite view of China (with the corner points of the contoured region at 15N, 73E and 55N, 145E).
- Convert the ccpsps1 example to overlay contours on a Lambert Conformal map of South America (with the corner points of the contoured region and of the map at 55S, 95W and 15N, 35W).
When plotting polar coordinate data (rho/theta data), you need to know what portion of the Cartesian plane your data cover, and what kind of data you will have after projection onto the Cartesian plane. Conpack has four parameters to set the minimum and maximum values of rho and theta, and a mapping parameter to specify polar coordinates.
1 CALL SET (0.05, 0.95, 0.05, 0.95, -RHOMX, RHOMX, -RHOMX, RHOMX, 1)
2 CALL CPSETI ('SET - DO-SET-CALL FLAG', 0)
3 CALL CPSETR ('XC1 - X COORDINATE AT INDEX 1', RHOMN)
4 CALL CPSETR ('XCM - X COORDINATE AT INDEX M', RHOMX)
5 CALL CPSETR ('YC1 - Y COORDINATE AT INDEX 1', THETMN)
6 CALL CPSETR ('YCN - Y COORDINATE AT INDEX N', THETMX)
7 CALL CPSETI ('MAP - MAPPING FLAG', 2)
8 CALL CPRECT (Z, M, M, N, RWRK, LRWK, IWRK, LIWK)
9 CALL CPCLDR (ZREG, RWRK, IWRK)
CPSETR ('XC1', rho-min)
CPSETR ('XCM', rho-max)
CPSETR ('YC1', theta-min)
CPSETR ('YCN', theta-max)
CPSETI ('MAP', imap)
- XC1
- Real---The X Coordinate at index 1 parameter is the value of rho that corresponds to a value of 1 for the first subscript of the data array. Alternatively, you can think of XC1 as being the minimum rho value of your data.
- XCM
- Real---The X Coordinate at index M parameter is the value of rho that corresponds to a value of M for the first subscript of the data array, where M is the first dimension of your data. Alternatively, you can think of XCM as being the maximum rho value of your data.
- YC1
- Real---The Y Coordinate at index 1 parameter is the value of theta, in degrees, that corresponds to a value of 1 for the second subscript of the data array. Alternatively, you can think of YC1 as being the minimum theta value of your data.
- YCN
- Real---The Y Coordinate at index N parameter is the value of theta, in degrees, that corresponds to a value of N for the second subscript of the data array, where N is the second dimension of your data. Alternatively, you can think of YCN as being the maximum theta value of your data.
- MAP
- Integer---The MAPping flag for subroutine CPMPXY.
- 0 Cartesian data. This is the default.
- 1 Latitude/longitude data.
- 2 Rho/theta data.
Line 1 of the ccpcir.f code segment calls the SPPS routine SET so that the polar plot appears in the center of the viewport. Line 2 uses the Conpack parameter SET to tell Conpack that subroutine SET has been called. XC1, XCM, YC1, and YCN fix the minimum and maximum values of rho and theta.
Line 7 sets the MAP parameter so that Conpack knows we are using polar coordinates. Notice that all of the parameters are set before the CPSPS2 call to initialize Conpack for drawing.
Lines 8 and 9 initialize Conpack and draw contours just as they would be for a simple Cartesian plot.
- Modify ccprect.f so that it fills the top half of a circle in polar coordinates.
CPMPXY maps Conpack output from a rectangular coordinate system superimposed on the data grid to some other coordinate system. The default version handles the mapping of longitudes and latitudes into rectangular coordinates on a given Ezmap projection. It also handles mapping polar coordinates into rectangular coordinates. You can supply your own version of CPMPXY to produce any other desired mapping. CPMPXY is not called by you; it is called by Conpack when the parameter MAP is nonzero. This module explains how to write simple height and pressure transformations.
1 SUBROUTINE CPMPXY (IMAP, XINP, YINP, XOTP, YOTP)
2 PARAMETER (JX=60, KX=26)
3 COMMON /HEIGHT/ Z (JX, KX)
4 ELSEIF (IMAP .EQ. 3 .OR. IMAP .EQ. 4) THEN
5 XOTP = XINP
6 X = XINP
7 IIX = INT(X)
8 DIFX = X - FLOAT(IIX)
9 Y = YINP
10 IY = INT(Y)
11 DIFY = Y - FLOAT(IY)
12 IXP1 = MIN0 (JX, IIX + 1)
13 IYP1 = MIN0 (KX, IY + 1)
14 Z1 = Z(IIX, IY) + DIFY * (Z(IIX, IYP1) - Z(IIX, IY))
15 Z2 = Z(IXP1, IY) + DIFY * (Z(IXP1, IYP1) - Z(IXP1, IY))
16 ZR = Z1 + DIFX * (Z2 - Z1)
17 YOTP = ZR
18 IF (IMAP .EQ. 4) YOTP = 1000. * EXP (-ZR / 7.)
SUBROUTINE CPMPXY (IMAP, XINP, YINP, XOTP, YOTP)
- IMAP
- Integer, Input---The current (nonzero) value of the parameter MAP.
- XINP
- Real, Input or Output---The X coordinate of a point on the contour plot. If XC1=XCM (the default situation), then XINP lies in the range from 1 to M, where M is the first dimension of the array being contoured (equal to the value of the parameter ZDM). In this case, the X coordinate has the same range as the first index of the data array. If you set XC1<>XCM, then XINP lies in the range from XC1 (corresponding to an index value of 1) to XCM (corresponding to an index value of M).
- YINP
- Real, Input or Output---The Y coordinate of a point on the contour plot. If YC1=YCN (the default situation), then YINP lies in the range from 1 to N, where N is the second dimension of the array being contoured (equal to the value of the parameter ZDN). In this case, the Y coordinate has the same range as the second index of the data array. If you set YC1<>YCM, then YINP lies in the range from YC1 (corresponding to an index value of 1) to YCN (corresponding to an index value of N).
- XOTP
- Real, Output---The mapped X coordinate of a point on the contour plot, in a coordinate system consistent with the current window, as specified by arguments 5 through 8 of the last call to the SPPS routine SET or by the equivalent GKS call.
- YOTP
- Real, Output---The mapped Y coordinate of a point on the contour plot, in a coordinate system consistent with the current window, as specified by arguments 5 through 8 of the last call to the SPPS routine SET or by the equivalent GKS call.
IMAP contains the value of the mapping parameter MAP and is used by CPMPXY to determine which transformation is used. In the ccpmpxy example, IMAP=4 on entry to CPMPXY. XINP and YINP are the untransformed coordinates of a point on a contour line. These points may not lie on the grid of initial data points. XOTP and YOTP are the output data points for CPMPXY, and represent the final locations of the points defining contour lines.
Line 3 of the ccpmpxy.f code segment passes the data array containing height values into CPMPXY for use in calculating the pressure transformation. Line 4 checks to see whether a height or pressure transformation is specified. Since there is no transformation in the X direction, line 5 gives the X output coordinate the same value as the X input coordinate.
Because the point on the contour line probably is not on one of the grid points in the original data, it is necessary to interpolate the height and pressure data value in this case. Therefore, lines 7 through 15 find the nearest data points in the Y direction and interpolate for the height at the point on the contour line. Line 16 calculates the interpolated height, and line 17 returns it as the Y output coordinate. If the MAP parameter IMAP specifies a pressure transformation, line 18 calculates that transformation and returns the pressure value as the Y output coordinate.
This module describes a common problem that does not have any quick solution at this time. Many scientists want to contour data that is not neatly laid out over a rectangular domain. There are two common problems with this kind of data. In the first case, contours can flow over the irregular boundary, and in the second case, they cannot.
If contours can be allowed to flow over the boundary (such as air temperature over the ocean), there are two ways to end the contour lines and draw the boundary. You can put special values into your regular grid over areas where you don't have data values, or you can use Areas to mask the contour lines over the regions where you don't have data values. See module "Cp 3.6 Missing or special data" for an example of how to use special values, or see section "Cp 8. Overlaying filled contours on a map" for details on how to mask contour lines.
Some contours cannot be allowed to flow over the boundary. For example, ocean temperature doesn't exist over land, so contours showing ocean temperature must follow the shoreline. Unfortunately, the data are usually not dense enough along the boundary to force contours to conform to the boundary line, and worse, Bivar assumes that the data have a continuous first derivative. What this means in practice is that by using the methods discussed in section "Cp 3. Initializing Conpack," contour lines are almost guaranteed to cross boundary lines. When interpolation is being used in cases like this, it may be possible to find an interpolation package that better fits your needs for interpolation libraries (FITPACK may be a good choice).
Because FORTRAN 77 lacks pointer variables and dynamic storage allocation, Conpack requires that you allocate real and integer workspace for your calculations.
The amount of workspace needed to produce a contour plot often depends on how many tightly curved contour lines you have and on how several parameters are set. A plot having only a few contours with large, gradual curves needs much less workspace than a plot with small, winding contours.
Although it is possible to calculate an upper bound for both integer and real work arrays, the process is tedious, and it must be done for each Conpack routine called. Please see the Conpack programmer document if you need to calculate an upper bound for your work arrays. It is much easier to let Conpack tell you how much space it needs, and then adjust your array sizes downward to match.
Integer Workspace Used: 100 Real Workspace Used: 200
1 CALL CPRECT (Z, K, M, N, RWRK, LRWK, IWRK, LIWK)
2 CALL CPBACK (Z, RWRK, IWRK)
3 CALL CPCLDR (Z, RWRK, IWRK)
4 CALL CPGETI ('IWU - INTEGER WORKSPACE USAGE', IIWU)
5 CALL CPGETI ('RWU - REAL WORKSPACE USAGE', IRWU)
6 WRITE (6,*) 'Integer Workspace Used: ',IIWU,
+ ' Real Workspace Used: ',IRWU
CALL CPGETI ('IWU', iwu)
CALL CPGETI ('RWU', irwu)
- IWU
- Integer---The Integer Workspace Usage parameter is intended for retrieval only. It is set to zero by any of the initialization routines. It is then updated by each subsequent Conpack routine called to reflect the largest number of words of integer workspace needed at any one time.
- RWU
- Integer---The Real Workspace Usage parameter is intended for retrieval only. It is set to zero by any of the initialization routines. It is then updated by each subsequent Conpack routine called to reflect the largest number of words of real workspace needed at any one time.
Lines 4 and 5 of the ccprwu.f code segment retrieve IWU and RWU, then line 6 prints them. They are retrieved after all the calls to Conpack have been completed so we can see how much workspace was used for the entire plot. In this case, an absolute minimum of workspace is used. As mentioned in previous modules, it is a good idea to start with LRWK=2500, and LIWK=1000 (where LRWK is the length of RWRK, and LIWK is the length of IWRK), then move to smaller values if memory is at a premium on your machine.
Since you use IWU and RWU most frequently when you are planning to run the same job over and over with different data, we recommend that you always make LRWK and LIWK somewhat larger than the values returned by RWU and IWU.
- Using the ccpezct example, determine the amount of real and integer workspace used.
Previous Chapter Tutorial Home Next Chapter