Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SATPASS(1)	      User Contributed Perl Documentation	    SATPASS(1)

NAME
       satpass - Predict satellite passes over an observer.

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

	$ satpass

	[various front matter displayed]

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

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

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

       The "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
       Open Street Maps, 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::OSM 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://metacpan.org/release/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) in Open Street Maps.	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 Open	Street Maps. 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::OSM module.

       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://metacpan.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:

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

       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:

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

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

	   "-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:

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

	   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.

       illum (string)
	   This	parameter specifies the	name of	the class to set as the
	   'illum' attribute for any bodies that require it. This is used for
	   calculating Iridium flares, and potentially other things. The value
	   must	be the name of a subclass of "Astro::Coord::ECI".

	   The default is "'Astro::Coord::ECI::Sun".

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

       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.

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

       sun (string)
	   This	parameter specifies the	name of	the class to set as the	'sun'
	   attribute for any bodies that require it. The value must be the
	   name	of a subclass of "Astro::Coord::ECI::Sun".

	   The default is "'Astro::Coord::ECI::Sun".

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

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

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

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

	   The default is 'civil'.

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

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

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

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

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

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

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

       webcmd (string)
	   This	parameter specifies the	system command to spawn	to display a
	   web page. If	not the	empty string, the help command uses it to
	   display the help for	this package on	<http://metacpan.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
       <https://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
       Copyright (C) 2005-2020 by Thomas R. Wyant, III

       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/LineA(R) is a registered trademark	of the U.S. Census Bureau.

perl v5.32.0			  2020-08-19			    SATPASS(1)

NAME | SYNOPSIS | NOTICE | DETAILS | COMMANDS | PARAMETERS | SPECIFYING ANGLES | SPECIFYING TIMES | INVOCATION | ENVIRONMENT VARIABLES | ACKNOWLEDGMENTS | BUGS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=satpass&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help