space-command documentation

Version:0.7.3

Features

• Retrieve orbits as TLE from Celestrak or Space-Track
• Compute visibility from a given point of observation
• Compute phases of the Moon and other solar system bodies
• Animated map of the orbit of satellites
• Compute events for a given satellite (day/night, node, AOS/LOS, etc.)
• Retrieve Solar System bodies ephemeris

Installation

$ pip install space-command

If you need the last development version, make sure to also install the last version of beyond, which space relies heavily upon.

$ pip install git+https://github.com/galactics/beyond
$ pip install git+https://github.com/galactics/space-command

Quickstart

$ wspace init        # Create the empty workspace structure
$ space tle fetch    # Retrieve orbital data for major satellites

Stations are accessed by their abbreviation, and by default there is only one declared: TLS. As it is not likely you live in this area, you need to declare a new station of observation.

$ space station create                # Interactively create a station
$ space station --map                 # Check if your station is well where you want it to be
$ space passes <abbrev> "ISS (ZARYA)"  # Compute the next pass of the ISS from your location

Available commands

For full details on a command, use -h or --help arguments

space events : Compute events encountered by the satellite : day/night transitions, AOS/LOS from stations, Node crossing, Apoapsis and Periapsis, etc.

space map : Display an animated map of Earth with the satellites

space passes : Compute visibility geometry (azimuth/elevation) from a given ground station

space phase : Compute and display the phase of the Moon and other solar system bodies

space planet : Compute the position of planets

space station : Create and display ground stations

space sat : Satellite database management

space tle : Retrieve TLEs from Celestrak or Space-Track, store them and consult them

space ephem : Compute Ephemeris and manage Ephemeris database

In addition, the following commands allow you to access non orbital informations

space clock : Handle the time

space config : Allow to get and set different values to change the way the space command behaves

space log : Access the log of all space commands

Command argmuents

Dates

Unless otherwise specified, dates should be given following the ISO 8601 format %Y-%m-%dT%H:%M:%S. You can also use the keywords ‘now’, ‘midnight’ and ‘tomorrow’. All dates are expressed in UTC

Example: It is 2019-07-04T20:11:37, now will yield 2019-07-04T20:11:37, midnight will yield 2019-07-04T00:00:00, and tomorrow will yield 2019-07-05T00:00:00.

Dates are generally used to give the starting point of a computation.

Time range

Time ranges may be expressed in weeks (w), days (d), hours (h), minutes (m) or seconds (s). All descriptors except weeks accept decimals:

• 600s is 600 seconds (10 minutes)
• 2w7h is 2 weeks and 7 hours
• 3h20.5m is 3 hours 20 minutes and 30 seconds

Time ranges are generally used to give the ending point and the step size of a computation.

Station selection

Station selection is done using the abbreviation of the station. By default, only the station TLS (located in Toulouse, France) is present.

Satellite selection

Satellite selection, or rather Orbit selection can be made multiple ways. First you have to pick the descriptor of the satellite. For instance, the International Space Station (ISS) can be accessed by its name (ISS (ZARYA)), NORAD ID (25544), or COSPAR ID 1998-067A. The following commands are equivalent

$ space passes TLS name="ISS (ZARYA)"
$ space passes TLS "ISS (ZARYA)"   # default to name field
$ space passes TLS norad=25544
$ space passes TLS cospar=1998-067A

As this could be a bit tiresome, it is possible to define aliases.

$ space sat alias ISS norad=25544

The ISS alias is already defined

Then, you have to decide which source you want to compute from. By default, space-command uses TLE previously fetched, but this behaviour can be overridden. In some cases, it is not possible to retrieve TLEs for a given object, particularly if this object is an interplanetary spacecraft. In this case, we have to rely on ephemeris files (OEM).

Examples

$ space passes TLS ISS      # Use the latest TLE
$ space passes TLS ISS@tle  # Use the latest TLE
$ space passes TLS ISS@oem  # Use the latest OEM

ISS                : latest TLE of ISS
norad=25544        : latest TLE of ISS selected by norad number
cospar=2018-027A   : latest TLE of GSAT-6A selected by COSPAR ID
ISS@oem            : latest OEM
ISS@tle            : latest TLE
ISS~               : one before last TLE
ISS~~              : 2nd before last TLE
ISS@oem~25         : 25th before last OEM
ISS@oem^2018-12-25 : first OEM after the date
ISS@tle?2018-12-25 : first tle before the date

Piping commands

It is possible to chain commands in order to feed a result from one to another. Generaly, this is used to provide orbital data (TLE, ephemeris, etc.). In this case, the name of the satellite should be replaced by - in the second command.

$ # Compute the pass of Mars above a station
$ space planet Mars | space passes TLS - -s 600s -g

$ # Search for TLEs and display them on a map
$ space tle find tintin | space map -

Workspaces

Workspaces allow the user to work on non-colluding databases. The default workspace is main. The companion command wspace allow to list, create or delete workspaces. To actually use a workspace during a computation, you can use the SPACE_WORKSPACE environment variable, or directly in the command line, with the -w or --workspace options

$ export SPACE_WORKSPACE=test  # all commands coming after will be in the 'test' workspace
$ space passes TLS ISS
$ space events ISS
...
$ unset SPACE_WORKSPACE  # Disable the 'test' workspace, return to 'main'

# The above is equivalent to
$ space passes TLS ISS -w test
$ space -w test events ISS

It is also possible to use the wspace on command. It will open a new shell with the SPACE_WORKSPACE variable set.

$ wspace on test-workspace  # Open the test workspace
$ space passes TLS ISS
$ space events ISS
$ exit  # back to the main workspace

When using wspace on, you can add the following lines to your .bashrc file to help visualize when working on workspaces

if [[ -n $SPACE_WORKSPACE ]]; then
    PS1="$PS1(\033[32m$SPACE_WORKSPACE\033[39m) "
fi

By default all workspaces are located in the .space/ folder in the home directory. It is possible to change the location with the SPACE_WORKSPACES_FOLDER environment variable.

Extension

It is possible to create your own scripts and extensions to this framework.

To do that you have to create a space.commands entry point. This will declare the extension to space-command, and make it available as an additional subcommand.

If you need to extend the initialisation process (wspace init), the entry point is space.wshook.

Proxy

By setting up the HTTP_PROXY and HTTPS_PROXY variables to correct values, space-command should be able to retrieve any file from the web

$ export HTTP_PROXY=http://<login>:<password>@<adress>:<port>
$ export HTTPS_PROXY=https://<login>:<password>@<adress>:<port>