.. highlight:: rst

.. _scrttv:

######
scrttv
######

**Real-time trace view.**


Description
===========

scrttv visualizes waveform data in miniSEED format
(see :ref:`Figure below <fig-scrttv-overview>`) in real-time or from archives
with a defined window length (default: 30 minutes) of defined streams/stations
(default: streams defined by global bindings). Additionally, phase picks are
visualized.

scrttv can be used for view waveforms,
:ref:`visual waveform quality control <scrttv-waveform-qc>` or
:ref:`interactive signal detection <scrttv-signal-detection>`.

When in :ref:`message mode <scrttv-modes>` scrttv dynamically resorts waveforms:
Normally, the trace order is given by configuration, e.g., ordering by epicentral
distance from a location given by :confval:`streams.sort.latitude` and
:confval:`streams.sort.longitude`.
In the event that a new SeisComP :term:`event` arrives from the messaging, the
traces are sorted  automatically by epicentral distance to the latest origin
received. In addition to waveforms, information about gaps or overlaps, picks
and the time of incoming origins are displayed.

.. _fig-scrttv-overview:

.. figure:: media/scrttv/scrttv.png
   :width: 16cm
   :align: center

   scrttv overview

   An example of scrttv and the dialog window to associate picks to new origins.
   Tabs: Enable/Disable; Amplitude: mean and maximum;
   Stream: station, network, sensor location and channel code;
   Filter: filter applied traces; Status = connection status to messaging.

scrttv shows two tabs: the Enabled and the disabled tab
(see :ref:`fig-scrttv-overview`). Stations listed in the disabled tab
are excluded from automatic processing (e.g. phase picking). To move a station
from one tab to another just drag and drop the trace to the new tab. An alternative solution is
to double click on the trace label to disable a trace. Read the section
:ref:`scrttv-waveform-qc` for the details.

Normally, the raw data are displayed. Pressing :kbd:`f` the predefined bandpass filter
of third order from 0.5 Hz to 8 Hz, :ref:`BW(3,0.5,8) <filter-bw>` is applied
to the traces. Also zoom functions for the time and amplitude axis are provided.
Read the sections :ref:`<scrttv-filtering>` and  :ref:`scrttv-visualization` for
more details.

Among the configurable parameters are:

* Global :term:`bindings <binding>`:

  * default definition of traces to show (:confval:`detecStream` and :confval:`detecLocid`).

* :term:`Module <module>` configuration:

  * network, stations, locations and streams to show extending or overriding the
    default definition (:confval:`streams.codes`),
  * :ref:`data filters <scrttv-filtering>`,
  * buffer size controlling the length of loaded data (:confval:`bufferSize`),
  * sorting of traces upon arrival of new origins (:confval:`resortAutomatically`),
  * reference coordinate for sorting traces by default (:confval:`streams.sort.*`),
  * region filters (:confval:`streams.region.*`),
  * :ref:`grouping of streams <scrttv-grouping>` with different properties,
  * number of traces to show with fixed height (:confval:`streams.rows`).

* Scheme parameters in global :term:`module` configuration:

  * trace properties and trace background colors,
  * font and general GUI parameters.

More parameters are available on the command-line:

.. code-block:: sh

   scrttv -h


.. _scrttv-modes-operation:

Modes of Operation
==================

scrttv can be started in message mode or in offline mode.

* Message mode: scrttv is started normally and connects to the messaging,
  :term:`picks <picks>`, :term:`origins <origin>` and inventory are read from
  the database and received in real time from the messaging. Data are received
  from :term:`recordstream`.
* Offline mode: scrttv is started without connection to the messaging,
  :term:`picks <picks>` and :term:`origins <origin>` are not received in real
  time from the messaging. However, they can be loaded from XML files using the
  *File* menu. Data are received from :term:`recordstream` or from file. The
  offline mode is invoked when using the option :option:`--offline` or when
  passing a file name to scrttv at startup. Example:

  .. code-block:: sh

     scrttv file.mseed


.. _scrttv-visualization:

Waveform Visualization
======================


Stream selection
----------------

Without further configuration scrttv displays waveforms for streams defined
in global bindings. The selection can be refined by configuring
:confval:`streams.codes` and overridden on the command line using
:option:`--channels`.


Stream hiding
-------------

Streams with :ref:`data latency <scqc>` < :confval:`maxDelay` are hidden but
shown again when applicable. By default  :confval:`maxDelay` is unconfigured and
hiding streams is inactive. For listing
streams hidden from one tab press :kbd:`h`.


.. _scrttv-time-windows:

Time windows
------------

The reading waveforms from RecordStream, the data is displayed for a time
window which by default ends at current time or as given by the command-line
option :option:`--end-time`. Initially, the time window takes the length defined
in :confval:`bufferSize` or by the option :option:`--buffer-size`. When reading data
directly from file in offline mode, the time window is set
from the time limits of the waveforms.

* The **length of visible time windows** can be adjusted by
  :ref:`zooming <scrttv-zooming>`.
* The **end time of the data** progresses in continuously in real time (UTC)
  with the time of the computer clock unless fixed (:kbd:`F8`). The end time is
  fixed during startup when applying :option:`--end-time`.
* For **progressing or rewinding by 30 minutes** press :kbd:`Alt right` or
  :kbd:`Alt left`, respectively. Data will be loaded immediately.
* You may also **freely zoom** into any time window. Data and picks will be loaded
  when pressing :kbd:`Ctrl + r`
* **Return to default real-time processing** by pressing :kbd:`Ctrl + Shift + r`
  or :kbd:`N`.

.. hint::

   Gaps and overlaps in waveforms are indicated by yellow and purple areas,
   respectively. The colors are configurable.


.. _scrttv-zooming:

Zooming
-------

Waveforms can be zoomed in and out interactively in amplitude and time. Use the
*View* menu or refer to the section :ref:`scrttv-hot-keys` for options. In
addition to the actions available from the View menu, zooming is supported by
mouse actions:

* Zooming in in time: Right-click on time axis, drag to the right. A green bar appears
  which is the new time window. Dragging up or down (gray bar) disables zooming.
* Zooming out in time: Right-click on time axis, drag to the left. A red bar appears. The
  longer the bar, the more you zoom out.  Dragging up or down (gray bar)
  disables zooming.
* Zooming in time and amplitude: Mouse over a trace of interest, use
  :kbd:`Ctrl + mouse wheel` for zooming in or out.
* Zooming around a selected area: Press :kbd:`z` and drag an area with while
  pressing the left mouse button. Press :kbd:`z` again for leaving the zoom
  mode.


.. _scrttv-grouping:

Stream grouping
---------------

scrttv allows grouping of stations and even streams with different properties,
e.g. colors or color gradients.

.. _scrttv-fig-group-filter:

.. figure:: media/scrttv/groups.png
   :width: 16cm
   :align: center

   Stations with 2 groups and different line color gradients. Ungrouped stations
   are visible with default line properties. The applied filter
   is shown in the lower left corner. The tooltip on top of station CX.PB19
   is derived from :confval:`streams.group.$name.title`.


**Configuration**

Adjust the scrttv module configuration (:file:`scrttv.cfg`).

#. Define the groups:

   * add a new group profile to :confval:`streams.group`.
   * set the properties for this group profile. :term:`Colors <color>` and color
     gradients are defined by hexadecimal values or by
     :term:`color keyword name`.
     When choosing gradients the colors of the traces within one group will be
     varied in alphabetic order of the streams.
   * set a group title in :confval:`streams.group.$name.title`.

#. Register the groups in :confval:`streams.groups`.


**Viewing groups**

#. Open :program:`scrttv` to view the data.
#. Select *Sort by group* in the *Interaction* menu or use the hotkey :kbd:`5`
   to sort the traces by their groups.
#. Mouse over a station belonging to a group. The tooltips shows the group title.
#. For maintaining the sorting by groups adjust the :program:`scrttv` module
   configuration (:file:`scrttv.cfg`): ::

      resortAutomatically = false


.. _scrttv-picks:

Phase picks and arrivals
------------------------

Previous versions of scrttv (< 5.4) only displayed :term:`picks <pick>` with the
colors indicating the pick evaluation mode along with the phase hint of the
pick:

* red: automatic,
* green: manual.

This hasn't really changed in later versions but additionally scrttv determines
an additional state of a pick called :term:`arrival`. In scrttv a pick is
considered an arrival if it is associated to an valid origin. An origin is
called valid if its evaluation status is not REJECTED. When scrttv loads all
picks from the database for the currently visible time span it also checks if
each pick is associated with a valid origin and declares the arrival state if
the check yields true. The visibility of picks and arrivals can be toggled by
pressing :kbd:`Ctrl + p` and :kbd:`Ctrl + a`, respectively. :kbd:`c` removes all
markers. The configuration parameter :confval:`showPicks` controls the default
visibility.

Picks and arrivals can be differentiated visually by their colours. When
configured in global module configuration, the same colours are being used
consistently as in any other GUI displaying both types, namely

* :confval:`scheme.colors.picks.automatic`
* :confval:`scheme.colors.picks.manual`
* :confval:`scheme.colors.picks.undefined`
* :confval:`scheme.colors.arrivals.automatic`
* :confval:`scheme.colors.arrivals.manual`
* :confval:`scheme.colors.arrivals.undefined`

That visual difference should support the operator in finding clusters of picks
and creating new location missed by the automatic system.

The next sections will only use the :term:`pick` which can be used
interchangeable for pick or arrival.


.. _scrttv-record-borders:

Record borders
--------------

The borders of records are toggled by using the hotkey :kbd:`b`.

.. figure:: media/scrttv/borders.png
   :width: 16cm
   :align: center

   Record borders in box mode on top of waveforms.

Border properties can be adjusted and signed records can be visualized by colors
configured in the scheme parameters in :file:`global.cfg` or :file:`scrttv.cfg`:

* :confval:`scheme.records.borders.drawMode`: Define where to draw borders, e.g. on top, bottom or as boxes.
* :confval:`scheme.colors.records.borders.*`: Define pen and brush properties.


.. _scrttv-waveform-qc:

Waveform Quality Control
========================

Use scrttv for regular visual waveform inspection and for enabling or disabling
of stations. Disabled stations will not be used for automatic phase detections
and can be excluded from manual processing in :ref:`scolv`. They will also be
highlighted in :ref:`scmv` and :ref:`scqc`.

To enable or disable a station for automatic data processing in |scname| select
a station code with the mouse and drag the stations to the disable / enable tab
or simply double-click on the station code in the respective tab.


Stream Processing
=================


.. _scrttv-filtering:

Filtering
---------

scrttv allows filtering of waveforms. Any
:ref:`filter available in SeisComP <filter-grammar>` can be considered. The
filter selection dropdown menu (see :ref:`Figure above <fig-scrttv-overview>`)
and the hotkeys :kbd:`g` or :kbd:`d` can be used to toggle the list of filters.
This list of pre-defined in :confval:`filter` or in :confval:`filters`. You may
switch between filtere and unfiltered data by pressing :kbd:`f`. To show
filtered and raw data together use the hotkey :kbd:`r`.

.. note::

   The list of filters defined in :confval:`filters` overwrites :confval:`filter`.
   Activate :confval:`autoApplyFilter` to filter all traces at start-up of scrttv
   with the first filter defined in :confval:`filters`.



Gain correction
---------------

The stream gain is applied to waveforms and amplitude values are given in the
physical units defined in the inventory of the stream by default. For showing
amplitudes in counts, deactivate the option *Apply gain* in the Interaction menu.


.. _scrttv-signal-detection:

Interactive Signal Detection
============================

Beside visual inspection of waveforms for quality control, scrttv can also be
used for interactive signal detection in real time or for selected time windows
in the past.


.. _scrttv-artificial-origins:

Artificial origins
------------------

.. figure:: media/scrttv/artificial-origin.png
   :width: 16cm
   :align: center

   Artificial origin.

In case the operator recognizes several seismic signals which shall be processed
further, e.g. in :ref:`scolv`, an artificial/preliminary origin can be set by
either pressing the middle mouse
button on a trace or by opening the context menu (right mouse button) on a trace
and selecting "Create artificial origin". The following pop-up window shows the
coordinates of the selected station and the time the click was made on the
trace. The coordinates and time define the hypocenter parameters of the the new
artificial origin without adding any arrivals.
Pressing "Create" sends this origin to the LOCATION group. This artificial
origin is received e.g., by :ref:`scolv` and enables an immediate manual analysis
of the closest traces.

In order to send artificial origins and receive them in other GUIs
:confval:`commands.target` of the global module configuration must be configured
in line with :confval:`connection.username` of the receiving GUI module.

Alternatively, picks can be selected and preliminary origins can be created
which are sent to the system as regular origin objects, see section
:ref:`scrttv-origin-association`.


.. _scrttv-origin-association:

Pick association
----------------

scrttv comes with a minimal version of a phase associator and manual locator
based on selected and associated picks (Fig. :ref:`fig-scrttv-overview`). The
workflow is:

#. Visually identify phase picks which potentially belong to an event of interest,
#. :ref:`Select these picks <scrttv_pick-selection>` for automatic association,
#. :ref:`Control <scrttv_pick-locating>` the locator,
#. :ref:`Commit <scrttv_pick-commit>` created origins along with all associated
   picks.

Origins are committed to the messaging system as manual but preliminary location.
In contrast to the artificial origin operation which requires an immediate
intervention with, e.g. :ref:`scolv`, this operation allows to store all those
detected origins and work on them later because they will be stored in the
database.

.. note::

   More detailed waveform and event analysis can be made in :ref:`scolv`.


.. _scrttv_pick-selection:

Pick selection
~~~~~~~~~~~~~~

In order to select picks, the pick association mode must be entered. When done,
clicking with mouse onto the data and dragging a box (rubber band) around the
picks of interest will add the picks to a "cart".
"cart" refers to the list of selected picks which then available in the
associator/locator control widget used for locating an origin.

Simply dragging a new box will remove all previously selected picks. Further
keyboard-mouse options are:

* :kbd:`Shift + drag`: Add more picks to the while keeping the previous selection.
* :kbd:`Ctrl + drag`: Remove selected picks from the previous selection.

If at least one pick has been selected, the associator control will open as a
dock widget for locating based on the selected picks. There, individual picks
can also be removed from the selection by clicking on the close icon of each
pick item. Selected picks are also highlighted in the traces by a color
background bar.

.. note::

   A dock widget is a special kind of window which can be docked to any border
   of the application or even displayed floated as kind of overlay window. The
   position of the dock widget will be persistent across application restarts.

At any change of the pick set, the associator will attempt a relocation
displaying the results in the details. Error message will show up at the top.


.. _scrttv_pick-locating:

Locating from picks
~~~~~~~~~~~~~~~~~~~

The associator control exposes all locators available in the system presenting them
in a dropdown list at the bottom. The locator which should be selected as default
can be controlled with :confval:`associator.defaultLocator` and its default
profile by :confval:`associator.defaultLocatorProfile`.

Whenever the operator changes any of the values, a new location attempt is being
made which can succeed or fail. A successful attempt will update the details,
a failed attempt will reset the details and print an error message at the top
of the window.

Each locator can be configured locally by clicking the wrench icon. This
configuration is not persistent across application restarts. It can be used
to tune and test various settings. Global locator configurations in the
configuration files are of course being considered by scrttv.

In addition to the locator and its profile a fixed depth can be set. By default
the depth is free and it is up to the locator implementation to assign a depth
to the origin. The depth dropdown list allows to set a predefined depth. The
list of depth values can be controlled with :confval:`associator.fixedDepths`.


.. _scrttv_pick-commit:

Committing a solution
~~~~~~~~~~~~~~~~~~~~~

Once you accept a solution you may press the button "Commit" be for sending it
to the messaging as a regular origin. The receiving message group is defined by
:confval:`messaging.groups.location`. The new origin is then grabbed by all
connected modules, e.g., :ref:`scevent` and possibly associated to an
:term:`event`.

.. note::

   When considering non-default message groups such as in multi-pipeline systems,
   :confval:`messaging.groups.location` should be configuring accordingly.

Alternatively, the button "Show Details" can be used to just send the origin to
the GUI group and let :ref:`scolv` or other GUIs pick it up and show it. This
will not store the origin in the database and works the same way as creating
:ref:`artificial origins <scrttv-artificial-origins>`.


.. _scrttv-hot-keys:

Hotkeys
=======

=======================  =======================================
Hotkey                   Description
=======================  =======================================
:kbd:`F1`                Open |scname| documentation
:kbd:`Shift+F1`          Open scrttv documentation
:kbd:`F2`                Setup connection dialog
:kbd:`F11`               Toggle fullscreen
:kbd:`ESC`               Set standard selection mode and deselect all traces
:kbd:`c`                 Clear picker  markers
:kbd:`b`                 Toggle record borders
:kbd:`h`                 List hidden streams
:kbd:`Ctrl+a`            Toggle showing arrivals
:kbd:`Ctrl+p`            Toggle showing picks
:kbd:`n`                 Restore default display
:kbd:`o`                 Align by origin time
:kbd:`p`                 Enable pick selection mode
:kbd:`Alt+left`          Reverse the data time window by buffer size
:kbd:`Alt+right`         Advance the data time window by buffer size
-----------------------  ---------------------------------------
**Filtering**
-----------------------  ---------------------------------------
:kbd:`f`                 Toggle filtering
:kbd:`d`                 Switch to previous filter in list if filtering is enabled.
:kbd:`g`                 Switch to next filter in list if filtering is enabled.
:kbd:`r`                 Toggle showing all records
-----------------------  ---------------------------------------
**Navigation**
-----------------------  ---------------------------------------
:kbd:`Ctrl+f`            Search traces
:kbd:`up`                Line up
:kbd:`down`              Line down
:kbd:`PgUp`              Page up
:kbd:`PgDn`              Page down
:kbd:`Alt+PgUp`          To top
:kbd:`Alt+PgDn`          To bottom
:kbd:`left`              Scroll left
:kbd:`right`             Scroll right
:kbd:`Ctrl+left`         Align left
:kbd:`Ctrl+right`        Align right
-----------------------  ---------------------------------------
**Navigation and data**
-----------------------  ---------------------------------------
:kbd:`Alt+left`          Rewind time window by 30' and load data
:kbd:`Alt+right`         Progress time window by 30' and load data
:kbd:`Ctrl+r`            (Re)load data in current visible time range
:kbd:`Ctrl+Shift+r`      Switch to real-time with configured buffer size
-----------------------  ---------------------------------------
**Sorting**
-----------------------  ---------------------------------------
:kbd:`1`                 Restore configuration order of traces
:kbd:`2`                 Sort traces by distance
:kbd:`3`                 Sort traces by station code
:kbd:`4`                 Sort traces by network-station code
:kbd:`5`                 Sort traces by group
-----------------------  ---------------------------------------
**Zooming**
-----------------------  ---------------------------------------
:kbd:`<`                 Horizontal zoom-in
:kbd:`>`                 Horizontal zoom-out
:kbd:`y`                 Vertical zoom-out
:kbd:`Shift+y`           Vertical zoom-in
:kbd:`s`                 Toggle amplitude normalization
:kbd:`Ctrl+mouse wheel`  Vertical and horizontal zooming
:kbd:`z`                 Enable/disable zooming: Drag window with left mouse button
=======================  =======================================


.. _scrttv_configuration:

Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/scrttv.cfg`
| :file:`etc/global.cfg`
| :file:`etc/scrttv.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/scrttv.cfg`

scrttv inherits :ref:`global options<global-configuration>`.



.. confval:: maxDelay

   Default: ``0``

   Type: *int*

   Unit: *s*

   If greater than 0, then all traces for which the data latency is
   higher than this value are hidden. 0 disables the feature.


.. confval:: resortAutomatically

   Default: ``true``

   Type: *boolean*

   If enabled, then all traces are sorted by distance when a new
   origin arrives.


.. confval:: showPicks

   Default: ``true``

   Type: *boolean*

   If enabled, picks are shown.


.. confval:: mapPicks

   Default: ``false``

   Type: *boolean*

   Map picks to best matching rows. This is important
   if picks created on BHN should be shown but only the BHZ trace
   is part of the list. Network code, station code and location code
   must match anyway.


.. confval:: filter

   Type: *string*

   Define the filter to be used when filtering is activated. This
   parameter is ignored if \"filters\" is configured.
   This parameter exists mainly for backward compatibility.


.. confval:: filters

   Default: ``"RMHP(2)>>ITAPER(5)>>BW(3,0.5,8.0)","RMHP(2)>>ITAPER(5)>>BW_HP(3, 3)"``

   Type: *list:string*

   Define a list of filters that is cycles through when pressing
   'G' or 'D'. Filtering is toggled with 'F'.
   This parameter supersedes \"filter\". If undefined,
   \"filter\" is used instead. If defined, this filter
   list is used exclusively and the filter option is ignored.
   
   Formats:
   
   \"filter grammar\": filter grammar is shown in
   the scrttv filter selection and applied.
   
   \"name;filter grammar\": name is shown in the scrttv
   filter selection but filter grammar is applied.


.. confval:: autoApplyFilter

   Default: ``false``

   Type: *boolean*

   Activate the first filter of the configured filter list
   after startup. This is equivalent to pressing 'f'.


.. confval:: bufferSize

   Default: ``1800``

   Type: *int*

   Unit: *s*

   Define the buffer size in seconds of the ring bu of each trace.


.. confval:: allTracesInitiallyVisible

   Default: ``false``

   Type: *boolean*

   If set to true, all traces will be visible on application startup
   independent of data availability.


.. confval:: autoResetDelay

   Default: ``900``

   Type: *int*

   Unit: *s*

   Time span in seconds to switch back to the last view after an origin
   caused resorting. The default is 15 min.


.. confval:: 3c

   Default: ``false``

   Type: *boolean*

   If enabled, all three components \(vertical, 1st and 2nd horizontal\)
   related to the detecStream will be shown rather than only the
   component configured in global bindings. The option is ignored
   when using \-\-no\-inventory.


.. confval:: messaging.groups.config

   Default: ``CONFIG``

   Type: *string*

   The messaging group to which config messages \(such
   as station enable\/disable messages\) are being sent.


.. confval:: messaging.groups.location

   Default: ``LOCATION``

   Type: *string*

   The messaging group to which location messages
   are being sent.


.. confval:: streams.codes

   Type: *list:string*

   The list of channel codes to be displayed. List items
   may contain wildcards at any position and are separated
   by comma. Wildcard support depends on RecordStream,
   e.g.:
   
   caps\/sdsarchive: \*.\*.\*.\*
   
   slink: NET.STA.\*.\*
   
   The channel list is intersected with all channels
   configured in inventory unless \-\-no\-inventory is used.
   
   Examples:
   
   default : display all streams configured by global
   bindings
   
   default, PF.BON.00.HH? : display default and all HH
   streams of PF.BON.00


.. confval:: streams.blacklist

   Type: *list:string*

   If not empty then all stream patterns are part of the blacklist.
   The blacklist is only active if \"streams.codes\"
   is omitted and the default stream list according to the
   bindings is to be shown. Each pattern can include wildcards
   \(either ? or \*\). The pattern is checked against the channel
   id which is a concatenation of network code, station code,
   location code and channel code separated with a dot,
   e.g. \"GE.MORC..BHZ\".


.. confval:: streams.rows

   Type: *integer*

   Number of rows to show at once in one windows. If more traces
   than rows are loaded, the are accessible by a scroll bar.


.. confval:: streams.groups

   Type: *string*

   Stream group profiles to be considered which must be defined in
   group section. Use comma separation for a list of groups.


.. confval:: streams.profiles

   Type: *string*

   Stream profiles to be considered which must be defined in
   profile section. Use comma separation for a list of profiles.


.. note::
   **streams.sort.\***
   *Configure the initial stream sorting.*



.. confval:: streams.sort.mode

   Default: ``distance``

   Type: *string*

   The sort mode applied initially. Allowed values
   are: config, distance, station, network, group.


.. confval:: streams.sort.latitude

   Default: ``0.0``

   Type: *double*

   Unit: *deg*

   Latitude of the initial location for sorting traces.
   Only valid if mode \=\= distance.


.. confval:: streams.sort.longitude

   Default: ``0.0``

   Type: *double*

   Unit: *deg*

   Longitude of the initial location for sorting traces.
   Only valid if mode \=\= distance.


.. note::
   **streams.region.\***
   *Define a region used for clipping requested stations.*



.. confval:: streams.region.lonmin

   Default: ``-180.0``

   Type: *double*

   Unit: *deg*

   Minimum longitude.


.. confval:: streams.region.lonmax

   Default: ``180.0``

   Type: *double*

   Unit: *deg*

   Maximum longitude.


.. confval:: streams.region.latmin

   Default: ``-90.0``

   Type: *double*

   Unit: *deg*

   Minimum latitude.


.. confval:: streams.region.latmax

   Default: ``90.0``

   Type: *double*

   Unit: *deg*

   Maximum latitude.


.. note::
   **streams.group.\***
   *Definiton of stream groups shown in scrttv with unique features.*
   *Register the profiles in "groups" to apply them.*



.. note::

   **streams.group.$name.\***
   $name is a placeholder for the name to be used and needs to be added to :confval:`streams.groups` to become active.

   .. code-block:: sh

      streams.groups = a,b
      streams.group.a.value1 = ...
      streams.group.b.value1 = ...
      # c is not active because it has not been added
      # to the list of streams.groups
      streams.group.c.value1 = ...


.. confval:: streams.group.$name.members

   Type: *list:string*

   List of channels codes to be displayed within
   this group. List items may contain wildcards at any position
   and are separated by comma.
   The list is	intersected with all channels configured in inventory.
   
   Example:
   
   CX.\*..BH?,PF.BON.00.HH? : all BH streams of the CX network
   and all HH streams of PF.BON.00


.. confval:: streams.group.$name.title

   Type: *string*

   Title of the group visible as a tooltip of the traces.


.. note::
   **streams.group.$name.pen.\***
   *Define the trace pen of the group.*



.. confval:: streams.group.$name.pen.color

   Type: *color*

   The color of the pen. If not given, the default
   trace color is being used. The parameter is overridden
   by \"streams.group.\$profile.gradient\" .


.. confval:: streams.group.$name.pen.gradient

   Type: *gradient*

   Define the color gradient used to generate the
   trace color for each group member. When given, the
   value in \"streams.group.\$profile.pen.color\"
   is ignored. The colors are distributed equally and
   given in hexadecimal representation or by or
   :term:`color keyword names`.
   The stop points
   can be set at any value. The final trace color
   will be interpolated from the normalized gradient
   where the value range is scaled to [0,1].
   
   Format: value1:color1,value2:color2
   
   Examples:
   
   0:yellow,1:green
   
   0:FFBF00,1:C70039


.. confval:: streams.group.$name.pen.style

   Default: ``SolidLine``

   Type: *string*

   The style of the pen. Supported values are: NoPen,
   SolidLine, DashLine, DotLine, DashDotLine,
   DashDotDotLine.


.. confval:: streams.group.$name.pen.width

   Default: ``1.0``

   Type: *double*

   Unit: *px*

   The width of the pen.


.. note::
   **streams.profile.\***
   *Definiton of profiles for streams shown with unique decorations.*
   *Register the profiles in "profiles" to apply them.*



.. note::

   **streams.profile.$name.\***
   $name is a placeholder for the name to be used and needs to be added to :confval:`streams.profiles` to become active.

   .. code-block:: sh

      streams.profiles = a,b
      streams.profile.a.value1 = ...
      streams.profile.b.value1 = ...
      # c is not active because it has not been added
      # to the list of streams.profiles
      streams.profile.c.value1 = ...


.. confval:: streams.profile.$name.match

   Type: *string*

   Stream applying this profile to. Use regular expressions
   for defining multiple streams. Examples:
   
   GR.BFO.00.BHZ: One stream on vertical component
   
   
   GR.\*.00.BHZ: All stations from GR network and their
   vertical components.


.. confval:: streams.profile.$name.description

   Type: *string*

   Text added to streams.


.. confval:: streams.profile.$name.minMaxMargin

   Default: ``0.0``

   Type: *double*

   Fraction of trace amplitude added to trace widgets.


.. confval:: streams.profile.$name.unit

   Type: *string*

   The physical unit shown along with stream maximum and
   minimum values.


.. confval:: streams.profile.$name.gain

   Default: ``0.0``

   Type: *double*

   The gain applied to scale trace amplitudes. 0 disables
   showing trace amplitude value


.. confval:: streams.profile.$name.fixedScale

   Default: ``false``

   Type: *boolean*

   


.. note::
   **streams.profile.$name.minimum.\***
   *Properties defining the minimum line on each trace.*



.. confval:: streams.profile.$name.minimum.value

   Default: ``0.0``

   Type: *double*

   Value at which to draw a line.


.. note::
   **streams.profile.$name.minimum.pen.\***
   *Line properties.*



.. confval:: streams.profile.$name.minimum.pen.width

   Default: ``1``

   Type: *string*

   


.. confval:: streams.profile.$name.minimum.pen.style

   Default: ``solidline``

   Type: *string*

   


.. confval:: streams.profile.$name.minimum.pen.color

   Default: ``000000ff``

   Type: *string*

   


.. note::
   **streams.profile.$name.minimum.brush.\***
   *Properties of the area below the minimum.*



.. confval:: streams.profile.$name.minimum.brush.style

   Default: ``nobrush``

   Type: *string*

   


.. confval:: streams.profile.$name.minimum.brush.color

   Default: ``000000ff``

   Type: *string*

   


.. note::
   **streams.profile.$name.maximum.\***
   *Properties defining the maximum line on each trace.*



.. confval:: streams.profile.$name.maximum.value

   Default: ``0.0``

   Type: *double*

   Value at which to draw a line.


.. note::
   **streams.profile.$name.maximum.pen.\***
   *Line properties.*



.. confval:: streams.profile.$name.maximum.pen.width

   Default: ``1``

   Type: *string*

   


.. confval:: streams.profile.$name.maximum.pen.style

   Default: ``solidline``

   Type: *string*

   


.. confval:: streams.profile.$name.maximum.pen.color

   Default: ``000000ff``

   Type: *string*

   


.. note::
   **streams.profile.$name.maximum.brush.\***
   *Properties of the area above the maximum.*



.. confval:: streams.profile.$name.maximum.brush.style

   Default: ``nobrush``

   Type: *string*

   


.. confval:: streams.profile.$name.maximum.brush.color

   Default: ``000000ff``

   Type: *string*

   


.. note::
   **associator.\***
   *Define parameters for manually associating phases to origin and*
   *for locating the origins.*



.. confval:: associator.defaultLocator

   Type: *string*

   The locator which is activated as default locator.


.. confval:: associator.defaultLocatorProfile

   Type: *string*

   The locator profile which is activated as default profile for
   the default locator.


.. confval:: associator.fixedDepths

   Default: ``0, 10, 18``

   Type: *list:double*

   Unit: *km*

   A list of depths used to populate the locator depth selection
   dropdown list.


.. note::
   **spectrogram.\***
   *Define parameters for spectrogram representation.*



.. confval:: spectrogram.smoothing

   Default: ``false``

   Type: *boolean*

   Whether to plot the spectrogram filtered bilinearily.


.. confval:: spectrogram.logScale

   Default: ``false``

   Type: *boolean*

   Whether to use logarithmic frequency scale.


.. confval:: spectrogram.normalization

   Default: ``fixed``

   Type: *string*

   Which amplitude normalization mode to use: \"fixed\",
   \"frequency\" or \"time\".


.. confval:: spectrogram.axis

   Default: ``false``

   Type: *boolean*

   Whether to show the frequency axis.


.. confval:: spectrogram.minimumAmplitude

   Default: ``-15``

   Type: *double*

   Unit: *log(ps)*

   The lower bound of the static amplitude range give as logarithm of
   the power spectrum \(log\(real\*\*2 + imag\*\*2\)\).


.. confval:: spectrogram.maximumAmplitude

   Default: ``-5``

   Type: *double*

   Unit: *log(ps)*

   The upper bound of the static amplitude range give as logarithm of
   the power spectrum \(log\(real\*\*2 + imag\*\*2\)\).


.. confval:: spectrogram.minimumFrequency

   Default: ``0``

   Type: *double*

   Unit: *Hz*

   The lower bound of the frequency to be shown.


.. confval:: spectrogram.maximumFrequency

   Default: ``0``

   Type: *double*

   Unit: *Hz*

   The upper bound of the frequency to be shown. Zero is a special
   value and means \"auto\" and sets the maximum
   frequency from the spectra.


.. confval:: spectrogram.timeSpan

   Default: ``20``

   Type: *double*

   Unit: *s*

   The time span of each data slice used to compute the
   frequency spectrum.


.. confval:: spectrogram.overlap

   Default: ``0.5``

   Type: *double*

   The overlap of the data time window between zero and one
   \(exclusive\).



Command-Line Options
====================

.. program:: scrttv

:program:`scrttv [options] [miniSEED file]`


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file arg

   Use alternative configuration file. When this option is
   used the loading of all stages is disabled. Only the
   given configuration file is parsed and used. To use
   another name for the configuration create a symbolic
   link of the application or copy it. Example:
   scautopick \-> scautopick2.

.. option:: --plugins arg

   Load given plugins.

.. option:: --auto-shutdown arg

   Enable\/disable self\-shutdown because a master module shutdown.
   This only works when messaging is enabled and the master
   module sends a shutdown message \(enabled with \-\-start\-stop\-msg
   for the master module\).

.. option:: --shutdown-master-module arg

   Set the name of the master\-module used for auto\-shutdown.
   This is the application name of the module actually
   started. If symlinks are used, then it is the name of
   the symlinked application.

.. option:: --shutdown-master-username arg

   Set the name of the master\-username of the messaging
   used for auto\-shutdown. If \"shutdown\-master\-module\" is
   given as well, this parameter is ignored.


Verbosity
---------

.. option:: --verbosity arg

   Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
   4:debug.

.. option:: -v, --v

   Increase verbosity level \(may be repeated, eg. \-vv\).

.. option:: -q, --quiet

   Quiet mode: no logging output.

.. option:: --component arg

   Limit the logging to a certain component. This option can
   be given more than once.

.. option:: -s, --syslog

   Use syslog logging backend. The output usually goes to
   \/var\/lib\/messages.

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

   Execute in debug mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 .

.. option:: --log-file arg

   Use alternative log file.

.. option:: --print-component arg

   For each log entry print the component right after the
   log level. By default the component output is enabled
   for file output but disabled for console output.

.. option:: --trace

   Execute in trace mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 \-\-print\-component\=1
   \-\-print\-context\=1 .


Messaging
---------

.. option:: -u, --user arg

   Overrides configuration parameter :confval:`connection.username`.

.. option:: -H, --host arg

   Overrides configuration parameter :confval:`connection.server`.

.. option:: -t, --timeout arg

   Overrides configuration parameter :confval:`connection.timeout`.

.. option:: -g, --primary-group arg

   Overrides configuration parameter :confval:`connection.primaryGroup`.

.. option:: -S, --subscribe-group arg

   A group to subscribe to.
   This option can be given more than once.

.. option:: --content-type arg

   Overrides configuration parameter :confval:`connection.contentType`.

.. option:: --start-stop-msg arg

   Set sending of a start and a stop message.


Database
--------

.. option:: --db-driver-list

   List all supported database drivers.

.. option:: -d, --database arg

   The database connection string, format:
   service:\/\/user:pwd\@host\/database.
   \"service\" is the name of the database driver which
   can be queried with \"\-\-db\-driver\-list\".

.. option:: --config-module arg

   The config module to use.

.. option:: --inventory-db arg

   Load the inventory from the given database or file, format:
   [service:\/\/]location .

.. option:: --db-disable

   Do not use the database at all


Records
-------

.. option:: --record-driver-list

   List all supported record stream drivers.

.. option:: -I, --record-url arg

   The recordstream source URL, format:
   [service:\/\/]location[#type].
   \"service\" is the name of the recordstream driver
   which can be queried with \"\-\-record\-driver\-list\".
   If \"service\" is not given, \"file:\/\/\" is
   used.

.. option:: --record-file arg

   Specify a file as record source.

.. option:: --record-type arg

   Specify a type for the records being read.


Options
-------

.. option:: -i, --input-file xml

   Load picks in given XML file during startup


Mode
----

.. option:: --filter arg

   Overrides configuration parameter :confval:`filter`.

.. option:: --offline

   Do not connect to a messaging server and do not use the
   database.

.. option:: --no-inventory

   Do not read streams from inventory but display all streams
   available from the specified record source. This option may
   be combined with the streams.codes parameter to filter the
   available streams.

.. option:: --end-time arg

   Set the acquisition end time, e.g. '2017\-09\-08 13:30:00',
   default: 'gmt'.

.. option:: --buffer-size arg

   Overrides configuration parameter :confval:`bufferSize`.

.. option:: --max-delay arg

   Overrides configuration parameter :confval:`maxDelay`.

.. option:: --start-at-now

   Subscribe to data starting at now rather than now \- bufferSize

.. option:: --rt

   Do not ask for time window at data server. This might be
   important if e.g. Seedlink does not allow time window
   extraction.

.. option:: --map-picks

   Overrides configuration parameter :confval:`mapPicks`.

.. option:: --3c

   Overrides configuration parameter :confval:`3c`.

.. option:: --channels

   Channel\(s\) to display. The channel code may contain wildcards
   at any position but the support of wildcards depends on
   RecordStream. Repeat the option for multiple
   channel groups. Examples:
   
   default : all streams configured by global bindings.
   
   GE.\*.\*.HH? : all HH channels of all stations from GE network.


Cities
------

.. option:: --city-xml arg

   The path to the cities XML file. This overrides the default
   paths. Compare with the global parameter \"citiesXML\".


User interface
--------------

.. option:: -F, --full-screen

   Start the application filling the entire screen.
   This only works with GUI applications.

.. option:: -N, --non-interactive

   Use non\-interactive presentation mode. This only works with
   GUI applications.

