The Sattool Manual - Chapter 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.)