.. highlight:: rst
.. _scmvx:
#####
scmvx
#####
**Map view showing maps with stations and events. Issues related to
configuration of stations are indicated.**
Description
===========
.. raw:: html
.. figure:: media/scmvx-events-tab.png
:alt: scmvx events tab
Events tab
.. figure:: media/scmvx-tabs-network.png
:alt: scmvx network tab
Network tab
.. figure:: media/scmvx-tabs-gm.png
:alt: scmvx ground motion tab
Ground motion tab
.. figure:: media/scmvx-tabs-qc.png
:alt: scmvx quality control tab
Quality control tab
.. raw:: html
scmvx (SeisComP map view extended) provides maps that visualize information of
stations, :term:`events` and phase picks at stations. Events are
received and updated in real time or loaded from a |scname| database. Stations
are loaded from inventory independent of bindings but compared with bindings.
Station information include:
* Location (not sensor location) along with network, station and full
stream code. The latter is defined by global bindings.
* Current ground motion.
* Current station quality.
* Current trigger status.
* Instantaneous waveforms.
* Station inventory and bindings configuration issues.
The maps can be customized by global :confval:`scheme.map` parameters and
additional layers can be added as outlined in the
:ref:`GUI documentation `.
:program:`scmvx` shows all information in tabes which are outlined in section
:ref:`sec-scmvx-tabs`. More applications and use cases are described in section
:ref:`sec-scmvx-use-cases`.
.. note::
scmvx is the next generation of :ref:`scmv` which is deprecated but shipped
along with the |scname| package for maintaining backwards compatibility.
.. _sec-scmvx-tabs:
Tabs
====
scmvx provides multiple :ref:`tabs ` for visualizing stations
along with station parameters or issues and for showing events updated in
real time or read from the |scname| database:
* :ref:`Network `: Map showing events and network
information including station configuration and inventory issues.
* :ref:`Ground motion `: Map with events and stations. The
color of stations symbols represents recent ground motion calculated by scmvx
in a configurable time window.
* :ref:`Quality control `: Map with events and stations. The
color of stations symbols represents recent waveform quality control
parameters calculated by :ref:`scqc`.
* :ref:`Events `: Event list updated in real time and
allowing to filter events and to load historic events from database.
Stations with recent phase picks are blinking with red triangles.
When a new event arrives, the details are shown and updated in the latest event
field. Yellow and blue circles indicate the predicted wavefronts of P and S
phases, respectively. The wavefronts fade out and disappear depending on
magnitude.
Any tab can be shown in full-screen mode (:kbd:`F11`) where it is detached
from the main window and shown without any frame.
.. note::
The following figures show maps which are optimized for file size (134 MByte)
and coloring and made available by :cite:t:`gempa`:
.. code-block:: sh
cd Downloads
wget -O /tmp/maps.tar "https://data.gempa.de/packages/Public/maps/gempa-minimal/gempa-minimal.tar"
cd $SEISCOMP_ROOT/..
tar -xvf /tmp/maps.tar
rm /tmp/maps.tar
You may add the maps to your global configuration
(:file:`$SEISCOMP_ROOT/etc/global.cfg`):
.. code-block:: properties
map.location = @DATADIR@/maps/world%s.png
map.format = mercator
.. _sec-scmvx-network-tab:
Network
-------
The network tab shows all stations available with the loaded inventory.
Station symbols (triangles) and event (circles) are color-coded according to
network code and source depth, respectively. Activate the legend (right-click
on map) for the color-coding. Stations having issues in global bindings or
inventory are highlighted by error symbols.
.. _fig-scmvx-network-tab:
.. figure:: media/scmvx-tabs-network.png
:width: 16cm
:align: center
Network tab showing stations and events. Two events were received
recently. The yellow and blue circles indicate the predicted wavefronts of
P and S phases, respectively, with their degrees of epicentral distance shown
next to the circles.
Clicking on a station opens the details view showing stations details and
waveforms. Issues are explained.
.. _fig-scmvx-network-tab-issue:
.. figure:: media/scmvx-tabs-network-issue.png
:width: 16cm
:align: center
Network tab explaining a conflict of a station binding configuration with
loaded inventory. Click on the corresponding station symbol for opening the
details view.
.. _fig-scmvx-network-tab-issue-no-gb:
.. figure:: media/scmvx-tabs-network-issue-no-gb.png
:width: 16cm
:align: center
Network tab indicating a station with missing global bindings.
.. _sec-scmvx-gm-tab:
Ground motion
-------------
The ground motion tab shows the current ground motion situation at a station.
Station symbols (triangles) and event (circles) are color-coded according to
recent ground motion and source depth, respectively.
.. _fig-scmvx-gm-tab:
.. figure:: media/scmvx-tabs-gm.png
:width: 16cm
:align: center
Ground motion tab with stations (triangles) and events.
.. _fig-scmvx-gm-tab-event:
.. figure:: media/scmvx-tabs-gm-event.png
:width: 16cm
:align: center
Ground motion tab. Clicking on an event symbol (circle) opens the object
inspector in which the event details can be read.
.. _fig-scmvx-gm-tab-event:
.. figure:: media/scmvx-tabs-gm-station.png
:width: 16cm
:align: center
Ground motion tab. Clicking on a station symbol (triangle) opens the details
view in which station details and waveforms can be read.
.. _sec-scmvx-qc-tab:
Quality control
---------------
The quality control tab shows current waveform QC parameters as computed by
:ref:`scqc` which must be running for showing the values.
.. _fig-scmvx-qc-tab:
.. figure:: media/scmvx-tabs-qc.png
:width: 16cm
:align: center
Quality control (QC) tab. The QC parameter type may be selected in the View
menu. Here, the maps are greyed out interactively (:kbd:`G`).
.. _sec-scmvx-events-tab:
Events
------
Events are shown as they arrive in real time and may be interactively loaded
from database and filtered thereafter in the Events tab.
During startup events from within a period of time are loaded and shown
according the configuration of :confval:`readEventsNotOlderThan`.
More events are added in real time as they arrive.
Historic events can be loaded from database for time spans and other filter
criteria.
The loaded events can be sorted interactively by clicking on the table header.
Events out of scope can be hidden based on region, event type or agency ID.
In contrast to other event lists, e.g. in :ref:`scolv` or :ref:`scesv`, this
event list only gives access to parameter of the preferred but no other origins
of events.
.. _fig-scmvx-events-tab:
.. figure:: media/scmvx-events-tab.png
:width: 16cm
:align: center
Events tab with events loaded from database and updated in real time.
Hotkeys
-------
.. csv-table::
:header: Hotkey, Description
:widths: 30,70
:delim: ;
C; Center map around latest event upon event update
G; Show map base layer in gray scale
N; Reset view to default
:kbd:`F1` ;Open SeisComP documentation in default browser
:kbd:`Shift + F1` ;Open scmvx documentation in default browser
:kbd:`F2` ;Open dialog for connecting to database and messaging
:kbd:`F6` ;Toggle latest event information on map
:kbd:`F7` ;Toggle legend
:kbd:`F8` ;Toggle station issues in Network tab
:kbd:`F9` ;Toggle station annotation
:kbd:`F10` ;Switch to event list (Events tab)
:kbd:`F11` ;Toggle full screen mode
:kbd:`CTRL + F` ;Search station
:kbd:`CTRL + O` ;Open event parameter XML file
:kbd:`CTRL + Q` ;Quit scmvx
:kbd:`left`, :kbd:`right`, :kbd:`up`, :kbd:`down` ;Move focus of map left, right, up, down
Double mouse click ;Center map
Mouse wheel ;Zoom in or out in map
:kbd:`+` ;Zoom in into map around current center
:kbd:`-` ;Zoom out in map around current center
:kbd:`Shift` + Hold left mouse button + Drag ;Select a map area and zoom into it
Right mouse button ;Open context menu
.. _sec-scmvx-use-cases:
Use Cases
=========
Identify networks
-----------------
Application:
* Identify a network on map.
Procedure:
#. Navigate to the :ref:`Network tab`.
#. Activate the legend: Right-click on map, select *Show legend(s)*.
#. Identify all stations by the color of the corresponding network.
Search stations
---------------
Application:
* Identify a station on map.
Procedure:
#. Press :kbd:`CTRL + F` to open the search window.
#. Type any string from a station and/or network name in the input field or just
select a station from the list.
#. Double click in a station in the list to center the map at this location.
Get station information, detail issues
--------------------------------------
Application:
* Read station information.
* Identify and read station inventory and bindings configuration issues (in
:ref:`Network tab`).
* View instantaneous waveforms.
Procedure:
#. Navigate to the :ref:`Network tab`.
#. Position the mouse above a triangle representing a station. The selected
station is highlighted. Zoom in if stations are overlapping.
#. Click your left mouse button for opening the station info widget.
Data and potential configuration issues are shown.
Search for and show an event
----------------------------
Application:
* Browse event catalogs in |scname| database.
* Search the list of loaded events.
Procedure:
#. Navigate to the :ref:`Events tab` load events from
database in a relevant time range. You may narrow down the database search
through the filter button. After events are loaded the list may be limited by
hiding irrelevant events and you may change the sorting of the event table by
clicking on the header.
#. Identify the event and double-click on the event line to load the parameters.
You will immediately switch to a map centered around the selected event.
Get event information
---------------------
Application:
* View event details.
* Send origin information to other applications, e.g., :ref:`scolv` for further
processing.
Procedure:
#. Position the mouse above a circle representing the location of an event.
Zoom in if events are overlapping.
#. Click the left mouse button for opening the event object inspector.
#. Click on **Show details** for sending the origin to the messaging for further
processing, e.g., by :ref:`scolv`.
Set artificial origin
---------------------
Application:
* Identify an event of interest, e.g., by blinking stations.
* Send origin information to other applications, e.g. :ref:`scolv` for further
processing from scratch.
Procedure:
#. Position the mouse in the map.
#. Press the middle mouse button.
#. Set date & time and latitude, longitude & depth.
#. Press "Create" to open the origin in another GUI, e.g., :ref:`scolv` which
must be running already.
Command-Line Examples
=====================
* Real-time view of events and stations on a local server
.. code-block:: properties
scmvx -H localhost -I slink://localhost --debug
* Offline view of event parameters given in an XML file. Inventory is read from
database.
.. code-block:: properties
scmvx -d localhost -i events.xml --debug
.. _scmvx_configuration:
Module Configuration
====================
| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/scmvx.cfg`
| :file:`etc/global.cfg`
| :file:`etc/scmvx.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/scmvx.cfg`
scmvx inherits :ref:`global options`.
.. confval:: displaymode
Type: *string*
Values: ``groundmotion,qualitycontrol``
Set one of the available display modes used during startup. When
empty, the Network tab is shown.
.. confval:: readEventsNotOlderThan
Default: ``86400``
Type: *double*
Unit: *s*
Sets the time span before current time to read events initially
from database.
.. confval:: centerOrigins
Default: ``false``
Type: *boolean*
If a new origin\/event is set\/selected, this option defines if
the map is centered or not at the origin location.
.. confval:: annotations
Default: ``false``
Type: *boolean*
Enables\/disabled drawing of station annotations at startup.
.. confval:: annotationsWithChannels
Default: ``true``
Type: *boolean*
Show full stream codes with station annotations including
location and channel codes as NET.STA.LOC.CHA.
.. confval:: showUnboundStations
Default: ``true``
Type: *boolean*
Enable\/disable drawing of stations which are not bound with
global bindings.
.. confval:: mapLegendPosition
Default: ``topleft``
Type: *string*
Values: ``topleft,topright,bottomright,bottomleft``
The legend location for station symbols \(network, QC, ground
motion\).
.. confval:: eventLegendPosition
Default: ``bottomleft``
Type: *string*
Values: ``topleft,topright,bottomright,bottomleft``
The legend location for event symbols.
.. confval:: stations.amplitudeTimeSpan
Default: ``10``
Type: *double*
Unit: *s*
Time span for forming the maximum value as envelope to the
traces in the trace window for a station.
.. confval:: stations.groundMotionRecordLifeSpan
Default: ``600``
Type: *double*
Unit: *s*
Time to keep waveform data in memory.
.. confval:: stations.triggerTimeout
Default: ``60``
Type: *double*
Unit: *s*
Time span to show phase picks of a station by a blinking
triangle.
.. confval:: stations.groundMotionFilter
Default: ``ITAPER(60)>>BW_HP(4,0.5)``
Type: *string*
Sets the filter applied to determine ground motion.
.. note::
**display.\***
*The initial rectangular region for the map. The eventual region*
*is also scaled to the dimension of the opened map widget.*
.. confval:: display.latmin
Default: ``-90.0``
Type: *double*
Unit: *deg*
Range: ``-90:90``
Minimum latitude in degrees.
.. confval:: display.lonmin
Default: ``-180.0``
Type: *double*
Unit: *deg*
Range: ``-360:360``
Minimum longitude in degrees.
.. confval:: display.latmax
Default: ``90.0``
Type: *double*
Unit: *deg*
Range: ``-90:90``
Maximum latitude in degrees.
.. confval:: display.lonmax
Default: ``180.0``
Type: *double*
Unit: *deg*
Range: ``-360:360``
Maximum longitude in degrees.
Command-Line Options
====================
.. program:: scmvx
:program:`scmvx [options]`
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 .
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.
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`.
Default: ``binary``
.. option:: --start-stop-msg arg
Default: ``0``
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 and simply the name of a miniSEED file can be given.
.. option:: --record-file arg
Specify a file as record source.
.. option:: --record-type arg
Specify a type for the records being read.
Cities
------
.. option:: --city-xml arg
Type: *file*
Values: ``*.xml``
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.
MapviewX
--------
.. option:: --display-mode arg
Overrides configuration parameter :confval:`displaymode`.
.. option:: -i, --input-file file
Load events in given XML file during startup and switch to
offline mode.
.. option:: --offline
Do not connect to a messaging server and do not subscribe
channel data.
.. option:: --with-legend
Show the map legends.