            WXtrack - Satellite and ground picture prediction

PURPOSE

This program is designed to predict the tracks of weather satellites both as
paths above the earth, and as images produced by these satellites when scanning
the ground.  It can drive a number of hardware trackers.  It was designed for
use during the early stages of my satellite receiving activities, when clouds
and interference prevented easy identification of what I was actually observing!

It can read processed satellite images from one or more folders of your choice,
and present these images side-by-side with the ground track prediction.  To make
visual correlation easier, minute markers are produced on the predicted image to
match those on NOAA APT transmissions.  Map overlay images suitable for
subsequent combining with actual satellite pictures can be produced.


REGISTRATION

WXtrack is copyright software, requiring purchase of a licence for any
commerical use.  If you want say "thank you" for the program, or if you want
technical support, then you must register the program.  Support is only
available on the self-help mailing list if you have not registered.  As a
"thank you" for registering, there are a number of extras in the registered
version which you may find very useful.  They are listed later in this note.

  To register:  http://www.satsignal.eu/software/reg-wxtrack.html

  Self-help group: http://tech.groups.yahoo.com/group/SatSignal/


KNOWN LIMITATIONS

 o  The program displays most dates and times in UTC.  The local time is
    provided as a "hint" on the time setting box for the World Map tab, and
    the program will search for files named with local time, as well as UTC.

 o  If the World map display is corrupt, simply switch to a different map
    projection and back.  This can also happen if you forget to install a
    World map background like UserMap.jpg - the wrong background is cached
    for future use!


WARRANTY

WXtrack is provided "as is" and without any warranty as to merchantability or
fitness for a particular purpose or any other warranties either expressed or
implied.  The author will not be liable for data loss, damages, loss of profits
or any other kind of loss while using or misusing this software.

This software may not be used in safety-critical or life-critical systems.


INSTALLATION - REQUIRED LIBRARY FILES

In order for the program to run properly some runtime library files must be
present in your  Windows System32 folder.  The files are available for download
here:

  http://www.satsignal.eu/software/runtime.html

If you get error messages like "A device attached to the system is not
functioning" or "WXtrack.exe is linked to missing export..." or "dll file
<name> cannot be found", you are either missing one of the run-time library
bundle, or you do not have the latest version of the library bundle.  There is
information on analysing "Missing DLL" messages at the above URL.


INSTALLATION, FILES AND RUNNING

If you are installing from scratch, extract all files from the Zip file to a
location of you choice, and run WXtrack.exe.  See "Usage notes" later in this
file for what to do next!  If you get messages about missing DLLs, or even the
misleading "A device attached to the system is not functioning" please read the
section that follows on Library Files.

There are some suggestions on file locations here:

  http://www.satsignal.eu/software/faq.htm#keplermanager

I suggest you install the files into the following directory, which you may have
to create yourself:

  C:\Tools\SatSignal\WXtrack\

For Windows Vista and later, I strongly reccomend you avoid installing into
the \Program Files\ tree.

If you are updating a previous installation of WXtrack, please be very
careful not to overwrite your own data with the defaults in the Zip file!

The files included in the archive are:

  WXtrack.exe		the main program
  WXtrack.chm		the help file
  WXtrack.txt		this file!
  ReadMe.txt            reminder pointing to WXtrack.txt
  UserMap.jpg		1800 x 900 pixel world map, hill shading, blue background
  amateur.txt		sample 2-line orbit information files
  geo.txt                         "
  Navigation.txt                  "
  SpecialInterest.txt             "
  weather.txt                     "
  TLEnotes.txt		sample satellite frequency and comments file
  horizon.dat		sample local horizon profile (for radio horizon)
  IssGroundStations.dat sample user-defined ground stations for ISS
  _City.txt             sample city data, rename to City.txt to use
  GroundStations.ini    sample ground stations overlay file
  frequencies.ini       sample frequencies.ini file
  Radio.ini             sample radio data file
  ScanOffsets.ini       scan angle sample data file
  Tracker.ini           sample tracker data file
  #25544.icn            sample satellite icon
  #27509.ico                      "
  #28912.ico                      "
  SatIni.SQF            only required for ServerLabjack tracker interface
  Flip.SQF              .. (see the Help information)

If you wish accurate radio horizon display, you must edit horizon.dat to give
the elevation angle of your local horizon for each azimuth angle.  If you have
no horizon data, please simply delete the file, as the program will work
perfectly well without it.

Note: the Kepler files supplied are from the Space-Track Web site and
redistributed with permission.  I recommend using my Kepler Manager to update
the Keplers automatically.  Please use Kepler data from the CelesTrak Web site
if you want to use the built-in Update Keplers function in WXtrack.  Only copy
the Kepler data from this Zip archive if you have none yourself already!  Be
careful not to over-write current Kepler data with older information.

Note: if you rename the program to something other than WXtrack.exe, other
programs in the suite will not be able to share data with WXtrack.


OPTIONAL DOWNLOADS

  LargeUserMap.jpg	1800 x 900 pixel world map, more details
  UserMap.jpg		1800 x 900 pixel world map, more details, hill shading
  countries.dat         country and state boundary data
  Overlay.bmp           master overlay bitmap
  MakeOverlay		Program to generate master overlay bitmap
  etopo5.elev           5 minute elevation data (not on this site)
  wave sounds for AOS   http://www3.sympatico.ca/konecny/golden/sounds.zip
        "               http://users.accesscomm.ca/monitoringpost/software.htm
  TLEnotes.txt updates  http://www.va3dbj.ca

  wxtrack-frequencies-uhf-satcom.txt
    alternative data with 584 satellite frequencies, update 05/01/2014
    from: uhf-satcom.com - Twitter @UHF_Satcom
    rename to frequencies.ini before use
    Original at: http://uhf-satcom.com/frequencies.ini

The more detailed world image maps are separate, as they don't change for new
versions of the software so it seems unfair to ask you to download them every
time.  Justin Priami KG4CEO has kindly provided a high quality bitmap with the
artic region shaded and more accurate country colours.  One user has reported a
problem when using the large map backgrounds, where the footprint style become
corrupted for one satellite.

If you wish a Spanish language help file, please see Ferran Alegret's Web site
at: www.qsl.net/ea3dlv.  I am very grateful to the late Ferran for making this
available as his time permitted.

You should update the element files regularly, perhaps once a week, from the Web
site: www.celestrak.com/NORAD/elements/.  WXtrack will warn you when the orbit
data is too old and needs an update, and you can update on-line with the
Options, Update Keplers menu item.  Dr T S Kelso has articles at
www.celestrak.com/columns/V04n03/ describing the format of the data in detail.
Please note that the CelesTrak service may be withdrawn from the end of March
2005, and you may wish to register with the Space-Track.org Web site instead
and use my Kepler Manager program for automated Kepler data downloads.

If you use the file TLEnotes.txt, be sure to place it in the same directory
as your other Kepler data files.

NightUserMap.jpg is from:
  http://earthobservatory.nasa.gov/images/imagerecords/0/896/earth_lights_lrg.jpg


OPTIONAL FILES

If you wish to generate map overlays, you will need the file Overlay.bmp which
is available on the Web at this address:
  http://www.satsignal.eu  --> Satellite Tools, WXtrack, Downloads
    Pre-compiled overlay bitmap  (404KB)

Extract the file Overlay.bmp to the same folder as WXtrack.exe.  The file will
occupy 30MB when uncompressed, but fortunately compresses well!

If you wish to use cartographic data, as an enhancement to the Azimuthal
Equdistant projection, for example, you will need the file Countries.dat which
is available on the Web at this address:
  http://www.satsignal.eu  --> Satellite Tools, WXtrack, Downloads
    Country & State boundary data  (459KB)

Extract the file Countries.dat to the same folder as WXtrack.exe.

If you wish, you can generate your own version of Overlay.bmp by using the small
MakeOverlay program listed on the Web page at:
  http://www.satsignal.eu  --> Mapping Tools
    MakeOverlay - for WXtrack  (31KB)

MakeOverlay requires the file Countries.dat mentioned above.  Note that running
MakeOverlay requires at least 32 MB RAM to generate at a reasonable speed,
although it will work in 24 MB but take many minutes.  You can change the
gridline spacing, put the gridlines behind or in front of the land areas, and
choose to add annotation in your font and size to the gridlines.

From version 2.7.4, WXtrack can make use of sound files to annouce a number of
events during the pass of a selected satellite.  Please note that these events
will be tracked ONLY if WXtrack is not minimised!  You can set up what events to
annouce by using the Control Panel (Start menu, Settings, Control Panel) Sounds
option.  Under the Sound Events tab, scroll down the list of programs until you
see WXtrack.  You will see the list of events that can make a sound, and you can
choose whatever wave file you want for each of the 8 sounds.  There is also the
option to turn off sounds within WXtrack itself, should you wish to
temporarily disable sounds.


USAGE NOTES

The program has four tabs, Setup, World Map, Ground Path and Flight.  It
normally starts on the World Map tab, but you will be shown the setup screen
when you first run the program.  Drag and drop the satellites you want from the
Available to the Active list box.  You can test the program by switching to the
World Map tab, but you will want to return to the Setup tab to enter the
co-ordinates of your location.  Longitude is negative west of Greenwich, and
latitude negative below the equator.  More accurate predictions can be made if
you enter your height, and the average elevation of the radio horizon from your
location.  You can add mutiple locations to WXtrack, and a small set is
supplied.  You can also have multiple horizon profiles, each  named according to
your location.  If have no specific data, the file Horizon.dat is used.  If your
location was named Edinburgh, then WXtrack would first try the file
EdinburghHorizon.dat.

You can choose the satellites that interest you by dragging and dropping from
the available satellites list.  This list is built up from all two-line elements
files in the same folder as WXtrack.exe, or in a folder of your choice.  It is
up to you to keep these files up to date.  You have four lists or "banks" that
you can fill with satellites.  This may be helpful if you want to switch between
Weather Satellites and Amateur Radio, for example.  The pass generator will show
you a list of passes for a single day, and when you select one of these passes
the buttons which link to the World Map and Ground Path tabs become enabled.  If
no files with satellite details are found, the list of available satellites will
be blank.  You can name the files anything you want - the program will read all
files ending in .TXT, .2LI or .TLE.  Duplicate entries for satellites in
multiple files are allowed, as the program will then use entries with the most
recent epoch.

You should update the element files regularly, perhaps once a fortnight, from
the Web site:  www.celestrak.com/NORAD/elements/  and get the files:
resource.txt, stations.txt and weather.txt or whatever you desire.  Please note
that this service may be withdrawn from the end of March 2005, and you may wish
to register with the Space-Track.org Web site and use my Kepler Manager program
for automated Kepler data downloads from that site.  Place the optional
TLEnotes.txt in the same diretcory as your element files.

You can print a diary of passes for the next few days, an ephemeris, either from
the Setup tab, or from the main File, Print pass list menu.

The World Map tab allows real-time and manual updates of the chosen satellite
positions, or you can open a file from WXSAT (e.g. 12250000.bmp for December
25th) to make the program use the date and time from the file as the map time.
The "selected" satellite will have dotted line showing its scan pattern on the
ground.  The track of the satellite is shown by a number of dots marking the
position in the previous few minutes.  More information is available as "hints"
of some of the controls.

The Ground Path tab allows two functions, the prediction of a ground path given
the satellite, start of pass, and direction of pass, and loading an actual
satellite image.  You can choose the folder (or folders) containing these images
from the setup tab.  The filename is assumed to be in WXSat format, but to allow
the viewing or processed visible or IR images, various file extensions are also
recognised:

Colour:   -c.jpg, -c.bmp, -c.png
Visible:  -a.jpg, -a.bmp, -a.png
IR:       -b.jpg, -b.bmp, -b.png

So if today is March 26, and the time 12:58 UTC, then the filename from WXSat
might be 03261258.bmp, and you may have processed the pass to produce a false-
colour file that you have called 03261258-C.jpg.  This file would be the first
one found as shown in the table above.  The program also tries to look for files
a few minutes on either side on the nominal, and also files named in your
equivalent local time.

I have specifically included PNG file support as this format is typically only
about 2/3 of the size of a BMP file, but without any loss of quality that is
associated with JPEG files.  Storing images as JPEG files can cause errors in
the level of the telemetry bars, required for apparent temperature measurement.

(Note that I am assuming that an image contains a single picture, not a combined
side-by-side channel A and channel B picture.  I currently store side-by-side
PNG images as my master image, and processed JPG images for each channel.)

You can zoom and scroll both the map and the picture.  Normally, scrolling the
map will scroll the picture as well, but as there might be some misalignment,
perhaps the satellite wasn't acquired at the start of the pass, scrolling the
picture will, intentionally, not scroll the map.

As ground path prediction can take some time, pressing the escape key will
interrupt.  Each time a new ground path map is generated, a copy will be saved
as a file named Result.jpg in the same folder as the program.  Note that this
file will be overwritten every time a new pass is created, so save it if you
want to keep it!  Both the Result.jpg file and the other results files will
accumulate in the WXtrack folder, unless you have used the "Path for Results
Files" on the setup tab to redirect the output.

The Flight tab allows you to fly a pass, either what a satellite is doing in
real-time, or an earlier pass.  Enjoy this strictly for fun mode!


WORLD MAP DATA

The predicted picture quality on the Ground Path and Flight tabs can be
substantially enhanced by downloading higher resolution topographic data than
that supplied with the program in the *UserMap.jpg files.  The backdrop on the
World Map tab will _not_ be affected, only the Ground Path and Flight tabs.  The
highest resolution data in the *UserMap.jpg is at 12 minute angle intervals, and
is compressed with JPG resulting in slight artefacts.  If the image quality is
adequate for you, then you do not need the higher resolution data.  However,
using the ETOPO5 5 minute data will increase the number of pixels in the
predicted image by about 5.6 times - more when you consider that it is not
compressed.  Resolution of the ETOPO5 data is adequate, and there is no need to
download the higher resolution databases available on the Internet, which are
not supported read by WXtrack.

The program will use the US National Geophysical Data Center (NGDC) ETOPO5 5
minute data file for ground path prediction if the file etopo5.elev is present
in the same folder as the program executable.  This data file may be obtained
from the Internet, for example:

  http://www.ngdc.noaa.gov/mgg/global/relief/ETOPO5/TOPO/ETOPO5/ETOPO5.DAT
  18,662,400 bytes
or:
  http://www.ngdc.noaa.gov/mgg/global/relief/ETOPO5/TOPO/ETOPO5/ETOPO5.DOS
  18,662,400 bytes
or:
  http://www.geol.binghamton.edu/faculty/jones/etopo5.zip
  18,666,720 bytes (unzipped, link may no longer work)

Be warned that this zip file is an 11MB download that expands to 18MB when
unzipped.  But the results _are_ worth it.

You can name the file:
  etopo5.elev  or  etopo5.dat  or  etopo5

Data from these two sources are not identical, the earlier Jones data has one
extra 16-bit field per line, and has a different byte order.  WXtrack attempts
to determine which file you are using, and to behave appropriately.  Using the
high-resolution data file will not alter the appearance of the world map
display, simply the predicted ground path (and the Flight mode display).


NOTES ON KEPLER DATA

It was originally announced that after April 1st 2005, only users registered
with the Space-Track Web site would be able to get Kepler data.  So I wrote a
small program called Kepler Manager which could download the required Kepler
data from www.space-track.org and package the data into sets just like you could
get from the old CelesTrak Web site.  The program also allows you to build up
multiple-entry 2-line data sets in the same format as the archive files from
CelesTrak.  This program is available at:

  http://www.satsignal.eu/software/KeplerManager.htm

and if used on a PC which has a registered WXtrack licence, the Kepler Manager
can be automated to run overnight and thereby keep your Keplers continually
up-to-date.  I run mine twice a week.

However!  The USA have now granted the CelesTrak site a licence to continue
redistributing Kepler data as before, so you can now use WXtrack itself to
update the Kepler data.  I also have a licence from the USA to distribute Kepler
data with my WXtrack program.  My guess is that the CelesTrak licence will be
permanent, but in these troubled times, who knows?  CelesTrak also provide
software to access the Space-Track Web site.

When updating with WXtrack, after using the Space-Track data, you may get an
error message if the file that was used with Space-Track naming is not present
on the CelesTrak Web site - in which case find out what data was in that file
and download the equivalent file from the CelesTrak site once by hand.  As the
files are not directly equivalent, you may also get a warning that the number of
Kepler elements is not the same, but this should only happen once for each
changed file.


USING IMAGE FILES

The images must be named according to the WXsat convention - MMDDhhmm.bmp or
whatever.  For example, without a pass selected, the program starts up with the
date 26th February 1999 at 1327 in the "When" box on the "Ground Path" tab.  It
would therefore look for files named 02261327.jpg.  When using the "Timeframe
from File" option on the World Map page, loading a file merely sets the date and
time for the satellite display.


TRACKING THE ANTENNA

WXtrack can drive a number of popular antenna tracking systems including
controllers based on EA4TX, Kansas City Tracker (RR.DLL), LVB (from G6LVB),
SeaTel, CX6DD (and therefore Yaesu GS232), EasyComm, FodTrack, ServerLabjack
and WiSP DDE.

If you have another tracker that you would like supported, why not write to me
and ask?  Priority is given to registered users, of course.

You can get WiSPDDE from:
  http://www.laboratoriomederos.com/CX6DD/wispdde/

For use with WiSP DDE, with the Settings DDE link... menu, set as follows:

  - Receive DDE from:  SatScape
  - Source application: WXtrack
  - Link Topic: Tracking (this is the default with Satscape)
  - Link Item: Tracking (this is the default with Satscape)
  - Query Interval: as desired, I've used both 1 second and 3 seconds


EXTRA FACILITIES IN THE REGISTERED VERSION

The registered version offers a range of extra facilities designed both to make
the program easier to use for regular users, and to extend the facilities
offered.

- The details of the location indicated by the mouse co-ordinates are shown
  - latitude and longitude
  - range and bearing from the home location
  - satellite azimuth and elevation from the cursor location
- Details about the selected pass are available as hints on the Setup tab
- You can add your own ground stations to the World Map display
- Extra options reached by right-clicking the World Map display
- Extra menu items to integrate with the Kepler Manager and SatBatch.
- Extended functionality on the "Radar view"
- You can rename a wave file to match a selected pass using Shift-Click on
  the "Map from pass" button (on the Setup tab).  You would want to do this
  if you recorded passes on an external recorder, and the file names do not
  match the pass times.
- Kepler data can be saved and printed.
- You can control the step time for displaying Pass Details on the View,
  Ephemeris dialog.
- HRPT channel selection is possible with the Götz Romahn/Bob Barnes CX6DD
  interface variant.
- The Tracker Parking option is enabled.
- You can set the tracker gain accurately (experimental, KCT only)
- The Tracker Test command is considerably enhanced by adding manual
  positioning and RA/Dec tabs.  This allows full manual control over the
  positioning of an antenna at specific azimuth/elevation or RA/Dec
  co-ordinates, checking of flip-mode etc.  The operations have been
  developed in conjunction with people who are commissioning antennas
  for satellite tracking operations.
- For more accurate antenna tracking, WXtrack can be set to look ahead a
  number of seconds from the current position, thus compensating for any
  lag in positioning the antenna.
- Satellites may be prioritised, and automatic switching between satellites
  is enabled.
- The program will read your current location from a standard GPS source
  over a serial link (e.g. COM1).  This is ideal for mobile users.


OPERATING SYSTEM NOTES

The program is written with Embarcadero's Delphi and has been developed on
Windows XP and Windows-10.  It runs on Windows-7 and later.  The program may
work on older version of Windows, but is no longer guaranteed or supported.


RECENT RELEASE INFORMATION

Release V3.8.36.1032
2015-Sep-29           Add support for KVH tracker ..
                      .. 350 msec gap between Az and El commands

Please see the Help, What's New menu for the complete release history.


PROGRAM STATUS AND DISTRIBUTION

This program is freeware, and remains copyright of David J Taylor, Edinburgh,
1999-2015.  This program is provided "as is", without any support from me. There
is a self-help mailing list at: SatSignal-subscribe@yahoogroups.com where other
users of the software may be contacted.  Whilst I cannot answer queries relating
to the use of this program, I'd value any comments or suggestions for
improvements you may have.  If you report a problem, be sure to include the full
program version number (from the Help, About command), and details of the
operating system you are using.

Any attempt to decompile this program is strictly forbidden.

If you want say "thank you" for the program, if you want the more advanced
features, or if you want technical support, then you must register the program.
Support is only available on the self-help mailing list if you have not
registered.

  To register:  http://www.satsignal.eu/software/reg-wxtrack.html


COMMERCIAL USE

The WXtrack program may be used for personal or educational, non-commercial
purposes free of charge.  Use by any commercial organisation, or any individual
for commercial purposes requires the purchase of a commercial licence from
David Taylor, Edinburgh.

  http://www.satsignal.eu/software/reg-wxtrack.html


ACKNOWLEDGEMENTS

First, I would like to thank all the folk who have bothered to download and try
out this software, and the valuable suggestions you have all made are built into
the current version of the program.

Many routines were modified from Dr TS Kelso's invaluable SGP4 routines, used
with permission, which are:
  Copyright (c)  1991-1999, Dr TS Kelso, All Rights Reserved
  E-mail:   tskelso@celestrak.com
  Web site: http://www.celestrak.com

Dr TS Kelso's site at: www.celestrak.com/NORAD/elements/ provided the orbital
elements, and is your best source for up to the minute data.

Footprint calculation code adapted from James Miller's (G3RUH)
"PLAN-13 SATELLITE POSITION CALCULATION PROGRAM" available at:
  http://www.amsat.org/amsat/articles/g3ruh/111.html
  (previously: ftp.amsat.org  /amsat/articles/g3ruh/a111.zip)

The moon prediction code, used with permission, was adapted from Paul Schlyter's
comprehensive orbit calculation page at:
  http://hotel04.ausys.se/pausch/comp/ppcomp.html

Peter, ON1CIM, wrote the KCT Server add-on.  You can get the software directly
from him.
  E-mail: on1cim@easynet.be

The PNG support is from Edmund H Hand's interface to LPng.dll
  e-mails:  edhand@worldnet.att.net
  updated by: Dominique Louis (Dominique@SavageSoftware.com.au)
              Uberto Barbini (uberto@usa.net)
              David Taylor (davidtaylor@writeme.com)

The library LPng.dll is freeware and the source is:
  Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
  Copyright (c) 1996, 1997 Andreas Dilger
  Copyright (c) 1998 Glenn Randers-Pehrson

Thanks to Milan Konecny & Craig Orban for making sound files available on their
sites, to David Bate (va3dbj@bell.net) for the TLEnotes.txt frequency data, and
to Leonardo Righini (Nuova Elettronica) for suggesting and supplying the
City.txt data.  Eric Khentigan provided helpful suggestions and encouragement
for geostationary satellites and multiple ground stations.

Thanks to Charlie LU4DGN from Argentina for many useful hints and suggestions,
and to Michel Casabonne for his many suggestions about the ISS mode and icons.


CONTACTING THE AUTHOR

Web site:  http://www.satsignal.eu
E-mail:    davidtaylor@writeme.com
Self-help group: http://tech.groups.yahoo.com/group/SatSignal/

2015-Sep-29