.. _toast_create_gnss:

Import / Export / Create displacements
======================================

There are several ways to create or import
:term:`displacements <Displacement>` in |toast|:

* |scname| displacement amplitudes are received via an active messaging connection
  and new displacements are :ref:`created automatically<toast-gnss-messaging>`.
* Displacement amplitudes are
  :ref:`imported manually from an XML file<toast-gnss-import>`.
* The user
  :ref:`creates a displacement manually for a GNSS station<toast-manual-gnss>`.

.. _toast-note-amps:

.. note::
  Technically, an *amplitude* is a |scname| object, while a *displacement* is a
  |toast|-specific object.
  The automatic amplitudes (received by messaging) and those
  imported from an XML file are converted to displacements and are
  referenced in the displacement components, analogous to event and incident.
  Required amplitude attributes are type ('Gd'), amplitude value and waveformID.
  The public IDs of the amplitudes can be looked up in the
  :ref:`toast_gnss_perspective`.
  A manually entered displacement does not reference an amplitude.
  The priority of the displacements is: manual, automatic, imported
  (manual displacements overwrite automatic and imported etc.).

For more information on Displacements functionality see: :ref:`toast_gnss_perspective`.


.. _toast-gnss-messaging:

Receive displacements via messaging
-----------------------------------

If a connection to a |scname| system is configured, displacements are
automatically created and updated upon receiving displacement amplitudes from
GNSS observations.

.. note::
   Automatically created displacements overwrite
   :ref:`imported<toast-gnss-import>` displacements,
   but never :ref:`manually created<toast-manual-gnss>` ones.


.. _toast-gnss-import:

Import displacement amplitudes from an XML file
-----------------------------------------------

GNSS displacements can be imported from a file in XML format containing
displacement amplitudes via
:menuselection:`File --> Import --> Displacements amplitudes...`.

This is an example for a file containing such amplitudes.
It was created by the *gdisp* plugin:

.. include:: media/toast/gnss_import/gnss_amplitudes.xml
  :literal:

Upon import, the amplitudes are converted to displacements for the currently
active |toast| incident.

.. note::
   Imported displacements can be overwritten by :ref:`manually<toast-manual-gnss>`
   or :ref:`automatically<toast-gnss-messaging>` created displacements.


.. _toast-manual-gnss:

Create observed displacements manually
--------------------------------------

It is possible to enter or override the observed displacement for a GNSS station
manually.
This is useful if there are no automatic displacements available
or for training purposes.
To do so, right-click on a GNSS station in :ref:`toast_map_perspective`
or in :ref:`toast_gnss_perspective` and select:
:menuselection:`Observed displacement --> Set manually...`.
Note that it is not necessary to enter all components.
The horizontal contribution to the displacement residual is computed if both
East and North components are present and the vertical contribution if the Up
component is present.

.. _fig-gnss_custom:

.. figure:: media/toast/gui/gnss_custom_dialog.png
   :align: center
   :width: 7 cm

   Manual displacement input dialog

A user icon on the left side of the displacement columns in
:ref:`toast_gnss_perspective` indicates manually entered values.

.. note::
   Manually displacements can never be overwritten, neither by
   :ref:`automatically<toast-gnss-messaging>` received or
   :ref:`imported<toast-gnss-import>` ones.

.. note::
   If all components are not set in the manual setting dialog,
   the displacement will be removed.


.. _toast_gnss_save:

Export displacements
--------------------

Observed displacements can be saved to an XML file via
:menuselection:`File --> Save --> Observed displacements as...`.

Note that they are stored as displacement objects and not amplitudes, and thus
can not be re-imported in |toast|.