SATPASS(1)

💫 SATPASS(1) — satpass 💫

User Contributed Perl Documentation, bestie — this is the satpass manual page and it is so much. Buckle up. 🎀

🌸 NAME 🌸

satpass — predict satellite passes over an observer. Periodt. 🛰️✨

🛰️ SYNOPSIS 🛰️

Okay so the whole 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. It’s giving command-line main character energy. 💅

$ 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 <https://www.space-track.org/>, <https://spaceflight.nasa.gov/>, or <http://celestrak.org/> (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.sourceforge.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 lowkey the same vibe as the example before it, except it defaults to 'tomorrow midnight' — meanwhile the 'almanac' command over there defaults to 'today midnight'. ✨

And here's a slightly less trivial example, because we love a glow-up:

macro ephemeris 'almanac "${1:=tomorrow midnight}"' 'quarters "$1"'

which makes the quarters command see 'tomorrow midnight' if no arguments were given when the macro gets expanded. Slay. 💅

The following commands are available: 💖

almanac 🌅

satpass> almanac start_time end_time

This one displays almanac data for the current background bodies (peep sky for what that means). You get at minimum rise, meridian transit, and set. For the Sun you also get beginning and end of twilight, plus local midnight. You also get equinoxes and solstices — but those are only good to within about 15 minutes, so don't come for them, okay? 😭 For the Moon you get quarter-phases. All of it is based on the current parameter settings (see "PARAMETERS" below).

The output comes at you in chronological order. ⏳

This command supports these options:

• -horizon — says report rise and set times. -rise and -set are both synonyms for this; -rise also reports when the bodies set, and vice versa (iconic mutual support, honestly 🫶).
• -quarter — says report quarters.
• -transit — says report transits. This includes transits below the observer (e.g. local midnight), if those get generated.
• -twilight — says report the beginning and end of twilight.

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 📁

satpass> cd directory

This command changes to the named directory, or to the user's home if you give it no directory and the user's home directory can be determined. This change affects this script and any processes it invokes — but not the invoking process. In plainer English: it does not affect the directory you find yourself in after exiting satpass. So no, it won't move your shell, bestie. 🙈

check_version 🔍

satpass> check_version

This one downloads <https://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 give you a mechanism for checking the currency of this script in the event it becomes a separate distribution from Astro::Coord::ECI. Basically a "am I up to date" vibe check for the script itself. ✨

choose 🎯

satpass> choose name_or_id ...

This command retains only the objects named on the command in the observing list, eliminating all others. It's meant for shrinking a downloaded catalog down to a manageable size. You can give names, NORAD ID numbers, or a mixture. Numeric items get matched against the NORAD IDs of the items in the observing list; non-numeric items get turned 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 even need this option — unless you're trying to assemble and save a set of elements relevant to a given time in the past. 🦋

clear 🧹

satpass> clear

This command clears the observing list. And no, it is not an error to issue it when the list is already clear. Zero drama. 💅

drop 🗑️

satpass> drop name_or_id ...

This command removes the objects named in the command from the observing list, retaining all others. You can give names, NORAD ID numbers, or a mixture. Numeric items get matched against the NORAD IDs of the items in the observing list; non-numeric items get turned into case-insensitive regular expressions and matched against the names of the items, if any. Bye babes 👋

echo 📢

satpass> echo ...

This command just prints its arguments to standard output. Environment variable substitution and pseudo-redirection is done. Heads up though: 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. Honestly? Relatable. 😭

exit 🚪

satpass> exit

This command causes this script to terminate immediately. If it's issued from a 'source' file, this is done without giving control back to the user. So like, gone-gone. 💀

'bye' and 'quit' are synonyms. End-of-file at the command prompt will also cause this script to terminate. 👑✨

export 🌍

satpass> 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. Temporary slay only. 🫶

If the name is the name of a parameter, the value is optional — but if supplied, it will be used to set the parameter. The environment variable is set from the value of the parameter, and it will track changes in it. Cute, right? 🎀

flare 💥

satpass> flare start_time end_time

This command predicts flares for any bodies in the observing list capable of generating them. Currently, that 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, meaning 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, meaning those between morning twilight and evening twilight.
• -pm — ignores evening flares, meaning 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 observer's location has already been set, you can predict flares for the next two days like this:

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 📍

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

Here's the tea: this command actually works by dispatching to one of the following geocode_* commands, which may also be invoked explicitly. In fact, it's the existence of such a command that makes a given country code work at all. Wild, I know. 🤯

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. On top of that, 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 so 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). Tragedy, honestly. 😭

In addition to the global options, these 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 here, and will be passed through to it. 🫶

The above options are also available on all of the 'geocode_*' commands.

geocode_as 🏝️

satpass> geocode_as location

American Samoa is handled by geocode_us. That's it, that's the whole vibe. 🦋

geocode_ca 🍁

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

Lowkey legal note carrying over: because of restrictions on the use of the Geocoder.ca site, you may not use this command for commercial purposes.

🦋 geocode_fm

satpass> geocode_fm location

The Federated States of Micronesia are handled by geocode_us. Simple as that, bestie.

🌸 geocode_gu

satpass> geocode_gu location

Guam is handled by geocode_us.

💜 geocode_mh

satpass> geocode_mh location

The Marshall Islands are handled by geocode_us.

✨ geocode_mp

satpass> geocode_mp location

The Northern Mariana Islands are handled by geocode_us.

🎀 geocode_pr

satpass> geocode_pr location

Puerto Rico is handled by geocode_us.

🫶 geocode_pw

satpass> geocode_pw location

Palau is handled by geocode_us.

🔥 geocode_us

satpass> geocode_us location

Okay so this command attempts to look up the given location — either a street address or a 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

satpass> geocode_vi location

The U.S. Virgin Islands are handled by geocode_us.

👑 height

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

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

satpass> height_as latitude longitude

American Samoa is handled by height_us.

💖 height_ca

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

satpass> height_fm latitude longitude

The Federated States of Micronesia are handled by height_us.

🌟 height_gu

satpass> height_gu latitude longitude

Guam is handled by height_us.

💫 height_mh

satpass> height_mh latitude longitude

The Marshall Islands are handled by height_us.

🎀 height_mp

satpass> height_mp latitude longitude

The Northern Mariana Islands are handled by height_us.

🌺 height_pr

satpass> height_pr latitude longitude

Puerto Rico is handled by height_us.

🪄 height_pw

satpass> height_pw latitude longitude

Palau is handled by height_us.

💎 height_us

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

satpass> height_vi latitude longitude

The U.S. Virgin Islands are handled by height_us.

🧸 help

satpass> 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 https://metacpan.org/ page for this package, and any arguments will be ignored.

🦋 list

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

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

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

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

Just so you know bestie — there's literally no syntax checking done when the macro is defined 😭. Like, zero. You only find out if your macro definition is actually good by trying to execute it. Vibes-based debugging, we love to see it 💀.

🌸 magnitude_table

satpass> magnitude_table ...

This one displays or maintains the satellite magnitude table ✨ — the table used to initialize satellite magnitudes.

See the Astro::Coord::ECI::TLE documentation for the whole story on how this table gets populated initially 🫶. And if you have Astro::SpaceTrack installed, you can update the status using one of the commands that fetches magnitude data, like st mccants vsnames, or you can update it with the add, clear, and drop subcommands, which we're getting into right now 👇

• add — adds the given body to the magnitude table. The arguments are OID and magnitude.
• clear — clears the magnitude table. Poof. Gone. 🧚
• 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

satpass> 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 (ngl, it's just decorative otherwise 💅).

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

satpass> 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. Iconic but limited, iykyk.

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

satpass> 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 Ctrl+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

satpass> 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 😭 — so like, don't plan your whole equinox party around it.

See the SPECIFYING TIMES topic below for how to specify times.

The defaults are 'today noon' and 30 days after the start time.

🍓 retrieve

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

satpass> 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 👑 (efficiency, we stan).

💀 show

satpass> 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 — so it's literally giving "here's how you'd set this again" energy 💅.

🌈 sky

satpass> 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. Bye bestie 🧚

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

satpass> source file_name

This command takes commands from the given file and just keeps reading until it's exhausted, periodt. That file can also contain more source commands — the nesting limit is literally determined by how many files your system lets you have open at once. 💅

To be consistent with the bash shell, you can use . as a synonym for source. And if you do, there need not be a space between the . and the file name. Slay.

The file name must be quoted if it contains whitespace. No cap.

The one legal option is -optional, which means that no error is reported if the file cannot be opened. Chill vibes only.

st 🛰️

satpass> 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. King behavior honestly. 👑

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

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. Obsessed with the consistency era. ✨

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. Matching energy fr fr.

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. Non-negotiable bestie. 🚨

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 📋

satpass> 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. So like... start migrating bestie 💀

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. Iconic upgrade path. 🎀

• 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 💾

satpass> 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. Saving your faves, love that for you. 🫶

system 💻

satpass> 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. Nerdy details but we respect them. 🤓

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. Order matters bestie, don't test it. ⚠️

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. Same letters, totally different main character. 💅

times 🕰️

satpass> times time

This command displays the universal, dynamical, local standard, local mean, and local time for the given input time. All the times, in one place, we love a buffet. ✨

The time defaults to the current time.

tle 📡

satpass> 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. Very demure, very mindful. 🎀

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. RIP to the fallen 🪦

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

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. Very "if it's not zero it's a vibe" of Perl. 😌

The parameters are:

almanac_horizon 🌅

This numeric or string 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 🧚

This numeric 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. So like, close-encounter detection mode, iykyk. 🔭

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.

okay bestie, we are so back in the parameter list, and this is where satpass gets its whole personality adjusted one setting at a time 💅 every default is coming with us, no skips.

• autoheight — this Boolean parameter decides whether the geocode command even tries to grab the height of the location above sea level. It only does that when the parameter is true. You may want to turn this off (like, set it to 0) if the USGS elevation service is being balky. The default is 1 (i.e. true). ✨
• backdate — this Boolean parameter decides whether the pass command will attempt to use orbital elements before their epoch. It is actually just propagated to the backdate attribute of the individual TLE objects, so it 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 https://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 — this Boolean parameter decides whether the location of the background body is displayed when the appulse logic detects an appulse. The default is 1 (i.e. true). 🌌
• country — this string 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 https://www.iso.org/iso-3166-country-codes.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 — this string 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://man.openbsd.org/i386/strftime. Heads up: that URL is long 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 — this numeric 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, nor 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 — this time 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 — this Boolean 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 — this numeric 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 — this string 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 — this Boolean 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 — this Boolean 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 — this Boolean 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 — this Boolean 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 — this numeric 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 — this numeric 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 — this Boolean 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 — this Boolean parameter specifies whether output times are local (if false) or GMT (if true). The default is 0 (i.e. false). 🕰️
• height — this numeric parameter specifies the height of the observer above mean sea level, in meters. There is no default; you must specify a value. 📏
• horizon — this numeric 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 — this string 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 — this numeric 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 — this string 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 — this string 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 — this numeric 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 — this string 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:

okay so before we get into the rest of the parameters, real quick — here's the whole ✨ model menu ✨, since a bunch of these are values you can feed to model:

• sgp — the simple, no-frills model for near-Earth objects. Baby's first orbit math. 🍼
• sgp4 — a lil more sophisticated than sgp for near-Earth objects. This is currently the model normally used for near-Earth objects, so like… the default-est default that ever defaulted.
• sdp4 — the deep-space glow-up of sgp4, except it includes resonance terms. This is currently the model normally used for deep-space objects. Obsessed with a model that knows about resonance, ngl.
• sgp4r — the model straight out of "Revisiting Spacetrack Report #3", and it corrects and combines sgp4 and sdp4. It's giving "we fixed it and merged it, you're welcome". 💅
• sgp8 — a proposed model for near-Earth objects. Proposed! Fancy word for "we're workshopping it".
• sdp8 — a proposed deep-space model corresponding to sgp8. Same energy, deep-space edition.
• null — the non-model 💀 it causes no position computation to be done at all. Useful for testing, maybe. "Maybe" is doing a lot of heavy lifting there and I respect it.

and then the meta-models, which are like the managers of models:

• model — uses the normal model appropriate to the object. Currently that means sgp4r, but it'll change if the preferred model changes (at least, if the author becomes aware of the fact 😭). Honesty, king.
• model4 — uses either sgp4 or sdp4 as appropriate. Right now it's the same as model, BUT model4 will still run sgp4 and sdp4 even if they stop being the preferred models. Loyalty. 🫶
• model4r — a synonym for sgp4r, implemented just to keep the meta-models consistent. Consistency slay.
• model8 — uses either sgp8 or sdp8 as appropriate.

The default is 'model'.

---

• pass_threshold — this angle-or-undef parameter corresponds to the Astro::Coord::ECI::TLE "pass_threshold" attribute. It's set in degrees, bestie. You can also set it to the "undef" value by specifying the string 'undef' (unquoted) as its value.
• perltime — okay so this Boolean parameter is, and I quote, "a wart" 🙈 caused by Date::Manip failing to understand summer time before version 6. It gets ignored if you're on Date::Manip 6.0 or greater, or if you're using the internal ISO-8601 parser, since neither of those needs this mechanism.

If you're on a Date::Manip older than 6.0, keep reading, babe. That includes literally 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 the time zone is GMT, and the time zone conversion is done by "gmtime( timelocal( $time ) )".

The problem it's trying to fix: in jurisdictions that do summer time, Date::Manip gives the wrong time if the current time is not summer time but the time being converted is. Like — with a time zone of EST5EDT, in January, 'jan 1 noon' converts to 5:00 PM GMT. But 'jul 1 noon' does too, and it should convert to 4:00 PM GMT. 😭 The math is not mathing.

So if you turn this setting on, 'jul 1 noon' comes out 4:00 PM GMT even if you do it in January. But if you plan to parse times with zones (e.g. 'jul 1 noon edt'), you should turn this setting off.

heads up: at some point this setting will be no-oped and its use deprecated, though given the state of things it may well not happen until this script itself starts requiring Perl 5.010. So like… eventually. probably. 💀

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

• prompt — this string parameter is the string used to prompt you for commands. The default is 'satpass>'. Iconic little arrow, no notes.
• refraction — Boolean parameter, specifies whether atmospheric refraction should be taken into account in the azel() calculation. The default is 1 (i.e. true).
• simbad_url — okay so this string parameter does not, strictly speaking, specify a URL 🫠 but it does specify the server used 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. Chain of command, love to see it.

• simbad_version — this integer parameter specifies the version of the SIMBAD application being used, and the valid values are 3 or 4. Set it to 3 and the Astro::SIMBAD package gets used for SIMBAD lookups. Set it to 4 and Astro::SIMBAD::Client gets used. As of early January 2007, 'simbad.u-strasbg.fr' supports both versions, though 3 is being phased out. 'Simbad.harvard.edu' appears — to the author — to be phasing out, and redirected to simbad.u-strasbg.fr.

As of satpass 0.013_09, the default is 4.

• singleton — if this Boolean 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.

heads up: using the Astro::Coord::ECI::TLE::Set object makes calculations take about 15% longer. Bestie said "performance cost" and meant it. 😭

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

• sun — this string parameter names 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 — this string parameter is the strftime(3) format used to display times. You'll 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. Prefer AM and PM? Use something like '%I:%M:%S %p'. Documentation on the strftime(3) subroutine lives at <http://man.openbsd.org/i386/strftime>.

okay so that's a long URL and it 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 — this string-or-numeric parameter specifies how many degrees the sun must be below the horizon before it counts as dark. The words 'civil', 'nautical', or 'astronomical' are also acceptable, as is any unique abbreviation of those 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 — this string parameter specifies the time zone for Date::Manip. You probably won't need it, unless you're running under MacOS (that's OS 9, bestie — not OS X) or VMS. You'll know you need to set it if commands that take times as parameters complain mightily about not knowing what time zone they're in. Otherwise, don't bother. 🦋

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

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

• verbose — this Boolean parameter says whether the 'pass' command should give the position of the satellite every step it's above the horizon. If false, only rise, set, max, into or out of shadow, and the beginning or end of twilight get displayed.

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

• visible — this Boolean parameter says whether the 'pass' command reports only visible passes (if true) or all passes (if false). A pass counts as having occurred if the satellite, at some point in its path, had an elevation above the horizon greater than the 'horizon' parameter. A pass counts as visible if it's 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. ✨ two conditions, both required, no shortcuts.

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

• webcmd — this string parameter is the system command to spawn to display a web page. If it's not the empty string, the help command uses it to display the help for this package on <https://metacpan.org/>. Mac OS X girlies will find 'open' a useful setting, and Windows girlies 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. vibes-based feature deployment, honestly iconic.

The default is '' (i.e. the empty string), which leaves the functionality disabled.

---

🎀 SPECIFYING ANGLES 🎀

Okay so this script accepts angle input in these formats, bestie — memorize the vibe:

• Decimal degrees. Simple. Clean. Number goes brr.
• Hours, minutes, and seconds, specified as hours:minutes:seconds. You'd typically only use this for right ascension. You may specify fractional seconds — or fractional minutes, for that matter. Live your truth.
• Degrees, minutes, and seconds, specified as degreesDminutesMsecondsS. The letters may be in either case, and trailing letters may be omitted. You may specify fractional seconds, or fractional minutes for that matter. Again: freedom.

Examples, because examples are the moment:

23.4 specifies 23.4 degrees.
1:22.3 specifies an hour and 22.3 minutes
12d33m5 specifies 12 degrees 33 minutes 5 seconds

And the sign rules, which are important so listen up 🧚:

• 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 ✨

Okay bestie, real talk: this script (or, more properly, the modules it's 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 relative 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. Quoting is giving necessary, not giving optional 🎀

🌸 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)). Like, it's trying its best, okay 😭

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. It's literally so chill about your formatting 🫶

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. Iconic behavior honestly 👑

🦋 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. The way this is just tidy little rules 🎀

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'. See how it stacks? It's giving cumulative energy ✨

---

💜 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. VMS girlies, you know what to do 💅

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.sourceforge.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. No clipboard, no service 😤
• -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. Short and sweet, just don't be ambiguous about it 🍓

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. Quoting chaos, we love to see it 🙈

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`

Look at all these options, main character energy fr fr 💅

---

🌈 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. Peek behind the curtain, bestie 🧚

---

🫶 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 💀

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.

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. Not me shipping untested code, but honestly same 😭

As of 0.003, clipboard functionality is provided by this code, not by the Clipboard module, making clipboard bugs mine also. Owning my mistakes, we love personal accountability 🫡

---

👑 AUTHOR 👑

Thomas R. Wyant, III (wyant at cpan dot org)

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright (C) 2005-2025 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. Important legal caveat, keep it in mind 💜

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

---

And that's the whole page, bestie — you made it to the end 🦋 This beauty is running on perl v5.42.2, dated 2026-02-15, and it's SATPASS(1) all the way down. Go forth and compute your passes, no cap ✨💅🔥