.. highlight:: rst

.. _scheli:

######
scheli
######

**Real-time helicorder view for one stream.**


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

:program:`scheli` visualizes waveforms from a single stream or multiple stations
mimicking a drum-recorder plot (see :ref:`fig-scheli`):

* :program:`scheli` plots one configurable trace in helicorder style in the
  :term:`GUI` (:ref:`GUI mode <scheli-show>`).
* Configurable GUI: trace colors, visualized time spans, number of rows, data filtering,
  amplitude ranges and much more.
* Automatic image capturing: Capture helicorder images at configurable time intervals
  of one trace in :ref:`GUI mode<scheli-show>` or a set of multiple channels in
  :ref:`capture mode<scheli-capture>`.
  The images can be used, e.g. for showing data images on web sites.

.. _fig-scheli:

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

   scheli in GUI mode


Examples
========

.. _scheli-show:

1. **GUI mode - Simple helicorder window:**

   * Learn about the plenty command-line options for :program:`scheli`: ::

        scheli -h

   * Start :program:`scheli` with the configured values and informative debug output: ::

        scheli --debug

   * Let :program:`scheli` show data from the CX station PB01 for the previous
     5 hours overriding configuration by command-line paramaters:

     .. code-block:: sh

        scheli --stream CX.PB01..HHZ --rows 10

   * Define the data request window by end time and duration; scale traces to the
     maximum amplitude per row: ::

        scheli --stream IU.TSUM.00.BHZ --end-time "2021-04-22 14:00:00" --time-span 600 --amp-scaling row

.. _scheli-capture:

2. **Capture mode - Image capturing:**

   Capture the helicorder plot for 3 stations in intervals of 10 seconds.
   The data is retrieved using seedlink and the plots are stored as PNG images.
   The image files are named according to network, station, stream and location codes
   of the requested stations. Command-line parameters override the module configuration.

   .. code-block:: sh

      scheli capture --stream CX.PB01..HHZ --stream CX.PB02..HHZ --stream CX.PB04..HHZ --interval 10 -o "/tmp/heli_%N_%S_%L_%C.png" -H localhost -I slink://localhost

   The output file names will be generated based on network code (%N), station code (%S),
   location code (%L) and stream code (%C): ::

      /tmp/CX.PB01..HHZ.png
      /tmp/CX.PB02..HHZ.png
      /tmp/CX.PB04..HHZ.png

Setup
=====

Specifc :program:`scheli` parameters are adjusted in the :ref:`module configuration <scheli_configuration>`.
Colors of traces etc. can be adjusted by setting the *scheme* parameters in
the global configuration of scheli. For alternating colors between the traces
set the parameters scheme.colors.records.foreground and
scheme.colors.records.alternateForeground in :file:`scheli.cfg`:

.. code-block:: sh

   # The general color of records/traces.
   scheme.colors.records.foreground = 4286F4

   # A general trace color of the alternate trace (eg scheli).
   scheme.colors.records.alternateForeground = B72D0E


.. _scheli_configuration:

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

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

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



.. confval:: heli.streams

   Type: *list:string*

   List of stream codes to be plotted.
   If not in capture mode, only the first stream is shown.
   When using a list, the first entry is considered.
   Use commas for separating streams.
   
   Format: NET.STA.LOC.CHA
   
   Example: GR.CLL..BHZ,GR.MOX..BHZ


.. confval:: heli.filter

   Type: *string*

   Filter to be applied on the data.


.. confval:: heli.numberOfRows

   Default: ``48``

   Type: *integer*

   Filter to be applied on the data.


.. confval:: heli.rowTimeSpan

   Default: ``1800``

   Type: *double*

   Unit: *s*

   Length of data per trace.


.. confval:: heli.timeFormat

   Default: ``%F``

   Type: *string*

   The time format used to print the start and end time of the
   whole plot \(upper right corner\). The format specification is
   the one used in the strftime function \(man strftime\).


.. confval:: heli.recordTime

   Default: ``false``

   Type: *boolean*

   Set current time to last data sample.


.. confval:: heli.lineWidth

   Default: ``1``

   Type: *integer*

   Unit: *px*

   Line width of traces.


.. confval:: heli.colors

   Default: ``FF0000, 0000FF``

   Type: *list:string*

   A list of alternating row colors cycled through for painting
   traces.


.. confval:: heli.antialiasing

   Default: ``false``

   Type: *boolean*

   Use anti aliasing to plot the traces. The default uses the
   settings from scheme.records.antiAliasing


.. confval:: heli.stream.description

   Default: ``true``

   Type: *boolean*

   Add stream description to traces.


.. note::
   **heli.amplitudeRange.\***
   *Gain-corrected amplitudes given in units of the sensor.*
   *For example: m/s.*



.. confval:: heli.amplitudeRange.scaling

   Default: ``minmax``

   Type: *string*

   Values: ``minmax,row``

   Define the method to scale traces within rows. Possible
   values are:
   
   minmax: Scale all rows to configured minimum and maximum
   amplitudes configured by amplitudeRange.min and
   amplitudeRange.max
   
   row: Scale each row to the maximum within this row.


.. confval:: heli.amplitudeRange.min

   Default: ``-0.00001``

   Type: *double*

   Unit: *unit of input data*

   Minimum amplitude to show in trace. Requires
   amplitudeRange.scale \= \"minmax\".


.. confval:: heli.amplitudeRange.max

   Default: ``0.00001``

   Type: *double*

   Unit: *unit of input data*

   Minimum amplitude to show in trace. Requires
   amplitudeRange.scale \= \"minmax\".


.. note::
   **heli.dump.\***
   *Control dumping of PNG images.*
   *Execute "scheli capture" for image generation in*
   *the background without the graphics.*



.. confval:: heli.dump.interval

   Default: ``-1``

   Type: *integer*

   Unit: *s*

   Image creation interval. Negative values disable image
   dumping.
   If enabled, images are generated at the configured
   interval.


.. confval:: heli.dump.outputFile

   Default: ``/tmp/heli_%N_%S_%L_%C.png``

   Type: *string*

   Name of output file.
   The filename can contain placeholders
   that are replaced by the corresponding streamID parts:
   
   %N : network code
   
   %S : station code
   
   %L : location code
   
   %C : channel code
   
   Placeholders are important if more than one stream
   is given and capture mode is active.


.. confval:: heli.dump.dpi

   Default: ``300``

   Type: *integer*

   Unit: *dpi*

   Image resolution.


.. confval:: heli.dump.xres

   Default: ``1024``

   Type: *integer*

   Unit: *px*

   Number of pixels horizontally.


.. confval:: heli.dump.yres

   Default: ``768``

   Type: *integer*

   Unit: *px*

   Number of pixels vertically.


.. confval:: scripts.postprocessing

   Type: *path*

   Define the path to a script that is called whenever an image
   has been captured and written to disc. The only parameter is
   the path to the generated image.



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

.. program:: scheli

:program:`scheli [options]`


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file file

   The alternative module configuration file. When this option
   is used, the module configuration is only read from the
   given file and no other configuration stage is considered.
   Therefore, all configuration including the definition of
   plugins must be contained in that file or given along with
   other command\-line options such as \-\-plugins.

.. option:: --plugins arg

   Load given plugins.

.. option:: -D, --daemon

   Run as daemon. This means the application will fork itself
   and doesn't need to be started with \&.

.. 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, e.g., \-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`.

   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:: --config-db arg

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


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.


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.


Mode
----

.. option:: --offline

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

.. option:: --end-time arg

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


Data
----

.. option:: --stream arg

   The record stream that should be displayed. Can be used
   multiple times for multiple streams.
   
   Example: GR.MOX..BHZ \(net.sta.loc.cha\)

.. option:: --filter arg

   The filter to apply

.. option:: --gain arg

   Unit: *counts/unit*

   Gain applied to the data before plotting

.. option:: --amp-scaling arg

   Default: ``minmax``

   Lower bound of amplitude range per row. Possible values:
   
   minmax: Scale all rows to configured minimum and maximum
   amplitudes.
   
   row: Scale each row to the maximum within this row.

.. option:: --amp-range-min arg

   Lower bound of amplitude range per row

.. option:: --amp-range-max arg

   Upper bound of amplitude range per row

.. option:: --amp-range arg

   Arround zero bound of amplitude range per row

.. option:: --record-time arg

   Do the last row always contain the last record received


Output
------

.. option:: --desc arg

   Enable\/disable the display of a station description

.. option:: --rows arg

   Configure the number of rows to display

.. option:: --time-span arg

   Unit: *s*

   Configure the time\-span \(in secs\) per row. Unit: seconds.

.. option:: --aa arg

   Set antialiasing for rendering the traces

.. option:: --xres arg

   Unit: *dpi*

   Output x resolution when generating images. Unit: dpi.

.. option:: --yres arg

   Unit: *dpi*

   Output y resolution when generating images. Unit: dpi.

.. option:: --dpi arg

   Unit: *dpi*

   Output dpi when generating postscript. Unit:dpi.

.. option:: -o arg

   Output filename. Placeholders are %N,%S,%L,%C for network
   code, station code, location code, channel code.

.. option:: --interval arg

   Unit: *s*

   Snapshot interval \(less than 0 disables timed snapshots\).
   Unit: seconds.

