.. space-command documentation master file, created by
sphinx-quickstart on Sun Feb 24 21:11:04 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
space-command documentation
===========================
:Version: |release|
.. toctree::
:maxdepth: 2
:hidden:
index
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
------------
.. code-block:: shell
$ 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.
.. code-block:: shell
$ pip install git+https://github.com/galactics/beyond
$ pip install git+https://github.com/galactics/space-command
Quickstart
----------
.. code-block:: shell
$ 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.
.. code-block:: shell
$ space station create # Interactively create a station
$ space station --map # Check if your station is well where you want it to be
$ space passes "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
.. code-block:: bash
$ 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.
.. code-block:: shell
$ 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**
.. code-block:: bash
$ 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
.. code-block:: text
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
.. _pipping:
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.
.. code-block:: shell
$ # 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
.. code-block:: bash
$ 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.
.. code-block:: bash
$ 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
.. code-block:: bash
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
.. code-block:: bash
$ export HTTP_PROXY=http://:@:
$ export HTTPS_PROXY=https://:@: