.. _apiv2: APIv2 ***** .. contents:: :backlinks: none 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. - `Interactive camera module `__ -- Functions to manipulate the camera in interactive mode. * `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 :ref:`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. - `Latest API version `__ - `Older API versions (javadoc) `__. Scripting with APIv2 ==================== First of all, :ref:`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. .. code:: python # 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. .. code:: python 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: .. code:: python 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: .. code:: python 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: .. code:: python # 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 .. code:: java double[] galactic_to_cartesian(double l, double b, double r); may not work if called like this from Python: .. code:: 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)