Special thanks to David Kennison and Bob Lackman for reviewing this document. Also, thanks to Dennis Joseph and Ken Hansen for sharing their wind barb program.
Copyright 1996 University Corporation for Atmospheric Research (UCAR)
All Rights Reserved
Published by: National Center for Atmospheric Research, Scientific Computing Division, P.O. Box 3000, Boulder, CO 80307-3000. The National Center for Atmospheric Research is operated by the University Corporation for Atmospheric Research and is sponsored by the National Science Foundation. Any opinions, findings, and conclusions or recommendations expressed in this publication are those of the authors and do not necessarily reflect the views of the National Science Foundation.
The functionality of the package, and the documentation, is broken into: plotting front lines; plotting regions showing weather type or temperature zone; plotting city names and daily high/low temperature readings; plotting regional weather labels (like "BREEZY," "HUMID," and so forth); plotting regional temperature labels with optional arrows; plotting special symbols (like ones for high and low pressure) and icons representing daily weather; plotting map legends; plotting wind barbs and station model data.
Either C or Fortran procedures may be invoked to effect the above functionality. In the descriptions of the procedures, the Fortran entry will be described in detail. A synopsis of the equivalent C procedure follows.
The basic programming approach is to set values for internal parameters that control various aspects of the output and then invoke the appropriate C or Fortran procedure. For a complete list of, and an explanation of how to set and retrieve values for, the internal parameters available in this package, consult the section Setting and Retrieving Internal Parameters. An easy way of using this package is to thumb through the example plots in Appendix A to find that plot that illustrates what you want to do, then modify the code that produces that plot to accomplish the desired goal. See the EXAMPLES section to find out how to retrieve and run the codes that produce the plots in Appendix A.
Fortran:
CALL WMDRFT(N,X,Y)where X and Y are linear arrays of dimension N and ((X(I),Y(I)),I=1,N) are world coordinate values.
C:
#include <ncarg/ncargC.h> void c_wmdrft(int n, float *x, float *y)
where the parameters are analogous to the Fortran ones.
The coordinate values are used as control points for a spline curve fit. The curve passes through the given coordinates. If the front has little curvature, then only a few points need to be specified to get a nice smooth curve. See Figure 2 in Appendix A for an illustration.
If a non-negative value is specified for NMS, then precisely NMS symbols will be drawn along the front line, regardless of the settings for BEG, END, BET, and SWI. Setting the value of NMS to zero results in drawing a spline curve along the front line coordinates with no symbols appearing along it.
It is possible to specify the exact sequence in which warm front and cold front symbols appear along a front line, as well as which side of the line they point. The internal parameter array STY is used for this purpose. The legal values for elements of the STY array are plus or minus 1 and plus or minus 2. A "1" will produce a cold front symbol (a small triangle) and a "2" will produce a warm front symbol (a semi-circular bump). The algebraic sign of the elements of STY indicate what side of the front line the symbols will point - a positive value will cause the symbol to point to the right of the line (as traversed from the start to the end), and a negative value will cause the symbol to point to the left. Elements of the STY array are defined by using the internal parameter PAI to indicate which element is being specified and then providing a value for STY. The internal parameter REV can be used to reverse the directions that the symbols along a front line point.
Each of the bumps along a warm front is defined by points along a bezier curve. The default number of points along such a curve is 51 which makes these curves appear smooth at most sizes. If desired, this number can be reset by assigning the desired value to NBZ.
See the table of internal parameters for details on the internal parameters discussed in this section. See Figure 4 in Appendix A for an example that illustrates the use of the internal parameters BEG, BET, END, NMS, SWI, STY, PAI, and REV.
See the table of internal parameters for details on the internal parameters discussed in this section. See Figures 1, 4, and 14 in Appendix A for examples that illustrate setting colors for front lines.
See the table of internal parameters for details on the internal parameters discussed in this section. See Figure 3 in Appendix A for an example that illustrates setting endpoint slopes.
See the table of internal parameters for details on the internal parameters LIN, DWD, and WTY.
Fortran:
CALL WMDRRG(N,X,Y,ITYPE,NC,XC,YC)where X and Y are linear arrays of dimension N and ((X(I),Y(I)),I=1,N) are world coordinate values specifying a region. A spline fit is effected using the input coordinates so that only a few coordinates are needed to specify a smooth region. The spline fit passes through the input coordinates. See figure 2 in Appendix A for an example of a region defined by seven points. The region constructed is filled with either patterns or a solid color depending on ITYPE.
The legal values for ITYPE are:
ITYPE | = 'T' for thunderstorms.
|
= 'SH' for showers.
| |
= 'R' for rain.
| |
= 'F' for snow flurries.
| |
= 'SN' for snow.
| |
= 'I' for ice.
| |
= 'INDEXnn' where nn denotes a color index to use for the fill. |
If NC is greater than 2, then the region resulting from the spline fit to ((X(I),Y(I)),I=1,N) will be clipped against the region in ((XC(I),YC(I)),I=1,NC). If no clipping is to be done, then set NC equal to 1.
C:
#include <ncarg/ncargC.h> void c_wmdrrg(int n, float *x, float *y, char *itype, int nc, float *xc, float *yc)
where the parameters are analogous to the Fortran ones.
Internal parameter RHT can be used to change the size of the symbols in the weather patterns and COL can be used to change the colors. For examples of using WMDRRG, see Figures 2, 5, 13, 14 in Appendix A.
Fortran:
CALL WMLABC(X,Y,CITY,TEMPS)where X and Y are world coordinates specifying the position of the composite label that consists of the city name in the character variable CITY and the temperature ranges in the character variable TEMPS. For example, if CITY='Boulder' and TEMPS='84/68', then these strings would be plotted with CITY on top and TEMPS below.
C:
#include <ncarg/ncargC.h> void c_wmlabc(float x, float y, char *city, char *temps)
where the parameters are analogous to the Fortran ones.
There are four internal parameters that control the appearance of the city labels: CBC, CHT, CMG, and RFC. Each character in the city name and the HI/LOW value is drawn against a background that surrounds the character. The color of this background is controlled by the value of CBC and the extent of the background is controlled by the value of CMG. This background can be used to provide space around the labels for readability. The size of the labels is controlled by the value of CHT and the color of the characters is given by RFC.
Plotting dots to mark the city positions is facilitated by using the entry WMLABS which is described in the section Dots below.
For examples of plotting city names, hi/low data, and dots, see Figures 6, 13, and 14 in Appendix A.
Fortran:
CALL WMLABW(X,Y,LABEL)where X and Y are world coordinates specifying the center position of the label in the character variable LABEL.
C:
#include <ncarg/ncargC.h> void c_wmlabw(float x, float y, char *label)
where the parameters are analogous to the Fortran ones.
The labels are plotted in a rectangle that surrounds the label. This rectangle has a shadow. The internal parameters that control the appearance of the regional weather labels are: RC1, RC2, RC3, RC4, RC5, and WHT. WHT specifies the height of the characters in the label; RC4 specifies the color index of the text in the label; RC1 specifies a color index for the outline of the rectangle surrounding the text; RC2 specifies the color index of the interior of the box; RC3 specifies the color index of the rectangle shadow; and RC5 specifies the color index for outlines around each character in the LABEL (the character outlines are drawn only if RC5 is non-negative). For further details on these internal parameters, see the table of internal parameters.
For examples of plotting regional weather labels, see Figures 6, 13, and 14 in Appendix A.
Fortran:
CALL WMLABT(X,Y,LABEL,IPOS)where X and Y are world coordinates specifying a position for the label in the character variable LABEL. IPOS is a flag for controlling whether an optional arrow is drawn. If IPOS is 0, then no arrow is drawn and the label is centered at (X,Y). If IPOS is between 1 and 12, then arrows are drawn at the positions indicated in the following diagram:
This diagram is but a rough sketch of the positions. For example, if position 4 is requested, the the label will appear under the arrow; if position 3 is requested, then the arrow will be on a line that goes through the center of the label at an angle of 67.5 degrees, and so forth.
If an arrow is drawn, then (X,Y) specifies the position at the tip of the arrow.
C:
#include <ncarg/ncargC.h> void c_wmlabt(float x, float y, char *label, int ipos)
where the parameters are analogous to the Fortran ones.
The internal parameters that control the appearance of the regional temperature labels are: RBS, RFC, RLS, ROS, and THT. The appearance of the (optional) arrows is controlled by the internal parameters for arrows (see the section Arrows for details). THT specifies the label height; RFC specifies the color index for the character color; RLS specifies the color index for character shadows; ROS specifies the color index for character outlines (drawn only if this index is non-negative). RBS specifies a color index for background boxes drawn around each character in the temperature label; these background boxes are drawn only if RBS is non-negative. RMG controls the size of the margins for the background boxes. For further details on these internal parameters, see the table of internal parameters.
For examples of plotting regional temperature labels, see figures 6, 13, and 14 in Appendix A.
Fortran:
CALL WMLABS(X,Y,SYMTYP)where X and Y are world coordinates specifying the center position of the symbol requested in the character variable SYMTYP. The available symbols include symbols for high and low pressure areas, arrows, dots, and icons representing daily weather (such as snow, rain, sun, etc.). These symbols are described in more detail in the subsections of this section.
C:
#include <ncarg/ncargC.h> void c_wmlabs(float x, float y, char *symtyp)
where the parameters are analogous to the Fortran ones.
If SYMTYP='LOW', then a circular symbol with an "L" in it will be drawn at position (X,Y). The internal parameters controlling the appearance of the low pressure symbols are: SHT, LOF, LOB, LOS. SHT controls the size of the symbol; LOF specifies the color of the "L" inside the circle; LOB specifies the color of the interior of the circle; LOS specifies the color of the symbol shadow. For further details on these internal parameters see the table of internal parameters. For examples of the usage of low pressure symbols, see figures 6, 13, and 14 in Appendix A.
1 | 'CLOUD' |
2 | 'ICE' |
3 | 'IS' (Intermittent showers) |
4 | 'IT' (Sunny, chance of T-storms) |
5 | 'MC' (Mostly cloudy) |
6 | 'MS' (Mostly sunny) |
7 | 'RAIN' |
8 | 'RS' (Rain and snow) |
9 | 'SNOWFLAKES' |
10 | 'SUN' |
11 | 'THUNDERSTORM' |
12 | 'WIND' |
Fortran:
CALL WMLGND(X,Y,NTYPE,IROWS,ICOLS)where X and Y are world coordinates. NTYPE specifies what legends are to be drawn:
NTYPE = 1 | Plot the legend for the weather types. There are six weather types: showers; T-storms; rain; flurries; snow; ice. The coordinate (X,Y) for this type specifies the lower left corner of the legend. |
= 2 | Plot the legend for front types. There are three front types labeled: cold; warm; stationary. The (X,Y) coordinate for this legend specifies the lower right corner of the legend. |
= 3 | Plot the explanatory legend. The (X,Y) coordinate for this legend specifies the bottom center of the legend. |
C:
#include <ncarg/ncargC.h> void c_wmlgnd(float x, float y, int ntype, int irows, int icols)
where the parameters are analogous to the Fortran ones.
The internal parameters that apply to the appearance of legends are COL for specifying color and those parameters that apply to the appearance of weather fronts. See the section PLOTTING FRONT LINES for details on the internal parameters that apply to weather fronts. For examples of weather map legends, see Figures 13 and 14 in Appendix A.
Fortran:
CALL WMBARB(X,Y,U,V)where X and Y are world coordinates specifying the center position of the base of the barb and U and V are the components of the wind vector. The angle at which the wind barb is drawn is determined by the vector (U,V) and the magnitude of that vector denotes the wind speed in knots, plotted as per the chart in Figure 9 of Appendix A.
C:
#include <ncarg/ncargC.h> void c_wmbarb(float x, float y, float u, float v)
where the parameters are analogous to the Fortran ones.
The internal parameters that apply to the appearance of wind barbs are COL, WBA, WBD, WBF, WBS, WBT.
COL specifies the color of the barb; WBA specifies the angle, in degrees, that the wind barb tick marks make with the wind barb shaft; WBD specifies the spacing between tick marks along the shaft, expressed as a fraction of the shaft length; WBF is a flag indicating whether space should be left at the base of a wind barb for a sky cover circle; WBS specifies the size of the wind barb shaft; WBT specifies the length of a wind barb full tick mark. See the table of internal parameters for details on the internal parameters that apply to wind barbs. For examples of wind barb usage, see Figures 10, 11, and 12 in Appendix A.
Fortran:
CALL WMSTNM(X,Y,IMDAT)where X and Y are world coordinates specifying the center position of the base of the wind barb shaft. IMDAT is a CHARACTER*5 array of dimension 10 encoded as per the WMO/NOAA guidelines. In more detail:
IMDAT(1)(1:1) | = | iR- | the precipitation data indicator | IMDAT(1)(2:2) | = | iX | - | weather data and station type indicator | IMDAT(1)(3:3) | = | h | - | height above ground of base of lowest cloud | IMDAT(1)(4:5) | = | VV | - | visibility in miles and fractions | IMDAT(2)(1:1) | = | N | - | total amount of cloud cover | IMDAT(2)(2:3) | = | dd | - | direction from which wind is blowing | IMDAT(2)(4:5) | = | ff | - | wind speed in knots
| |
'1', | then | IMDAT(I)(2:2) | = | sn- sign of temperature | | | IMDAT(I)(3:5) | = | TTT | - current air temperature | | | | | | | '2', | then | IMDAT(I)(2:2) | = | sn | - sign of dew point temperature | | | IMDAT(I)(3:5) | = | Td | - dew point | | | | | | | '3', | then | IMDAT(I)(2:5) | = | PO | - station pressure (not plotted) | | | | | | | '4', | then | IMDAT(I)(2:5) | = | PPPP | - pressure reduced to sea level | | | | | | | '5', | then | IMDAT(I)(2:2) | = | a | - characteristic of barograph | | | IMDAT(I)(3:5) | = | ppp | - pressure change, last 3 hrs. | | | | | | | '6', | then | IMDAT(I)(2:4) | = | RRR | - precipitation | | | IMDAT(I)(5,5) | = | tR | - time duration of precipitation | | | | | | | '7', | then | IMDAT(I)(2:3) | = | ww | - present weather | | | IMDAT(I)(4:4) | = | W1 | - most significant past weather | | | IMDAT(I)(5:5) | = | W2 | - 2nd most sig. past weather | | | | | | | '8', | then | IMDAT(I)(2:2) | = | Nh | - Fraction of sky cover | | | IMDAT(I)(3:3) | = | CL | - cloud type, low clouds | | | IMDAT(I)(4:4) | = | CM | - cloud type, medium clouds | | | IMDAT(I)(5:5) | = | CH | - cloud type, high clouds | |
#include <ncarg/ncargC.h> void c_wmstnm(float x, float y, char *imdat)
where the parameters are analogous to the Fortran ones.
The internal parameters that control the appearance of wind barbs apply to the wind barbs that are part of the station model display. See the section Wind Barbs for details on wind barbs. In addition to the wind barb parameters, the parameters WBC and WBL apply to the station model display. WBC specifies the diameter of the sky cover circle at the base of the wind barb and WBL specifies the size of the text labels in the station model display.
See the table of internal parametersfor details on the internal parameters that apply to the display of station models and wind barbs. For examples of station mode displays, Figures 11 and 12 in Appendix A.
Fortran:
CALL WMDFLT()C:
#include <ncarg/ncargC.h> void c_wmdflt()
CALL WMSETI(CNP, IVP)where CNP is a character string at least three characters long (whose legal values are those given in the table of internal parameters), and IVP is the integer value to be assigned to that parameter.
C:
#include <ncarg/ncargC.h> void c_wmseti(char *cnp, int ivp)
where the parameters are analogous to the Fortran ones.
CALL WMSETR(CNP, RVP)where CNP is a character string at least three characters long (whose legal values are those given in the table of internal parameters), and RVP is the real value to be assigned to that parameter.
C:
#include <ncarg/ncargC.h> void c_wmsetr(char *cnp, float rvp)
where the parameters are analogous to the Fortran ones.
CALL WMSETC(CNP, CVP)where CNP is a character string at least three characters long (whose legal values are those given in the table of internal parameters), and CVP is the character value to be assigned to that parameter.
C:
#include <ncarg/ncargC.h> void c_wmsetc(char *cnp, char *cvp)
where the parameters are analogous to the Fortran ones.
CALL WMGETI(CNP, IVP)where CNP is a character string at least three characters long (whose legal values are those given in the table of internal parameters), and IVP is returned as the current integer value assigned to that parameter.
C:
#include <ncarg/ncargC.h> void c_wmgeti(char *cnp, int ivp)
where the parameters are analogous to the Fortran ones.
CALL WMGETR(CNP, RVP)where CNP is a character string at least three characters long (whose legal values are those given in the table of internal parameters), and RVP is returned as the real value currently assigned to that parameter.
C:
#include <ncarg/ncargC.h> void c_wmgetr(char *cnp, float rvp)
where the parameters are analogous to the Fortran ones.
CALL WMGETC(CNP, CVP)where CNP is a character string at least three characters long (whose legal values are those given in the table of internal parameters), and CVP is the character value currently assigned to that parameter. CVP should be of a length suitable to receive the string value returned.
C:
#include <ncarg/ncargC.h> void c_wmgetc(char *cnp, char *cvp)
where the parameters are analogous to the Fortran ones.
By default, SETER prints a line and STOPs. The line printed will look something like this:
ERROR 2 IN WMDRFT - not enough space along the input curve to draw two symbols for a stationary frontThe error number ("2", in the example) may be of use to a consultant (to determine exactly where the error occurred), but is not otherwise meaningful. The actual error message consists of the name of the routine in which the error occurred ("WMDRFT", in the example), a blank, a minus sign, another blank, and, lastly, a short description of the error.
All errors are "recoverable" in the sense that, if the user program puts SETER into "recovery mode", control will be returned to the caller of the WMAP routine in which the error occurred. In some cases, it is then possible to take remedial action to get around whatever problem has occurred; in any case, the error flag can be cleared and execution of the user's program can continue.
Figure 1 - ncargex example wmex01
Figure 2 - ncargex example wmex02
Figure 3 - ncargex example wmex03
Figure 4 - ncargex example wmex04
Figure 5 - ncargex example wmex05
Figure 6 - ncargex example wmex06
Figure 7 - ncargex example wmex07
Figure 8 - ncargex example wmex08
Figure 9 -ncargex example wmex09
Figure 10 - ncargex example wmex10
Figure 11 - ncargex example wmex11
Figure 12 - ncargex example wmex12
Figure 13 - ncargex example wmex13
Figure 14 - ncargex example wmex14