Instructions for the use of the Ausmap

Graphics Program

David Jones

National Climate Centre, Bureau of Meteorology

1. Introduction

ausmap - a graphics program for the visualisation of two dimensional earth orientated scalar or vector data.

Ausmap is a general purpose graphics program for the visualisation of spatial dataset. The package allows the user to plot contours, vectors, and streamlines, with or without colour, grey shade, or patterned banding. Based on the libraries of the NCAR graphics package, ausmap produces a NCAR CGM file (NCGM) called gmeta which can be translated using ctrans to produce a printable PostScript file or converted into a variety of graphics formats including CGM, GIF and TIFF.

Ausmap is chiefly designed for (earth bound) spatial datasets, and supports the visualisation of such data on a variety of projections. The plotting of oordinate information such as coastlines and latitude and longitude lines is provided by the package. The input data provide to ausmap will typically consist of one or more scalar and/or vector fields with data values contained on a regular latitude and longitude grid.


2. Synopsis

ausmap [-A<idcode> -x<#> -BCDFGHKLNOPSTVX -abcdfghilknoprstvz -2] [file1] [file2] [file2]

Ausmap expects an unformatted fortran file(s) listed on the command line or defaulted to tape1 (tape2 and tape3). This input file(s) will be of the form,

nlat
ylat(j),j=1,nlat
nlon
xlon(i),i=1,nlon
header
((data(i,j),i=1,nlon),j=1,nlat)
where nlat and nlon are integers giving the number of latitudes and longitudes on the grid, ylat and xlon are real arrays containing the latitude and longitude coordinates in units of degrees, for the grid starting in the south-west corner and data is a real array containing the values of the data on the (i,j) grid. header is a character*80 variable which contains title information plotted on the output figure.

Upto three input gridded data files may be required of the user, depending on the complexity of the plotting to be performed. If contours are to be plotted with stippling (-t option) then the contoured data is taken from the first listed file (or default to tape1) and the stippling information from the second file (or default to tape2). If -V or -r (vectors or streamlines) and -C (contours) then vector data is read from file1 (or default to tape1) and contour data from file2 (or default to tape2). If -V or -r (vectors or streamlines) and -C (contours) and -t (stippling) then vector data is read from file1 (or default to tape1), contour data from file2 (or default to tape2) and stippling data from file3 (or default to tape3).

Ausmap has two major functions: setting the map projection and domain and performing the data visualisation. The easiest way to set the map projection is by using one of the options -G, -N, or -S for global, northern, or southern hemisphere projections respectively. Otherwise ausmap will prompt the user with a series of questions to define the projection which may be answered explicitly or through the UNIX redirection arrow (<).

A total of five projection types are supported by ausmap . For each projection the user is also able to specify the domain. In the absence of the -G, -N, or -S options the user is required to explicitly provide the projection type (indicated by a two letter code). These are,

ST - polar stereographic, both northern and southern supported.

CE - cyclindrical equidistant

LC - Lambert conformal

ME - Mercator

LE - Lambert equal area

The type of plot is determined by the options provided by the user on the command line, the details of which are detailed below.


3. Description

The function of ausmap is controlled by a series of options which are given on the command line and the users answer to questions asked by ausmap in response to these options. Each of the options is listed below with a brief explanation.

-2 this option switches the colour table used from a rainbow to a two colour scale containing reds and blues only (see the -B option).

-A<idcode> causes ausmap to stamp the figure with the text string "idcode" which is placed at the bottom of the figure frame. Note the idcode stamp is only printed when the user prints the Bureau Logo.

-B allows colour filling of contour bands. The selection of colours may be performed automatically by ausmap , or manually, using the internally specified colour tables, or through colour tables specified by the user (see the -T option). Contours are overlaid in black. The threethree colour palettes provided internal to ausmap are shown below.

Ausmap colour palettes

-C this option causes ausmap to produce vectors and contours on the same map. It only works with the -V option (i.e., -C -V). Ausmap will expect two input files (listed on the command line or defaulting to tape1 and tape2, respectively) containing zonal and meridional vector components (the first listed file) and the file to be contoured (second file).

-D cause ausmap to automatically generate generic decile key information. This option is only meaningful for banding figures with percentile data.

-F option causes ausmap to perform a 1:2:1 two dimensional low pass smoothing of all input data grids. This is useful if the field being plotted is noisy, and leads to a smoother mean preserving field.

-G,-N,-S set the projection to be global cylindrical equidistant, northern polar stereographic and southern polar stereographic projections, respectively. Only one of these options is valid at a time. These provide a simplified way of specifying the projection to be used for the data visualisation.

-H option allows the user to change the header displayed on the plot. The new header replaces that which is contained in the input file.

-K allows the user to plot data or place names on the plot, using coordinates (in degrees) contained in a user listed ascii format file. During the processing ausmap asks for the name of this file. When plotting data values the input file is taken to consist of repeating free formatted units of the form,

i,ylat,xlon,data

where I is an integer (typically, but necessarily, being the station number), ylat and xlon real variable giving the latitude and longitude coordinates, and data the spot value to be drawn. An example file is given below. If the user wishes to plot names on the plot, then the input is taken to consist of units of the form,

header

.. .. .. ..

header

where header is a fortran character variable of length 63 or greater which is interpreted as,

read(header(2:10),'(f9.5)')ylat
read(header(18:26),'(f9.5)')xlon
read(header(30:62),'(a)')cdata
read(header(63:63),'(i1)')ipos
If header(1:1) equals "#" then the entry is skipped and not plotted. cdata is the character string to be plotted and ipos is an integer giving the off-set of the plotted text string from the ylat/xlon position. ipos equal to 1 causes left justified text to the upper-left, 9 cause right justified text to the lower-right, etc. An example file is given below.

 -14.30          126.64      KALUMBURU                        1
#-18.23          127.66      HALLS CREEK                      6
#-17.95          122.23      BROOME                           1
 -20.37          118.63      PORT HEDLAND                     2
 -22.24          118.34      WITTENOOM                        1
 -24.88          113.67      CARNARVON                        3
 -26.61          118.54      MEEKATHARRA                      1
 -30.28          116.66      DALWALLINU                       3
 -28.80          114.70      GERALDTON                        1
 -34.37          115.13      CAPE LEEUWIN                     1

-L allows the user to choose contour labels for each of the contours drawn on the display. This allows the user to overwrite the default labels on the contours.

-O gives the user the option to overwrite the key labels for banding figures. This option is only valid with the -b or -B options.

-P option causes ausmap to print the actual grid data values contained in the input file on the plot frame, with data values given at the centre point of the grid cells.

-T allows the user to provide a colour table which is used by ausmap. By default, ausmap has a 22 colour table, with colours 0 and 1 white and black and colours 2 to 20 a rainbow of colours from blue to red (see the -B option). Ausmap prompts the user for the name of the colour table to over-ride the default when this option is used. An example colour file is shown below,

c----------------------------------------------------------------------
cFILE: colourtable
c----------------------------------------------------------------------
c
cThis file contains a list of red-green-blue transmission
ccolour triplets which are used by  ausmap. A total of 100
ccolours may be listed, with index values from 0 to 99,
cwhile the 100th index is preserved for the (blue) Bureau logo.
cIndex 0 and 1 should be left as is, these are defining white
cand black respectively.
c
cThe format of the file is,
c
cncol
credindex greenindex blueindex< This is index 0
c ......
c ......
credindex greenindex blueindex< This is index ncol-1
c
cwhere,
c
credindex is the red transmissivity (range 0 to 1, 0 no red),
cgreenindex is the green transmissivity (range 0 to 1, 0 no green),
cblueindex is the blue transmissivity (range 0 to 1, 0 no blue),
c
cFor example,
c
c1.00 1.00 1.00 is white,
c1.00 0.00 0.00 is a full red,
c1.00 0.00 1.00 is a full purple, etc.
c
c----------------------------------------------------------------------
22
1.00 1.00 1.00
0.00 0.00 0.00
0.80 0.00 0.80
0.40 0.00 0.90
0.15 0.00 1.00
0.00 0.30 1.00
0.00 0.45 0.75
0.00 0.60 0.50
0.02 0.78 0.20
0.18 0.88 0.18
0.40 0.95 0.10
0.50 1.00 0.00
0.80 1.00 0.00
0.99 0.99 0.00
1.00 0.00 0.00
1.00 0.65 0.20
0.95 0.45 0.15
0.95 0.30 0.10
0.97 0.20 0.05
1.00 0.10 0.00
1.00 0.00 0.00
1.00 1.00 1.00
-V this option causes ausmap to produce a vector plot. Ausmap will expect the input file (defaulting to tape1) to contain both zonal and meridional vector components in concatenated units of the standard ausmap write.

-X this option causes ausmap to produce a raster type plot, where each grid value is plotted as a single colour coded pixel. An example is given below. Warning, grid squares crossing the 0E merdian are not plotted.

-a[value] this option allows the user to specify the text size to be used for the headers. The default value is 0.011. Size is specified as a fractional distance across the plotter frame (the page), and is linear. For example -a0.025 causes headers to be written as size 0.025.

-b allows pattern filling in user specified bands (data taken from tape1 or its equivalent). Ausmap prompts for the number of bands to be shaded and then, for each band, the lower value, upper value, the pattern density, the pattern width and the banding pattern. The dot density can take values from 1 (widest spacing) to 10 (solid fill). There are eight possible patterns, these are

0 - stippling (circular dots)

1 - angled stippling (circular dots)

2 - lines bottom left to top right

3 - lines bottom right to top left

4 - vertical lines

5 - horizontal lines

6 - angled cross hatching

7 - cross hatching

8 - solid fill

Importantly, for the solid fill, the pattern density has the role of changing the colour (1 is black), and the pattern width has no meaning. The pattern width is the width of the elements composing the pattern (for example the lines in hatching), the default is 1000 units.

-c causes ausmap to prompt for the contour range and interval to be used for the drawing of contours.

-d this allows the user to specify the dot size, spacing, and colour for significance stippling (-t option). The required values are input when requested by ausmap. The default dotsize (diameter) is 2000 units and the default spacing is 0.01.

-f option causes ausmap to infill data holes (areas of special values) using an inverse distance weighting Gaussian function. This in effect is a one pass Barnes analysis.

-g causes ausmap to use the NCAR provided low resolution global map data set. This should be used for map domains which extend beyond the Australia region. All options are supported for both the low and high resolution map data sets.

-h causes ausmap to not produce any header or footer information. This is useful for publication quality output.

-i option allows the user to plot lines on the figure using lat/lon coordinates contained in a user given ascii format file. The input file is taken to be of the form,

header
xlon,ylat
 .. ..
 .. ..
xlon,ylat
where xlon,ylat are written as 2f7.3, header is a character string of any length used to demarcate continuous line segments. The name of the input file is requested by ausmap during its running. An example file is given below,

murray darling basin outline segment 1
147.118-24.971
147.192-24.996
147.239-24.987
147.278-24.957
147.278-24.923
147.319-24.873
murray darling basin outline segment 2
147.646-24.797
147.649-24.774
147.681-24.772

-k allows the user to plot asterixes on the figure frame, using coordinates contained in a user given file. The input file is taken to consist of repeating units of the form,

i,ylat,xlon
 .. .. .. .. ..
i,ylat,xlon
written as a free format ascii file. For each ylat,xlon pair ausmap draws an asterix on the figure frame.

-l allows the user to change the spacing and size of contour labels. ausmap prompts the user to enter values for the spacing of labels, and also their size.

-m causes ausmap to mask the continents or oceans in white. Ausmap prompts the user to indicate whether the continents or oceans are to be masked.

-n causes ausmap to not produce a bold zero contour. The default is for the zero contour on plots to appear bold (double width).

-o option suppresses the drawing of coastlines.

-s sets the special value on ausmap so that special values are not contoured (the special value is 99999.9). Those areas on the input grid which contain these special values are shaded grey and a no data labels is added to a the key if such a key exsists. Without this option those regions of no data are left blank (i.e., appear as white space).

-r option causes ausmap to plot streamlines. The input file must contain a zonal and meridional vector components as for the -V option.

-t causes ausmap to take the second named file (defaulting to tape2) and stipple those region on the plot domain where the absolute values exceed a value given by the user. This is particularly useful for the stippling of significance areas on figures.

-v sets variable interval contouring. Ausmap will prompt the user for the number of contours required and the value for each one.

-x<#> allows the user to plot # sets of data on a figure frame. The input file (tape1 default) is taken to consist of # concatenated ausmap files, where # is a number greater than or equal to 1.

-z allows the user to turn off the smoothing. This may be useful for highly erratic data (particularly with the -b, -B, or -t options) because smoothing can very occasionally cause the contour lines to cross or out of bound errors to occur. If these problems occur, then the user should rerun the ausmap command but include the -z option as well.


4. Viewing, Printing and Converting Gmeta files

The output file from ausmap (gmeta) is in the NCAR CGM format (NCGM) which can be converted to a wide variety of file formats including PS, CGM, GIF and TIFF.

To view the NCGM file the easiest method is to use the NCAR ictrans graphics viewer. The syntax for viewing the NCGM file gmeta is,

ictrans gmeta

This will open a bordered black window on the screen and give the user an ictrans> type prompt in the working area. To display the frame type p followed by return at the ictrans> prompt, i.e.,

ictrans> p

The graphics should now display. To quit type return followed by q then return, at the ictrans> prompt.

The NCAR ctrans command is used to convert a NCGM file to a Postscript file which may be printed or viewed. The command syntax is,

ctrans -d ps.color gmeta > psfile

where psfile is the output postscript file (of course, this may be any name) and gmeta the NCGM file. This file may be viewed using ghostview (or your favourite PS viewer), i.e.,

ghostview psfile

and printed using lpr (or lp). For example, to print the PS file psfile on the printer tektr type,

lpr -Ptektr psfile

To convert the NCGM file to the portable CGM format the NCAR command ncgm2cgm is used, the syntax is,

ncgm2cgm gmeta > output

where output is the CGM equivalent of the NCGM file gmeta. This file may then be converted using any one of the many graphics packages (such as paintshop, alchemy or PBMPLUS) to the desired graphics format.


5. Example Figures From Ausmap 5. Example Figures From Ausmap

Following is a set of example products which demonstrate some of the abilities of the ausmap program. The command used to generate these is also given. Note that the slightly degraded image quality is due to the modest resolution of the gifs and not a product of ausmap.

Example 1: ausmap -S input_file

Description: Southern polar stereographic projection with ausmap selected contour interval.

Example 2: ausmap -S -h input_file

Description: Southern polar stereographic projection with contours and without header.

Example 3: ausmap -S -g -z input_file

Description: Southern polar stereographic projection with global map set and unsmoothed contours.

Example 4: ausmap -S -g -h -r input_file

Description: Southern polar stereographic projection with global map set and streamlines.

Example 5: ausmap -G -g -c input_file

Description: Global cylindrical equidistant projection and user specified contour intervals.

Example 6: ausmap -B -S -g -m -v input_file

Description: Southern polar stereographic projection with colour banding, variable contour interval, land masking, separate key and global map set.

Example 7: ausmap ausmap -c -g -t -a 0.021 -C -V input_file1 input_file2 input_file3

Description: Lambert conformal Australian region projection, with contours, vectors, stippling and large font header. The projection information provided by the use for this example is,


LC
135
-10.0
-40.0
n
-40.0 90.0
-40.0 180.0
-50.0 100.0
-8.0 120.0

Example 8: ausmap -v -T -m -B -O -a0.014 input_file

Description: Lambert conformal Australian region projection, with variable contours, colour stippling, large font header, ocean masking and user specified colours.

Example 9: ausmap -z -x 6 -v input_file

Description: User defined (cylindrical equidistant Australian projection) with variable contour interval, unsmoothed contours, and 6 sets of contour data.

Example 10: ausmap -B -K -m -2 -c input_file

Description: User defined (cylindrical equidistant projection) with user chosen contour interval, colour banding (two colour scheme), ocean masking and data values overlayed.

Example 11: ausmap -B -K -T -m -I -v input_file

Description: User defined (cylindrical equidistant regional Australian projection) with variable contours, colour banding, ocean masking and Murray Darling Basin outline. User selected colour scheme.

Example 12: ausmap -D -O -K -b -m -v input_file

Description: User defined (Lamber conformal Australian projection) with variable contours, banding, decile information, ocean masking, place names and user defined key label.

Example 13: ausmap -h -P input_file

Description: User defined (Lamber conformal Australian projection) with grid values plotted and no header.

Example 14: ausmap -c -h -k input_file

Description: User defined (Lamber conformal Australian projection) with data points plotted, no header and contour levels chosen to give no contours.

Example 15: ausmap -v -m -B -T -K input_file

Description: User defined (SW Australian projection) with variable contours, ocean masking, colour banding, user defined colour table and station names.

Example 16: ausmap -2 -X -c -g -G input_file

Description: A global raster type figure with key and blue to red colour palette.

Example 17: ausmap -l -X -P -c -g input_file

Description: An Australian region raster type figure with key. Grid values are also overlayed (-P) option. Projection is Lambert conformal.