DragonFly On-Line Manual Pages

SATPASS(1) User Contributed Perl Documentation SATPASS(1)

NAME
satpass - Predict satellite passes over an observer.

SYNOPSIS
The intent is to be 'one stop shopping' for satellite passes. Almost
all necessary data can be acquired from within the satpass script, an
initialization file can be used to make your normal settings, and
macros can be defined to issue frequently-used commands.

$ satpass

[various front matter displayed]

satpass> # Get observer's latitude, longitude and height.
satpass> geocode '1600 Pennsylvania Ave Washington DC'
satpass> # Don't use SpaceTrack when a redistributor has the data.
satpass> # If you don't set direct, you must have a SpaceTrack login.
satpass> st set direct 1
satpass> # Get the top 100 (or so) visible satellites from CelesTrak.
satpass> st celestrak visual
satpass> # Keep only the HST and the ISS by NORAD ID number
satpass> choose 20580 25544
satpass> # Predict for a week, with output to visual.txt
satpass pass 'today noon' +7 >visual.txt
satpass> # Get Iridium satellites.
satpass> st celestrak iridium
satpass> # Predict flares and scroll thru output if you have 'less'.
satpass> flare |less
satpass> # We're done
satpass> exit

NOTICE
As of release 0.057 this script is deprecated. See below for details.
In the first release of the year 2014 I intend to remove the question
in the installer that allows this script to be installed, and to rename
the entire distribution from the current "Astro-satpass" to
"Astro-Coord-ECI".

This release supports the new "pass_threshold" attribute of
Astro::Coord::ECI::TLE, which provides a way to decouple how high a
pass need to be to be reported from how high the horizon is.

The use of the SOAP::Lite interface to <http://geocoder.us> is no
longer supported. As of version 0.056_01, attempting to geocode
without Geo::Coder::Geocoder::US is a fatal error.

The "status iridium" command is now fatal. It has been deprecated in
favor of "status show" for some time now, and has warned on every use
since version 0.044 (October 19 2011).

A production version of the "Asto-App-Satpass2" package, which is the
planned successor to this script, was released February 5 2012.

Once I consider this production-quality (six months to a year after I
go to a production version number) the satpass script will become
deprecated, and eventually will be removed (or moved to the eg/
directory). When this happens, the "Astro-satpass" distribution will be
replaced by the "Astro-Coord-ECI" distribution.

Most of the functionality of the Astro-App-Satpass2 distribution will
be in the Astro::App::Satpass2 class. A minimal satpass2 script will be
provided to manufacture an Astro::App::Satpass2 object and invoke its
run method. I will try to keep the core functionality the same, and to
document in Astro::App::Satpass2 any incompatibilities introduced.

Since Perl's dependency mechanism is based on module names, not package
names, I assume that there will be no problems with packages that
depend on the Astro::Coord::ECI modules. But I will try to give the
authors of such packages a month's notice before releasing the first
Astro-Coord-ECI package.

One incentive for doing this is to restructure the satpass
functionality to be more easily testable. Placing the satpass
functionality in its own object achieves this; indeed the work flushed
out a couple subtle bugs in the satpass script, whose fixes have been
back-ported into this script.

A second incentive is that the natural dependencies for the application
are quite different than those of the Astro::Coord::ECI classes. It
seems desirable not to force those who only want the latter to download
and install all the stuff required by the former.

DETAILS
The satpass script provides satellite visibility predictions, given the
position of the observer and the NORAD element sets for the desired
satellites. It also provides the following bells and whistles:

* The ability to acquire the NORAD element sets directly from
<http://www.space-track.org/>, <http://spaceflight.nasa.gov/>, or
<http://celestrak.com/> (or, indeed, any source supported by
Astro::SpaceTrack), provided the user has an Internet connection and
the relevant site is functional. The Space Track site also requires
registration. You will need to install Astro::SpaceTrack to get this
functionality.

* The ability to acquire the observer's latitude and longitude from
<http://geocoder.us/>, given a street address or intersection name, and
provided the user has an Internet connection and the relevant site is
functional and has the data required. This function may not be used for
commercial purposes because of restrictions Geocoder.us places on the
use of their data. You will need to install Geo::Coder::Geocoder::US to
get this functionality.

* The ability to acquire the observer's height above sea level from
<http://gisdata.usgs.gov/>, given the latitude and longitude of the
observer, and provided the user has an internet connection and the
relevant site is functional and has the data required. You will need to
install Geo::WebService::Elevation::USGS to get this functionality.

* The ability to look up star positions in the SIMBAD catalog. You will
need to install Astro::SIMBAD (if using SIMBAD 3) or
Astro::SIMBAD::Client (if using SIMBAD 4) to get this functionality.
The SIMBAD version is selected using the simbad_version parameter.

* The ability to produce solar and lunar almanac data (rise and set,
meridian transit, and so forth).

* The ability to define macros to perform frequently-used operations.
These macros may take arguments, and make use of any "PARAMETERS" or
environment variables. You will need to install IO::String to get this
functionality unless you are running Perl 5.8 or above.

* An initialization file in the user's home directory. The file is
named satpass.ini under MacOS (meaning OS 9 - OS X is Darwin to Perl),
MSWin32 and VMS, and .satpass under any other operating system. Any
command may be placed in the initialization file. It is a good place to
set the observer's location and define any macros you want. The default
initialization file can be overridden using the SATPASSINI environment
variable or the -initialization_file command option. Internally to
satpass and any commands it spawns, environment variable SATPASSINI
will be set to the name of the initialization file actually used. See
"ENVIRONMENT VARIABLES" for how to find out the actual initialization
file used.

COMMANDS
A number of commands are available to set operational parameters,
manage the observing list, acquire orbital elements for the observing
list, and predict satellite passes.

The command execution loop supports command continuation, which is
specified by placing a trailing '\' on the line to be continued.

It also supports a pseudo output redirection, by placing '>filename'
(for a new file) or '>>filename' (to append to an existing file)
somewhere on the command line. It is also possible to redirect the data
into a spawned command using the pipe character ('|'). Additional pipe
characters may be specified on the same command line if your operating
system supports this. Note that the redirection character must be the
first character of the token; that is, 'pass >file.txt' or 'pass
|less', but not 'pass>file.txt' or 'pass|less'. See the "SYNOPSIS" for
examples.

In addition, all commands support the following options:

-clipboard places the output of the command on the clipboard. This will
be discussed more below.

-debug is accepted but not supported - that is, the author makes no
claims of what will happen if you assert it, and reserves the right to
change this behavior without warning. It is really a development aid.

-time causes the elapsed time of the command in seconds to be
displayed. This is another development aid.

Individual commands may have options specific to them. Option names may
be abbreviated, provided the abbreviation is unique among all options
valid for that command. They may appear anywhere in the command line
unless otherwise documented with the specific command ('system' being
the only exception at the moment).

If the -clipboard option is asserted, output to standard out will be
placed on the clipboard. This output will not appear on the clipboard
until the command completes.

The clipboard functionality requires the availability of the
Win32::Clipboard module under MSWin32 (standard with ActivePerl), the
Mac::Pasteboard module or the pbcopy command under darwin (and any Mac
OS X I know of comes with pbcopy and pbpaste), or the xclip command
(available from <http://freshmeat.net/projects/xclip>) under any other
operating system.

The clipboard functionality is implemented as a singleton object, so
that if you redirect output away from the clipboard and then back to
it, both sets of clipboard data are considered to be the same data
stream, and both end up on the clipboard, without the intervening data.

The command loop also supports rudimentary interpolation of arguments
and other values into commands. The "magic" character is a dollar sign,
which may be followed by the name of what is to be substituted. A
number represents the corresponding macro or source argument (numbered
from 1), and anything else represents the value of the named parameter
(if it exists) or environment variable (if not). The name may be
optionally enclosed in curly brackets.

If the name of the thing substituted is enclosed in curly brackets, it
may be optionally followed by other specifications, as follows:

${arg:-default} substitutes in the default if the argument is undef or
the empty string. If the argument is 0, the default will not be
substituted in.

${arg:=default} not only supplies the default, but sets the value of
the argument to the specified default. Unlike bash, this works for any
argument.

${arg:?message} causes the given message to be displayed if the
argument was not supplied, and the command not to be processed. If this
happens when expanding a macro or executing a source file, the entire
macro or file is abandoned.

${arg:+substitute} causes the substitute value to be used provided the
argument is defined. If the argument is not defined, you get an empty
string.

${arg:default} is the same as ${arg:-default}, but the first character
of the default must be alphanumeric.

Interpolation is not affected by quotes. If you want a literal dollar
sign in the expansion of your macro, double the dollar signs in the
definition. It is probably a good idea to put quotes around an
interpolation in case the interpolated value contains spaces.

For example:

macro ephemeris 'almanac "$1"'

sets up "ephemeris" as a synonym for the 'almanac' command. The
forward-looking user might want to set up

macro ephemeris 'almanac "${1:tomorrow midnight}"'

which is like the previous example except it defaults to 'tomorrow
midnight', where the 'almanac' command defaults to 'today midnight'.

As a slightly less trivial example,

macro ephemeris 'almanac "${1:=tomorrow midnight}"' 'quarters "$1"'

which causes the quarters command to see 'tomorrow midnight' if no
arguments were given when the macro is expanded.

The following commands are available:

almanac start_time end_time
This command displays almanac data for the current background
bodies (see sky). You will get at least rise, meridian transit, and
set. For the Sun you also get beginning and end of twilight, and
local midnight. You also get equinoxes, and solstices, but they are
only good to within about 15 minutes. For the Moon you get quarter-
phases. This is all done based on the current parameter settings
(see "PARAMETERS" below).

The output is in chronological order.

This command supports the following options:

-horizon specifies that rise and set times are reported. -rise and
-set are both synonyms for this; -rise also reports when the bodies
set, and vice versa.

-quarter specifies that quarters are reported.

-transit specifies that transits are reported. This includes
transits below the observer (e.g. local midnight), if these are
generated.

-twilight specifies that the beginning and end of twilight are
reported.

By default, all events are reported.

The start_time defaults to 'today midnight', and the end_time to
one day after the start time.

See "SPECIFYING TIMES" below for how to specify times.

cd directory
This command changes to the named directory, or to the user's home
if no directory is specified and the user's home directory can be
determined. This change affects this script, and any processes
invoked by it, but not the invoking process. In plainer English, it
does not affect the directory in which you find yourself after
exiting satpass.

check_version
This command downloads
<http://search.cpan.org/dist/Astro-satpass/>, parses out the
version, and compares it to the version of this script, displaying
both versions and the result of the comparison. The intent is to
provide a mechanism for checking the currency of this script in the
event it becomes a separate distribution from Astro::Coord::ECI.

choose name_or_id ...
This command retains only the objects named on the command in the
observing list, eliminating all others. It is intended for reducing
a downloaded catalog to manageable size. Either names, NORAD ID
numbers, or a mixture may be given. Numeric items are matched
against the NORAD IDs of the items in the observing list; non-
numeric items are made into case-insensitive regular expressions
and matched against the names of the items if any.

For example:

satpass> # Get the CelesTrak "top 100" list.
satpass> st celestrak visual
satpass> # Keep only the HST and the ISS
satpass> choose hst iss

The one command-specific option is -epoch. It takes as an argument
any valid time, and retains the most recent set of elements for
each object which are before the given time. If there are none
before the given time for a given object, the earliest set of
elements is retained.

For example:

satpass> # Get some historical data
satpass> st search_name zarya -start 2006/04/01 \
_satpass> -end 2006/04/07
satpass> # Keep the set relevant to noon the 6th
satpass> choose -epoch 'Apr 7 2006 noon'

Most commands that operate on the observing list choose the correct
elements based on the time (or the start time) specified on the
command. So barring bugs, you may not need this option unless you
are trying to assemble and save a set of elements relevant to a
given time in the past.

clear
This command clears the observing list. It is not an error to issue
it with the list already clear.

drop name_or_id ...
This command removes the objects named in the command from the
observing list, retaining all others. Either names, NORAD ID
numbers, or a mixture may be given. Numeric items are matched
against the NORAD IDs of the items in the observing list; non-
numeric items are made into case-insensitive regular expressions
and matched against the names of the items if any.

echo ...
This command just prints its arguments to standard output.
Environment variable substitution and pseudo-redirection is done.
You may not get out exactly what you put in, because the output is
reconstructed from the tokens left after substitution and
redirection.

This was added on a whim, to prevent having to shell out to get
some random text in the output.

exit
This command causes this script to terminate immediately. If issued
from a 'source' file, this is done without giving control back to
the user.

'bye' and 'quit' are synonyms. End-of-file at the command prompt
will also cause this script to terminate.

export name value
This command exports the given value to an environment variable.
This value will be available to spawned commands, but will not
persist after we exit.

If the name is the name of a parameter, the value is optional, but
if supplied will be used to set the parameter. The environment
variable is set from the value of the parameter, and will track
changes in it.

flare start_time end_time
This command predicts flares for any bodies in the observing list
capable of generating them. Currently, this means Iridium
satellites. The start_time defaults to 'today noon', and the
end_time to +7.

In addition to the global options, the following options are legal
for the flare command:

-am ignores morning flares -- that is, those after midnight but
before morning twilight.

-choose chooses bodies from the observing list. It works the same
way as the choose command, but does not alter the observing list.
You can specify multiple bodies by specifying -choose multiple
times, or by separating your choices with commas. If -choose is not
specified, the whole observing list is used.

-day ignores daytime flares -- that is, those between morning
twilight and evening twilight.

-pm ignores evening flares -- that is, those between evening
twilight and midnight.

-questionable requests that satellites whose status is questionable
(i.e. 'S') be included. Typically these are spares, or moving
between planes. You may use -spare as a synonym for this.

-quiet suppresses any errors generated by running the orbital
model. These are typically from obsolete data, and/or decayed
satellites. Bodies that produce errors will not be included in the
output.

See the "SPECIFYING TIMES" topic below for how to specify times.

For example, assuming the observers' location has already been set,
you can predict flares for the next two days as follows:

satpass> # Get data for Iridium satellites
satpass> st celestrak iridium
satpass> # Use shorter twilight for Iridium flares
satpass> set twilight 3
satpass> # We are not interested in range to flare
satpass> set local_coord azel
satpass> # Supress date line in output, include in time
satpass> set date_format "" time_format "%d-%b %H:%M:%S"
satpass> # Not interested in night flares dimmer than -1
satpass> set flare_mag_night -1
satpass> # Finally, predict the flares. Include spares.
satpass> flare -spare now +2

geocode location country_code
This command attempts to look up the latitude and longitude of the
given location in the given country. The country is an ISO 3166
two-character country code, and defaults to the contents of the
country parameter.

This command actually works by dispatching to one of the following
geocode_* commands, which may also be invoked explicitly. In fact,
it is the existence of such a command that makes a given country
code work.

If a single location is found, the latitude and longitude
parameters will be set. The location parameter will also be set if
it was not defaulted. In addition, if the autoheight parameter is
asserted the height command will be issued with the latitude and
longitude defaulted, and the effective country code used for the
geocode lookup.

Yes, it would be nice to simply parse the country code off the end
of the location, but unfortunately there are many conflicts between
the ISO 3166 country codes and the U.S. Postal Service state codes
and Canadian province codes, ranging from AL (either Albania or
Alabama) through PE (either Peru or Prince Edward Island) to VA
(either Vatican City or Virginia).

In addition to the global options, the following additional options
are available:

-height causes the command to behave as though the autoheight
parameter were complemented. That is, it causes the height command
to be issued if autoheight is false, and vice versa.

Also, any options legal for the height command are legal, and will
be passed through to it.

The above options are also available on all of the 'geocode_*'
commands.

geocode_as location
American Samoa is handled by geocode_us.

geocode_ca location
Notice: This command is unsupported as of satpass 0.021, and
probably will not work anyway, since geocoder.ca has started
requiring registration to use its free port.

This command attempts to look up the given location (either street
address or street intersection) at <http://geocoder.ca/>. The
results of the lookup are displayed. If no location is specified,
it looks up the value of the location parameter.

If exactly one valid result is returned, the latitude and longitude
of the observer are set to the returned values, and the name of the
location of the observer is set to the location passed to the
command.

If the location contains whitespace, it must be quoted. Example:

satpass> geocode_ca '80 wellington st ottawa on'

Because of restrictions on the use of the Geocoder.ca site, you may
not use this command for commercial purposes.

geocode_fm location
The Federated States of Micronesia are handled by geocode_us.

geocode_gu location
Guam is handled by geocode_us.

geocode_mh location
The Marshall Islands are handled by geocode_us.

geocode_mp location
The Northern Mariana Islands are handled by geocode_us.

geocode_pr location
Puerto Rico is handled by geocode_us.

geocode_pw location
Palau is handled by geocode_us.

geocode_us location
This command attempts to look up the given location (either street
address or street intersection) at <http://geocoder.us/>. The
results of the lookup are displayed. If no location is specified,
it looks up the value of the location parameter.

If exactly one valid result is returned, the latitude and longitude
of the observer are set to the returned values, and the name of the
location of the observer is set to the canonical name of the
location as returned by geocoder.us. Also, the height command is
implicitly invoked to attempt to acquire the height above sea level
provided the autoheight parameter is true.

In addition to the usual qualifiers, this command supports the
-height qualifier, which reverses the action of the autoheight
parameter for the command on which it is specified.

If the location contains whitespace, it must be quoted. Example:

satpass> geocode_us '1600 pennsylvania ave washington dc'

Because of restrictions on the use of the Geocoder.us site, you may
not use this command for commercial purposes.

If you wish to use this command, you must install the
Geo::Coder::Geocoder::US module.

Caveat: The geocoder.us web site gets its data from the U.S. Census
Bureau's TIGER/LineX database. They add their opinion that it tends
to be buggy and not to cover rural areas well.

geocode_vi location
The U.S. Virgin Islands are handled by geocode_us.

height latitude longitude country
This command attempts to look up the height above sea level at the
given latitude and longitude in the given country. The country is
an ISO 3166 two-character country code, and defaults to the
contents of the country parameter.

Yes, technically country is redundant given latitude and longitude,
but I lacked a means to take advantage of this in practice.

This command actually works by dispatching to one of the following
height_* commands, which may also be invoked explicitly. In fact,
it is the existence of such a command that makes a given country
code work.

The latitude and longitude can be omitted, in which case the
current latitude and longitude parameters are used.

In addition to the global options, the following options are
available for this command:

-all causes all results to be fetched, rather than just the 'best'
one. This probably makes no difference in the value you get, since
the results are assumed to be in descending order of goodness, and
we return the first one.

-retry_on_zero specifies the number of times to retry the query if
the result is zero. The default is 0, but you can specify more.

-source_layer specifies the data set to retrieve the height from.
The default is '-1', which specifies the 'best' dataset. This is
ignored unless -all is asserted, and you can probably ignore it
too.

These options are also available on all of the 'height_*' commands.

height_af latitude longitude
Afghanistan is handled by height_us, since this is (supposedly)
covered by the U.S. Geological Survey's Afghanistan Digital
Elevation Model.

height_as latitude longitude
American Samoa is handled by height_us.

height_ca latitude longitude
This command is equivalent to height_us and in fact is handled by
it since the U.S. Geological Survey dataset includes all of North
America. But in order to cover some observed weirdness in the data
returned, -source_layer is defaulted to 'SRTM.C_1TO19_3' and
-retry_on_zero is defaulted to 3.

height_fm latitude longitude
The Federated States of Micronesia are handled by height_us.

height_gu latitude longitude
Guam is handled by height_us.

height_mh latitude longitude
The Marshall Islands are handled by height_us.

height_mp latitude longitude
The Northern Mariana Islands are handled by height_us.

height_pr latitude longitude
Puerto Rico is handled by height_us.

height_pw latitude longitude
Palau is handled by height_us.

height_us latitude longitude
This command attempts to look up the height above sea level at the
given latitude and longitude in the U.S. Geological Survey's EROS
Web Services (<http://gisdata.usgs.gov/>). If the lookup succeeds,
the latitude and longitude parameters are set to the arguments and
the height parameter is set to the result.

The latitude and longitude default to the current latitude and
longitude parameters.

If you wish to use this command, you must install the
Geo::Webservice::Elevation::USGS module.

Caveat: It is the author's experience that this resource is not
always available. You should probably geocode your usual location
and put its latitude, longitude and height in the initialization
file. You can use macros to define alternate locations if you want.

height_vi latitude longitude
The U.S. Virgin Islands are handled by height_us.

help
This command can be used to get usage help. Without arguments, it
displays the documentation for this script (hint: you are reading
this now). You can get documentation for related Perl modules by
specifying the appropriate arguments, as follows:

eci ------ Astro::Coord::ECI
iridium -- Astro::Coord::ECI::TLE::Iridium
moon ----- Astro::Coord::ECI::Moon
sun ------ Astro::Coord::ECI::Sun
st ------- Astro::SpaceTrack
star ----- Astro::Coord::ECI::Star
tle ------ Astro::Coord::ECI::TLE
utils ---- Astro::Coord::ECI::Utils

The viewer is whatever is the default for your system.

If you set the webcmd parameter properly, this command will launch
the <http://search.cpan.org/> page for this package, and any
arguments will be ignored.

list
This command displays the observing list. Each body's NORAD ID,
name (if available), dataset epoch, and orbital period are
displayed. If the observing list is empty, you get a message to
that effect.

In addition to the global options, the following options are legal
for the list command:

load file ...
This command loads the contents of one or more files into the
observing list. The files must contain NORAD two- or three- line
element sets.

localize parameter_name ...
This command localizes the values of the given parameters. If done
in a macro or source file, this causes the old parameter values to
be restored when the macro or source file exits.

If you localize a parameter more than once in a given macro or
source file, the duplicate localizations are ignored.

macro name command ...
This command bundles one or more commands under the given name,
effectively creating a new command. If any of the component
commands contain whitespace, they must be quoted. This may require
playing games if the component command also requires quotes. For
example:

satpass> macro foo list 'pass \'today noon\' +7'

or equivalently (since single and double quotes mean the same thing
to the parser)

satpass> macro foo list "pass 'today noon' +7"

Macro names must be composed entirely of alphanumerics and
underscores (characters that match \w, to be specific) and may not
begin with an underscore. As of version 0.008_03, macros may
redefine built-in commands. A macro is undefined inside itself, so
use of the name inside the macro invokes the built-in. The macro
becomes redefined again when it exits. The built_in can still be
accessed by prefixing the string 'core.' to its name, e.g.
'core.quarters', whether or not you have overridden the built_in
with a macro.

If you specify a macro name with no definition, it deletes the
current definition of that macro, if any. You can change this
behavior by setting the explicit_macro_delete parameter true; this
will cause 'macro name' to list the named macro, and require an
explicit -delete to delete it. Macros can also be redefined, simply
by issuing the 'macro' command, naming the macro, and giving its
definition.

The macro command takes the following options in addition to the
global ones:

-brief lists the names of macros. If names are given, they are
listed provided they are currently defined. If no names are given,
the names of all defined macros are given.

-delete deletes the named macros. If no macro names are given, all
macros are deleted. A macro may also be deleted by giving its name
but no definition, but as of 0.009_01, this mechanism is deprecated
in favor of use of the -delete option. The explicit_macro_delete
parameter may be used to require an explicit -delete to delete
macros.

-list lists the names and definitions of macros. If names are
given, they are listed if they are defined. If no names are given,
all defined macros are listed.

Macros may be nested - that is, a macro may be defined in terms of
other macros. A macro temporarily becomes undefined when it is
called to prevent endless recursion. It becomes defined again when
it exits.

Be aware that there is no syntax checking done when the macro is
defined. You only find out if your macro definition is good by
trying to execute it.

magnitude_table ...
This command displays or maintains the satellite magnitude table.
This table is used to initialize satellite magnitudes.

See the Astro::Coord::ECI::TLE documentation for information on how
this table is populated initially. If you have installed
Astro::SpaceTrack, you can update the status using one of the
commands that fetches magnitude data, such as 'st mccants vsnames',
or you can update it using the 'add', 'clear', and 'drop'
subcommands, which are discussed in more detail below.

"add" adds the given body to the magnitude table. The arguments are
OID and magnitude.

"clear" clears the magnitude table.

"drop" drops the given body from the magnitude table. The argument
is the OID to be dropped.

"molczan" reloads the magnitude table with the contents of the
named Molczan-format file. An optional second argument is a
magnitude offset to be added to the magnitudes read.

"quicksat" reloads the magnitude table with the contents of the
named Quicksat-format file. An optional second argument is a
magnitude offset to be added to the magnitudes read.

"show" displays the contents of the magnitude table, as a series of
'magnitude_table add' commands. If arguments are passed, only those
OIDs specified in the arguments are displayed.

pass start_time end_time increment
This command predicts visibility of the contents of the observing
list, in accordance with the various "PARAMETERS", between the
given start_time and end_time, using the given increment. See the
"SPECIFYING TIMES" topic below for how to specify times. The
increment is in seconds, and does nothing useful unless the verbose
setting is true.

The position of the visible body is given in either elevation,
azimuth, and range or right ascension, declination, and range as
seen from the location of the observer, as determined by the value
of the local_coord parameter. The geodetic latitude, longitude, and
altitude are also given.

The defaults are 'today noon', seven days after the start time, and
60 (seconds) respectively.

Example:

satpass> pass 'today noon' 'tomorrow noon'

In addition to the global options, the following options are legal
for the pass command:

"-brightest" is a synonym for "-magnitude".

"-choose" chooses bodies from the observing list. It works the same
way as the choose command, but does not alter the observing list.
You can specify multiple bodies by specifying -choose multiple
times, or by separating your choices with commas. If -choose is not
specified, the whole observing list is used.

"-magnitude" includes magnitude data in the output, and adds the
moment the satellite is brightest to the pass events.

"-quiet" suppresses any errors generated by running the orbital
model. These are typically from obsolete data, and/or decayed
satellites. Bodies that produce errors will not be included in the
output.

phase time
This command gives the phase of the relevant background bodies (see
sky) at the given time. At the moment, the only body that supports
this is the Moon.

The display shows the time, the phase angle in degrees (0 being
new, 90 being first quarter, and so on), and a description of the
phase ('new', 'waxing crescent', 'first quarter', 'waxing gibbous',
'full', 'waning gibbous', 'last quarter', or 'waning crescent').
The body is considered to be at quarter-phase if it is within 6.1
degrees (about 12 hours for the Moon) of 0, 90, 180, or 270
degrees. Otherwise you get waxing|waning crescent|gibbous.

The default time is the time the command was issued.

position start_time end_time interval
This command gives the positions of all objects in the observing
list and in the sky between the given start_time and end_time, at
the given interval. The default for both start_time and end_time is
the current time, and the default interval is 60 (seconds).

The position is given as seen by the observer, either as elevation,
azimuth, and range, or as right ascension, declination, and range,
depending on the setting of the local_coord parameter.

If the satellite is capable of producing flares, the status of each
potential flare is given also.

In addition to the global options, the following options are legal
for the position command:

"-magnitude" adds the object's magnitude to the output. To be
consistent with the 'pass' command you can use "-brightest" as a
synonym for this.

"-questionable" causes the code to consider spares (status 'S') to
be capable of flaring. You may use "-spare" as a synonym for this.

"-realtime" causes a running display in near-real-time. The default
end_time changes to '+10' (i.e. 10 days), and the default interval
to 10 (seconds). Also, the script sleeps between outputs, so the
output is more or less as it happens, at least to the nearest
second. You can break out of this by sending the script a SIGINT
signal (typically by typing control/C).

The default start_time is the current time.

The default end_time is the start time unless -realtime is
specified, in which case the default end_time is ten days after the
start time.

The default interval is 60 (seconds) unless -realtime is specified,
in which case the default interval is 10 (seconds).

quarters start_time end_time
This command gives the quarters of such current background bodies
(see sky) as support this function. This means quarter-phases for
the Moon, and equinoxes and solstices for the Sun. The Solar data
may be off by as much as 15 minutes, because we are only
calculating the position of the Sun to the nearest 0.01 degree.

See the "SPECIFYING TIMES" topic below for how to specify times.

The defaults are 'today noon' and 30 days after the start time.

retrieve filename
This command is one half of the interface to the Storable module.
It uses the retrieve() subroutine to read the observing list from
the given file.

set name value ...
This command sets operating parameters. See "PARAMETERS" below for
the list, and what they are used for.

You can specify more than one name-value pair on the same command.

show ...
This command shows the named operating parameters. See "PARAMETERS"
below for the list, and what they are used for. If no names are
given, it displays the complete list.

The display format is in terms of the 'set' commands used to set
the given values.

sky ...
This command manipulates the background objects (Sun, Moon, stars
...) that are used in the various calculations. If specified by
itself it lists the current background objects. Note that,
beginning with version 0.002, this list is formatted as 'sky add'
commands.

The 'sky' command also takes the following subcommands:

add - adds the named background object, provided it is not already
in the list. You must specify the name of the object (Sun, Moon, or
star name). 'Sun' and 'Moon' are not case-sensitive.

If you specify a star name, you must also specify its right
ascension and declination in J2000.0 coordinates. See "SPECIFYING
ANGLES" for more on specifying angles. You can also specify:

* Distance, followed by units 'm', 'km', 'au', 'ly', or 'pc', the
default being 'pc' (parsecs). For example, '4.2ly' represents 4.2
light-years. Beginning with version 0.002, the default distance is
10000 parsecs. This is probably too big, but we are not correcting
for stellar parallax anyway.

* Proper motion in right ascension, in seconds of arc per year, or
seconds of right ascension per year if 's' is appended. The default
is 0.

* Proper motion in declination, in seconds of arc per year. The
default is 0.

* Proper motion in recession, in kilometers per second. The default
is 0.

clear - clears the list of background objects.

drop name ... - removes the objects with the given names from the
background object list. The name matching is done using case-
insensitive regular expressions.

For example,

satpass> sky
Sun
Moon
satpass> sky drop moon
satpass> sky add Spica 13:25.193 -11d9.683m
satpass> sky
sky add Sun
sky add Spica 13:25:11.58 -11.161 10000.00 0.0000 0.00000 0
satpass>

lookup - Looks up the given object in the SIMBAD catalog, using the
simbad_url parameter to determine which copy of the catalog is
used, and the simbad_version parameter to determine which version
of SIMBAD is used. If the named object is found, it is added to the
list of background objects. Range defaults to 10000 parsecs, and
the proper motions to 0.

For example,

satpass> sky lookup 'Theta Orionis'
sky add 'Theta Orionis' 05:35.3 -05d24 10000.00 0 0 0

If simbad_version is set to 3, you need to have Astro::SIMBAD
installed. If it is 4, you need to have Astro::SIMBAD::Client
installed. The latter uses the SOAP interface, which appears to be
a work in progress, so I am not sure how stable it will be. Since
SIMBAD 3 is being phased out, The 'lookup' function should be
considered experimental.

source file_name
This command takes commands from the given file, reading it until
it is exhausted. This file may also contain source commands, with
the nesting limit determined by how many files your system allows
you to have open at one time.

To be consistent with the bash shell, you can use '.' as a synonym
for source. If you do, there need not be a space between the '.'
and the file name.

The file name must be quoted if it contains whitespace.

The one legal option is -optional, which means that no error is
reported if the file cannot be opened.

st ...
This command uses the Astro::SpaceTrack package to acquire orbital
data directly from the Space Track web site (assuming it is
available). It can also retrieve them from the CelesTrak web site
for as long as Dr. Kelso retains his authorization to redistribute
the orbital elements, or any other location supported by
Astro::SpaceTrack.

What comes after the 'st' is the name of an Astro::SpaceTrack
method, followed by any arguments to that method. If the method
returns orbital elements, those elements will be added to the
observing list. You can use 'st help' to get brief help, or see
Astro::SpaceTrack.

In addition to the legal Astro::SpaceTrack methods, 'show' has been
made a synonym to 'get', for consistency. Also, as of satpass
0.006_13, multiple attributes may be shown, 'show' or 'get' without
an argument shows all Astro::SpaceTrack arguments, and the output
is formatted as 'st set' commands.

You can also use the 'st localize' command to localize
Astro::SpaceTrack attribute values in exactly the same way that the
localize command localizes satpass parameters.

In addition to the usual options, the following options specific to
this command are supported:

-start and -end specify the start and end of the date range to be
retrieved. The date may be specified in any legal format. See
SPECIFYING TIMES for the details. If you specify relative times, be
aware that the -start value is parsed before the -end value,
regardless of their positions on the command line. Yes,
Astro::SpaceTrack already supports this, but by pre-parsing them we
get more flexibility on how to specify the date and time.

-verbose causes the content of the response to be displayed in
cases where it normally would not be (e.g. cases where the content
is "OK", or where it would normally simply be digested by this
application (e.g. orbital elements)).

You must install Astro::SpaceTrack version 0.017 or higher to use
this command.

Example of retrieving data on the International Space Station and
the Hubble Space Telescope from Space Track:

satpass> # Specify your Space Track access info
satpass> st set username your_username password your_password
satpass> # Ask for data with the common name
satpass> st set with_name 1
satpass> # Get the data by NORAD ID number
satpass> st retrieve 20580 25544

Example of retrieving the data from CelesTrak without using a Space
Track login:

satpass> # Specify direct retrieval.
satpass> st set direct 1
satpass> # Get the "top 100" or so.
satpass> st celestrak visual
satpass> # Only keep the ones we want.
satpass> choose 20580 25544

Example of retrieving predicted Space Shuttle elements from the
Human Space Flight web site. You need -all because the elements
change as the Shuttle maneuvers. Position (etc.) predictions will
be made using whatever element set is current at the time. If no
shuttle flight is impending (or in progress) you will get an error.

satpass> # Specify direct retrieval.
satpass> st set direct 1
satpass> # Get the data
satpass> st spaceflight shuttle -all

status ...
This command displays or maintains the satellite status list. This
list is used by the flare command to predict Iridium flares. If
given without a subcommand, it lists the known statuses.

Beginning with version 0.007, this list is formatted as "status
add" commands, and the syntax "status iridium" is deprecated.

Beginning with version 0.035_02, "status iridium" generates a
warning on the first use. Beginning with version 0.044 it will
generate a warning on every use, and six months after that release
it will become fatal.

See the Astro::Coord::ECI::TLE documentation for information on how
this list is populated initially. If you have installed
Astro::SpaceTrack, you can update the status using the 'st
iridium_status' command, or you can update it using the 'add',
'clear', and 'drop' subcommands, which are discussed in more detail
below.

The 'status' command also takes the following subcommands:

add - adds the given body to the status list. The arguments are
NORAD ID, satellite type ('iridium' is the only valid type at the
moment), status ('+' for in-service, 'S' for spare, '-' for
tumbling or otherwise unable to flare), name (e.g. 'Iridium 12'),
and a comment, with the status defaulting to '+', and name and
comment to ''. For example:

satpass> status add 12345 iridium S 'Bogus body' TRW

The 'add' command can also be used to change the status of an
existing body, with the new entry replacing the old.

drop - removes the given body from the status list. You will get a
message if the body does not exist. For example, to remove the
previously-added bogus body,

satpass> status drop 12345

show - is equivalent to a bare status command, and displays all
known statuses. However, you can also specify the bodies to display
as either NORAD IDs or names or a mixture of both. Names will be
taken as regular expressions. For example:

satpass> status show 36 97

to display the status of Iridium 36 and 97.

store filename
This command is one half of the interface to the Storable module.
It uses the nstore() subroutine to write the observing list to the
given file.

system command
This command passes its arguments to the system as a command. The
results are displayed unless redirected.

Technically, what happens is that if the current output is a tty,
the command is executed using the core system command; otherwise
its output is captured with backticks and printed.

If the command is omitted, the value of environment variable SHELL
is used as the command, with the intent of dropping you into the
given shell. If environment variable SHELL is not defined and you
are running under MSWin32, value 'cmd' is used as the command.

The -clipboard qualifier must come immediately after the verb
'system', and before the name of the command you are actually
issuing if any. This restriction is to prevent legal qualifiers
from being stripped from the command. For example:

satpass> system -c ls

Issues the 'ls' command, and captures the output on the clipboard.
That is to say the satpass script handles the -c. But

satpass> system ls -c

displays the status change time of the file, with output going to
standard out. That is to say the ls command handles the -c.

times time
This command displays the universal, dynamical, local standard,
local mean, and local time for the given input time.

The time defaults to the current time.

tle This command displays the original two- or three- line element data
which was used to build the observation list.

In addition to the global options, the following options are legal
for the tle command:

The "-verbose" qualifier causes the data to be displayed verbosely,
one item per line, labeled and with units if applicable.

validate start_time end_time
This command validates the observing list over the given time
range, dropping any TLEs that do not validate. See the "SPECIFYING
TIMES" topic below for how to specify times.

In addition to the global options, the following options are legal
for the validate command:

-quiet suppresses any errors generated by running the orbital
model. These are typically from obsolete data, and/or decayed
satellites.

The defaults are 'today noon' and seven days after the start time
respectively.

PARAMETERS
This script has a number of parameters to configure its operation. In
general:

Strings must be quoted if they contain blanks. Either kind of quotes
will work, but back ticks will not.

Angles may be specified in a number of formats. See "SPECIFYING ANGLES"
for more detail.

Boolean (i.e. true/false) parameters are set by convention to 1 for
true, or 0 for false. The evaluation rules are those of Perl itself: 0,
'', and the undefined value are false, and everything else is true.

The parameters are:

almanac_horizon (numeric or string)
This parameter specifies the horizon used for almanac calculations,
in degrees above or below the plane of the observer. The following
strings are also accepted:

* "height" causes the horizon to be adjusted for the height of the
observer above sea level. This adjustment assumes a spherical Earth
and an unobstructed horizon.

* "horizon" causes the value of the "horizon" setting to be used
for almanac calculations also.

The default is 0.

appulse (numeric)
This parameter specifies the maximum reportable angle between the
orbiting body and any of the background objects. If the body passes
closer than this, the closest point will appear as an event in the
pass. The intent is to capture transits or near approaches.

If this parameter is set to 0, no check for close approaches to
background objects will be made.

See "SPECIFYING ANGLES" for ways to specify an angle. This
parameter is displayed in decimal degrees.

The initial setting is 0.

autoheight (boolean)
This parameter determines whether the geocode command attempts to
acquire the height of the location above sea level. It does this
only if the parameter is true. You may wish to turn this off (i.e.
set it to 0) if the USGS elevation service is being balky.

The default is 1 (i.e. true).

backdate (boolean)
This parameter determines whether the 'pass' command will attempt
to use orbital elements before their epoch. It is actually simply
propagated to the 'backdate' attribute of the individual TLE
objects, and so takes effect on a per-object basis. If it is
false, the pass () method will silently move the start of the pass
prediction to the epoch of the data if the specified pass start is
earlier than the epoch.

You may wish to set this to 0 (i.e. false) if you are dealing with
future launches -- i.e. the predicted Space Shuttle data from
<http://spaceflight.nasa.gov/>.

The default is 1 (i.e. true), which is consistent with the behavior
of the code before this parameter was added.

background (boolean)
This parameter determines whether the location of the background
body is displayed when the appulse logic detects an appulse.

The default is 1 (i.e. true).

country (string)
This parameter determines the default country for the geocode
functionality. The intent is that it be an ISO 3166 two-character
country code, but at the moment only 'CA' (Canada) and 'US' (United
States of America) do anything useful.

See <http://www.iso.org/iso/en/prods-services/iso3166ma/index.html>
for the current list of country codes. Note that these are not
always the same as the corresponding top-level geographic domain
names (e.g. Great Britain is 'GB' in ISO 3166 but for historical
reasons has both 'gb' and 'uk' as top-level geographic domain
name).

The country codes are case-insensitive, since they will be
converted to lower case for use.

The default is 'us'.

date_format (string)
This parameter specifies the strftime(3) format used to display
dates. You will need to quote the format if it contains spaces.
Documentation on the strftime(3) subroutine may be found at
<http://www.openbsd.org/cgi-bin/man.cgi?query=strftime&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html>.

The above is a long URL, and may be split across multiple lines.
More than that, the formatter may have inserted a hyphen at the
break, which needs to be taken out to make the URL good. Caveat
user.

The default is '%a %d-%b-%Y', which produces (e.g.) 'Mon
01-Jan-2001' for the first day of the current millennium.

debug (numeric)
This parameter turns on debugging output. The only supported value
is 0, which is the default. The author makes no representation of
what will happen if a non-zero value is set, not does he promise
that the behavior for a given non-zero value will not change from
release to release.

The default is 0.

desired_equinox_dynamical (time)
This parameter specifies the desired equinox for equatorial and
ecliptic coordinates. It is specified as a dynamical time, or as 0,
'', or undef if you want whatever the various models give
(generally the current equinox, or something reasonably close to
this).

This parameter is used to precess equatorial coordinates to the
correct equinox for display. Any legal satpass time specification
will parse, but you probably want to specify an absolute time in
the UT zone, e.g. '1-Jan-2000 12:00 UT' for J2000.0. Yes,
technically UT is universal, but values specified for this setting
are handled as dynamical. See SPECIFYING TIMES for the full story
on how to specify times.

The only reason I can think of to set this is if you are displaying
equatorial coordinates for the 'flare', 'pass', or 'position'
commands, and want the coordinates for a given epoch.

The default is 0.

echo (boolean)
This parameter causes commands that did not come from the keyboard
to be echoed. Set it to a non-zero value to watch your scripts run,
or to debug your macros, since the echo takes place after parameter
substitution has occurred.

The default is 0.

edge_of_earths_shadow (numeric)
This parameter specifies the offset in elevation of the edge of the
Earth's shadow from the center of the illuminating body (typically
the Sun) as seen from a body in space. The offset is in units of
the apparent radius of the illuminating body, so that setting it to
1 specifies the edge of the umbra, <-1> specifies the edge of the
penumbra, and 0 specifies the middle of the penumbra. This
parameter corresponds to the same-named Astro::Coord::ECI
parameter.

The default is 1 (i.e. edge of umbra).

ellipsoid (string)
This parameter specifies the name of the reference ellipsoid to be
used to model the shape of the earth. Any reference ellipsoid
supported by Astro::Coord::ECI may be used. For details, see
Astro::Coord::ECI.

The default is 'WGS84'.

error_out (boolean)
This parameter specifies the behavior on encountering an error. If
true, all macros, source files, etc are aborted and control is
returned to the command prompt. If standard in is not a terminal,
we exit. If false, we ignore the error.

The default is 0 (i.e. false).

exact_event (boolean)
This parameter specifies whether visibility events (rise, set, max,
into or out of shadow, beginning or end of twilight) should be
computed to the nearest second. If false, such events are reported
to the step size specified when the 'pass' command was issued.

The default is 1 (i.e. true).

explicit_macro_delete (boolean)
This parameter specifies whether an explicit -delete qualifier is
needed to delete a macro. If false, 'macro foo' deletes macro foo.
If true, 'macro foo' lists macro foo.

The default is 0 (i.e. false). This will change, as deletion
without an explicit -delete is deprecated.

extinction (boolean)
This parameter specifies whether magnitude estimates take
atmospheric extinction into account. It should be set true if you
are interested in measured brightness, and false if you are
interested in estimating magnitudes versus nearby stars.

The default is 1 (i.e. true).

flare_mag_day (numeric)
This parameter specifies the limiting magnitude for the flare
calculation for flares that occur during the day. For this purpose,
it is considered to be day if the elevation of the Sun is above the
twilight parameter.

The default is -6.

flare_mag_night (numeric)
This parameter specifies the limiting magnitude for the flare
calculation for flares that occur during the night. For this
purpose, it is considered to be night if the elevation of the Sun
is below the twilight parameter.

The default is 0.

geometric (boolean)
This parameter specifies whether satellite rise and set should be
computed versus the geometric horizon or the effective horizon
specified by the 'horizon' parameter. If true, the computation is
versus the geometric horizon (elevation 0 degrees). If false, it is
versus whatever the 'horizon' parameter specifies.

The default is 1 (i.e. true).

gmt (boolean)
This parameter specifies whether output times are local (if false)
or GMT (if true).

The default is 0 (i.e. false).

height (numeric)
This parameter specifies the height of the observer above mean sea
level, in meters.

There is no default; you must specify a value.

horizon (numeric)
This parameter specifies the minimum elevation a body must attain
to be considered visible, in degrees. If the 'geometric' parameter
is 0, the rise and set of the satellite are computed versus this
setting also.

See "SPECIFYING ANGLES" for ways to specify an angle. This
parameter is displayed in decimal degrees.

The default is 20 degrees.

latitude (numeric)
This parameter specifies the latitude of the observer in degrees
north. If your observing location is south of the Equator, specify
a negative number.

See "SPECIFYING ANGLES" for ways to specify an angle. This
parameter is displayed in decimal degrees.

There is no default; you must specify a value.

local_coord (string)
This parameter determines what local coordinates of the object are
displayed by the pass and position commands. The only legal values
are:

az_rng - displays azimuth and range;

azel - displays elevation and azimuth;

azel_rng - displays elevation, azimuth, and range;

equatorial - displays right ascension and declination.

equatorial_rng - displays right ascension, declination, and range.

The default is 'azel_rng'.

Note that prior to version 0.005_04, the 'azel' and 'equatorial'
formats included range.

location (string)
This parameter contains a text description of the observer's
location. This is not used internally, but if it is not empty it
will be displayed wherever the observer's latitude, longitude, and
height are.

There is no default; the parameter is undefined unless you supply a
value.

longitude (numeric)
This parameter specifies the longitude of the observer in degrees
east. If your observing location is west of the Standard Meridian
(as it would be if you live in North or South America), specify a
negative number.

See "SPECIFYING ANGLES" for ways to specify an angle. This
parameter is displayed in decimal degrees.

There is no default; you must specify a value.

model (string)
This parameter specifies the model to be used to predict the
satellite. There are different models for 'near-Earth' and
'deep-space' objects. The models define a near-Earth object as one
whose orbit has a period less than 225 minutes. Objects with
periods of 225 minutes or more are considered to be deep-space
objects. A couple 'meta-models' have been provided, consisting of a
near-Earth model and the corresponding deep-space model, the
computation being done using whichever one is appropriate to the
object in question.

The models implemented are:

sgp - A simple model for near-earth objects.

sgp4 - A somewhat more sophisticated model for near-Earth objects.
This is currently the model normally used for near-Earth objects.

sdp4 - A deep-space model corresponding to sgp4, but including
resonance terms. This is currently the model normally used for
deep-space objects.

sgp4r - The model from "Revisiting Spacetrack Report #3", which
corrects and combines sgp4 and sdp4.

sgp8 - A proposed model for near-Earth objects.

sdp8 - A proposed deep-space model corresponding to sgp8.

null - A non-model, which causes no position computation to be
done. Useful for testing, maybe.

The 'meta-models' implemented are:

model - Use the normal model appropriate to the object. Currently
this means sgp4r, but this will change if the preferred model
changes (at least, if I become aware of the fact).

model4 - Use either sgp4 or sdp4 as appropriate. Right now this is
the same as 'model', but 'model4' will still run sgp4 and sdp4,
even if they are no longer the preferred models.

model4r - Synonym for sgp4r, implemented to keep the 'meta-models'
consistent.

model8 - Use either sgp8 or sdp8 as appropriate.

The default is 'model'.

perltime (boolean)
This parameter is a wart occasioned by the failure of Date::Manip
to understand summer time prior to version 6. It is ignored if you
are using Date::Manip 6.0 or greater, or if you are using the
internal ISO-8601 parser, since neither needs this mechanism.

If you are using a Date::Manip prior to 6.0, you should read on.
This includes anyone not using Perl 5.010 or later, since Perl
5.010 is required for Date::Manip 6.0 and above.

This parameter specifies the time zone mechanism for date input. If
false (i.e. 0 or an empty string), Date::Manip does the conversion.
If true (typically 1), Date::Manip is told that the time zone is
GMT, and the time zone conversion is done by "gmtime( timelocal(
$time ) )".

The problem this attempts to fix is that, in jurisdictions that do
summer time, Date::Manip gives the wrong time if the current time
is not summer time but the time converted is. That is to say, with
a time zone of EST5EDT, in January, 'jan 1 noon' converts to 5:00
PM GMT. But 'jul 1 noon' does also, but should convert to 4:00 PM
GMT.

If you turn this setting on, 'jul 1 noon' comes out 4:00 PM GMT
even if done in January. If you plan to parse times with zones
(e.g. 'jul 1 noon edt'), you should turn this setting off.

Note that at at some point this setting will be no-oped and its use
deprecated, though given the state of things this may well not
happen until this script itself starts requiring Perl 5.010.

The default is 0 (i.e. false).

prompt (string)
This parameter specifies the string used to prompt for commands.

The default is 'satpass>'.

refraction (boolean)
This parameter specifies whether atmospheric refraction should be
taken into account in the azel() calculation.

The default is 1 (i.e. true).

simbad_url (string)
This parameter does not, strictly speaking, specify a URL, but does
specify the server to use to perform SIMBAD lookups (see the
'lookup' subcommand of the sky command). Currently-legal values are
'simbad.u-strasbg.fr' (the original site) and 'simbad.harvard.edu'
(Harvard University's mirror).

As of satpass 0.013_09, the default is 'simbad.u-strasbg.fr', since
Harvard seems to be redirected to Strasbourg these days.

Please note that the command this parameter supports is
experimental, and see the warnings on that command. Changes in the
command may result in this parameter becoming deprecated and/or no-
oped.

Also note that the version of SIMBAD used to access the site is
controlled by the simbad_version parameter.

simbad_version (integer)
This parameter specifies the version of the SIMBAD application
being used, the valid values being 3 or 4. If you set it to 3, the
Astro::SIMBAD package will be used for SIMBAD lookups. If you set
it to 4, Astro::SIMBAD::Client will be used. As of early January
2007, 'simbad.u-strasbg.fr' supports both versions, though 3 is
being phased out. 'Simbad.harvard.edu' appears to me to be phasing
out, and redirected to simbad.u-strasbg.fr.

As of satpass 0.013_09, the default is 4.

singleton (boolean)
If this parameter is true, the script uses
Astro::Coord::ECI::TLE::Set objects to represent all bodies. If
false, the set object is used only if the observing list contains
more than one instance of a given NORAD ID. This is really only
useful for testing purposes.

Use of the Astro::Coord::ECI::TLE::Set object causes calculations
to take about 15% longer.

The default is 0 (i.e. false).

pass_threshold (angle or undef)
This parameter corresponds to the Astro::Coord::ECI::TLE
"pass_threshold" attribute. It is set in degrees. It can also be
set to the "undef" value by specifying the string 'undef'
(unquoted) as its value.

time_format (string)
This parameter specifies the strftime(3) format used to display
times. You will need to quote the format if it contains spaces.
The default is '%H:%M:%S', which produces (e.g.) '15:30:00' at 3:30
PM. If you would prefer AM and PM, use something like '%I:%M:%S
%p'. Documentation on the strftime(3) subroutine may be found at
<http://www.openbsd.org/cgi-bin/man.cgi?query=strftime&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html>.

The above is a long URL, and may be split across multiple lines.
More than that, the formatter may have inserted a hyphen at the
break, which needs to be taken out to make the URL good. Caveat
user.

twilight (string or numeric)
This parameter specifies the number of degrees the sun must be
below the horizon before it is considered dark. The words 'civil',
'nautical', or 'astronomical' are also acceptable, as is any unique
abbreviation of these words. They specify 6, 12, and 18 degrees
respectively.

See "SPECIFYING ANGLES" for ways to specify an angle. This
parameter is displayed in decimal degrees, unless 'civil',
'nautical', or 'astronomical' was specified.

The default is 'civil'.

tz (string)
This parameter specifies the time zone for Date::Manip. You
probably will not need it, unless running under MacOS (OS 9 is
meant, not OS X) or VMS. You will know you need to set it if
commands that take times as parameters complain mightily about not
knowing what time zone they are in. Otherwise, don't bother.

If you find you need to bother, see the TIMEZONES section of
Date::Manip for more information.

This parameter is not set at all by default, and will not appear in
the 'show' output until it has been set.

verbose (boolean)
This parameter specifies whether the 'pass' command should give the
position of the satellite every step that it is above the horizon.
If false, only rise, set, max, into or out of shadow, and the
beginning or end of twilight are displayed.

The default is 0 (i.e. false).

visible (boolean)
This parameter specifies whether the 'pass' command should report
only visible passes (if true) or all passes (if false). A pass is
considered to have occurred if the satellite, at some point in its
path, had an elevation above the horizon greater than the 'horizon'
parameter. A pass is considered visible if it is after the end of
evening twilight or before the beginning of morning twilight for
the observer (i.e. "it's dark"), but the satellite is illuminated
by the sun.

The default is 1 (i.e. true).

webcmd (string)
This parameter specifies the system command to spawn to display a
web page. If not the empty string, the help command uses it to
display the help for this package on <http://search.cpan.org/>. Mac
OS X users will find 'open' a useful setting, and Windows users
will find 'start' useful.

This functionality was added on speculation, since there is no good
way to test it in the initial release of the package.

The default is '' (i.e. the empty string), which leaves the
functionality disabled.

SPECIFYING ANGLES
This script accepts angle input in the following formats:

* Decimal degrees.

* Hours, minutes, and seconds, specified as hours:minutes:seconds. You
would typically only use this for right ascension. You may specify
fractional seconds, or fractional minutes for that matter.

* Degrees, minutes, and seconds, specified as degreesDminutesMsecondsS.
The letters may be specified in either case, and trailing letters may
be omitted. You may specify fractional seconds, or fractional minutes
for that matter.

Examples:

23.4 specifies 23.4 degrees.
1:22.3 specifies an hour and 22.3 minutes
12d33m5 specifies 12 degrees 33 minutes 5 seconds

Right ascension is always positive. Declination and latitude are
positive for north, negative for south. Longitude is positive for east,
negative for west.

SPECIFYING TIMES
This script (or, more properly, the modules it is based on) does not,
at this point, do anything fancy with times. It simply handles them as
Perl scalars, with the limitations that that implies.

Times may be specified absolutely, or relative to the previous absolute
time, or to the time the script was invoked if no absolute time has
been specified.

Both absolute and relative times may contain whitespace. If they do,
they need to be quoted. For example,

satpass> pass today +1

needs no quotes, but

satpass> pass 'today midnight' '+1 12'

needs quotes.

Absolute time
Any time string not beginning with '+' or '-' is assumed to be an
absolute time. If Date::Manip is available, the string is fed to that
for parsing. See the documentation for that module for all the
possibilities. Some of them are:

today 'today noon' 'next monday'
tomorrow 'yesterday 10:00' 'nov 10 2:00 pm'

Date::Manip has at least some support for locales, so check Date::Manip
before you assume you must enter dates in English.

If "Date::Manip" is not available, this script will do the best it can
with an internal parsing routine. This routine accepts ISO-8601 dates,
but not ordinal day specifications (e.g. 2009365 for December 31 2009)
or week specifications (e.g. 2009W0101 for January 4 2009 (if that is
in fact the correct interpretation of the spec)).

The internal routine is rather permissive about punctuation: any non-
digit character is accepted, and multiple whitespace characters are
accepted between date and time, and between time and zone. Years can be
two- or four-digit, with two-digit years representing years between
1970 and 2069, inclusive. Any other date or time field can be shortened
if it has trailing punctuation or is the last field specified before
the zone.

In addition, the internal routine accepts the strings 'yesterday',
'today', and 'tomorrow' in lieu of a date. If time is not specified,
these represent midnight.

So, using the internal parser the following are valid:

today 'today 12:00' '2009/2/1 6:00Z' (i.e. February 1)
tomorrow yesterday6:00

As a refresher, ISO-8601 dates are numeric and specified as year,
month, and day. If all fields are full-width (4 digits for years, 2 for
everything else) no punctuation at all is needed, other than in an
optional zone specification.

Relative time
A relative time is specified by '+' or '-' and an integer number of
days. The number of days must immediately follow the sign. Optionally,
a number of hours, minutes, and seconds may be specified by placing
whitespace after the day number, followed by hours:minutes:seconds. If
you choose not to specify seconds, omit the trailing colon as well. The
same applies if you choose not to specify minutes. For example:

+7 specifies 7 days after the last-specified time.

'+7 12' specifies 7 days and 12 hours after the last-specified time.

If a relative time is specified as the first time argument of a
command, it is relative to the most-recently-specified absolute time,
even if that absolute time was specified by default. Relative times in
subsequent arguments to the same command are relative to the
previously-specified time, whether absolute or relative. For example:

almanac '' +5

establishes the most-recently-specified time as 'today midnight', and
does an almanac for 5 days from that time. If the next command is

almanac +5 +3

this produces almanac output for three days, starting 5 days after
'today midnight'.

INVOCATION
Assuming this script is installed as an executable, you should be able
to run it just by specifying its name. Under VMS, the DCL$PATH logical
name must include the directory into which the script was installed.

The only command qualifiers are

-clipboard
which causes all output to go to the clipboard. Use of this
qualifier requires module Win32::Clipboard under MSWin32 (standard
with ActivePerl), the Mac::Pasteboard module or the 'pbcopy'
command under Darwin (the latter standard with Mac OS X), or the
xclip command (available from
<http://freshmeat.net/projects/xclip>) under any other operating
system. This script will warn and abort the command using this
option if the requisites are not available.

-filter
which suppresses extraneous output to make satpass behave more like
a Unix filter. The only thing suppressed at the moment is the
banner text.

-initialization_file filename
which specifies an initialization file to use in place of the
default.

-version
which causes the banner text to be displayed and the script to
exit. This option overrides -filter if both are specified.

These qualifiers can be abbreviated, as long as the abbreviation is
unique.

It is also possible to pass commands on the command line, or to pipe or
redirect them in. The execution order is

1. The initialization file;
2. Commands on the command line;
3. Commands from standard input.

For example, assuming the initialization file defines a macro named
'usual' to load the usual observing list, you could do:

$ satpass usual 'pass "today noon" +1' exit

to display passes for the next day. Obviously you may need to play
games with your shell's quoting rules. In the above example, MSWin32
and VMS users would be advised to interchange the single and double
quotes.

Should you wish to execute the above from a file, each command needs to
go on its own line, thus:

usual
pass "today noon" +1
exit

and the file is then invoked using either

$ satpass <commands

(assuming 'commands' is the name of the file), or, under the same
naming assumption,

$ satpass 'source commands'

or (under some flavor of Unix)

$ cat commands | satpass

or even

$ satpass `cat commands`

ENVIRONMENT VARIABLES
SATPASSINI can be used to specify an initialization file to use in lieu
of the default. This can still be overridden by the
-initialization_file command option. To see the current setting,

satpass> echo $SATPASSINI

which reports the name of the file actually used to initialize.

ACKNOWLEDGMENTS
Astro::Coord::ECI acknowledges those without whom this code would not
exist. But the script has its own issues, and I would like to
acknowledge here those who made this script better:

Imacat of Tavern IMACAT in Taiwan, for helping me to work out a satpass
script testing problem.

BUGS
Bugs can be reported to the author by mail, or through
<http://rt.cpan.org/>.

The VMS- and MSWin32-specific code to find the initialization file and
do tilde expansion is untested, since I do not currently have access to
those systems.

As of 0.003, clipboard functionality is provided by this code, not by
the Clipboard module, making clipboard bugs mine also.

AUTHOR
Thomas R. Wyant, III (wyant at cpan dot org)

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl 5.10.0. For more details, see the full
text of the licenses in the directory LICENSES.

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

TIGER/LineX is a registered trademark of the U.S. Census Bureau.

perl v5.20.2 2015-06-25 SATPASS(1)

DragonFly On-Line Manual Pages

NAME

SYNOPSIS

NOTICE

DETAILS

COMMANDS

PARAMETERS

SPECIFYING ANGLES

SPECIFYING TIMES

INVOCATION

ENVIRONMENT VARIABLES

ACKNOWLEDGMENTS

BUGS

AUTHOR

COPYRIGHT AND LICENSE