.\" Process this file with
.\" groff -man -Tascii voaAreaPlot.1
.\"
.TH voaAreaPlot 1 "Nov 2009" Linux "User Manuals"
.SH NAME
voaAreaPlot \- Plot VOACAP Area Data Files
.SH SYNOPSIS
.B voaAreaPlot [options] file_name
.SH DESCRIPTION
.B voaAreaPlot
A python script used to graphically display the contents of output files
produced by VOACAP 'area' calculations. the 'file_name parameter defines the
path to a .voa or .vgz file.  If a .voa file is specified, the corresponding
output files (e.g. '.vg1') must be located in the same directory.
.SH OPTIONS
.IP "--version"
Display the version number and exit.
.IP "-c, --contours"
Plot contours on the map.
.IP "-d DATATYPE, --datatype=DATATYPE"
An integer number representing the data type (MUF, REL or SNR) to plot. Valid values of DATATYPE are 1 (MUF), 2 (REL), 3 (SNR) 4 (SNRxx), 5 (SDBW) and 6 (SDBW - formatted as S-Meter values).  Default value is 1 (MUF)
.IP "--filled-contour"
Creates a filled contour plot.
.IP "-h, --help"
Print a help message and exit.
.IP "-i, --meridian"
Plot meridians (lines of constant latitude) on the map..
.IP "-k, --background"
Specify the colour of the background. Any legal HTML color specification is supported e.g '-k red', '-k #eeefff', (default = white)
.IP "-l, --parallels (lines of constant longitude) on the map."
Plot parallels.
.IP "-m COLOURMAP, --cmap=COLOURMAP"
COLOURMAP specifies the Colour map used by the plot.  Valid values are; 'autumn', 'bone', 'cool','copper', 'gray', 'hot', 'hsv', 'jet', 'pink', 'spring', 'summer', 'winter'.  Default value is 'jet'
.IP "-n POI_FILE, --interest=POI_FILE"
POI_FILE is a text file with points of interest to plot on the map.  The file is comma (,) delimited with a single point of interest on each line in the form "longitude, latitude, text_name". The file format is the same as Garmin's POI csv files.  A sample file would look like;
.br
36.599998, 28.366667, Tabuk
.br
39.183334, 21.700001, Jeddah
.br
42.799999, 18.299999, Khamis Mushait
.br
40.549999, 21.483334, Taif
.br
50.150002, 26.266666, Dahran
.IP "-p PROJECTION, --projection=PROJECTION"
PROJECTION specifies the map projection.  Valid values are 'cyl' (Equidistant
Cylindrical), 'mill' (Miller Cylindrical), gall' (Gall Stereographic),
\(aqrobin' (Robinson), 'vandg' (van der Grinten), 'sinu' (Sinusoidal), 'mbtfpq'
(McBryde-Thomas Flat Polar Quartic), 'eck4' (Eckert IV), 'kav7' (Kavrayskiy
VII), 'moll' (Mollweide), 'hammer' (Hammer).
.IP "-r RESOLUTION, --resolution=RESOLUTION"
A single character representing resolution of the final plot.  RESOLUTION may be one of 'c' (crude), 'l' (low), 'i' (intermediate), 'h' (high), 'f' (full)
.IP "-t, --terminator"
Displays the night/day regions on the map.
.IP "-v VG_FILES, --vg_files=VG_FILES"
VG_FILES specifies which .vg files to plot, e.g. '-v 1,3,5,6' or use '-v a' to print all plots associated with the input file.  Default is 1.
.IP "-z TIMEZONE, --timezone=TIMEZONE"
Specify a timezone.  This option adjusts the (UTC) time specified in the datafile to the users local time.

.SH EXAMPLES
.IP "voaAreaPlot aDataFile.voa"
Plots the contents of the file aDataFile.voa using default settings.
.IP "voaAreaPlot aZipArchive.vgz"
Plots the contents of the .voa file found in the .vgz archive using the default
settings.
.IP "voaAreaPlot -r i -p mill aDataFile.voa"
Plots an intermediate resolution miller projection.
.IP "voaAreaPlot -m autumn -p ortho aDataFile.voa"
Plots an orthographic projection using the colour map 'autumn'.

.SH ENVIRONMENT
voaAreaPlot does not require or make use of any environmental variables.   The program requires the matlibplot library and basemap toolkit to run.
.SH BUGS
No major bugs are known. Please submit .voa and .vg* files when submitting bug reports.
.SH AUTHOR
The application and and man page was written by James Watson (M0DNS / HZ1JW) <jimwatson at mac dot com>

.SH ACKNOLEDGMENTS
I'm indebted to the authors of matplotlib and the basemap toolkit which make plotting complex data sets straight forward and fun :-) Also to Lowell and Alex for beta testing and support.