NAME
passes - Compute satellite rise and set times
SYNOPSIS
passes -user yehudi -pass menuhin -lat 42 -lon -90 25544=ISS
passes -file driver.txt
passes -help
passes -version
DESCRIPTION
This Perl script downloads TLE data for specified satellites from the Space Track web site, and uses these data to predict passes of the satellites over the observer during the desired period of time. Output is normally chronological by culmination time. If -split
is specified, output is chronological by individual event time. Location- and user-specific options such as observing location and Space Track account information can be specified in a configuration file.
The configuration of this script consists of "OPTIONS" (documented below) and the OID numbers to be displayed. You can override Space Track's common name for the object by suffixing =your_desired_name
to the OID. An example of this occurs in the "SYNOPSIS".
By default, output is one line per pass. You can get an event per line by specifying the -split
option.
By default, the reporting period is the seven days beginning at midnight on the current day. You can change this using the -start
and -finish
options.
Output is controlled by a templating system. In general the output line consists of satellite-specific data followed by event-specific data. The satellite-specific data are specified by the -body-template
option. The event-specific data are specified by the -event-template
option. Time formats (for strftime(3)
) are set using the -time-format
option. The string used to separate multiple events on the same line is specified by the -join
option.
OPTIONS
Several options are available. Option names may be abbreviated down to the shortest unique abbreviation, but the shortest abbreviation may change if new options are added.
Not all the options are in fact optional. Some of them specify information this script needs to run. You must provide values for options -username
and -password
to obtain satellite information, and -latitude
and -longitude
to provide the location of the observer. You may wish to provide the -height
for the observer as well. You need not specify these if you specify -help
or -version
, since both cause the script to exit after they are encountered.
Other options may be of particular interest. To change the reporting period, use -start
and -finish
. To report only passes which can actually be seen from the ground, use -visible
. To report rises and sets separately, use -split
.
- -body-template template_string
-
This option specifies the template used to insert information about the satellite into the output. The templating system is described under the
-event-template
option, below.The %a (azimuth) and %e (elevation) specifications do nothing useful in a
-body-template
.The default is '%N%t' (i.e. the name of the satellite, followed by a horizontal tab).
- -event-template output_template
-
This option specifies the template used to insert information about an individual pass event into the output.
All characters in the template are output verbatim, except for the '%', which is magic. Data from the event are substituted into the output according to the character that follows the '%', as follows:
a - azimuth of event in degrees from north; e - elevation of event in degrees above geometric horizon; i - international launch designator of satellite; l - illumination (lit or not, PASS_EVENT_* numeric code, undefined in -body-template); L - illumination (string, if available, undefined in -body-template); n - a literal newline; N - name of satellite; o - OID (SATCAT ID) of satellite; t - a literal horizontal tab; T - event time (or culmination time in -body-template); u - number of satellites up after event (undefined if -split is not asserted); v - event (Astro::Coord::ECI::TLE PASS_EVENT_* numeric code); V - event (string, if available from Astro::Coord::ECI::TLE); % - a literal '%'.
The behavior when any other character follows the '%' is undefined. The word 'undefined' does not mean that you get a literal
undef
under those circumstances. It means that the behavior (whatever it is) may not be what you expect or want, and that it may change without notice.All times are formatted according to the value of the
-time-format
option.The default template is '%V %L %T' (that is, the name of the event, whether the satellite is lit or shadowed, and the time of the event).
- -finish iso_time_or_days
-
This option specifies the finish time. It is either an ISO-8601-ish string such as is legal for
-start
, or a plus sign followed by an integer, which is the number of days after the-start
time.The default is '+7'.
- -geometric
-
This option specifies that rise and set take place when the satellite crosses the geometric horizon, regardless of the setting of the
-horizon
option. If not asserted, rise and set take place when the satellite crosses the elevation specified by the-horizon
option.This option can be negated by specifying
-nogeometric
.The default is
-nogeometric
- -gmt
-
This option specifies that times be either GMT (if asserted) or local (if negated). It can be negated by specifying
-nogmt
.The default is
-nogmt
. - -height meters_above_geoid
-
This option specifies the observer's height in meters above the WGS84 geoid.
The default is 0.
- -horizon degrees_of_elevation
-
This option specifies the effective horizon in degrees above (or below, if negative) the geometric horizon.
The default is 0.
- -join joining_string
-
This option specifies the string to be inserted between events in the output. This string is run through the templating system before use, but the only supported characters after a percent sign are 't' to insert a horizontal tab, 'n' to insert a newline, and '%' to insert a literal percent sign. The results of using any other character after a percent sign are undefined.
The default is '%n%t' (that is, a newline followed by a horizontal tab).
- -latitude degrees_north_of_equator
-
This option specifies the observer's latitude in degrees. South latitudes are negative.
This option must be specified. There is no default.
- -longitude degrees_east_of_prime_meridian
-
This option specifies the observer's longitude in degrees east of Greenwich England. West longitudes are negative.
This option must be specified. There is no default.
- -password spacetrack_password
-
This option specifies the Space Track password.
This option must be specified. There is no default.
- -split
-
This option reports individual events of a pass separately. This may be more useful for telling how many satellites are above the horizon at a given time. If negated (which is the default, and which can be specified explicitly by
-nosplit
) you get all events for the pass on the same line.The default is
-noevent
. - -start iso_time
-
This option specifies the start time as an ISO-8601-ish time. Only the year-month-day-hour-minute-second version of the specification is implemented. Years must be 4 digits, and all other fields must be two digits. Trailing fields can be omitted, and default to 00 or 01 as appropriate. Non-numeric characters may appear between fields, and after the final field. So, for example,
-start 2010-04-01:00:00:00
specifies a start at midnight of April 1 2010. In fact, so does
-start 201004
As a convenience, the date portion can be replaced by one of the strings
yesterday
,today
, ortomorrow
. So data starting today at noon can be specified as-start today12
The default is 'today', meaning midnight, since all the time fields default to 0.
- -split
-
If asserted, this option causes each event of the pass to be reported on a separate line of output.
The default is
-nosplit
. - -time-format strftime_format
-
This option sets the strftime(3) format used to format the time in the output.
The default is '%d-%b-%Y %H:%M:%S' (that is, day, month name, four-digit year, hour, minute, second).
- -twilight degrees_below_horizon
-
This options sets the number of degrees the Sun is below the horizon at the beginning or end of twilight. Unlike the
satpass
script, you must specify a number.The default is 6, which corresponds to civil twilight.
- -username spacetrack_username
-
This option specifies the Space Track user name.
This option must be specified. There is no default.
- -visible
-
If asserted, this option causes only visible passes to be reported. A pass is considered visible if the satellite is sunlit and the observer is in darkness during some portion of the pass. The rise or set may actually not be visible.
This option can be negated by specifying
-novisible
.The default is
-novisible
. - -want-events event_types
-
This option specifies what pass events are wanted in the output. The value is a string composed of one or more individual event type codes, as follows:
r = rise and set; m = maximum elevation (culmination); l = illumination (passing into sunlight or shadow); t = beginning or end of twilight
The default is 't'.
FILES
Configuration for this script can be done by a file as well as on the command line. Configuration information is taken in the following order:
- 1) The default configuration file, if any.
- 2) The file specified by the
-file
command option, if any. - 3) The command line.
In the case of command options, the last-specified value of a given option is the one used. Boolean options (e.g. -gmt
) can be negated by prefixing 'no' (e.g. -nogmt
).
The lists of OIDs from the above sources are simply concatenated.
Blank lines and lines beginning with '#' are ignored in configuration files, as are leading and trailing whitespace on a line. Each non-blank non-comment line in a configuration file goes to make up a single token in a command line that is built internally and parsed.
This means that each option must be specified on a line by itself, as must each OID. If an option takes a value, that value must either be joined to the option name by an equals sign, or appear on the next line.
An example configuration file might look like this:
# Observing location:
# Elysee Palace, Rue Faubourg Saint-Honore, Paris
-latitude=48.870727
-longitude=2.316925
-height=32
#
# Space Track login
-username=nicolas
-password=sarkozy
The name and location of the default configuration file depend on the host operating system.
For Darwin (Mac OS X) the default configuration file is $HOME/Library/Application Support/passes.ini.
For MSWin32 the default configuration file is %APPDATA%/passes.ini.
For VMS the default configuration file is SYS$LOGIN:passes.ini.
For any other operating system, the default configuration file is $HOME/.risesetrc.
BUGS
Bugs can be reported to the author by mail, or through http://rt.cpan.org/.
AUTHOR
Thomas R. Wyant, III (wyant at cpan dot org)
COPYRIGHT AND LICENSE
Copyright (C) 2010-2018 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.