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/Line® 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.

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)

COPYRIGHT AND LICENSE

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/Line® is a registered trademark of the U.S. Census Bureau.

To install Astro::Coord::ECI, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Astro::Coord::ECI

CPAN shell

perl -MCPAN -e shell
install Astro::Coord::ECI

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

NOTICE

DETAILS

COMMANDS

PARAMETERS

SPECIFYING ANGLES

SPECIFYING TIMES

Absolute time

Relative time

INVOCATION

ENVIRONMENT VARIABLES

ACKNOWLEDGMENTS

BUGS

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions