NAME
seesat5 - 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.
SEE ALSO
seesat5(1), SEESAT5.INI(5), tle(5), cr(1)
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 <dwarf@polaris.net>.