APIv2

The Gaia Sky APIv2 (Javadoc) is the preferred interface to access Gaia Sky scripting.

Some of the advantages of APIv2 over APIv1 are:

  • It is modular.

  • It is well organized.

  • It uses Python’s snake_case instead of Java’s camelCase for function and parameter naming.

  • It uses consistent function names.

  • It uses consistent parameter names.

Since the APIv2 is modular, its calls are organized into different groups:

  • Base module – Functions to manipulate and query global attributes and systems, or elements that do not fit anywhere else.

  • Time module – Functions to manipulate and query simulation time.

  • Camera module – Functions to manipulate and query the camera system. Contains an inner module.

  • Scene module – Functions to add and remove objects from the internal scene.

  • Data module – Functions to load datasets.

  • Graphics module – Functions to manipulate and query the graphics system.

  • Camcorder module – Functions to manipulate and query the camcorder system.

  • Ui module – Functions to manipulate and query the user interface.

  • Input module – Functions to manipulate and query input events.

  • Output module – Functions to manipulate and query output systems like frame output or screenshots.

  • Refsys module – Functions to convert between reference systems.

  • Geom module – Functions to perform geometry operations.

  • Instances module – Functions to work with multiple connected instances in the primary-replica model.

Gaia Sky provides a REST server that enables the remote execution of API calls over HTTP. This is described in the REST server section.

APIv2 reference

The only up-to-date APIv1 documentation for each version is in the interface header files themselves. Below is a list of links to the different APIs.

Scripting with APIv2

First of all, install the environment if you have not done so.

Using the APIv2 from a Python script is very easy. We use the single-threaded model of Py4J to connect to Gaia Sky from Python. These are the necessary steps to set up your script:

  1. Import ClientServer and JavaParameters from py4j.clientserver.

  2. Create a gateway and get its entry point.

  3. Use the entry point to access the APIv2 modules.

  4. Use the modules to access APIv2 methods.

  5. Properly shut down the gateway. Since Gaia Sky spawns a new server per script, the gateway must be shut down at the end of the script so that the Python program can terminate correctly and Gaia Sky can create a new server to deal with further scripts listening to the Py4J port.

The following snippet exemplifies these 5 points in Python code.

# 1. Imports
from py4j.clientserver import ClientServer, JavaParameters

# 2. Create the gateway and entry point
gateway = ClientServer(java_parameters=JavaParameters(auto_convert=True))
apiv2 = gateway.entry_point.apiv2

# 3. Access modules
# Base module
base = apiv2.base
# Camera module
camera = apiv2.camera
# Time module
time = apiv2.time

# 4. Call module methods
camera.go_to_object("Mars", 10.0, 5.0)
time.start_clock()

# More code goes here
[...]

# 5. Shutdown
gateway.shutdown()

Backing up and restoring settings

Typically, scripts modify various program settings when they run (camera speed, star brightness, field of view, etc.). In order to leave Gaia Sky in the state it was before, scripts have the option to back up and restore the entire settings state of Gaia Sky. To do that, the APIv1 includes a few calls to push and pull settings states from an internal LIFO stack:

  • base.settings_backup() — push the current settings state to the settings stack.

  • base.settings_restore() — restore the top-most settings state from the settings stack so that they become immediately effective. This call re-initializes the user interface of Gaia Sky, so be aware that the UI will be reset.

  • base.settings_clear_stack() — clears the settings stack. Calling base.settings_restore() after this will have no effect.

These calls can be used at the start and end of scripts to back up and restore the user settings, so that everything is left unchanged after a script execution.

from py4j.clientserver import ClientServer, JavaParameters

gateway = ClientServer(java_parameters=JavaParameters(auto_convert=True))
apiv2 = gateway.entry_point.apiv2
base = apiv2.base

# 1. Back up settings before anything
base.settings_backup()

# 2. Script does things and modifies the settings
[...]

# 3. Restore the settings backed up at point 1.
base.settings_restore()

gateway.shutdown()

Logging to Gaia Sky and Python

When printing messages, you can either log to Gaia Sky or print to the standard output of the terminal where Python runs:

base.print("This goes to the Gaia Sky log")
print("This goes to the Python output")

In order to log messages to both outputs, you can define a function which takes a string and prints it out to both sides:

def pprint(text):
    base.print(text)
    print(text)

pprint("Hey, this is printed in both Gaia Sky AND Python!")

Method and attribute access

Py4J allows accessing public class methods but not public attributes. In case you get objects from Gaia Sky, you can’t directly call public attributes, but need to access them via public methods:

# Get the Mars model object
body = scene.get_object("Mars")
# Get spherical coordinates as a Vector2
radec = body.getPosSph()

# DO NOT do this, it crashes!
gs.print("RA/DEC: %f / %f" % (radec.x, radec.y))

# DO THIS instead
gs.print("RA/DEC: %f / %f" % (radec.x(), radec.y()))

Strict parameter types

As general advice, it is better to be strict with the parameter types. Use a floating point number when the method signature takes in a float or double, and integers when it takes in an int or long. The scripting interface still tries to perform conversions under the hood but it is better to do it right from the beginning. For example, this method from the refsys module of APIv2

double[] galactic_to_cartesian(double l, double b, double r);

may not work if called like this from Python:

refsys.galactic_to_cartesian(10, 43.5, 2)

Note that the first and third parameters are integers rather than floating point numbers. It is better to use explicit floating point numbers instead: like this instead:.. code:: python

refsys.galactic_to_cartesian(10.0, 43.5, 2.0)