Scripting#

Gaia Sky exposes an API that is accessible through Python (via Py4j) or through HTTP over a network (using the REST API HTTP server).

In this tutorial, we focus on the writing of Python scripts that tap into the Gaia Sky API. You will need Python 3 installed, along with the packages NumPy and Py4j.

We use the Python package manager pipenv. You can install it using pip:

pip install --user pipenv

Then, create a virtual environment (if it does not yet exist).

pipenv shell

Now, you may want to install numpy and py4j directly, or use the requirements.txt file in the directory assets/scripts of the Gaia Sky repository to install the dependencies.

# Either one or the other
pipenv install py4j numpy
pipenv install -r requirements.txt

Once this is ready, you can run a script with the Python 3 interpreter in your virtual environment. Of course, you need to launch Gaia Sky in the same computer for the connection to succeed. Right now, only local scripting is supported. If you need to operate Gaia Sky over the network, have a look at the REST API section.

To run a script named my-gaiasky-script.py, run this in a terminal:

python3 my-gaiasky-script.py

If everything works well, the connection should succeed and Gaia Sky should react accordingly.

But wait, we don’t have a script to run yet! Do not fret, in the next section we learn the basics of writing a script for Gaia Sky.

Docs

See the scripting section in the user manual.

A basic script#

Writing a basic script is quite simple. Essentially, you need a header that imports Py4j and creates the connection object. Then, you can start using the connection object to run calls.

The following script simply connects to Gaia Sky and prints “Hello from a script!” to both Python and the Gaia Sky log.

from py4j.clientserver import ClientServer, JavaParameters

gateway = ClientServer(java_parameters=JavaParameters(auto_convert=True))
gs = gateway.entry_point

# User code goes here.
# We use the 'gs' object to access the API.

# Let's print something.
message = "Hello from a script!"
# Print to Gaia Sky.
gs.print(message)
# Print with Python.
print(message)

# Shutdown the gateway at the end.
gateway.shutdown()

Note that you need to shutdown the gateway at the end, this is important to clean things up and be able to run more scripts afterwards!

It is cool that we can print messages, but what other actions can we perform via scripting? Read on to know more about the API.

Gaia Sky API#

The Gaia Sky API (here) contains many more calls to interact with the platform in real time from Python scripts or a REST HTTP server. The API includes calls to:

  • Add and remove messages and images to the interface,

  • start and stop time, and change the time warp,

  • add scene elements like shapes, lines, etc.,

  • load full datasets in VOTable, CSV, FITS, or the internal JSON format,

  • manage datasets (highlight, change settings, etc.),

  • manipulate the camera position, orientation and mode,

  • move the camera by simulating mouse actions (rotate around, forward, etc.),

  • activate special modes like planetarium or panorama,

  • create smooth camera transitions in position and orientation,

  • change the various settings and preferences,

  • back-up and restore the full configuration state,

  • take screenshots, use the frame output mode.

The API specification is documented in the links below:

Showcase scripts#

The Gaia Sky repository contains many test and showcase scripts that may help with getting up to speed with Gaia Sky scripting. Many of them contain comments explaining what is going on:

  • Interesting showcase scripts can be found here.

  • Basic testing scripts can be found here.

Hands-on session#

Here, we have a look at some real world scripts (full file listing), and write our own to later run them on Gaia Sky.

The proposed scripts are:

  • Locating_the_Hyades_tidal_tails.py – a simple sequential script which exemplifies some of the most common API calls, and can be used to capture a video. The script requires the following data and subtitles files to run (save them in the same directory as the script):

  • line-objects-update.py – a script showcasing the feature to run scripting code within the Gaia Sky main loop, so that it runs synchronized with the main loop, every frame. This is used to run update operations every single frame. In our test script, we create a line between the Earth and the Moon, start the time simulation, and update the position of the line every frame so that it stays in sync with the scene.