/ 
Astro-satpass-0.003
River stage one • 7 direct dependents • 8 total dependents
/ satpass

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> # We're done
satpass> exit

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 SOAP::Lite 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 SOAP::Lite, and maybe XML::Parser, to get this functionality.

* The ability to look up star positions in the SIMBAD catalog. You will need to install Astro::SIMBAD to get this functionality.

* 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.

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. See the "SYNOPSIS" for an example.

In addition, any command can place text on the clipboard if the -clipboard qualifier is specified. This qualifier will be ignored if -clipboard is already in effect. This functionality requires the availability of the Win32::Clipboard module under MSWin32, or the Clipboard module under any other operating system. If the required module is not available, the command containing it will be ignored with a warning. The -clipboard qualifier can be abbreviated. Currently, the minimum abbreviation is "-c", but this may change if other conflicting qualifiers are added.

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 rudamentary 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.

The start_time defaults to 'today midnight', and the end_time to '+1'.

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.

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 managable 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
clear

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

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.

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.

geocode 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 '1600 pennsylvania ave washington dc'

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

If you wish to use this command, you must install the SOAP::Lite module.

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

height 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 SOAP::Lite 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.

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
moon - Astro::Coord::ECI::Moon
sun -- Astro::Coord::ECI::Sun
st --- Astro::SpaceTrack
star - Astro::Coord::ECI::Star
tle -- Astro::Coord::ECI::TLE

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.

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.

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. They also may not conflict with a builtin command.

If you specify a macro name with no definition, it deletes the current definition of that macro, if any. Macros can also be redefined.

If you specify the macro command without a macro name, it lists all the currently-defined macros and their definitions. The quoting in the listing may not be identical to the quoting originally specified, but will be functionally equivalent, and specifically will look like the first example above.

Macros may be nested - that is, a macro may be defined in terms of other macros. There is no protection against the endless recursion that results if a macro invokes itself either directly or indirectly.

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.

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.

The defaults are 'today noon', '+7' (meaning 7 days after the most-recently-specified explicit time), and 60 (seconds) respectively.

Example:

satpass> pass 'today noon' 'tomorrow noon'
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 default time is the time the command was issued.

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.

position time

This position gives the positions of all objects in the observing list and in the sky at the given time, the default being the current time.

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' (meaning 30 days after the most-recently-specified explicit time).

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

The 'lookup' function should be considered experimental. SIMBAD 4 was scheduled to be out January 2006, and (according to its announcement at http://simbad.u-strasbg.fr/simbad4.htx) will probably break this function. If this function gets broken, it may be upgraded, replaced with a more expeditious data source, or retracted completely; the author makes no promises of which, or of timing. Caveat user.

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.

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.

What comes after the 'st' is a legal command to the Astro::SpaceTrack package. If a command 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 usual qualifiers, you can specify -verbose to cause 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.011 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

Exampe 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
status

This command displays the operational status of satellites, fetching it if necessary. You can specify one or more satellite types if desired, but there is not much point since the only legal type at the moment is 'iridium'.

Normally, this command will not reload status if it is already available, since it does not change that often. But you can force a reload using the -reload qualifier.

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.

tle

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

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:

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 the Sun or Moon 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).

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).

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 behaviour for a given non-zero value will not change from release to release.

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.

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'.

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).

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).

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.

lit (boolean)

This parameter specifies how to determine if a body is lit by the sun. If true (i.e. 1) it is considered to be lit if the upper limb of the sun is above the horizon, as seen from the body. If false (i.e. 0), the body is considered lit if the center of the sun is above the horizon.

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

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.

sgp8 - A proposed model for near-Earth objects.

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

The 'meta-models' implemented are:

model - Use the normal model appropriate to the object. Currently this means sgp4 for near-Earth objects and sdp4 for deep-space objects, 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.

model8 - Use either sgp8 or sdp8 as appropriate.

The default is 'model'.

perltime (boolean)

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 appears (to me, at least) to give 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, and it seems to me that this should give 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.

I confess to considering this a wart. If I figure out how to get behaviour I consider more straightforward out of Date::Manip, I will no-op this attribute and deprecate its use.

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

prompt (string)

This parameter specifies the string used to prompt for commands.

The default is 'satpass>'.

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).

The default is 'simbad.harvard.edu'.

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.

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.

timing (boolean)

This parameter specifies whether timing information should be displayed on pass computations. A true setting (i.e. 1) displays this information, a false (i.e. 0) value does not.

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

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, and is fed to Date::Manip 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.

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 absolute time.

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

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, or Clipboard under any other operating system. This script will die if the requisite module is not available.

-filter

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

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`

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)

COPYRIGHT

Copyright 2005, 2006 by Thomas R. Wyant, III (wyant at cpan dot org). All rights reserved.

This script is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself. Please see http://perldoc.perl.org/index-licence.html for the current licenses.

This software is provided without any warranty of any kind, express or implied. The author will not be liable for any damages of any sort relating in any way to this software.

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