
                            The Sattool Manual
                            ------------------

                  Tom Rothamel <tom-sattool@onegeek.org>

                               Prerelease 1


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


Copyright Notice
----------------

     Copyright (C) 1999 Tom Rothamel

     This manual is free software; you may 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.

     This 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.

     A copy of the GNU General Public License is available on the World
     Wide Web at http://www.gnu.org/copyleft/gpl.html.  You can also obtain
     it by writing to the Free Software Foundation, Inc., 59 Temple Place,
     Suite 330, Boston, MA 02111-1307, USA.


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


Contents
--------

     1.        Introduction
     1.1.      Lists of Things
     1.2.      Command Line Options
     1.3.      Environment Variables

     2.        Using Sattool For Visual Satellite Prediction
     2.1.      Predicting Passes
     2.2.      Filtering Passes
     2.3.      Displaying The Passes
     2.4.      Putting it All Together
     2.5.      The Live Display

     3.        Command Reference
     3.1.      cat
     3.2.      writetle
     3.3.      filter
     3.4.      marker
     3.5.      live
     3.6.      predict
     3.7.      passes
     3.8.      step
     3.9.      summary


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


1. Introduction
---------------

     Sattool is a program for the prediction of the motion of artificial
     satellites.  Support for predicting the visual magnitudes of these
     satellites is already in place, with support for predicting the radio
     frequencies coming soon.

     Sattool is structured as a set of small sub-programs, each of which
     does one task.  In order to determine which sub-program to run,
     sattool first looks at the name it was called under.  If that name is
     of the format sat<prog>, it calls the subprogram <prog>.  Otherwise,
     it expects to be invoked as 'sattool <prog>', with the program name
     available as the first argument.

     Generally, shell pipelines are used to connect the various steps in a
     prediction process together.  This allows for maximum flexiblity and
     control of this process, even allowing the various steps to be run on
     different machines.  (For example, running the computationally
     intensive prediction step on one machine, and the less demanding live
     tracking on a second machine.) Using the shell also encourages the
     creation of scripts to automate common tasks.


1.1. Lists of Things
--------------------

     Sattool works on lists of things.  A thing is something like a
     satellite, a pass, a site, or an encounter.  Many things can look like
     other things when appropriate.  For example, if a Pass is used in a
     situation where a satellite is more appropriate, the satellite
     corresponding to the pass will be used rather than the pass itself.

     This may seem complicated, but usually results in sattool doing the
     right thing in most circumstances.


1.2. Command Line Options
-------------------------

     The following are the command line options that the various sattool
     sub-programs take.  Not every option is relavent to every sub-program,
     but the ones that are relevant are obeyed consistently.

     -i <filename>, --infile <filename>
          Forces input to be read from <filename>, rather than from the
          default location of stdin.

     -t, --tle
          Specifies that the input is in TLE format, rather than sattool's
          native format.

     -o <filename>, --outfile <filename>
          Specifies a filename for output.  If no filename is specified,
          this will default to stdout.

     -q, --quiet
          This engages quiet mode, suppressing the printing of progress
          messages.

     -v, --visual
          This selects visual mode.  Some sub-programs will behave slightly
          differently if visual mode is selected.  See the individual
          documentation below.


1.3. Environment Variables
--------------------------

     The following are environment variables that many of the sattool
     sub-programs take.  There are also environment variables that are only
     relavant to one of the sub-programs...  They're listed in the
     documentation for that sub-program.

     SATSITE
          This defines a site for prediction or live display.  The variable
          itself contains an input list entry for an object.  Usually, this
          is an earthsite entry, which has the format '(earthsite "<name>"
          <lat> <lon> <alt>")'.  For example, for the author's observing
          site, this is set to '(eartsite "Northport, NY" 40.9037 -73.3455
          0)'.


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


2. Using Sattool For Visual Satellite Prediction
------------------------------------------------

     This section is a tutorial on how to predict visual satellite passes
     using sattool.  I've set this up as a set of steps.  Please realize
     that the steps must be combined into a coherent whole to be useful.
     This is done either using pipes or using the -o and -i options to
     redirect the input and output into files.  Please see the section
     "Putting it Together" for details on how to do this.

     This section assumes you have acquired a TLE file containing orbital
     elements and magnitude information.  One such file is the mccants
     file, which can be dowloaded using the command 'gettle mccants.tle'.
     For the rest of this example, we'll be using mccants.tle to represent
     this file.  Any elements file with similar magnitude information will
     work.


2.1. Predicting Passes
----------------------

     The first step is to predict the visual passes.  In order to do that,
     the 'sattool predict' command is used.  Before it can be used,
     however, a site must be defined.  For our purposes, we'll assume that
     the site chosen is one that's fixed to the earth's surface, which is
     the case for most observers.  Such a site is defined by it's latitude,
     longitude, and altitude above the reference spheroid.  (AKA the
     elevation).

     The site is defined by the SATSITE environment variable.  The user's
     location must be substituted in.  For example, to set a location of
     Northport, NY (which is at 40.9037 N, 73.3455 W, 0 km elevation), the
     command in a bash-like shell is

            export SATSITE='(earthsite "Northport, NY" 40.9037 -73.3455 0)'

     Once the site is set, prediction can occur.  A sample command line is

            sattool predict -vti mccants.tle "noon today" "midnight today"

     This tells sattool to do visual prediction from noon to midnight on
     the day in which the command is issued.  It'll read tle format
     elements from the file mccants.tle.  The -v option tells sattool to
     calculate minimum magnitudes for each pass.

     Sattool will then send a list of passes to standard output, or to a
     file if the -o option was given.


2.2. Filtering Passes
---------------------

     Once a list of passes has been created, it must be filtered.  The
     filter sub-program is what does that.  The filter command takes an
     expression which defines which passes are allowed through.  It's
     defining this expression which is important.

     In order to see a visual satellite, there are two major conditions
     that must be met.  The first is that the satellite must be lit.  This
     is accomplished using the filter expression 'lit'.  The second
     condition is that the observer's site must be in darkness.  Generally,
     brighter satellites can be seen when the sun is 6 degrees beneath the
     horizon.  The corresponding filter expression is 'sunel lt -6'.  (lt
     is short for less than.)

     In addition, it's useful to filter out passes with minimum magnitudes
     above a certain value.  The choice of this value varies from user to
     user.  The author uses 3.0 when he's at home or school, or 3.5 if he's
     looking for some dimmer satellites in a dedicated viewing session.
     The exact choice is dependant on user skill and local light pollution.
     Anyway, the filter expression is 'minmag lt 3.0'.  (Or whatever, pick
     your own magnitude limit.)

     These expressions are combined using the 'and' keyword.  It also helps
     to use -- on the command line, so the -6 isn't parsed as an option.
     The net command is:

            sattool filter -- lit and sunel lt -6 and minmag lt 3.0 -o passlist

     Please note that this command will read a list of passes from standard
     input and write one out to the passlist file.


2.3. Displaying The Passes
--------------------------

     Now that we have a list of passes that are visible, it's useful to
     have the passes displayed in a more readable form.  The two commands
     that do this are passes and step.

     The passes command prints the list of passes in a human readable form.
     It displays the times of various events in a pass.  For each pass
     event, it prints out the list entries in the format:

          21147 91017A   Lacrosse 2
                  Pass Start: 19991126 16:53:02  179.4 S   10.1 +5.6 2074
               Pass Max Elev: 19991126 16:57:25  110.3 E   39.6 +3.0 987
                Pass Min Mag: 19991126 16:57:49   97.5 E   38.7 +3.0 1003
                    Pass End: 19991126 17:01:47   42.7 NE  10.2 +4.5 2086

     The first line of a pass display contains the satellite's norad
     number, its international designation, and its name.  The other lines
     contain the event type, the date, the time, the azimuth, a compass
     bearing based on the azimuth, the elevation, the magnitude, and the
     range in kilometers.  For example, the point of maximum elevation for
     this pass occurs at 4:57:25 pm on November 11th, 1999.  At that time,
     the azimuth is 110.3 degrees, which is in the east.  The elevation is
     39.6 degrees high, and the magnitude at that time is +3.0.  At that
     time, the satellite is 987 kilometers away.

     The command to invoke the passes sub-program is

             sattool passes -i passlist

     The other command for displaying passes is the step command.  This
     displays the information given above every specified number of
     seconds.  This is more useful for novices or people who want more
     details on the motion of the satellite.  It only prints out passes
     matching a filter expression.  (The filter expression can be 'true',
     which is true all the time, but it most be present.)

     The output looks like:

          21147 91017A   Lacrosse 2                     (4.906 days old.)
          	19991126 16:54:55  166.1 S   22.2 +4.5 1432
          	19991126 16:55:25  159.9 S   26.4 +4.1 1289
          	19991126 16:55:55  151.6 SE  30.8 +3.8 1165

     And the command is:

             sattool step 30 true

     where 30 is the number of seconds between each printed position.  The
     expression is evaluated at every position, with one useful expression
     being 'mag lt 4', which will only print times where the satellite's
     magnitude is less than 4.


2.4. Putting it All Together
----------------------------

     Now is the time for putting it all together.  There are two ways to do
     this: using pipes or using the -i and -o options to connect the two
     files.

     Generally, a mix of these are used.  For example, the command the
     author uses to find relatively bright satellites is:

            ./sattool predict -vti mccants.tle now midnight | \
            ./sattool filter -o passlist -- lit and sunel lt -6 and minmag lt 3
            ./sattool step -i passlist 30 mag lt 4.5

     This reads elements from the file mccants.tle, and predicts the passes
     from the current time to the next midnight.  It then pipes the list of
     passes to a filter, and saves the filtered list into the file
     passlist.  It then steps the passes.

     It's generally useful to store the filtered passlist in a file, since
     that allows the passlist to be viewed in some of the other tools.
     (Most notably, the live display sub-program.)


2.5. The Live Display
---------------------

     The live display is invoked with the command

              ./sattool live -i passlist

     It's important that a file is used, as piping it to standard input
     causes standard input to be closed.  That makes it impossible to give
     keyboard commands to the live display.

     Once the live display is up, press the 'v' key to call up a magnitude
     display.  Then, the arrow keys can be use to move forwards and
     backwards through the passlist.  Use the 'q' key to quit the live
     tracking display.

     More information about the list sub-program can be found in the
     command reference section below.


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


3. Command Reference
--------------------


3.1. cat
--------

     The cat command simply copies the input list to the output list.  It's
     only useful for converting from a TLE file to sattool's native format.
     Even at that, it isn't really all that useful.


3.2. writetle
-------------

     The writetle command attempts to parse each input list element as a
     Sgp4Sat.  If it can do this, it outputs the element in TLE format.


3.3. filter
-----------

     Filter allows for filtering the input list based on arbitrary
     expressions.  It's a fairly sophisticated expression parser, which
     allows expressions to be connected using 'and' and 'or' operators.
     It's also possible to use parenthesis to clarify your expression.

     Expressions contain keywords of two types.  Boolean keywords return
     true if what it represents is true.  Value keywords take an operator
     and something to compare it with, and they use that to determine the
     truth values.  The operators allowed are '<', which can be written as
     'lt'; '>', which can be written as 'gt'; and '='.  The keywords are:

     false
          A boolean keyword that's always false.

     lit
          A boolean keyword that's true if the pass is lit at it's
          beginning or end.

     mag
          A value keyword that's the satellite's visual magnitude during an
          encounter.

     minmag
          A value keyword that's the satellite's minimum magnitude for the
          current pass.  This is only defined if we're filtering a pass.

     norad
          A value keyword that represents the satellite's norad number.
          This works on satellites.

     sunel
          A value keyword that represents the sun's elevation at the time
          in question.  (Which is either the cumulation of a pass or the
          time of an encounter.)

     true
          A boolean keyword that's always true.

     Sample filter expressions are:

          norad = 16609 or norad = 25544
          lit and sunel lt -6 and minmag lt 3.56

     It may be necessary to place a -- on the command line before the
     expression to prevent negative numbers from being parsed as options.


3.4. marker
-----------

     The marker command takes a list of sats for it's input, and takes as
     an argument a number of seconds.  It also requires that an output file
     be specified with the -o option.  Then, every number of seconds, it
     writes the current latitude and longitude to the file in a way
     compatible with the markerfile capabilites of xearth and xglobe.


3.5. live
---------

     The live command reads in an input list of objects (or equivalents),
     and displays it in realtime.  Depending on what exactly is in the
     input list, more information may be displayed.  For example,
     satellites also display their norad number and international
     designations, and passed display times of rise, set, cumulation, and
     maximum magnitude.  Look angles, Latitude, Longitude, Altitude, and
     ECI vectors are always displayed.  The units are km, km/s, or degrees,
     as appropriate.

     The live command only works properly if it's input is a file specified
     with the -i option.

     Here's a list of valid keystrokes.

     v
          Toggle visual mode.  Visual mode consist of a display of
          magnitude information on the right stide of the screen.  This is
          the default if the -v option is given.

     1
          This fixed the display time to the start of the current pass.

     2
          This fixed the display time to the cumulation of the current
          pass.

     3
          This fixed the display time to the end of the current pass.

     1
          This fixed the display time to real time.

     space
          This displays either the next pass that hasn't been completed
          yet, or the next satellite that's currently risen.

     +
          This increases the offset between the time of the data displayed
          on the screen and the current time.

     -
          This decreases the offset between the time of the data displayed
          on the screen and the current time.

     l
          This toggles a lock on a satellite.  When lock is engaged, a pipe
          to the program defined in the environment variable SATLOCKPROG is
          established.  Then, every SATLOCKSTEP seconds, the azimuth,
          elevation, and current satellite name is send down the pipe to
          that program.

     ;
          This decreases the offset between the time used to calculate look
          angles in a lock, and real time.

     '
          This increases the offset between the time used to calculate look
          angles in a lock, and real time.

     down, right
          This moves the display to the next list element.

     up, left
          This moves the display to the previous list element.

     home, <
          This moves the display to the first list element.

     end, >
          This moves the display to the last list element.

     q
          This quits the live satellite display sub-program.


3.6. predict
------------

     The predict command is used to predict when a satellite pass will be
     visible at a given site.  A pass is defined as a time when the
     satellite is above a given elevation.

     If predict is invoked with one argument, that argument is the end time
     of the prediction.  The start time is now.  Otherwise, if two or more
     arguments are given, the first is the start time and the second is the
     end time.

     The time parser is fairly sophisticated.  Some of the time
     specifications it can handle are:

          1999-12-11 12:30
          noon today
          midnight + 2 hours

     If no day is mentioned, the time is considered to be it's next
     occurance.  For example if it's 19:30 today, the time specification
     20:00 occurs on today, while 19:00 occurs tomorrow.  (Unless a more
     specific date is mentioned.) It may be important to quote the time
     specifications so that they're not interpreted by the shell.

     There are also otional third and fourth arguments.  The third argument
     is is the minimum pass elevation.  This defaults to the contents of
     the SATMINELEV environment variable.  If that's not set, and the -v
     option is given, the default is 10 degrees.  Otherwise, it defaults to
     0 degrees.  The fourth option is a step time.  This controls the
     accuracy of the pass predictions, and defaults to the value of
     SATPREDICTSTEP, or 10 seconds if that's undefined.

     The -v option is useful with predict.  That option enables the
     prediction of visual pass information, namely the minimum magnitude
     found in a pass, as well as the time of that minimum magnitude.


3.7. passes
-----------

     The passes command displays information about every pass object that's
     piped to it.  For a more complete description of this command, please
     see the section on "Displaying the Passes" above.


3.8. step
---------

     The step command takes two arguments.  The first is a number of
     seconds, the second is an expression.  The step command filters the
     encounter that occur every given number of seconds during the pass.
     It then prints out each encounter that matches the filter.

     For a more complete description of this command, please see the
     section on "Displaying the passes" above.


3.9. summary
------------

     The summary command displays a one line summary of each of the passes
     in the input list.  The summarries look like:

          16609 86017A            Mir Complex 11/30 17:56  58 -0.6

     The fields in the display are, from left to right, the norad number,
     the international designation, the name, the date of the pass maximum,
     the time of the pass maximum, the maximum elevation in the pass, and
     the minimum magnitude during the pass.  (The latter is omitted if no
     visual information is associated with the pass.)


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


     The Sattool Manual

     Tom Rothamel <tom-sattool@onegeek.org>

     Prerelease 1

