.. highlight:: rst .. _gis: ### gis ### **Gempa Image Server - Tiny Web server for maps, tiles and trace images** Description =========== GIS is an image server allowing to generate images of various kinds showing event information, maps or waveform data. The images are :ref:`generated upon request ` and delivered in all formats supported by Qt: PNG, JPG, JPEG, BMP, PPM, TIFF, XBM, XPM. * :ref:`Event information ` on a map, optionally along with contributing stations, * :ref:`Station information ` on a map, * Waveform data: * :ref:`time series `, * :ref:`Fourier spectra `, * :ref:`composite images ` consisting of any components from above can be generated by GIS or external tools. The images can be generated :ref:`interactively on demand ` or automatically and on demand by other modules, e.g. `GDS `_. .. note :: The GIS package is automatically provided as a separate package when purchasing `GDS `_. Sources of Information ====================== GIS collects information from different sources depending on the :ref:`requested data type `. The source must be configured or the information must be provided: * Event and origin information is provided by HTTP POST as event XML. This includes: * events with preferred origin, magnitude and focal mechanism / moment tensor, * origins with arrivals and magnitudes, * moment tensors * Inventory information is read from the SeisComP database or from a provided inventory XML file, * Waveforms are read from the configured :term:`RecordStream `. .. hint :: The :term:`RecordStream ` configuration must not include any real-time source, such as seedlink. Use the option `?arch` when fetching data from a CAPS server * Map information: * Map Tiles - loaded from local tile store or map server, * Geo Features - loaded from BNA directory, * Geo Features - transmitted as JSON documents via HTTP POST, * Geo Images - transmitted via HTTP POST in order of their transmission, * Vector Layer - coordinate grid, cities loaed from cities XML file, * Event information, * Screen Images - transmitted via HTTP POST in order of their transmission. .. _gis-requests: Generating Requests =================== The GIS supports HTTP-GET and HTTP-POST requests. The detailed keys, values and descriptions are provided by the documentatin on the GIS Web page. The Web site is provided by the GIS server on port 20001 by default. To view the Web site, start the SeisComP messaging and gis: :: seiscomp start scmaster seiscomp exec gis --debug Then open the Web site with the configured port and view the options, e.g.: :: firefox localhost:20001 .. _fig-gis-webpage: .. figure:: media/gis-webpage.png :align: center :width: 50% GIS Web page exposed by default on http://localhost:20001. Sending Requests ================ Requests can be sent to the GIS server in different ways depending on the request content, e.g.: * A custom Python script * Linux commands :program:`wget` or :program:`curl` Find some examples in the section :ref:`gis-examples`. .. _gis-examples: Examples ======== Maps may contain event and station information alone or together. Data are shown as time series or Fourier spectra. This section provides examples for generating images interactively on demand. .. _gis-event-station: Maps: event with stations ------------------------- Plot :term:`event` information from one more events along with stations providing arrivals. The event and station information are provided in a single file :file:`event-inventory.xml`. Generate this file using :program:`scxmlmerge` or provide the inventory to gis from the database: :: scxmlmerge event.xml inventory.xml > event-inventory.xml curl -X POST -d @event-inventory.xml "http://localhost:20001/map?&dim=1024,512&stations=*&®=-30,180,40,20" -o gis-event-map.png .. _fig-gis-event: .. figure:: media/gis-event-map.png :align: center :width: 50% Map with event information, map features and stations providing arrivals. Multiple events are plotted if contained in the event XML file. .. _gis-inventory: Maps: stations -------------- Generate a map of stations. Post the inventory XML file and draw all stations. The file can be created using :program:`scxmldump`, e.g.: :: scxmldump -d localhost -If -o inventory.xml :: curl -X POST -d @inventory.xml "http://localhost:20001/map?&dim=1024,512®=0,110,20,10&stations=*" -o gis-stations.png .. _fig-gis-inventory: .. figure:: media/gis-stations.png :align: center :width: 50% Example of a map with stations from inventory. .. _gis-waveform-data: Waveform data with arrivals from events --------------------------------------- Generate plots of waveforms with arrival information from one event. The posted file :file:`event.xml` contains the complete event information. The file can be created for an event with ID eventID using :program:`scxmldump`, e.g.: :: scxmldump -d localhost -E [eventID] -PAf -o event.xml curl -X POST -d @event.xml "http://localhost:20001/traces?dim=1024,1024&num=7&fmt=png&buffersize=360&orderby=distance&removeoffset=1&weight=1.0&filter=BW(3,1.0,9.0)&showpicks=true&showtt=true&start=2021-02-03T05:28:00&range=10000000&usegain=true" -o gis-traces-arrivals.png .. _fig-gis-traces-arrival: .. figure:: media/gis-traces-arrivals.png :align: center :width: 50% Example of a trace plot with arrival information. While the measured phased arrivals are marked by red symbols, the theoretical times are indicated with blue dots. .. _gis-event-waveform-data: Waveform data ------------- Generate plots of waveforms for a given time range. Apply the gain to show physical units: :: wget -O gis-traces.png "http://localhost:20001/traces?streams=IU.M*.00.BHZ&dim=1024,700&start=2020-05-01&bufferSize=30000&num=5&usegain=true" .. _fig-gis-traces: .. figure:: media/gis-traces.png :align: center :width: 50% Example of a trace plot. .. _gis-waveform-specs: Fourier spectra --------------- Generate Fourier spectra from waveform data: * Amplitude spectra :: wget -O gis-spectra.png "http://localhost:20001/spectra?stream=IU.ANMO.00.BHZ&dim=1024,500&start=2020-05-01" .. _fig-gis-fourierspec: .. figure:: media/gis-spectra.png :align: center :width: 50% Example of a Fourier amplitude spectrum. * Phase spectra :: wget -O gis-spectra-phase.png "http://localhost:20001/spectra?stream=IU.ANMO.00.BHZ&dim=1024,500&start=2020-05-01?mode=phase" .. _fig-gis-fourierspec-phsae: .. figure:: media/gis-spectra-phase.png :align: center :width: 50% Example of a Fourier phase spectrum. * Power spectra :: wget -O gis-spectra-power.png "http://localhost:20001/spectra?stream=IU.ANMO.00.BHZ&dim=1024,500&start=2020-05-01&mode=power" .. _fig-gis-fourierspec-power: .. figure:: media/gis-spectra-power.png :align: center :width: 50% Example of a Fourier power spectrum. .. _gis-composite: Composite images ---------------- GIS can generate composite images consisting of different images generated before. Module Configuration ==================== | :file:`etc/defaults/global.cfg` | :file:`etc/defaults/gis.cfg` | :file:`etc/global.cfg` | :file:`etc/gis.cfg` | :file:`~/.seiscomp/global.cfg` | :file:`~/.seiscomp/gis.cfg` gis inherits :ref:`global options`. .. note:: Modules/plugins may require a license file. The default path to license files is :file:`@DATADIR@/licenses/` which can be overridden by global configuration of the parameter :confval:`gempa.licensePath`. Example: :: gempa.licensePath = @CONFIGDIR@/licenses .. confval:: dbDisable Default: ``false`` Type: *boolean* If set to true, no inventory and configuration is fetched from the database. Also no connection attempt to the messaging system is made to retrieve the database parameters. .. confval:: bind Default: ``127.0.0.1:20001`` Type: *host-with-port* IP and port to bind the command interface to. Use 0.0.0.0 to bind to all interfaces. Either the port or the IP address may be omitted, e.g. \"0.0.0.0\" or \":1234\". If set to an empty string the application will run without providing a command interface. .. confval:: rootURL Type: *string* Defines the root URL used to generate links. That option is only important if e.g. Apache with reverse proxy is used to forward GIS webpages. .. confval:: mediaDirectory Default: ``@DATADIR@/gis/media`` Type: *string* Path to media files \(index.html, .css, .js, .ico, ...\) served by GIS. .. confval:: accessLog Default: ``false`` Type: *boolean* Enables HTTP access logging to \@LOGDIR\@\/gis\-http\-access. Logfiles are created for 24h and kept for 7 days using log rotation. .. confval:: ttt Default: ``libtau`` Type: *string* Name of travel time table interface, e.g. 'libtau' or 'locsat' .. confval:: ttColors Type: *list:string* List of case sensitive phase name to color mappings, e.g. \"P:red,S:#00ff00,PP:#aabbcc\". Unmapped phases are not drawn. .. confval:: ttRadius Default: ``3`` Unit: *px* Type: *double* Radius of the travel time circles .. confval:: errorImage Default: ``false`` Type: *boolean* If enabled errors will be reported inside an image file. The HTTP status code will be set to '200 OK' in this case. .. confval:: urlLen Default: ``1024`` Type: *int* Maximum number of URL characters. .. confval:: tilesTimeout Default: ``0`` Unit: *s* Type: *double* Timeout in seconds after which the download of tiles should be aborted. On timeout the requested map image is rendered with an incomplete image layer. This option is only used if an asynchronous tile store is configured. .. confval:: originSymbol Type: *string* Origin symbol image. If defined the image is plotted instead of the standard circle. The size and color still depends on the magnitude and depth. Command-Line Options ==================== 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:: -D, --daemon Run as daemon. This means the application will fork itself and doesn't need to be started with \&. 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. Server ------ .. option:: -p, --port arg Overrides configuration parameter :confval:`port`.