.. _sec-vortex-config:

Getting Started
***************

The configuration parameters are described in the :ref:`technical description<vortex>`.
Read  :ref:`below <sec-vortex-configuration>` for the details. VORTEX also
requires :ref:`bindings <sec-vortex-bindings>`.


.. _sec-vortex-configuration:

Minimum Configuration
=====================

Use the module and bindings configuration of VORTEX to set the required configuration
parameters.
A minimum VORTEX configuration includes:

* **Module configuration**: The data source (:term:`RecordStream`),
* **Binding configuration**: Definition of stations and streams.


Date source
-----------

The data source is configured to the global parameters of the VORTEX module
configuration (:file:`vortex.cfg`).

#. Add the :term:`RecordStream` plugin *rsspec* to receive the spectra of
   :term:`miniSEED` data:

   .. code-block:: params

      plugins = ${plugins}, rsspec

   .. note::

      For reading data from a CAPS server :cite:p:`caps` using the *caps* or
      the *capss* RecordStream in a system with |scname|
      in version < 4.5.0 the *rsas* RecordStream plugin must be added as well.
      In all newer versions of |scname|, these RecordStreams are automatically
      available without configuration.

#. Configure the :term:`RecordStream` to set the data source. While the standard
   RecordStreams of |scname| supports :term:`miniSEED`, the *caps* RecordStream
   supports basically any format including camera, meteorological or chemical
   data. Use the *caps* RecordStream to read these and other auxiliary data from
   a CAPS server. Examples for different data sources:

   .. code-block:: params

      recordstream = caps://localhost:18002
      recordstream = slink://localhost:18000
      recordstream = combined://slink/localhost:18000;sdsarchive//home/data/archive


Station and stream definition
-----------------------------

Stations and streams are primarily configured by VORTEX :term:`bindings <binding>`.

3. Create |appname| :term:`bindings <binding>` to all stations which shall be
   considered by |appname|. Consider binding profiles for sharing identical
   parameters for a set of stations and station bindings for unique configurations.
#. In the bindings configuration set the :confval:`streams` parameter to define
   location and the stream of a station. You may use wildcards and define multiple
   streams in a comma-separated list. Example:

   .. code-block:: params

      # Comma-separated list of location and channel codes to use as primary streams,
      # e.g. BH or BH? or BHZ,BHN,BHE or 00.ENZ,00.EHN.
      streams = 00.BH?,HH?

   .. hint::

         The definition of streams can be further narrowed by the module configuration
         parameters :confval:`streams.codes` or on the command line, e.g.

         .. code-block:: sh

            vortex --streams.codes=IU.*.00.BHZ


Recommended Configuration
==========================


.. _sec-vortex-configuration-interaction:

Module configuration
--------------------

Apply further module configurations in :file:`vortex.cfg`.


Data streams and time windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* **Streams**: While the stations and streams to be considered are set in the
  :ref:`bindings <sec-vortex-binding>`, the streams can be further filtered by configuring
  :confval:`streams.codes`.

* **Duration**: By default, VORTEX loads and display 1 hour data until
  current time (GMT). Adjust :confval:`bufferSize` to alter the duration.
* **End time**: Adjust :confval:`endTime` to control the end of the time window.
  Use the usual time format for |scname|. Example:

  .. code-block:: params

     endTime = "2021-05-01 12:00:00"


GUI Interactions
~~~~~~~~~~~~~~~~

|appname| allows to create :ref:`artificial origins<sec-vortex-example-ao>` which
can be processed in other GUIs.

* **Interaction:** Configure the global parameter :confval:`commands.target`
  allowing to send artificial origins by VORTEX and to receive them by other GUIs:

  .. code-block:: sh

     commands.target = ".*$"


Overview layout
~~~~~~~~~~~~~~~

The widget layout of the Overview tab can be configured.

* **Rows and columns:** Adjust the number of rows and columns by
  :confval:`trace.overview.matrixLayout`, e.g. for 3 columns and 2 rows: ::

   trace.overview.matrixLayout = "3x2"


Spectrograms
~~~~~~~~~~~~

In the *spec* section the time window parameters for computing the spectrograms
as well as a custom gradient can be configured.

* **Spectrograms:** Configure length (:confval:`spec.length`), overlap  (:confval:`spec.overlap`)
  and number of samples  (:confval:`spec.samples`) of time windows:

  .. code-block:: params

     spec.length = 5
     spec.overlap = 0.5
     spec.samples = 512

After configuring the gradient, they can be adjusted interactively in the Overview and
the Detail tabs.

A variety of pre-defined :doc:`gradients </base/gradients>` is available by default.


.. _sec-vortex-bindings:

Bindings configuration
----------------------

In binding profiles or station bindings configure also:

* **Gain multipliers:** Convert the gain-corrected data
  values from the fundamental SI units to another derived unit, e.g. m to km, Pa to hPa.
  Set :confval:`gainMultiplier` to the respective power of 10, e.g. 3 for units of km.

  .. code-block:: params

     gainMultiplier = 3

* **Video data source and stream ID**: Set :confval:`videoStreams.videoURL`
  and :confval:`videoStreams.videoStreamID`. Video streams can be served by a
  CAPS server :cite:p:`caps`:

  .. code-block:: params

     videoStreams.videoURL = video.agency.de:18008
     videoStreams.videoStreamID = NZ.RUAP.NORTH.CAM

  Set :confval:`videoStreams.liveVideo` to any web-video source like `youtube <https://youtube.com>`_:

  .. code-block:: params

     videoStreams.liveVideo = https://www.youtube.com/embed/Q5M-5XFplo0?autoplay=1&modestbranding=1

  .. note::

     The whole website will be displayed.

     For the purpose of embedding videos, youtube for example, has options like
     ``embed``, ``modestbranding`` and ``autoplay``.

     Other web players may have similar options.

* **Auxiliary streams**: Up to 3 auxiliary streams, e.g. non-seismic data like
  air pressure can be fetched from the configured RecordStream.
  Non-miniSEED auxiliary streams can be served by a CAPS server :cite:p:`caps`.
  Example:

  .. code-block:: params

     auxStream1.stream = 30.HDF
     auxStream1.gainMultiplier = 2