URL protocol#
Installing Gaia Sky registers the custom URL scheme gaiasky:// with your operating system, so that opening such a URL hands it over to Gaia Sky. This registration is done by the installer on Windows and macOS, and by the .desktop files on Linux. Opening a Gaia Sky URL, either from the command line or from a web page, a desktop file or an e-mail, makes a running Gaia Sky instance (or a new one) act on it: load a dataset, fly to an object, change the focus, or run a scripting API call.
Hint
Any web page can trigger a gaiasky:// URL without user interaction, via a link, an iframe or a redirect. Gaia Sky therefore asks for confirmation before running a scripting API call or downloading a dataset from a URL. Only accept requests you initiated yourself and whose source you trust!
Syntax#
The general form of a Gaia Sky URL is:
gaiasky://$ACTION?param1=value1¶m2=value2
The action (the host part of the URL) is either one of the built-in actions load, goto and focus, or the name of an APIv2 module. In the latter case, the first path segment after the module is the API method to call, so that the URL has the form:
gaiasky://$MODULE/$METHOD?param1=value1¶m2=value2
This mirrors the syntax of the REST server: parameters are matched by name against the formal parameters of the scripting method (or positionally as arg0, arg1, …), and the string values are converted to the parameter types.
Built-in actions#
load#
Loads, installs and enables a dataset. The parameter is the key of a dataset in the dataset metadata, or the URL of a dataset stub:
gaiasky://load?dataset=messier
gaiasky://load?dataset=https://example.com/my-dataset.json
If the dataset is not installed yet, Gaia Sky shows a confirmation dialog, downloads and installs it, and then loads it. If it is already installed, it is simply enabled and loaded. catalog is accepted as a synonym for dataset.
goto#
Flies smoothly to an object in the scene:
gaiasky://goto?name=Mars&pos_duration=5&ori_duration=3
target, object, name and id are all accepted as the name of the target. pos_duration and ori_duration are the durations of the position and orientation transitions in seconds, and default to 20 s and 10 s.
focus#
Changes the focus to the given object, without moving the camera:
gaiasky://focus?name=Earth
Scripting API calls#
Any other action is dispatched to the scripting APIv2, where $MODULE is an APIv2 module and $METHOD is one of its methods. For example:
gaiasky://camera/focus_mode?name=Earth
gaiasky://camera/go_to_object?name=Mars&pos_time=5.0
gaiasky://time/set_time?year=2026&month=1&day=1
Values are given as they are in the REST server: booleans, integers and floats as-is, vectors and matrices as comma-separated values in square brackets, e.g. up=[1.,0.,0.]. Note that in most contexts you will need to URL-encode characters such as spaces, &, = and square brackets.
Note
Only methods that return no value can be called, because the return value of a URL-triggered call would be discarded. Getters, queries and listings are therefore not available through the URL protocol.
Warning
Some APIv2 modules are not reachable through the URL protocol, as they can modify or read arbitrary state of the running instance. Currently these modules are blocked: data, input, output, instances, scene. This list is compiled into Gaia Sky and cannot be changed in the configuration files. Individual methods can be blocked as well.
In all cases, Gaia Sky shows a dialog with the requested call before executing it, and the call runs only if you accept. Rejected and blocked calls are reported in a notification and written to the log.
Testing the URLs#
On the command line, you can pass a URL as a positional argument:
gaiasky "gaiasky://goto?name=Mars"
gaiasky "gaiasky://load?dataset=messier"
If another Gaia Sky instance is already running, the URL is forwarded to it and handled immediately; the new process then exits. Otherwise, Gaia Sky starts up and handles the URL once the user interface is ready.
Note
Depending on the platform, the operating system may ask for confirmation before handing a gaiasky:// URL to Gaia Sky, and browsers differ in whether they accept custom schemes in links at all. On macOS, URLs received through the open-URL event before the user interface is ready are handled once the welcome window has been created.