* Introduction *
================
PREDICT is a multi-user satellite tracking and orbital prediction program
written under the Linux operating system by John A. Magliacane, KD2BD.
PREDICT is free 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 of the License or any later version.

PREDICT is distributed in the hope that it will 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.


* Features *
============
The major features of PREDICT Version 2 include:

   * Fully year 2000 compliant code.

   * Designed under the Linux operating system to permit operation on a wide
     and expanding variety of hardware platforms ranging from palmtops to
     supercomputers (including 32-bit PCs (80386s or better) and Macintosh
     PowerPCs).

   * Licensed under the GNU General Public License, thereby allowing anyone
     to contribute new features to the program while forever keeping the
     software, and any derivative works, non-proprietary and freely
     available.

   * Includes a FAST orbital prediction mode that accurately predicts
     satellite passes, providing dates, times, coordinates, slant range
     distances, and sunlight and optical visibility information. Predictions
     are displayed in tabular form and may be saved to a log file for later
     reference or printing.

   * Includes a visual orbital prediction mode that displays satellite
     passes that are potentially visible to the ground station by optical
     means.

   * Features a real-time single satellite tracking mode that provides
     dynamic information such as sub-satellite point, ground station azimuth
     and elevation headings, Doppler shift, path loss, slant range, orbital
     altitude, orbital velocity, footprint diameter, orbital phase, the time
     and date of the next AOS (or LOS of the current pass), orbit number,
     and sunlight and visibility information for a single satellite, while
     providing live azimuth and elevation headings for both the sun and
     moon.

   * Features a multi-satellite tracking mode that provides sub-satellite
     point, azimuth and elevation headings, sunlight and visibility, and
     slant range distance information for all 24 satellites in the program's
     current database on a real-time basis. Azimuth and elevation headings
     for the sun and moon are also provided, as a well as a listing of the
     AOS dates and times for the next three satellites expected to come into
     range of the ground station.

   * Provides static information such as semi-major axis of ellipse, apogee
     and perigee altitudes, and anomalistic and nodal periods of satellite
     orbits.

   * Includes command line options that permit alternate ground station
     locations to be specified or alternate orbital databases to be read and
     processed by the program, effectively allowing an UNLIMITED number of
     satellites to be tracked and managed. Additional options allow any
     orbital database file to be automatically updated using NASA Two-Line
     element data obtained via the Internet or via Pacsat satellite without
     having to enter the program and manually select menu options to update
     the database.

   * Features a voice mode that allows live azimuth and elevation headings
     of a satellite to be articulated to an observer to assist in locating a
     satellite by optical means.


* First Time Use *
==================
PREDICT tracks and predicts passes of satellites based on the geographical
location of the ground station, the current date and time as provided by the
computer system's clock, and Keplerian orbital data for the satellites of
interest to the ground station. First time users of PREDICT are provided
default ground station location and orbital data information files. These
files are managed by the program, and are normally located in a user's home
directory under a hidden subdirectory named ".predict". First time users
will be prompted to supply PREDICT with their geographical location (the
same as selecting option [G] from the program's main menu) the first time
the program is run. Latitude is entered in decimal degrees north. Latitudes
south of the equator are entered as negative numbers. Longitude is entered
as decimal degrees west. Eastern longitudes may be entered as negative
numbers. Station altitude is entered as the number of meters the ground
station is located above sea level. This parameter is not very critical. If
unsure, make a realistic guess or simply enter 0.

Users of PREDICT need Keplerian orbital data for the satellites they wish to
track that is preferably no older than one month. The default orbital data
supplied with the program are liable to be quite old, and so must be brought
up to date if accurate results are to be expected. This may be accomplished
by selecting option [E] from PREDICT's main menu and manually entering
Keplerian data for each satellite in the program's database, or by selecting
option [U] and specifying a file containing recent 2-line Keplerian element
data sets that correspond to the satellites in the program's database.
Keplerian orbital data is available from a variety of sources, including
http://www.celestrak.com/ and http://www.amsat.org/.


* Program Operation *
=====================
The operation of PREDICT is uncomplicated by design. The start-up screen of
the program lists the program's main functions. Several tracking and orbital
prediction modes are available, as well as several utilities to manage the
program's orbital database.


* Predicting Satellite Passes *
===============================
Orbital predictions are useful for determining in advance when a satellite
is expected to come within range of a ground station. They can also be used
to look back to previous passes to help to confirm or identify past
observations.

PREDICT includes two orbital prediction modes to predict any pass above a
ground station (main menu option [P]), or list only those passes that might
be visible to a ground station through optical means (main menu option [V]).
In either mode, the user is asked to select a satellite of interest from a
menu, and then asked to enter the date and time (in UTC) at which prediction
calculations should start.

The current date and time may be selected by default by entering nothing and
hitting simply the ENTER key when prompted to enter the starting date and
time.

Otherwise, the starting date and time should be entered in the form:

        DDMonYY HH:MM:SS

After this is entered, orbital calculations are started and prediction
information is displayed on the screen.

The date and time in UTC, along with the satellite's elevation above ground,
azimuth heading, modulo 256 orbital phase, sub-satellite point latitude and
longitude, slant range between the ground station and the satellite, and the
satellite's orbit number are all displayed. An asterisk (*) displayed to the
right of the orbit number means the satellite is in sunlight at the date and
time listed on the line. A plus symbol (+) means the satellite is in
sunlight while the ground station is under the cover of darkness at the time
and date listed. Under good viewing conditions, large satellites such as the
International Space Station, and the US Space Shuttles are visible to the
naked eye. If no symbol appears to the right of the orbit number, then the
satellite is in the Earth's shadow at the time and date listed, and is not
receiving any illumination from the sun.

Pressing the ENTER key, the 'Y' key, or the space bar advances the orbital
predictions to a screen listing the next available passes. Pressing the 'L'
key allows the currently displayed screen plus any subsequent screens to be
logged to a text file in your current working directory. The name given to
this file is the name of the satellite plus a ".txt" extension. Any slashes
or spaces appearing in the satellite name are replaced by the underscore (_)
symbol. The logging feature may be toggled on and off at any time by
pressing the 'L' key. Exiting the orbital prediction mode by pressing 'N' or
hitting the ESCape key will also close the log file. The log file will be
appended with additional information if additional predictions are conducted
for the same satellite with the logging feature turned on.

Selecting [V] from PREDICT's main menu will permit a ground station to only
predict passes for satellites that are potentially visible through optical
means. Since all other passes are filtered out in this mode, and since some
satellites may never arrive over a ground station when optical viewing
conditions are possible, the program provides the option of breaking out of
visual orbital prediction mode by pressing the [ESC]ape key as calculations
are made. A prompt is displayed at the bottom of the screen to alert the
user of this option.

In either orbital prediction mode, predictions will not be attempted for
satellites that can never rise above the ground station's horizon, or for
satellites in geostationary orbits. If a satellite is in range at the
starting date and time specified, PREDICT will adjust the starting date back
in time until the point of AOS so that the prediction screen displays the
first pass in its entirety from start to finish.


* Single Satellite Tracking Mode *
==================================
In addition to predicting satellite passes, PREDICT allows satellites to be
tracked singly in real-time using PREDICT's Single Satellite Tracking Mode
(main menu option [T]), or simultaneously as a group of 24 using the
program's Multi-Satellite Tracking Mode (main menu option [M]). The
positions of the Sun and Moon are also displayed when tracking satellites in
real-time.

Selecting option [T] from PREDICT's main menu places the program in Single
Satellite Tracking Mode. The user will be prompted to select the satellite
of interest, after which a screen will appear and display tracking positions
for the satellite selected.

In Single Satellite Tracking Mode, the current date and time are displayed
along with the satellite's sub-satellite point, its orbital altitude in both
kilometers and statute miles, the slant range distance between the ground
station and the satellite in both kilometers and statute miles, the current
azimuth and elevation headings toward the satellite, the orbital velocity of
the satellite in both kilometers per hour and statute miles per hour, the
footprint of the satellite in both kilometers and statute miles, the orbital
phase of the satellite in both modulo 256 and 360, as well as the current
orbit number. Additionally, if the satellite is currently in range of the
ground station, the amount of Doppler shift experienced by the ground
station receiving downlinks at 146 MHz and 435 MHz are displayed, as well as
the one-way path loss for these frequencies. The predicted time of LOS as
well as sunlight and visibility information is also displayed at the bottom
of the screen. If the satellite is not in range, then the Doppler shift and
path loss calculations are not performed, and the next predicted AOS date
and time is shown at the bottom of the screen.

If a soundcard is present on your machine and the Single Satellite Tracking
Mode is invoked with an uppercase 'T' rather than a lowercase 't', PREDICT
will make periodic voice announcements stating the satellite's tracking
coordinates in real-time. Announcements such as:

    "This is PREDICT. Satellite is at 5 6 degrees azimuth and 4 5 degrees
                        elevation, and approaching."

are made at intervals that are a function of how quickly the satellite is
moving across the sky. Announcements can occur as frequently as every 50
seconds for satellites in low earth orbits such as the International Space
Station (370 km), or as infrequently as every 8 minutes for satellites in
very high orbits, such as the GE-2 geostationary satellite (35780 km). Voice
announcements are performed as background processes so as not to interfere
with tracking calculations as the announcements are made. Announcements can
be forced at any time by pressing the 'T' key in Single Satellite Tracking
Mode.


* Multi-Satellite Tracking Mode *
=================================
Selecting [M] from PREDICT's main menu places the program in a real-time
multi-satellite tracking mode. In this mode, all 24 satellites in the
program's database are tracked simultaneously along with the positions of
the Sun and Moon. Tracking data for the satellites is displayed in two
columns of 12 satellites each. The name, azimuth heading, elevation,
sub-satellite point latitude (in degrees North) and longitude (in degrees
West) positions are provided, along with the slant range (in kilometers),
and the slant range distance between the satellite and the ground station
(also in kilometers).

A letter displayed to the right of the slant range indicates the satellite's
sunlight and eclipse conditions. If the satellite is experiencing an eclipse
period, an N is displayed. If the satellite is in sunlight and the ground
station is under the cover of darkness, a V is displayed to indicate the
possibility that the satellite is visible under the current conditions. If
the satellite is in sunlight while conditions at the ground station do not
allow the satellite to be seen, a D is displayed. Satellites in range of the
ground station are displayed in BOLD lettering. The AOS dates and times for
the next three satellites predicted to come into range are displayed on the
bottom of the screen between the tracking coordinates of the Sun and Moon.
Predictions are not made for satellites in geostationary orbits or for
satellites so low in inclination and/or altitude that they can never rise
above the horizon of the ground station.


* Operating Under The X-Window System *
=======================================
PREDICT may be run under the X-Window System by invoking it through the
xpredict script contained with the software. xpredict requires that rxvt be
installed on your system, although the script can be modified to use xterm.
Holding down the SHIFT key while pressing the plus (+) and minus (-) keys
allow PREDICT's window to be re-sized.


* Command Line Arguments *
==========================
By default, PREDICT reads ground station location and orbital data
information from a pair of files located in the user's home directory under
a hidden subdirectory named ".predict". Ground station location information
is held in a file named "predict.qth", while orbital data information for 24
satellites is held in a file named "predict.tle".

If we wish to run PREDICT using data from alternate sources instead of these
default files, the names of such files may be passed to PREDICT on the
command line when the program is started. For example, if we wish to read
the TLE file "visual.tle" and the QTH file "holiday.qth" rather than the
default files, we could start PREDICT and pass the names of these alternate
files to the program in the following manner:

        predict -t visual.tle -q holiday.qth

or

        predict -q holiday.qth -t visual.tle

If the files specified are not located in the current working directory,
then their relative or absolute paths should also be specified along with
their names (predict -t /home/kd2bd/orbs/visual.tle).

It is also possible to specify only one alternate file while using the
default for the other. For example,

        predict -t visual.tle

reads QTH information from the default "~/.predict/predict.qth" location,
and TLE information from "visual.tle", while

        predict -q bobs.qth

reads QTH information from "bobs.qth" and TLE information from the default
"~/.predict/predict.tle" location.


* "Quiet" Orbital Database Updates *
====================================
It is also possible to update PREDICT's satellite orbital database using
another command line option that updates the database from a NASA two-line
element data set. PREDICT then quietly exits without displaying anything to
the screen, thereby eliminating the need for entering the program and
selecting the appropriate menu options. This option is invoked using the -u
command line switch as follows:

        predict -u orbs248.tle

This example updates PREDICT's default orbital database with the Keplerian
elements found in the file "orbs248.tle". If an alternate datafile requires
updating, it may also be specified on the command line using the -t switch
as follows:

        predict -t oscar.tle -u amateur.txt

This example updates the "oscar.tle" orbital database with the two-line
element data contained in "amateur.txt".

These options permit the automatic update of PREDICT's orbital data files
using Keplerian orbital data obtained through automatic means such as FTP or
pacsat satellite download.

For example, the following script can be used to update PREDICT's orbital
database via the Internet:

        #!/bin/sh
        # Simple script to update PREDICT's orbital database via the 'net.
        ftp -n ftp.celestrak.com << !
        user anonymous $LOGNAME@$HOSTNAME
        binary
        cd /pub/elements
        get amateur.txt
        quit
        !
        predict -u amateur.txt

To truly automate the process of updating your orbital database, save the
above commands to a file in your home directory (such as "kepupdate"), and
add the following line to your crontab (type crontab -e to edit your
crontab):

        0 2 * * * kepupdate

and PREDICT will automatically update its database every day at 2:00 AM.


* Neat Tricks *
===============
In addition to tracking and predicting passes of satellites, PREDICT may
also be used to generate a NASA two-line Keplerian element data set from
data entered via keyboard. For example, let's say you're listening to Space
Shuttle audio re-broadcasts via WA3NAN and Keplerian elements for the Space
Shuttle's orbit are given by the announcer. The orbital data provided by
WA3NAN in verbal form may be manually entered into PREDICT's orbital
database using option [E] of the program's main menu (Keyboard Edit of
Orbital Database). The orbital data for the Space Shuttle in NASA two-line
element form can then be found in your orbital database file, and may
imported to any other satellite tracking program that accepts two-line
element files or distributed to others electronically.

It is also possible to run PREDICT as a background process and direct its
display to an unused virtual terminal by using the following command:

        predict < /dev/tty8 > /dev/tty8 &

Switching to virtual console number 8 (ALT-F8) will allow PREDICT to be
controlled and displayed even after you've logged out.


* Glossary of Terms *
=====================

   * AOS: Acquisition of Signal - the time at which a ground station first
     acquires radio signals from a satellite. PREDICT defines AOS as the
     time when the satellite being tracked comes within +/- 0.03 degress of
     the local horizon, although it may have to rise higher than this before
     signals are first heard.

   * Apogee: Point in a satellite's orbit when the satellite is at its
     farthest distance from the earth's surface.

   * Anomalistic Period: A satellite orbital parameter specifying the time
     between successive perigees.

   * Ascending Node: Point in a satellite's orbit when its sub-satellite
     point crosses the equator moving south to north.

   * Azimuth: The compass direction measured clockwise from true north.
     North = 0 degrees, East = 90 degrees, South = 180 degrees, and West =
     270 degrees.

   * Descending Node: Point in a satellite's orbit when its sub-satellite
     point crosses the equator moving north to south.

   * Doppler Shift: The motion of a satellite in its orbit around the earth,
     and in many cases the rotational motion of the earth itself, causes
     radio signals generated by satellites to be received on Earth at
     frequencies slightly different than those upon which they were
     transmitted. PREDICT calculates what effect these motions have upon the
     reception of satellites transmitting on the 146 MHz and 435 MHz Amateur
     Radio bands.

   * Elevation: The angle between the local horizon and the position of the
     satellite. A satellite that appears directly above a particular
     location is said to be located at an elevation of 90 degrees. A
     satellite located on the horizon of a particular location is said to be
     located at an elevation of 0 degrees. A satellite with an elevation of
     less than zero is positioned below the local horizon, and radio
     communication with a satellite in such a position is not possible under
     normal circumstances.

   * Footprint: Diameter of the Earth's surface visible from a satellite.
     The higher the satellite's orbital altitude, the greater the footprint,
     and the wider the satellite's communications coverage.

   * LOS: Loss of Signal - the time at which a ground station loses radio
     contact with a satellite. PREDICT defines LOS as the time when the
     satellite being tracked comes within +/- 0.03 degress of the local
     horizon.

   * Orbital Phase: An orbital "clock" that describes a satellite's orbital
     position with respect to perigee. Orbital Phase may be modulo 256, or
     modulo 360, and is sometimes referred to as mean anomaly when speaking
     of amateur radio satellites in elliptical orbits, such as the Phase 3
     satellites. Orbital phase is zero at perigee.

   * Path Loss: The apparent attenuation a radio signal undergoes as it
     travels a given distance. This attenuation is the result of the
     dispersion radio waves experience as they propagate between transmitter
     and receiver using antennas of finite gain. Free space path loss is
     technically an oxymoron since free space is loss free.

   * Perigee: Point in a satellite's orbit when the satellite is at its
     closest distance to the earth's surface.

   * Nodal Period: A satellite orbital parameter specifying the time between
     successive ascending nodes.

   * Slant Range: The straight line distance between the ground station and
     the satellite at a given time.

   * Sub Satellite Point: The latitude and longitude specifying the location
     on the Earth that is directly below the satellite.

  ------------------------------------------------------------------------

John A. Magliacane, KD2BD
