This file is README.AZP for AZ_PROJ.PS v1.04b1, Oct 1996.
AZ_PROJ.PS (C) 1994, 1995 Joseph Mack NA3T and Michael Katzmann NV3Z.

LEGAL STUFF:

AZ_PROJ.PS is freely redistributable software; you can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or (at
your option) any later version.

What this means is that you can do anything with it for your
personal use, except make money with it - i.e. the commercial
rights belong to us.

This package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with AZ_PROJ.PS; see the file COPYING. If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.


WHAT DOES AZ_PROJ DO:


	AZ_PROJ is a set of postscript files that generates azimuthal
equidistant projections of the earth from almost (not from the poles)
any location, giving bearing and distance from your location to any
other place on the surface of the earth.

WHERE TO GET AZ_PROJ:

	The publically released versions of AZ_PROJ ver1.0x are archived in

North America at ftp://oak.oakland.edu/pub/hamradio/dos/ham-utils/azprj10x.zip
Europe        at ftp://nic.funet.fi/pub/ham/antenna/azprj10x.zip


	Beta release code (if it exists) is available at the AZ_PROJ website
(see below).

AZ_PROJ Website and MapServer: currently at http://www.xray.duke.edu:1080/

	The AZ_PROJ Map Server will generate GIF formatted maps for you
to download, using a subset of AZ_PROJ's features. A map of North America
takes about 5 mins to generate when the machine is lightly loaded.

	While code will be always available from the ftp sites, the
Website will move according to contingencies of work etc, and may have
moved, or not even exist by the time you read this. I am currently (Jan 97)
looking for a new job in which case this map server site will disappear.
The following people will update their links as soon as I have a new
web site. Look for links to AZ_PROJ

<a href="http://www.access.digex.net/~michaelk">Michael NV3Z</a>,
<a href="http://mo.net/~aa0yt">Colin K4SSO</a> and
<a href="http://www.connix.com/~wz1v/newsvhf.html">Ron WZ1V</a>

HOW DOES AZ_PROJ WORK:

	The AZ_PROJ files are a set of Postscript files.
Postscript is most commonly sent to a printer. If you
do not have a Postscript printer, then you can use a
Postscript interpreter, such as Ghostscript to output
the AZ_PROJ files to your display or to your non-Postscript
printer. (See the file ghost.doc for Ghostscript setup
suggestions). Postscript is computer independent, however
you have to get Ghostscript for your computer. Ghostscript
is available for many computers (MSDOS, unix) producing
display output in X-windows (unix or DesqviewX), or under
MSDOS/Win95 with a 386 chip to a VGA display. Ghostscript
produces native code for many printers, allowing many
printers to function as a postscript printer.

	The AZ_PROJ files contain geographic data and
routines to draw the azimuthal equidistant projection.
You edit the file az_ini.ps to enter such things as
your location and the scale of the map. You then
send the AZ_PROJ files to your printer or display
either directly or via Ghostscript.

	The data to produce the coastlines, countries,
states, rivers, lakes and islands comes from the public
domain CIA World Data Bank.

WHAT WILL AZ_PROJ RUN ON?

AZ_PROJ will run on anything that displays or prints Postscript,
or anything that can be made to run/display/print Postscipt
with the aid of a Postscript interpreter (like Ghostscript for
Intel and Unix machines).


The az_proj files have been run/used successfully on these platforms:

OS:

DOS5.0, DesqViewX v2.0, OS/2, Win3.1
Linux (1.1.92 -> 2.0.0 X11R6), Unix (SGI Irix 5.3, HPUX 9.0 X11R5)
Mac Quadra 950, System 7 (just sent to printer)

Interpreters:
Ghostscript 2.61, 3.33, 4.01

Printers:

- NEC LC890 Silentwriter with Adobe Postscript (Level 1)
- HP1200C/PS Color deskjet with Adobe Postscript (Level 2)
- Phaser II color printer (Tektronics ?) with Adobe Postscript (Level 2)
- HP Deskjet 500, HP Deskjet550C, HP Deskjet855C (fed with 550C code).

CPUs:
Intel 486, Pentium
HP9000/380
SGI MIPS


FILES IN AZ_PROJ

The zip file AZPRJ10x.ZIP contains the following files.
Files added in v1.04 are marked by an *


text files:
COPYING		The GNU Public License under which AZ_PROJ is distributed
GHOST.DOC	Hints for setting up ghostscript
SIMPSON.DOC	Article about NMEA by Wayne Simpson
README.AZP	This file
HISTORY.TXT	List of features added, with version number.

dat files:
ANNOT.DAT	An example annotation file
BEA_6M.DAT	The 6m beacon list, from M. Harrison in G land
BEA_W3EP.DAT	The beacon list, maintained by W3EP
DXCC.DAT	The ARRL dxcc countries list, maintained by K2DI
GRID.DAT	An example file for grid squares that have been worked
		This format is now superceded by the grid2 format. It
		will be removed in some future version of AZ_PROJ.
GRID.DAT	A modified version of GRID.DAT in which propagation mode
		(Au, F2, Es, EME, TEP or unknown) can be specified.
MOUNTAIN.DAT	An example file for plotting mountain tops
NMEA.DAT	An example NMEA format file for GPS location of QTH
QSOxxx.DAT	Pairs of QTH's and call signs for plotting paths of QSO's
		for other stations. Used for plotting contacts during an
		propagation opening (eg Es) with the idea of locating the
		scattering center.
REPEATER.DAT	An example file for plotting repeaters
ROVER.DAT	An example file for plotting rovers
US_CALL.DAT*	A file for labelling US call areas

Broadcast Stations:
TV_EURO.DAT*	European TV stations
TV_NACH2.DAT*	North American Channel 2 (55.25MHz) TV stations
TV_VK.DAT*	Australian TV stations

	Other broadcast stations will be released by Colin K4SSO
at http://walden.mo.net/~aa0yt as they become available.



Postscript files:
AZ_INI.PS	The initialisation file - edit for your location and needs
AZ_PROJ.PS	The Postsript file which has the routines and generates the
                   projection
CONTROLD.PS	The ^D symbol (EOF for a postscript printer).
HF_CONF.PS	Preconfigured file for HF maps (see comments in file).
VHF_CONF.PS	Preconfigured file for VHF maps (see comments in file).
10GHCONF.PS	Preconfigured file for 10Ghz mountain top events (see comments in file).
TV_CONF.PS*	Preconfigured file for North American Ch2 TV stations.


wdb files:
AFRICA.WDB	Positions of points on the surface of the earth
ANTARCT.WDB     	derived from the CIA World Data Base
EURASIA.WDB		""
N_AMER.WDB		""
OCEANIA.WDB		""
S_AMER.WDB		""

some of the example bat files for MSDOS:
(Make sure you change the name of the ghostscript executable
to that for your system. It will be something like
gs, gs386, gs261dvx...)

AZVIEW.BAT	view a continent under Ghostscript
AZVIEW1.BAT	like azview.bat except data is fed to Ghostscript stdin,
                    as if Ghostscript were a printer
AZFILE.BAT	generate a file for later printing, needs gs v3.33
AZGIF.BAT	generates a gif file with gs v2.61
AZPRINT.BAT	print under Ghostscript directly to a printer
AZPRN_PS.BAT	copy files to a Postscript printer
AZVHF.BAT	use of config file (this one for vhf)
AZ10GH.BAT	display map for 10GHz mountain top event, using GPS derived QTH
MAKBIG.BAT	concatenate files
MAKDAT.BAT	concatenate files
MAKWORLD.BAT    concatenates .wdb files into a world.wdb file

Files to Plot CT output

	CT is K1EA's contest logging software, a commercial program
(costs about US$80) popular among VHF'ers (how to get info below).
These files convert convert the CT .grd file (which contains grids
worked in the contest) into AZ_PROJ grid.dat files.

	CT updates and saves its files after each entry in the log,
so in principle it is possible to draw a new AZ_PROJ map after each
new grid is worked.

ct2ak.awk	Turns .grd files from CT into AZ_PROJ grid.dat files
jun95.grd	Sample CT .grd file from NA3T/NV3Z
jun95.dat	The file produced from jun95.grd by running the command
		C:\azproj\mawk -f ct2az.awk jun95.grd > jun95.dat
mawk122x.zip	An implementation of new/posix awk 
                by Mike Brennan, brennan@boeing.com.
		ported to DOS/OS2 by Darrel Hankerson 
                hankedr@mail.auburn.edu 4 February 1996.
		Unzip this file and put mawk.exe in a directory in 
		your path (eg C:\dos or C:\bin)

Old versions of CT are available free on various BBS's. There is also
an ftp site (ftp://maspar.maspar.com:/pub/k2mm/ct-files/).
Current versions of CT are available on the CT BBS (USA-508-460-8877).
There is a mailing list for CT users, to subscribe, send a message
to "CT-USER-REQUEST@ENG.PKO.DEC.COM" with the command
SUBSCRIBE in the body of the mail message.

CT is a copyright of K1EA Software, a division of Harvard Radio.  It can
be obtained from:

        K1EA Software
        A Division of Harvard Radio, Inc.
        5 Mount Royal Avenue
        Marlborough, MA  01752-9650
        508-779-5054




DESCRIPTION OF AZ_PROJ

	This file (README.AZP) is a brief description of the use of
AZ_PROJ.PS. For a detailed explanation see the comments in each file.

AZ_INI.PS

	AZ_INI.PS will arrive set up to give a map of North America
centered on the ARRL HQ in Newington CT, at a scale of 400km/cm.
To customise the maps, you edit az_ini.ps. Until you've got the
AZ_PROJ examples to work, you should not change any of the files
that come with the distribution.

	AZ_INI.PS has variables which allow the map to be customised.
In general the order of variables can be changed to suit your needs,
as long as variables which are defined in terms of other variables
are not exchanged in order (eg colors need to be defined before you
use them). AZ_INI.PS is full of comments which will tell you how to
customise AZ_PROJ. You can remove these comments when no longer
needed.

DATA FILES

	The format for these files is rigid and inflexible. AZ_PROJ
determines the type of data in a line from the first few characters.
Unrecognisable lines are ignored (with an error notice and the
offending line posted to stdout if verbose is on).

	Blank lines are not valid data. Make sure all comment lines
begin with a %

.WDB files

	These are an ascii version of the Central Intellegence Agency
Micro World Data Base (CIA WDB) adapted for AZ_PROJ. These files contain
geographic information. In general you will not need to change these
files. However if your favorite lake, island or river was not considered
worthy of inclusion by the CIA, then you can add it yourself using the
same format.

.DAT files:

	These are files containing one piece of information per line.
Each line starts with a word (eg beacon) followed by a ":" (beacon:).
These .dat files contain ham specific information such as dxcc
lists of countries (worked and not worked), grid squares worked,
beacons, mountain tops, and any annotations that you want to put
on the map ("Mom's place"). Enough information has been included at the
start of each .dat file for you to be able to add/change entries.

	Since the .dat files are just collections of independent
on line entries, there is no real reason to keep the .dat files
separate - in principle the .dat files can be concatenated and
the lines put in any order. We have kept each type of .dat
file separate mainly for bookkeeping purposes.

	Note: Order of files.

	The data (.dat and .wdb) files can be sent in any order. However
the output of each file will be drawn on top of the output of the previous
data files. Thus the order in which .dat files are sent to the output
(the order in the command line or in the combined file sent to a printer)
affects the look of the map.

	In particular if you're using a NMEA.dat file generated from
Global Positioning System (GPS) NMEA formatted data to center your
map (such as on a mountain top) then this file _must_be read first
as it will move the QTH from that established in az_ini.ps.

	Some of the .dat files (eg grid.dat) generate solid colors
that will cover anything under it. These types files should go next.
The other .wdb/.dat files put points or lines on the map and these can go
last.

	An example command line to put the files in the most sensible
order would be

C:>gs386 -q az_ini.ps -- az_proj.ps nmea.dat grid.dat n_amer.wdb *.dat

	When sending to a real Postscript printer, these files could be
concatenated, again in the chosen order, by generating the file big.ps,
using the following command line and then sending big.ps to the printer.

C:>copy az_ini.ps+AZ_PROJ.ps+grid.dat+n_amer.wdb+mountain.dat+beacon.dat big.ps


MAKING MAPS

1. SENDING TO SCREEN/PRINTER VIA AN INTERPRETER (eg GHOSTSCRIPT):

	If you don't have a real postscript printer or if you
want to display AZ_PROJ maps on a screen then you will need
a postscript interpreter like Ghostscript (see ghost.doc and
the comments in AZ_PROJ.ps).

	MAKE SURE THAT GHOSTSCRIPT IS RUNNING ON YOUR MACHINE BEFORE
TRYING TO RUN AZ_PROJ. RUN THE TEST FILES tiger.ps AND use.ps first.

	Run some of the example files that come with
Ghostscript (e.g. the graphics file tiger.ps) and a postscript file
which contains text (eg the manual, use.ps, which comes with
Ghostscript). A postscript file which contains text is needed
to show that you have the FONTMAP file pointing to the correct
fonts (otherwise you'll get complaints from ghostscript that it
cannot find various fonts).

	Ghostscript runs on your computer (rather than in your
printer as with Postscript) and hence it can find files on your
hard disk. The names of the data files can be given as parameters
to the interpreter. You can send any number of different .WDB and .DAT
files to ghostscript as command line parameters, rather than
concatenating the files together before sending them to the
output device as is done with a postscript printer.

	Note that AZ_PROJ checks the size of the display
it is printing (or screening) on. Since the screen and printer
could be different sizes, you will not neccesarily get the same
picture when previewed on a screen as you will on the
printer. (The versions of Ghostscipt compiled to run under
X-window think they're running on 8.5x11.0" paper).

- screen viewing for DOS:

	C:\az_proj>gs386 -q az_ini.ps -- az_proj.ps n_amer.wdb

	or run the supplied file azview.bat

	C:\az_proj>azview

- to a file for later printing

	To make the file `n_amer.cdj' which can then be sent to
a color desk jet 550 (which ghostscript calls a "cdj550", see the
ghostscript docs for details of other printers) -

	C:\az_proj>gs386 -q -sDEVICE=cdj550 -sOutputFile=n_amer.cdj az_ini.ps -- az_proj.ps n_amer.wdb dxcc.dat

	or run the supplied azfile.bat file

	C:\az_proj>azfile

	The format of the command line for ghostscript is

	exucutable              (gs386)
	gs switches		(-q -sDEVICE=cdj550 -sOutputFile=n_amer.cdj)
	postscriptfilename      (az_ini.ps)
	another switch	        (--)
	datafiles               (az_proj.ps n_amer.wdb dxcc.dat)

- sending a file to a non-postscript printer

	You can send output to the printer directly (see below). However
you might want to generate the file if you want to print several copies of
the map (and only have to calculate the map once), or you have a spooler
(recommend dmp205.zip, look on a BBS) which will give you back your
keyboard again, so you can go on with something else during the printing.


- without a spooler (note /b for binary)

	C:\az_proj>copy/b n_amer.cdj lpt1:

- to the printer directly (PRN is the normal output target in MSDOS)

	To send to the printer (through lpt1:, note: can use MODE to redirect)

	C:\az_proj>gs386 -q -sDEVICE=cdj550 az_ini.ps -- az_proj.ps n_amer.wdb dxcc.dat

	or run the supplied azprint.bat file

	C:\az_proj>azprint

- using ghostscript to simulate a printer

	A printer listens to its stdin (the printer cable). A printer
doesn't know about files. Ghostscript can run in this mode. Make a
big.ps file using makebig.bat. Then do


	c:\az_proj>type big.ps | gs386 -q -

	The first part of the instruction sends the file to stdout, the
second part tells gs386 to take input from stdin (for unix change "type"
to "cat"). You'll get a screen display instead of printout. Note that
big.ps will already have the EOF for the operating system and controld.ps
is not needed (but will do no harm).

COLOR PRINTERS:

	If you're going to output color maps to a non-postscript
printer, using ghostscript and you want the colors gamma corrected
(they'll be murkier if you don't), then you'll need v3.33 of ghostscript.
V2.61 either doesn't do it, or doesn't understand my code, or
has a bug.

	If you have a color printer, read the poop in AZ_PROJ.ps
about gamma correction (use an editor to search for string "gamma").
If you have a Deskjet550C or 1200C you are already covered (we've
coded it for you). If you don't get the gamma correction right,
then the colors you get on the printer will be darker (murkier)
that those seen on the screen.

GIF FILE OUTPUT:

	You'll need gs v2.61 for this (try AZGIF.BAT). The
gif feature was removed from later versions of ghostscript,
for fear of copyright infringement with Compuserve.

2. SCREEN DISPLAY IN A WINDOWING ENVIRONMENT.

	In a windowing environment like X-window, you can launch
the program from one window and have a new window pop-up to display
the map. In this case you can turn on a feature we used for debugging,
(verbose, in az_ini.ps) and the launching window will tell you what
is being drawn in the display window or what is being generated
in the printer output file. (Remember to turn verbose to off
for all other cases).

3. SENDING TO A POSTSCRIPT PRINTER:

	Printing on a Postscript printer is sloooooow. It takes
75 min to generate a map of the whole world on an HPLaserJet 5MP with
3M of memory.

	As well, AZ_PROJ needs lots of memory. Postscript printers which
only have enough memory to handle text may not be able to handle all the
graphics.

	The files must be sent as one stream (ie one big concatenated
file) in the suggested order

az_ini.ps
az_proj.ps
nmea.dat
grid.dat
*.wdb files
*.dat files
controld.ps

	Run makebig.dat to make such a file.

	At the end of the concatenated file, there MUST be an EOF
(a ctrl D for postscript) for the printer to know that it had come
to the end of the job. This is usually sent by the spooler, but
if your setup (like most MSDOS and some unix setups) doesn't do this,
you'll wait hours till the printer times out. If this is your
situation, concatenate controld.ps onto the end of your big.ps
file for printing.



Examples:

(make sure "verbose is "off" in the az_ini.ps file)

- to a postscript printer (DOS)-

	Run makebig.bat

	C:\az_proj>makebig

	This will produce big.ps. Send this new file to your postscript
printer with

	C:\az_proj>print big.ps

- to a postscript printer (UNIX)-

	$ cat az_ini.ps AZ_PROJ.ps n_amer.wdb |lp


Examples:

(make sure "verbose" in az_ini.ps to "off" in the az_ini.ps file)

- to a postscript printer (DOS)-

	Run makebig.bat

	C:\az_proj>makebig

	This will produce big.ps. Send this new file
to your postscript printer with

	C:\az_proj>print big.ps

- to a postscript printer (UNIX)-

	$ cat az_ini.ps az_proj.ps n_amer.wdb |lp



CUSTOMISING AZ_INI.PS FOR YOUR NEEDS

	Just start changing things in az_ini.ps to vary the map.
Hopefully there's enough documentation there to help you. Here are
some that you're likely to want to change.

QTH:

	You can change the lat/lon to your QTH (use decimal degrees,
eg 90.05, with N and E being positive, S and W being negative),
center_offset (2nd line) to "off", change the scale to "500"
and scale type to "off".

SCALE:

	A map of the whole world needs 2000km/cm

DECORATIONS:

	For example, you can turn letter_squares and labels on/off, with
number_squares and labels on/off.





That's it.


	Have fun
	Our addresses are in AZ_PROJ.PS

	Joe NA3T and Michael NV3Z
	Jul 1996

Map Server: http://www.xray.duke.edu:1080/

e-mail for comments on AZ_PROJ:
mack@xray.duke.edu
mack@ncifcrf.gov
