===========  THIS TEXT IS INCLUDED IN THE ASCII FILE 'README'  ==============

    
    Geographic,  site database, path and height plotting programs. 


           (c) A C Talbot G4JNT     May 1996

Latest changes and variations from older versions of this software.

All software included within this suite is public domain and may 
be copied freely  provided no charge is made for it other than
to  cover distribution costs.  Commercial users if you must, but
read below.

If any alterations are made to any of the programs please change
the name of the altered program before further copies are
distributed.  The heritage of the height database is somewhat
dubious, it was sent to me (almost) anonomously six years ago
with no indication as to where it came from or its structure and 
needed a lot of massaging and hacking to get it into its current 
form.  So, anyone who wants to use it for commercial purposes, 
on your own head be it!

The software is primarily aimed at Radio Amateurs for path plotting,
link calculations and contest scoring purposes.  Other users may find 
the note at the end of some use.

These programs allow a directory of sites to be consulted and
the distance and bearing of paths between them to be calculated.
Maps sites and paths can be plotted and accurate conversion 
between Locator, NGR and Lat/Long is provided.

The height database and associated programs allow terrain maps
to be generated of almost any region of Great Britain;  Ireland
and the Channel Islands are not included.  

The Power Basic (version 3) source code for all height software
in included so that the somewhat convoluted database structure
can be worked out and used in other programs.

Height Plotting accuracy.

The spatial resolution is based on National Grid Reference
500 metre squares, and height is stored to a mean accuracy of
3 metres although this accuracy figure worsens to 7 metres at the 
top of Ben Nevis (for the reason behind this see the file
structure notes later). 

The 100 km NGR square NG, including the Island of Skye, which was
damaged in earlier versions of this software has been repaired 
thanks to G3NKL who pieced it back together again!

Storage and computer requirements.

When decompressed, the entire software suite takes up 3.5 Meg and
all programs need to be within the same subdirectory with the single 
exception of the height database which may be in D:  see below.

Graphics need a colour VGA screen or higher.  The programs will
run on any processor, but using anything less than a 286 machine 
can be painfully slow for maximum plot extents.  To help speed 
things up HEIGHTS2.DAT can sit in a Ramdrive; provided this is 
configured as drive D: the software will find it IF the data file does
not also sit in the default directory. The easist way to ensure that
this state occurs is to keep only HEIGHTS2.ZIP and decompress to D: when
needed.  The whole process can be automated by a batch file as required.
This undocumented facility has always been available (hands up anyone
who found it) as I needed it for my original 286 machine, and now use it
to speed up the 286 laptop running this software.

Slightly more serious, some 386 and 486SX machines with NO maths
co-processor installed can lock up on LOCALMAP and possibly others.  I 
can do very little about this  as it is a function of the compiler and
not the program code.  Some machines work OK (two that I tested it on) 
but others lock up, there seems to be no logical reason why some machines 
are susceptible and others aren't.  A 386 with no 387 is uncomfortably 
slow anyway running several of these progs and old 80x87s are getting
quite cheap now........

Windows (ugh) icons are provided for five of the most popular programmes 
if you feel you have to resort to this operating system.

----------------------- PROGRAMS --------------------------------

                        LOCATION   

Location is a general purpose NGR, Lat/Long locator (and even the
old QRA) conversion utility;  including a distance and bearing
calculator.  8 digit locators (see the Nov 1991 Microwave
Newsletter and subsequent RadCom) are supplied as standard, but
either 6 or 8 or 10 digit ones may be entered.  10 digit locators
eg IO90IV58EI are generated where accuracy allows; whether these ever
come into common usage (18 metre accuracy) remains to be seen, but
some GPS systems do give 10 digit Maidenhead locators as an option.
Note that no other programs on this disc make use of or will accept
10 digit locators.

NGRs may be entered in any form or precision (eg SU4990512575 or 
su 499 126  or  SU 49).  Lat /Long may be entered in (nearly)
any form.  See the online help (F1) for more information.

All Lat/Long to/from NGR routines use the EXACT Ordnance Survey 
equations for very high accuracy, but note that other programs on 
this disc use the less accurate routines given in the Microwave
Handbook; these however are still accurate to better than 25m in
the central UK.  

The site database SITES.DAT can be called up for named locations, and
this can be scrolled through to find the wanted site, again see the 
online help.

                        SITECALC 
                              
This program provides a distance and bearing printout for a
number of operating sites in the UK stored in SITES.DAT.

Run SITECALC.EXE making sure SITES.DAT is in the current working
directory.  At the first prompt enter either a locator (6 or 8 digit), 
NGR or a sitename.   The format is recognised automatically.
In the case of a sitename, just enough of the name needs to be entered 
to positively identify the site in the database, but the letters can 
occur anywhere within the name. If return is pressed at this point the 
database can be scrolled through to review the list before entering a 
sitename.

Select Magnetic or True bearings (The default is True) and if
Magnetic, enter your own magnetic variation or press return for
an approximate calculated one.  This is calculated using the
empirically derived formula :- Mag Var. =  .09 * Lat - .5 * Long
and seems to hold good over most of Southern England at least:
to around 1 degree accuracy.

If you require a printout for ALL sites press return at minimum
and maximum distances for printout.  If only paths over a certain
distance, or under (or both) are wanted then enter the
appropriate figures.  If only bearings within a certain sector
are wanted, answer 'Y' at the prompt and enter the two required
limits, clockwise from A to B  eg. 350,40 prints those bearings
from 350 to 40 including north.

If a printout is required, answer Y/N for hardcopy and enter the
appropriate printer type,  then sit back and watch.  The printer
types should cover most common devices.  A print to file option
is provided at this point and the file may be sorted into order of
either Name, Bearing, Locator or Distance

If hardcopy has NOT been requested then the screen display will
halt after each screenful and can be continued by pressing the
spacebar.  As a shortcut when starting the program the sitename may 
be entered as part of the command line,  eg type   SITECALC G4JNT

The hardcopy option will also allow a file to be made.  This is
in the same format as printed copy, but in addition may be sorted
into order of either name, distance bearing, locator or NGR.  The
sorting options are presented after the initial calculations have
been completed.

8 digit locators are provided where the stored location accuracy 
allows; where location is stored as a 6 digit locator (many home 
stations for example) the generated NGR is only give to 1km accuracy
to avoid confusion.


DISTBEAR has been removed as its function is now covered in LOCATION


                        PATHPLOT

Plots the paths between any given sites on a map of the UK and
Europe. Requires EUCOAST.DAT and SITES.DAT to be in the DEFAULT
directory.  Sites may be specified by locator, NGR or the sitename.


                        PLSITES

Plots all the sites in SITES.DAT to a map of the UK.  By moving
a cursor around the screen with the cursor keys or mouse, any site 
can be named.  Requires .DAT files to be in the default directory.
The right mouse button calls TERRAIN (see later) to plot a height 
profile between the base site location and the cursor.

                        
                        GETSITE

Provides quick access to the database to find the NGR and locator 
of any site specified by name.  The name may be entered as part of 
the command line, eg.   GETSITE walbury.  ALL sites with entered 
search string will be found

                        WORLD

Plots a map of the world and allows the Locator for any spot to 
be read off using the mouse.  The data contained in CITIES.DAT is 
plotted to this map and the nearest country with its IARU prefix
can be found by clicking the left mouse button.  A base location 
(the default is Southampton) may be set by clicking the right 
mouse button where distance and bearing from here to anywhere in 
the world can be read off.

                        GTCIRCLE

Plots a great circle map of the World centred on any location 
specified by its locator (2, 4, 6 or 8 digit versions are all 
acceptable for this program ONLY).

                        GRIDS

Shows the Locator and NGR 'squares' plotted over UK and western 
Europe.  Thats all, nothing else!


---------- SITE DATABASE FILE AND PROGRAM STRUCTURE ---------------

Site data is stored in a simple serial file with arbitrary 
field lengths in the following form:-

Sitename~Location~Flags

The data may be edited using any text editor.  If using a word 
processor then make sure that the file is saved as a plain ASCII 
(or DOS) file to prevent any word processing control characters 
being included.  The tilde [~] is the delimiter between fields and
at least one must be included to separate the sitename from the
location. If the tilde cannont be found on the keyboard then it 
may be generated in the following manner:

Hold down the ALT key, and simultaneously type 126 on the NUMERIC 
KEYPAD keys. When ALT is released a ~ will suddenly appear!
At present, only the P flag (for 'popular' sites) is supported
by SITECALC.  Some sites also have a H flag followed by a number.
This is the mast height of the site (used mainly for fixed stations 
and beacons) and is called up automatically by most programs that 
require the figure.  If no mast info is stored, the programs will 
request the height.

When editing SITES.DAT make sure there are no spurious carrige
returns at the end of the file or blank lines in the body of it. 
All progs that read the database will throw a wobbler when they see
an invalid location in the file such as a blank entry.

Location is stored as either full alphanumeric NGR or locator. 
For 6 digit locators a four figure NGR is generated for this
lower accuracy reference, enclosed in square brackets. 10 digit 
locators and NGRs are not allowed (yet).

Bearings are calculated using the true great circle equations; this may
result in to and from  bearings not being exactly 180 apart. 
This is correct (think carefully about it).  A spherical Earth is
assumed, (radius 6371.29 km) so in most programs distance and bearing 
will not be calculated to the accuracy in LOCATION.  

Most of the programmes make use of an additional database called 
AUXSITES.DAT.  This has a format identical to that of SITES.DAT and allows
additional 'personal' sites to be called up without the risk of modifying 
the main database.

------------- HEIGHT MAPPING AND TERRAIN PROFILING -----------
                         
                         SHOWMAP

This program plots out a colour profile map of the UK, with a 
pixel resolution of 1 or 2 km.  At start up the 100 km
Northing for the bottom of the plot needs to be entered :-  eg.
1, 2, ... 12   Zero for the South Coast, 4 for Yorkshire up 
Scotland etc.  The plotting sequence is representative of the file 
structure (see later).

                        TERRAIN

Plots the profile between two sites to show obstructions or
visibility.  The plot follows the form shown in the Microwave
Handbook (Vol 1) where the curve of the Earths surface between
the points is mapped to a parabola.  Heights at any point between
are drawn vertically, and a straight line between the two sites
shows the visibility or otherwise.  

The refractive index related K value for the effective Earths
radio radius may be changed between spot values from 1 to 1.5 by
pressing the K key whilst the plot is showing.  The default value
is the average 1.33 usually assumed,  a K value of 1.0 represents
(nearly) the optical sight path.

Sites may be entered as either NGR - eg SU499126, 8 digit
Locator - eg IO90IV58 or by sitename, the format is recognised
automatically.  In the latter case the site database SITES.DAT
is consulted to find the location.  Whilst a six digit locator
will be accepted, this will have a 55 added to place the
reference at the centre of the square.  Note that 6 digit
locators are nowhere near accurate enough for height
determination using this database.

When TERRAIN is called up as an individual program, mast heights 
need to be entered, these are taken from the site database if 
applicable, and in several cases this is important in getting over 
the next hill.  TERRAIN may also be invoked by the mouse from 
several of the map plotting programs or by including the NGRs or 
Locators on the command line.  In these cases no options for mast 
height are presented but a default height of 1m (a short person ?) 
is assumed in order to get over local ground to at least the next 
500m point.

The mouse cursor allows heights at specific NGRs along the path
to be read off.  Clicking the left mouse button checks SITES.DAT 
for a site closer than 2km to the current cursor position


                        LOCALMAP

Plots a colour - height map of a square centred on a given
location.  Square sizes of 20 - 240 km may be entered, location
may be specified in any of the three forms as given above.

The mouse cursor may be moved within the square to read off spot
heights, distance and bearing from the centre reference but this is 
generated by the Pythagorus on NGRs method (as it in in all the height
programs) and its accuracy should not be implicitly believed.  (If 
distance and bearing are accurately needed use LOCATION or SITECALC)

By typing "T"  TERRAIN is invoked to plot the
path between the reference point and location specified by the
cursor.  Exit from TERRAIN back to the calling program is by a
further click on either mouse button.

A new reference location may be set by clicking the right mouse
button anywhere within the square.  Further calls to TERRAIN,
plus the distance and bearing will then use this new reference. 
However the square is still centred on the originally entered
point.   

The sites in SITES.DAT can be shown on the map and by clicking 
the left mouse button the site nearest to the cursor will be named.

Location may be specified from the command line by starting the
program for example   LOCALMAP Ben Nevis  or LOCALMAP ST260977.

Many other commands to change the colour scale, zoom etc are listed in
the menu.


                        LOCAL256 

Gives a coarse 256 colour height rendition which allows fine height detail 
to be seen. The crude graphics programming does not allow any mouse functions.

                        LOCALVES 

This is a version of LOCALMAP for VESA Bios based SVGA systems ONLY.  It
generates 256 colour plots at sizes of 640x480, 600x800, 1024x768 and
1280x1000.  Only use this last mode if your monitor can support the mode, if
it can't, and the SVGA card can, the monitor could do some very silly things.
No mouse functions as its a very major job writing SVGA mouse routines from
first principles.

I've ironed out the bugs found in previous versions of this prog that 
caused the plot to not page switch on some machines but this has only been 
fully validated on machines I have access to (later 486s and Pentiums less
that two years old).  Any problems with GENUINE VESA Bios SVGA machines let
me know.


                        3DMAP

Gives a 3 dimensional representation of height in addition to colour.  
Two different 3D representations can be toggled with the M key once 
data has been loaded.  The orthographic angle can be altered to provide 
an ideal looking display by use of the O and ctrl-O keys.  A different 
colour set can be toggled with the P (for Palette) key.


                        VIEW

Plots the visibility and horizon from any specified point.  A
polar/bearing type map is generated, with horizon distance being
shown by distance out from the centre, and horizon angle of up
to  0.8 by colour.

Bearing resolution and maximum distance out may be entered, but
default values to suit the specified site are generated by just
pressing return at the appropriate times.  Location, in any form,
may be specified on the command line.

Mouse cursor indicates NGR and height of any particular point and
distance / bearing from the centre.  Again, this is of dubious 
accuracy as it employs the Pythagorean flat Earth calculation method.  

Clicking then left mouse button identifies the nearest named site.


                        HORVIEW

Like  VIEW but on a rectangular scale of bearing v horizon angle.  
Distance is represented by colour.  Similar to view actually seen.
No mouse functions available, picturesque display only!


HORPLOT is nolonger included as it was just an early form of VIEW 
without visibility of intermediate land nearer than the horizon.


HORIZON has been removed as its functions are fully covered by
TROPPATH and TERRAIN


                        TROPPATH

As for HORIZON, but allows entry of RF and antenna parameters. 
These are used in the equations developed by G3YGF (Microwave
Handbook Vol. 1) to calculate the troposcatter loss between the
two stations.

                        SPOTHGT

Calls up the spot height for any individually entered location, 
as Sitename , NGR or locator.

BITMAP FILE OPTIONS

LOCALMAP, LOCAL256, TERRAIN, VIEW 3DMAP, HORVIEW and PATHPLOT have the 
option to generate a .BMP graphics file for exporting to other programmes 
or for printing.  Press F1 at the appropriate display time (or follow 
instructions) and a bitmap file will be generated.  The filename will 
be the part of the programme name followed by a serial number plus .BMP  
eg. TERRN001.BMP.  The serial number will increase with each file generated.  
The chosen colour palette will be included with the stored image.   Later 
versions of other programmes might also include this option so it might be 
worth trying F1 to see!



-------------------- HEIGHT DATABASE FILE STRUCTURE --------------------

The file HEIGHTS2.DAT contains spot heights at 500 metre
intervals over the bulk of the UK.  Heights are stored using one
byte per interval to keep the file within a manageable size and
reduce processing time.  

The UK is first divided into 100km high strips based on the NGR
northings,  the length of each strip is an integer multiple of
100km sufficient to cross the country country completely.  The
first 100 km square (the NGR letter square) that contains any
land becomes the  starting point for each horizontal strip whose
data length then depends on the width of Britain at that
Northing.  Therefore the 100km high strips start at arbitrary
points in the data file, and at arbitrary 100km Eastings on the
map.  The starting points in the data file are, however, all
multiples of 40000 (this being the total number of 0.5km grid
points in a 100km square).

The starting points need to be known in adavnce, and in each
program this information appears as a data statement which is
subsequently read into an array and accessed by the 100km
northing of any subsequently specified location.

Each 100 km strip is then broken down into 10 km squares which
are then further broken down into 400 individual data points. 
The order of the 10 km squares, and their subdivision, is not
straightforward.  Going through the data file,  the 10 km squares
start at the bottom left of the 100 km strips and 10 sucessive
squares are built up vertically from the bottom to form a strip
10 km wide by 100 km high.  This is repeated until the
easternmost limit for this strip is reached is reached.

Each 10km square consists of a raster scan of the 0.5km points
starting at the TOP of the square, plotting 20 points across and
then moving down one point to complete the 400 point square.

For any arbitrary NGR (Easting and Northing pair referred to as 
E and N and measured in km, floating point to allow 0.5) the
following stages are required to find the location in the
database where its associated height is stored :-

1)   Generate the 100km northing N100  =  N DIV 100 and use this
     to look up the file offset, FILEBREAK (in bytes), and 100km
     Easting, Estart (in km), of the start point of the strip. 
     Note that in the data statements of all the included
     programs, the FILEBREAK values are stored in kBytes and
     Estart in units of 100 km.  These have to be multiplied by
     1000 and 100 respectively to obtain the values as used
     below.

2)   Find the 10 km square from

     N10 = (N DIV 10) MOD 10  and
     E10 = (E DIV 10) MOD 10.


3)   Find the spot data pointers from 

     Npoint = 19 - (N DIV 0.5) MOD 20        nb. 19 -   because
                                             the data is stored 
     Epoint = (E DIV 0.5) MOD 20             downwards.

The file pointer is then given by :

POINTER   =    FILEBREAK + (E - ESTART) * 40000 + 
                    (N10 + 10 * E10) * 400 + 20 * Npoint + Epoint

Access the byte at this position to obtain   K   (0 to 255)

Then  Height  = K ^ 1.32

This seemingly strange compressed format was chosen in order to
map heights from zero to 1500m into the range 0 to 255.  Whilst
maintaining the accuracy of the original database based on
multiples of 5 feet (American and Olde English units) at low
elevations, the resolution degrades to around 7m at the highest
points.  The RMS deviation from the original database is 1.7m

To avoid excessive computational workload with floating point
maths, (not a problem if a maths coprocessor is available) the
colour maps are generated based on the compressed height, and
this is only expanded where needed to generate actual spot
heights.


-------- Note for non Radio Amateur users of this software ------

These programs are aimed at Amateur Radio (AR) communications but 
they are all of general interest, especially for educational
purposes.  The following items are all specific to AR operation 
although some have been encountered elsewhere, particularly the 
Maidenhead locator system.

SITES.DAT contains a lot of entries of the form G4JNT QTH.  These are
the home locations of Radio Amateurs whose callsign is the G.. part; 
QTH is a 'telegraphese' abbreviation meaning location.  Just delete 
these when customising the database for your own use.

The Locator  eg  IO90IV  or IO90IV58 is a locator system based on 
Lat / Long that allows any location in the World to be specified by
an alphnumeric code. An alphanumeric rather than all number system is 
chosen as it creates less ambiguity or confusion when quoted over 
a radio channel.  Originally invented by Radio Amateurs the Locator
system has been seen in several other areas where it is often referred
to as the Maidenhead locator (its original name, so called as its
inventor lived there).  Normally used in its 6 character form, a mean 
accuracy of around 4km is possible at European lattitudes; the 8 
digit form increases the accuracy to around 400m.  The format is 
as follows (note that the term 'square' is used very loosely; the 
shape in spherical geometry is anything but!) :

The first two letters specify Lat and Long in units of 20 degrees 
longitude (starting at -180 degrees) and 10 degrees of lattitude
starting at the South pole.  The letters are allocated A = 0, B = 1 
etc. Thus the bulk of the UK is in IO 'square' between longitude 
20 Deg West and 0 deg, and latitude 50 - 60 Deg N.  

( I = 8 so Long = -180 + 8 * 20  = -20 deg
  O = 14 so Lat = -90 + 14 * 10  =  50 deg  )
The next two digits divide this 'square' into 10 x 10 giving
1 deg lat and 2 deg longitude increments.  Thus 90 means:
9 * 2 = 18 deg N
0 * 1 =  0 deg E  Which are added to the Lat and Long given by the
first two digits  ie  Long = -2 Deg   Lat = 50 Deg
   
The next two characters divide this smaller 'square' into 24 x 24
giving 5' Long x 2.5' Lat subdivisions.  Thus IO90IV gives :
Long =  1 15'W   Lat = 50 52.5'N.  Since the centre of the 
'square' is taken as the reference (unlike NGR where the bottom left
hand corner is chosen) 2.5' and 1.25' respectively need to be added
to obtain the correct conversion.  Thus IO90IV gives Lat = 50 53.75'N , 
Long = 1 17.5'W.
   
The second pair of numbers, used where the accuracy requires it, 
divides the 'square' above into 10 parts, and again the centre of THIS 
'square' is used.    eg IO90IV58 = 50 54.62' N   1 17.25' W
   
To finally add confusion, two more letters can be added to further 
subdivide into 24 x 24 divisions of 12.5" x 6.25" (Seconds of arc). 
Thus IO90IV58EI = The tree in my back garden!  So far 10 digit locators 
have only been seen on certain up-market Global Positioning System 
receivers as the accuracy of 18m is rarely needed or even obtainable.

QRA as used in LOCATION is an older obsolete locator system applicable 
only to Europe, but still used (like feet and inches) by a few diehards!

The following are also irrelevant to non radio users of the software:
   
   TROPPATH program.
   K value in terrain (use K = 1 for optical sighting).
   Reference to mast heights unless climbing ladders.
   References to the Microwave Handbook (Published by the Radio
                                         Society of Great Britain)

Contact me on 01489 787424 for any other questions.
