seesat5(1) provides satellite visibility information.

DESCRIPTION

This man page explains the commands used by seesat5 to produce and control the satellites that will be analysed and the output criterion. These commands are valid for use in SEESAT5.INI, in the command line, and from the seesat5 prompt.
 

SELECTION COMMANDS

MAXELEV <number>
This selects data where the calculated elevation is less or equal to the entered value.
 
Example:
MAXELEV 70

means that only elevation values of 70 or less will be selected. Only satellites that are at 70 or less degrees in elevation will be selected.
 

MINELEV <number>
This selects data where the calculated elevation is greater or equal to the entered value.

Example:
MINELEV 15

means that only elevation values of 15 or more will be selected. Only satellites that get to 15 or more degrees in elevation will be selected.
 

MINPHASE <number>
This selects data where the calculated phase angle (the angle between the sun and the satellite as seen by the observer), is greater or equal the entered value.

MINRANGE and MAXRANGE <number>
This selects data where the range of the satellite is within these limits. The number denotes either miles or kilometers depending upon whether you set the MILES or KILOMETERS option. If the satellite never gets between the MINRANGE and MAXRANGE values at your location, then no data is printed for it. The default values for MINRANGE and MAXRANGE is zero and 65535 respectively.

SET and RESET
These commands are used to set and reset conditions and options. They are as follows :
 
SET SHOWTLE
SET SHOWNORAD
etc.

  is is useful when you want to see all the data using the ALL command. If you don't reset the selection conditions, the program does not print any lines because the conditions are not satisfied. The values for SHOWTLE, VISMAG, SUNELEVSAT, SUNELEVOBS, MINELEV, MINRANGE, MAXRANGE and SHOWAGE can be reset.

SET KILOMETERS | MILES
This varient of SET determines whether distances are to be printed in MILES or KILOMETERS. Various people can only visualize distance in one or the other of these units.

SHOWAGE
When this option is SET, the age (in days) of the element is displayed. This is the age of the element at the time for which the satellite data is printed. Also note that this value is UTC relative. For example, if you do a whole weeks run with the same satellite elements and the satellite is visible every day, then the TleAge value will be 1 day greater in each days printout.

SHOWNORAD
Show the satellite NORAD number on the printout.

SHOWTLE
Controles the printing of the Keplerian elements when a LOAD or NEXT is done. When SET, Keplerian elements are printed. When RESET, they are not
 
SUNELEVOBS <number>
This selects data where the calculated SUN's elevation at the observers location is less or equal the entered value.

Example:
SUNELEV 0

means select data when the sun is at or below the horizon. This will let you filter out satellite's that pass over in daylight.

SUNELEVSAT <number>
This selects data where the calculated SUN's elevation at the satellite is greater or equal than the entered value.

Example:
SUNVAL 0

means that only positive SUN values will be selected. This lets you select data when the sun is shining on the satellite.

VISMAG <number>
This selects data where the MAGNITUDE is less or equal to the supplied value.

Example:
VISMAG 1.0

means the calculated magnitude must be less than or equal to 1.0. This lets you select bright satellites only.

GENERAL COMMANDS

ALL
Toggles between normal mode (predictions below horizon suppressed) and a mode which displays all predictions.

APPENDSDF
This command requires a file name parameter. This is the same as the OPENSDF command except the file is opened for extend. If the file named does not exist, it will be created.

BLOCK
This command is used to customize the skyline that you view from. It has the format BLOCK begin-azimuth end-azimuth elevation. The azimuth values are integers between 0 and 359 and the elevation 0 and 90 degrees. You can use this to accurately define your view of the sky. You can enter up to 30 block commands, each one defines a block from a starting azimuth, ending azimuth and an elevation. If a satellite never gets out from behind the blocks you define then its data will not be printed. If at any time (be careful with time steps here), the satellite is visible, then its data is printed and the data where it is behind a block will be printed with a particular time you will not be able to see the satellite although it is above the horizon. The MINELEV command is a more simplified version of BLOCK and only useful in an open field where the "mist line" at the horizon is uniform. BLOCK provides a better solution for "city dwellers" where buildings tend to block only some areas of the sky.

CENTER
Followed by a time, this command determins the time to center the data run, usually used in conjuction with SPAN.

Comments
If you want to put comments inside your SEESAT5.INI file, just type in a forward slash (/) anywhere you want. When the slash is at the start of a line the entire line is treated as a comment. When it is in the middle of a line, everthing after the slash up to the end of the line is treated as a comment.

CMDLINE
This command is reserved for use in SEESAT5.INI. When seesat5 encounters this command it executes the commands found on the command line as though they were located in the init file where the cmdline command is located. The main use of this command is to impliment the "go label" command. Typically the init file begins with setup commands that set the viewing location as well as some general filter criterion. Following this with cmdline, followed by as many blocks of instructions as you like, each one beginning with a unique label, allows a runtime choice of which block to execute.

DBS and DBS#
To select satellites you want to run predictions on. You can maintain the list inside the seesat.bat file, together with comments. You may load the satellite either by name or by Norad Satellite Number.
 
DBS "HST ARRAY" / Last seen 2/3/94, dim, blinks
DBS HST / Last seen with shuttle
DBS "OKEAN 1" / Fast
DBS MIR / Must see soon
DBS 23028 / SEDS 2
DBS# 16609 / Its MIR again

After selecting your favorite satellites, run the prediction using the RUNDBS command.

RUNDBS is like RUNTIME but just runs satellites in your database. You can still do RUNALL or RUNTIME any time to run all the satellites loaded with your last OPEN.

If you want to select another set of DBS satellites, you can either OPEN a new TLE file (that resets all the DBS entries to false), or more efficiently (if you want to keep the current TLE file open), use the RESET DBS command.

EX <filename>
Execute a batch file of commands. Any SEESAT command may appear in a batch file. Multiple commands per line are allowed, just as if you were entering the command line manually. EX itself may be in a batch file. If encountered, it will close the current batch file and begin executing the specified file. Control will not return to the preceding file. I.e., you can chain batch files but not nest them.

EXIT
Exit from seesat5.

GO or GOTO
Requires a label name to go to, and starts processing there. The GOTO command is probably going to be most useful from the command line to let you jump into a particular SEESAT5.INI file section of your choice. Obviously, any commands following the GOTO will not be processed. When you specify a GOTO command, the program begins searching the SEESAT5.INI file from the beginning and looks for the LABEL <labelname> line. If one is not found, the message END OF BATCH FILE is displayed and the program goes into keyboard command mode. If you have duplicate labels, the first one will be processed. No checking is done to prevent you from making the program loop continously, so be careful. Also, if you use EX'ed files, the GOTO will only goto labels in the current file that is open.

HELP
Displays a help screen.

HEIGHT <number>
Number, specifies, in kilometers, the height of the viewing location. Errors incurred from incorrect values for height have little propogation into the satellite location prediction. As a result, if you don't know your height, it may safely be left 0.

INDEX
Lists the satellites in the currently open file. If there is more than one screenful, it will pause with a "more>" prompt. At this prompt you may either press RETURN to continue the listing, or enter a command (or commands) just as you would at the normal command prompt. In that case, the listing is aborted and your commands are executed.
 
LABEL
This command requires a parameter that is a label that you want to GOTO later. The maximum label length is 30 characters and it must be the FIRST command on the line. More commands are allowed after the label name if you want, but I found it more readable to have the command on a single line.
 
Example
LABEL DAILY-RUN

  Use labels to keep my run parameters for different situations in a single SEESAT5.INI file and select which ones to process using the GOTO command.

LAT <number>
The number, in degrees, specifies the latitude of the viewing location. Southern latitudes are declaired with a negative number. Precision in this location is critical. A .14 degree error in location, approximately 10 miles will cause a 1 degree error in the satellite position.

LENGTH <integer>
Sets maximum number of characters the OPEN command will consider significant in the satellite name when building the index. The LENGTH command must therefore be issued before OPEN, to have any effect. Any number from 1 - 22 is allowed. Default is 22, and may be left alone unless you're using a file such as Molczan's N2L series. In that case, you'll want to reduce LENGTH to 15 to prevent SEESAT from using the extra data as part of the satellite name. LENGTH is set to 22 if you enter a number larger than 22.

LINEFEED
This command as added for predictions done on a machine where a typical run takes hours. Starting the run with the output redirected to the printer serves two purposes:

1.to print out the data, and
2.to serve as an alarm.

How does this serve as an alarm? With a dot matrix printer the machine can be left to run. While other work gets done the machine chuggs along. Eventually, the program finds a satellite that can be seen. When the printer starts clacking away after the long silence you know that there is new data available. So that you can come to the printer and tear off the new data without interfering with potential new printing this command prints a selected number of linefeeds after the satellite listing.

LOAD <name>
Loads the named satellite from the file you opened with the OPEN command. If the name has spaces, begin the name with quotes.

LOAD# <number>
This is just like the original LOAD command except you must supply the Norad Satellite number. This is most usefull when you have TLE files from different sources and the satellite names are not consistent.

LON <number>
The number, in degrees, specifies the longitude of the viewing location. Western longitudes are specified with a negative number. As with latitude a relatively small error of .14 degrees will cause a 1 degree error in the satellite location.

MAG <number>
For entering the absolute magnitude of a satellite. It will be adjusted for range and illumination angle to generate the "mag" value in the prediction table. Absolute magnitude is its magnitude at 1000 km and 50% illuminated (i.e., 90 degree phase angle). Absolute magnitude input can be automatic during loading of the elements from the file. If the first line of the element set (the satellite name line) is longer than 32 characters, SEESAT assumes it's a Molczan format line, and reads the magnitude. You can use the MAG command to override the value if necessary.

MAGBIAS <number>
Bias to be applied to SEESAT's computed magnitude before display. A negative sign is allowed. The default is zero. If your absolute magnitudes assume a different range and/or illumination than 1000 km and 50%, the MAGBIAS command will bring your scale into coincidence with SEESAT's. If r and k are your assumed standard conditions (in km and percent, respectively), set MAGBIAS to:

2.5 * log10 ((1000/r)^2 * k/50)

For example, if your absolute magnitude is for 1000 km range and 100% illuminated, enter:

MAGBIAS .8

MERIDIAN
The satellite longitudes in the prediction table may be computed with respect to either Greenwich or your local meridian. MERIDIAN toggles this mode, and informs you of the current mode. Default is Greenwich.

MOON <date time>
Print the azimuth & elevation of the moon at the given time. Percentage of illumination is also given.
 
NEXT
Loads the next satellite from the current open element file.

NOMINAL <date time> / ACTUAL <date time>
These commands adjust the epoch and RAAN of the currently loaded elements for the difference between the nominal and actual launch times. They are useful for correcting a prelaunch element set.

EXAMPLE:
NOMINAL 19 1851 ACTUAL 1918

tells SEESAT that the currently loaded elements assume a launch on the 19th at 1851, but the launch actually occurred at 1918. You can't use NOMINAL or ACTUAL by itself! If you use one, you must also use the other or you'll get crazy results. The order of the commands does not matter, and they don't have to be on the same line. Just be sure that both commands have been given before starting a prediction run. The entered values are remembered. So you may, for example, use NOMINAL just once, then experiment with different ACTUAL values. Loading an element set (even reloading the same one) disables the effect of NOMINAL and ACTUAL. Their values are still remembered, however, so you may re-enable the adjustment by giving one or both commands. The NOMINAL and ACTUAL arguments may be for any time zone, as seesat5 cares only about their time difference.

NULL
This command is useful if you want to specify year, month day and time for the start/stop/span commands but don't want to do the RUN command automatically. It can save specifying repeated information on every line of your parameters.
 
Example :
open my.tle span 720 null
start 1993 oct 01 1900 runall
start 1993 oct 02 1900 runall
exit

OFFSET <time>
Applies an offset to the epoch of the satellite elements, thereby making the satellite come early or late in the predictions. Useful for putting a satellite ahead of or behind schedule, to evaluate the resulting track drift with respect to the stars. Also can be used to adjust for any discrepancy noted between predicted and actual times of passes. A negative sign is allowed on <time>. A negative <time> will make the effective epoch EARLIER, and make the satellite come EARLIER in your predictions. If OFFSET is nonzero, an advisory of its value is printed at the top of each prediction table. OFFSET is reset to zero when an element set is loaded.

OPEN <filename>
Opens the orbital element file. If an element file is already open, that file will be closed first.OPEN builds an index of the satellites in the file, using linked blocks in RAM. Each block holds 50 satellites. Storage is requested as needed at run time, so the size of the element file is limited only by available memory. Assuming your system uses 4-byte longs and 2-byte pointers, each 50-satellite block uses 1352 bytes.The index only contains the name of the satellite and its location in the file. The elements are not read from the disk until you issue the LOAD or NEXT command.
 
OPENSDF
This command requires a file name parameter that will open a STANDARD DELIMITED FILE with that name. The file format is as follows:
 
1st. record
"satellite","date","time", ...

2nd. record thru EOF
satellite name
date
time
:
:

ORBITMINS       
This a value that has a default of 60 minutes. This is used in the
RUNTIME mode to determine how long to keep a satellites above horizon values in memory before they are deemed un-useable. The way the RUNTIME mode works is that it does a prediction for a satellite. If that satellite is above the horizon at a particular time, that time is saved in memory. When the satellites other attributes (elevation, magnitude etc) are checked and they pass the conditions, the stored time values are used to start printing the prediction run. If the satellite never satisfied the selection conditions, then after 60 minutes has passed, the stored time values are reset. This prevents misleading prediction data being printed.

PARA <date time>
Print the parallactic angle at the predicted position of the satellite for the given time. Parallactic angle is the direction of celestial north, as seen in a binocular field of view. E.g., 0 = straight up, 90 = 3 o'clock. This command allows you to examine your star atlas plot and visualize the star field orientation you'll see when you go outside.

PRECESS <date time>
Controls the correction of Right Ascension and declination for precession. PRECESS sets the final epoch. The epoch of the elements is always used as the initial epoch. For 1950.0 or 2000.0 coordinates, respectively:

PRECESS 1950 JAN 0 2210
PRECESS 2000 JAN 1 1200

   These are Greenwich times, so, strictly speaking, the PRECESS command should be given before setting ZONE. But for all practical purposes it doesn't matter. Precession is so slow there will be virtually no error even if you miss by a full year. Over several decades, though, it will build up to a significant level. For example, if your atlas is 1950.0 and you neglect the PRECESS command, an error of up to 42 arc minutes can occur in your plot of a satellite's track. This is perhaps four or five times worse than SEESAT's prediction accuracy under good conditions! The PRECESS value remains until you change it or exit SEESAT. Default setting is 2000.0 at program startup.

PREDICT
This will run the current parameters and conditions for each satellite in the TLE file, and display results whenever a satellites data passes the selection conditions. It then increments the time by 1 minute and re-runs the prediction again. This will continue forever or until a key is pressed.

The START command must be done first to setup the date and time at which the prediction starts. This is the raw data generator for the realtime graphical display and also gives you in time order, the satellites you may be able to see.

PRINT?
If the last prediction run resulted in a line of data being printed, execute the command to the right of PRINT?. Otherwise, skip it. There must be at least one command after PRINT?.

PRINTLIMIT
This command is used to limit the number lines printed per satellite prediction when running in the RUNTIME mode. The reason you may want limit the lines printed is because of very slow moving or stationery satellites. The RUNTIME mode normally prints prediction data until the satellite dips below the horizon. Of course, some satellites never dip below the horizon so end up with either a lot of prediction data or the program just keeps printing the data forever. I had coded a default value for the printlimit of 60 lines. This default is fine for most regular runs, but for some special purpose runs you may want to change it.

RET
If encountered in a batch file, returns control to user. If entered manually, resumes execution of the batch file.

REPEAT
Jump back to beginning of command line.

REPORT
This command is used to suppress printing of lines that come from the SEESAT5.INI file. It requires a 0 or 1 as a parameter. The default is to suppress (value 0). If you want to see all command lines and messages printed, set the report option to 1. Messages like "complete; nn satellites found" are suppressed. More message may be suppressed by this command in the furure. This just helps to 'clean' the output to just the interesting satellite data.

RUN
Begin a prediction run, using the current time parameters. The START, STOP, CENTER, SPAN, or STEP command automatically begins a run if it is at the end of the command line. That is the normal way to get a run. The RUN command is convenient if, for example, you load a new element set and want a run without changing time parameters.

RUNALL
This command is almost a combination of OPEN, NEXT, RUN and REPEAT. It takes no parameter values or filenames. It will reposition the current TLE files pointer to BOF, read thru each two line element set, do the RUN command on it and repeat until all elements in the file have been read. The difference between this command and the commands it replaces, is that it carries on processing the next input command after all two line elements have been processed. The NEXT RUN REPEAT commands unfortunately stops the entire run as soon as it reaches the end of the elements file. I use this to generate a list of all satellites that I can see each day for the whole of the month!

Example :
open my.tle
start 1993 oct 01 1900 span 720 runall
:
start 1993 oct 18 1900 span 720 runall
:
start 1993 oct 31 1900 span 720 runall
exit

RUNDBS
Like RUNTIME but only runs the satellites in your database. You can still do RUNALL or RUNTIME any time to run all the satellites loaded with your last OPEN.

RUNTIME
This runs prediction in time order. This produces the exact same output data as the RUN command except it is in time order. It does however take a little longer to run. The processing involved in this command is to run through every satellite looking for a satellite that is above the horizon at a particalur instance. The instances starts at the start time and continues until the stop time is exceeded with an increment of the step.

When a satellite is found that is above the horizon and it also satifies the selection conditions, its data is printed until it dips below the horizon. At that time the printing stops and the next satellite in the input TLE file is processed.

For Geo Stationary satellites the parameter PRINTLIMIT comes into play. This allows you to stop the printing of data when a certain number of lines have been printed. If this command was not present, the data print would print forever if a geo-stationary satellite ever passed all the selection conditions.

SDFCLOSE
This command requires NO parameter, it just closes the last opened SDF file.

SKIP
Skip the command to the immediate right of SKIP. To be used following PRINT?, to reverse the test. There must be at least one command after SKIP.

SPAN
Followed by a time in minutes, this command determins the length of the data run. When used with the CENTER command the time value is centered on this time.

START
Defines the start time for the run. Requires a date and a time as parameters.

STEP <time>
Controls size of time steps in the prediction run in minutes. A run begins automatically if STEP is the last command on the line.

STOP
Defines the stop time for the run. If only a time is specified, the start date will be used. Accepts a date and a time as parameters.

STOPDAY (and STARTDAY)
These commands require an integer and a time. The integer is when you want to stop (start) the prediction in number of days from today, followed by a time that you want to stop (start). Just for consistency, the TODAY command can now also be specified as STARTDAY.

SUMMARY
This command will show a selected summary data about the last TLE file that you OPENed. At present it shows the satellites that have the earliest and latest epoch dates.

SUN <date time>
Print the azimuth & elevation of the sun at the given time.

TODAY
This commands automatically sets up todays date as the default START date. The command must be followed by a number indicating how many days you want to add to the system date as the START value. This number may be zero or an integer number of days.
 
Example :
OPEN NASA.TLE
TODAY +0 1700 STOP 2300 RUNALL
TODAY +1 0400 STOP 0800 RUNALL

  gives tonight and tomorrow mornings satellite viewing data. This command was implemented because it saves changing SEESAT5.INI every day to run nightly and morning predictions. You can set up the similar parameters as the example above, depending on when you do your regular/daily prediction run.

ZONE <time>
Set timezone to that at the viewing location in UTC. A negative sign is permitted. E.g., for Pacific Standard Time:

ZONE -800 or
ZONE -0800

The ZONE value need not be an integral number of hours, e.g., Newfoundland standard time is 3h 30m behind UTC:

ZONE -330

Default ZONE at program startup is Greenwich time.

ORBITAL ELEMENT ENTRY

The following commands are used for entering orbital elements when no tle file is available for the satellite in question.

AOP <number>
Number represents the argument of the perigee.

B <number>
Number represent the BSTAR value.

E <number>
Number specifies the eccentricity of the orbit

EPOCH <epoch>
Manually enter epoch of the orbital elements. Must be in NORAD format: YYDDD.DDD... (use any number of decimal places). Unused digits in the integer part of day number must be padded with spaces or zeros. If spaces are used for padding, the number must be enclosed in quotes.

EXAMPLE:
EPOCH 91003.52029891 or
EPOCH "91 3.52029891"

I <number>
The number stands for the inclination of the orbit.

MA <number>
This number specifies the mean anomaly.

MM <number>
Mean motion is determined by the value of number.

MMDOT <number>
This number represents the first derivative of the mean motion. Note: this value is not used in the SPG4 model used by seesat5 and is only retained for compatability with the older SPG model

MMDOTDOT <number>
The second derivative of the mean motion is specified by this number. Note: this value is not used in the SPG4 model used by seesat5 and is only retained for compatibility with the older SPG model.

NAME <satellite name>
Satellite name will appear in the printout for the current element data being loaded by the above commands.

RAAN <number>
This number specifies the right ascension of the ascending node.

BUGS

Many of the above commands "do not work well with others" so some unexpected behavior may result at times. Please report any suspected bugs to Dale Scheetz <[email protected]>.