passes - Compute satellite rise and set times
passes -user yehudi -pass menuhin -lat 42 -lon -90 25544=ISS passes -file driver.txt passes -help passes -version
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.
-split
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".
=your_desired_name
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.
-start
-finish
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.
-body-template
-event-template
strftime(3)
-time-format
-join
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.
-username
-password
-latitude
-longitude
-height
-help
-version
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.
-visible
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).
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.
undef
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).
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'.
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.
-horizon
This option can be negated by specifying -nogeometric.
-nogeometric
The default is -nogeometric
This option specifies that times be either GMT (if asserted) or local (if negated). It can be negated by specifying -nogmt.
-nogmt
The default is -nogmt.
This option specifies the observer's height in meters above the WGS84 geoid.
The default is 0.
This option specifies the effective horizon in degrees above (or below, if negative) the geometric horizon.
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).
This option specifies the observer's latitude in degrees. South latitudes are negative.
This option must be specified. There is no default.
This option specifies the observer's longitude in degrees east of Greenwich England. West longitudes are negative.
This option specifies the Space Track password.
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.
-nosplit
The default is -noevent.
-noevent
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, or tomorrow. So data starting today at noon can be specified as
yesterday
today
tomorrow
-start today12
The default is 'today', meaning midnight, since all the time fields default to 0.
If asserted, this option causes each event of the pass to be reported on a separate line of output.
The default is -nosplit.
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).
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.
satpass
The default is 6, which corresponds to civil twilight.
This option specifies the Space Track user name.
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.
-novisible
The default is -novisible.
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; b = brightest.
The default is 'rmltb'.
'rmltb'
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:
-file
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).
-gmt
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 the first found of $HOME/Library/Application Support/passes.ini or $HOME/.risesetrc.
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.
Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-satpass, https://github.com/trwyant/perl-Astro-Coord-ECI/issues, or in electronic mail to the author.
Thomas R. Wyant, III (wyant at cpan dot org)
Copyright (C) 2010-2021 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.
To install Astro::Coord::ECI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Astro::Coord::ECI
CPAN shell
perl -MCPAN -e shell install Astro::Coord::ECI
For more information on module installation, please visit the detailed CPAN module installation guide.