.. _url-protocol: 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! .. contents:: :backlinks: none Syntax ====== The general form of a Gaia Sky URL is: .. code:: 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 :ref:`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: .. code:: gaiasky://$MODULE/$METHOD?param1=value1¶m2=value2 This mirrors the syntax of the :ref:`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: .. code:: 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: .. code:: 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: .. code:: gaiasky://focus?name=Earth Scripting API calls =================== Any other action is dispatched to the scripting :ref:`APIv2 `, where ``$MODULE`` is an APIv2 module and ``$METHOD`` is one of its methods. For example: .. code:: 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 :ref:`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: .. code:: bash 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.