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.
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.
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.
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.
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.)
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.
tom-sattool@onegeek.org