.. _toast_gnss_save: Save displacements ================== Observed displacements can be saved to an XML file via :menuselection:`File --> Save --> Observed displacements as...`. Note that they are stored as displacement objects and not amplitudes, and thus can not be re-imported in |appname|. .. _toast_export: Create warning bulletins and other output using templates ========================================================= .. _toast_bulletins: Bulletin templates ------------------ |appname| provides the possibility for creating and disseminating tsunami bulletins whose content is based on data related to an :term:`incident` (like earthquake origin), to one or several simulations (like forecast zones warning level) or tide gauge observations. Bulletins are generated using so-called :ref:`templates `. You can disseminate a bulletin in following ways: #. Via :menuselection:`Menu --> File --> Export` to execute a :ref:`template ` #. Via button *Disseminate* in a :ref:`Live Tab ` .. hint:: The *Disseminate* button can be renamed using :confval:`liveTab.$name.buttonText`. Technically, clicking the button executes the :ref:`ClearSilver functions ` *save* and *addScript*. .. note:: If :confval:`confirmationRequired` is set, then after clicking the *Disseminate* button and before the external scripts in the templates are executed, the additional dialog: "Do you really want to continue?" pops up. Various output formats are possible, such as :term:`HTML`, :term:`XML`, images or video files. Bulletins can be disseminated via channels as needed, like: text message, e-mail, video stream and other. The format and action related to an export is based on templates whose design is described in detail in :ref:`toast_clear_silver` and the configuration in :ref:`toast_templates`. Live tabs allow the display and dissemination (export) of associated templates and appear as additional :ref:`tabs ` in the :ref:`toast_main_panel`. General scheme ~~~~~~~~~~~~~~ *Templates* can be defined and registered using :program:`scconfig`. They point to a file that describes the region for which the template is active and to a file which contains the actual code of the template. *Live tabs* also have to be defined and registered. They can be associated with one or several templates. .. note:: The sorting of the arrival table in a bulletin depends on the sorting of the :ref:`toast_arrivals_perspective`. The snapshot of a map in a bulletin shows by default the snapshot as selected in the :ref:`toast_map_perspective`. .. _toast_live_tabs: Live Tabs configuration ----------------------- A Live Tab displays data related to an :term:`incident` and results of the :ref:`active ` simulation(s) formatted in a way as encoded in the selected template. .. _fig-live_tab_example: .. figure:: media/toast/export/live_tab_example.png :align: center :width: 18 cm Live Tab PTWC with selected template ptwc_ocean Multiple templates can be configured for each Live tab. To switch the visible template, use the selection box at the top. Upon clicking the *Disseminate* button, all templates of the current live tab are exported (more precisely see: :ref:`Note on export `). To disseminate only a subset of templates, click and hold the button, then go to *With additional options...* and select the desired templates. To suppress the execution of external scripts by the templates using the function *addScript*, uncheck *Run external scripts*. The button text can be changed with :confval:`liveTab.$name.buttonText` and the title of the live tab (:confval:`liveTab.$name.title`). Keep in mind that the export only works if a storage location has been set in the template. .. note:: If :ref:`toast_test_mode` is active, a template can only be activated if the ClearSilver attribute *testMode* is used somewhere in the template. In this case, the template is executed and the *testMode* attribute can be used together with if/elif/else ClearSilver flow controls to modify the behavior of the template. For instance, a TEST header could be added or the dissemination while in test mode could be directed to a different target. The set-up procedure to create a live tab is to: * add a live tab profile (using :program:`scconfig` + Live tab profile), * add the template profile name(s) to it and * register it at :confval:`liveTabs`. Following parameters can be configured in a live tab profile: * :confval:`liveTab.$name.title` * :confval:`liveTab.$name.templ` * :confval:`liveTab.$name.buttonText` Consult hovertips in :program:`scconfig` for more information on the parameters. As an example: :: liveTab.ptwc.title = PTWC liveTab.ptwc.templ = ptwc_ocean, ptwc_region liveTabs = ptwc .. _toast_templates: Templates configuration ----------------------- Templates define how the data related to an :term:`incident` and of the :ref:`active ` simulations is visualized and disseminated. They are added and removed in the same way as live tabs: #. Add a template profile (using :program:`scconfig` + Template profile), #. configure the parameters and #. register the template profile at :confval:`templates.types`. #. Configure the logging of external scripts called by templates at :confval:`templates.logging`. Following parameters can be configured in a template profile: * :confval:`template.$name.aoi` - (Area Of Interest) * :confval:`template.$name.maxMagnitude` * :confval:`template.$name.minMagnitude` * :confval:`template.$name.name` * :confval:`template.$name.fileName` * :confval:`template.$name.prerequisites.scenario` Here is an example configuration for a template profile: :: template.ptwc_ocean.aoi = @DATADIR@/toast/world.bna template.ptwc_ocean.name = "PTWC Ocean" template.ptwc_ocean.fileName = @DATADIR@/toast/templates/ptwc_ocean.html templates.types = ptwc_ocean .. hint:: Don't forget to associate templates with live tabs as described in :ref:`toast_live_tabs`. Figure :ref:`fig-live_tab_example` illustrates an example of a bulletin generated with a template. .. _toast_template_examples: Template file examples ~~~~~~~~~~~~~~~~~~~~~~ The |appname| template file examples are located at: |toastdata|/templates and the example scripts at: |toastdata|/scripts. The standard installation package contains the following example templates: * forecast_zones.html, forecast_zones.kml, forecast_zones.txt * gif, video * ptwc_info.html, ptwc_local.html, ptwc_ocean.html, ptwc_region.html * ssh_max.kml .. note:: Before using the templates, remove the file ending *.example*, to avoid overwriting during a |appname| update: .. code-block:: sh sysop@host:~$ cp $SEISCOMP_ROOT/share/toast/templates/ptwc_ocean.html.example $SEISCOMP_ROOT/share/toast/templates/ptwc_ocean.html This is the template code *ptwc_ocean.html*, which generates the bulletin shown in: :ref:`fig-live_tab_example`: .. include:: media/toast/export/ptwc_ocean.html :literal: .. _toast_clear_silver: ClearSilver template syntax --------------------------- .. _ClearSilver documentation: https://github.com/blong42/clearsilver/wiki .. _ClearSilver syntax: https://github.com/blong42/clearsilver/wiki/Template-Syntax Basically, the bulletins are generated based on templates which are filled with data related to an :term:`incident`, like earthquake origin, simulation results and forecast zone warning levels. To achieve this, |appname| uses a fast and language-neutral :term:`HTML` template system called *ClearSilver*. The ClearSilver syntax supports variable substitution, conditionals, loops, functions, local variables etc. Here we explain specific |appname| template variables and functions that can be used in the template definitions. For more information about ClearSilver see the `ClearSilver documentation`_, especially `ClearSilver syntax`_. See also: :ref:`toast_template_examples` above. Each ClearSilver command starts with the opening tag ``. .. _note-export: .. note:: A visible template in a LiveTab is executed when a simulation is made active (e.g. by double click) but is also updated by other actions like a change in map position or zoom level or by an event update. However, the ClearSilver functions *save* and *addScript* are only executed if the template is disseminated either by :menuselection:`File -> Export` or the *Disseminate* button. Additionally, the *isLive()* function can be used to explicitly determine whether a template is executed within a LiveTab or by export/dissemination. Variables ~~~~~~~~~ ClearSilver provides many built-in variables, see `ClearSilver documentation`_ for more details. |appname| defines additional substitutions (variables and functions) listed below. The variables can be used in a template in the following way:: Common variables ^^^^^^^^^^^^^^^^ .. py:attribute:: agencyID The id of the agency. .. py:attribute:: availableTime Returns the available simulation duration. .. py:attribute:: creationTime The creation time and date of the bulletin. .. py:attribute:: ID The ID of the event. .. py:attribute:: testMode Indicates if the test mode is enabled or disabled. Origin parameters ^^^^^^^^^^^^^^^^^ .. py:data:: origin.depth The depth of the earthquake in km. .. py:data:: origin.latitude The latitude coordinate of the epicenter in degrees. .. py:attribute:: origin.longitude The longitude coordinate of the epicenter in degrees. .. py:attribute:: origin.magnitude Magnitude of the earthquake. .. py:attribute:: origin.magnitude.type Magnitude type of the earthquake. .. py:attribute:: origin.region The region of the earthquake. .. py:attribute:: origin.time The origin time. Grid rectangle coordinates ^^^^^^^^^^^^^^^^^^^^^^^^^^ Access the corner coordinates of the last :py:meth:`getGrid` export. .. py:attribute:: grid.box.top Latitude coordinate of the grid rectangle's top edge. .. py:attribute:: grid.box.left Longitude coordinate of the grid rectangle's left edge. .. py:attribute:: grid.box.bottom Latitude coordinate of the grid rectangle's bottom edge. .. py:attribute:: grid.box.right Longitude coordinate of the grid rectangle's right edge. Map rectangle coordinates ^^^^^^^^^^^^^^^^^^^^^^^^^^ Access the corner coordinates of the TOAST :ref:`Map perspective `. .. py:attribute:: map.box.top Latitude coordinate of the map rectangle's top edge. .. py:attribute:: map.box.left Longitude coordinate of the map rectangle's left edge. .. py:attribute:: map.box.bottom Latitude coordinate of the map rectangle's bottom edge. .. py:attribute:: map.box.right Longitude coordinate of the map rectangle's right edge. Datasets ^^^^^^^^ Nearest cities """""""""""""" A record of information of the nearest cities. .. py:attribute:: NearestCities.[0..n - 1] .. py:attribute:: NearestCities.[i].azimuth .. py:attribute:: NearestCities.[i].distance .. py:attribute:: NearestCities.[i].name .. py:attribute:: NearestCities.[i].lat .. py:attribute:: NearestCities.[i].lon .. note:: The data set does not contain data until the function :py:func:`nearestCities` has been called. Arrivals """""""" .. py:attribute:: Arrivals.[0..n - 1].[column name] The i-th value of the arrivals overview. For instance: Arrivals.0.POI. Forecast Zones """""""""""""" .. py:attribute:: ForecastZones.[0..n - 1].[column name] The i-th value of the forecast zones overview. For instance: ForecastZones.0.Name. Simulations """"""""""" .. py:attribute:: simulations.[0..n - 1] Returns the i-th simulation. .. py:attribute:: simulations.[i].id The simulation ID. .. py:attribute:: simulations.[i].type The simulation backend used for the simulation. .. py:attribute:: simulations.[i].source.depth The depth in km of the simulation earthquake. .. py:attribute:: simulations.[i].source.latitude The latitude coordinate of epicenter in degree of the simulation earthquake. .. py:attribute:: simulations.[i].source.longitude The longitude coordinate of the epicenter in degree of the simulation earthquake. .. py:attribute:: simulations.[i].source.magnitude The magnitude of the simulation earthquake. .. py:attribute:: simulations.[i].source.region The region of the simulation earthquake. .. py:attribute:: simulations.[i].source.originTime The origin time of the simulation earthquake. Functions ~~~~~~~~~ As already mentioned ClearSilver also supports functions. Here an example how to call a function in a template:: The |appname| specific functions are listed below. Common functions ^^^^^^^^^^^^^^^^ .. py:method:: addTimeSpan(time, seconds) :param time: String with format "%F %T" (yyyy-MM-dd HH:mm:ss). :param seconds: The number of seconds as integer value. :rtype: String with format as above. Adds n seconds to the given time. .. py:method:: currentTime() :rtype: String with format "%F %T" (yyyy-MM-dd HH:mm:ss). Returns the current date and time in UTC. .. py:method:: fill(in, width, ch, align) :param in: The Input string. :param width: The field width of the output. :param ch: The fill character which is used when the result is padded to the field width. :param align: Alignment of the output. :rtype: String Fills the input string with characters according the alignment(0 = left, 1 = right, 2 = center). .. py:method:: float(in, int precision) :param in: The input string. :param precision: The precision of the output. :rtype: String Formats floating point numbers. .. py:method:: ge(arg1, arg2) :rtype: Boolean Returns true if arg1 is greater than or equal to arg2. .. py:method:: gt(arg1, arg2) :rtype: Boolean Returns true if arg1 is greater than arg2. .. py:method:: le(arg1, arg2) :rtype: Boolean Returns true if arg1 is less than or equal to arg2. .. py:method:: lt(arg1, arg2) :rtype: Boolean Returns true if arg1 is less than arg2. .. py:method:: strfazi(azimuth) :param azimuth: Azimuth. :rtype: String Prints the geographic direction. .. py:method:: strfcoord(in, fmt) :param in: Latitude/ longitude value. :param fmt: The format string. :rtype: String Formats coordinates. .. py:method:: strftime(in, fmt) :param in: The input string. :param fmt: The format string. See the strftime man page for available format flags. :rtype: String Formats a given time. .. py:method:: toLower(in) :param in: The input string. :rtype: String: Converts the given input string to lower case. .. py:method:: toLocalTime(dateTime) :param dateTime: String with format "%F %T" (yyyy-MM-dd HH:mm:ss) representing UTC date and time. :rtype: String in same format. Converts given time from UTC to local time (system time). .. py:method:: toUpper(in) :param in: The input string. :rtype: String: Converts the given input string to upper case. .. py:method:: tz2tz(dateTime, timeZoneIn, timeZoneOut) :param dateTime: String with format "%F %T" (yyyy-MM-dd HH:mm:ss) representing UTC date and time. :param timeZoneIn: Input time zone. :param timeZoneOut: Output time zone. :rtype: String in format as above. Converts given time from one time zone to an other. Example: .. code-block:: none Functions with relation to bulletins ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:method:: isLive() :rtype: bool Returns whether the template is displayed in one of the live tabs. .. py:method:: useLocalTime(time) :param time: The input time. :rtype: bool Returns whether the time is changed to local time. .. py:method:: nearestCities(lat, lon, maxDist, minPopulation, maxCount) :param lat: Position for which the nearest cities are to be searched. :param lon: Position for which the nearest cities are to be searched. :param maxDist: Maximum distance from position to city. :param minPopulation: Minimum population of the city. :param maxCount: Maximum number of cities. Fills the dataset `Nearest cities`_ .. TODO:: py:method:: mapForecastZones(...) Note AHo 2023-02-15: Wird verwendet in dgmet_rtspbulletin_compare.txt und ncm_rtspbulletin_compare.txt. Könnte man eventuell durch loadTranslation ersetzen. .. py:method:: loadGradient(profile, gradient) :param profile: String: The name of the gradient profile. :param gradient: String: The kind of the gradient. The values are stored in the variable `grad` and can be iterated over. Useful to generate a legend in HTML. Example: .. code-block:: none .. py:method:: loadJSON(filename) :param filename: String: The filename of the JSON file. The content is made available as variables and can also be iterated over. This is useful to include data for test runs from external files. Example: .. code-block:: none Description: Name: Code: for the JSON file *training_definitions.json*: .. code-block:: json { "description": "Test Description", "testForecastZones": [ { "name": "Zone 1", "code": "1" }, { "name": "Zone 2", "code": "2" } ] } .. py:method:: loadTranslation(filename) :param filename: String: The filename of the translation map file in INI format. Loads translation map from file. Set paths and save bulletins ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:method:: save(filename) :param filename: Output file name. Saves the content of the bulletin to the file with the given filename. .. py:method:: saveArrivalLines(simType, filename, prettyPrint) :param simType: Simulation type. Example: "EasyWave2". Use "*" for all types. :param filename: Filename of the output GeoJSON file. :param prettyPrint: Pretty print JSON output (false/true). Saves arrival lines of the selected simulation(s) to a file in GeoJSON format. Example: .. code-block:: none .. py:method:: resolvePath(path) :param path: Path which can contain |scname|-variables. Returns absolute path with resolved |scname|-variables. Example: :: .. py:method:: setCurrentDir(path) :param path: Changes the current working directory to the directory given in path. If the directory doesn't exit, it is created. .. py:method:: tmpFile(template) :param template: Template which may contain the characters 'XXXXX'. :rtype: String: Generates a unique temporary filename from template, creates and opens the file, and returns the filename. The temporary file is removed when the script is finished. Add script ^^^^^^^^^^ .. py:method:: addScript(filename) :param filename: The absolute filename of the script. Marks an external script for execution upon dissemination of the template. This can be used to perform further operations regarding the bulletin like file conversions or to send the bulletin to a `GDS `_ etc. Generate images ^^^^^^^^^^^^^^^ .. py:method:: render(fileName, showLink) :param fileName: Output file. :param showLink: Indicates whether a link to the result is returned or not. :rtype: String Renders the current rendering stack and saves the result as an image to the given filename. .. py:method:: renderMeta(fileName, showLink) :param fileName: Output file. :param showLink: Indicates whether a link to the result is returned or not. :rtype: String The function `renderMeta` is the same as `render`, except that it additionally writes meta information about the rendering stack into an extra file with ending `.meta` in JSON format. This is useful if images have to be georeferenced. .. py:method:: getGrid(type, simType, step, fileName) :param type: Type of the grid. Currently available: "SSH max", "SSH", "Arrival times". :param simType: Simulation type. Example: "EasyWave2". Use "*" for all types. :param step: Time step. :param fileName: Output file. Save the simulation results for the layer *name* of simulation type *simType* for the given time step as an image to the given filename. Sets :py:attr:`grid.box.left`, :py:attr:`grid.box.right`, :py:attr:`grid.box.top` and :py:attr:`grid.box.bottom` to the grid coordinates. .. note:: See function *saveArrivalLines* to export arrival lines in GeoJSON format. Configure images ^^^^^^^^^^^^^^^^ .. py:method:: addGrid(type, simType, step, config) :param type: Type of the grid. Currently available: "SSH max", "SSH", "Arrival times", "Arrival lines". :param simType: Simulation type. Example: "EasyWave2". Use "*" for all types. :param step: Time step in seconds. :param config: Configuration of the grid. A comma separated list with '=' to assign the value to the variable (e.g. "legendTitle=Arrival times, arrivalFontSize=10, legendOrientation='vertical'") For available variables see the description below. Adds a grid to the rendering stack. Supported variables for the config parameter: .. _tab-cs_image_layer_params: ================= ========================================== Variable Type ================= ========================================== showLegend bool legendTitle string legendTextAlign 'left', 'right', 'center' legendFontSize int legendSpacing int legendOrientation 'horizontal', 'vertical' ================= ========================================== .. py:method:: addLayer(type, config) :param type: Name of the layer. :param config: Configuration. Adds a layer to the rendering stack. Currently available: "forecast zones". =============== ============================================================ Layer Config options =============== ============================================================ forecast zones See :ref:`supported config parameters for addGrid `, additionally: gradient (string), gradientProfile (string), drawFilled (bool), drawInactive (bool), drawInactiveColorized (bool), inactiveFillColor (string), inactiveLineColor (string), defaultLineColor (string), brush (string) =============== ============================================================ .. py:method:: setOriginSymbol(shape, fill) :param shape: Name of the shape. Available shapes are *circle* (black border as in map view), *circle-seiscomp* (red border as in |scname|) and *star*. The default shape is *circle*. :param fill: Indicates whether the symbol should be filled or not (default: filled). Sets the origin symbol of the map. .. py:method:: setGradientProfile(name) :param name: Gradient profile name. Set the gradient profile to the given name. For more information on color gradients, see: :ref:`toast_mapstyles`. .. py:method:: setRenderOptions(config) :param config: Configuration. A comma separated list with '=' to assign the value to the variable (e.g. "mapProjection=Rectangular, mapZoomLevel=8.0") Sets rendering options. Supported options are given below. ================= =========== ================== Option Type Example ================= =========== ================== mapCenter float float -5.0 100.0 mapProjection string Rectangular mapZoomLevel float 8.0 showMap bool true showGlobalFeature bool false showGrid bool true backgroundColor string white showGrayScale bool false encodeBase64 bool false ================= =========== ================== .. py:method:: setScenarioColors(colors) :param colors: List of colors. :type colors: string (list separated by ',', e.g. "white, red"). Set the colors of the active simulations, for example used for arrival lines color. The order defines the assignment to the simulations based on the selection in |appname|. .. TODO:: list default? .. py:method:: alignLegends(inout, orientation, align) :param inout: Legends inside or outside of the image ("in","out" or "" (default: inside)). :param orientation: Horizontal or vertical legend ("horizontal", "vertical" or "" (default: vertical)). :param align: Alignment of legend ("left", "right", "bottom", "top" or mixed values, default: top). Set the alignment and the orientation of the legends and if the legends should be rendered in or outside the image. .. py:method:: setGlobalLayerConfig(str) :param str: String with information about how to show the legend text. :rtype: string See :ref:`layer configuration ` for more detail. .. py:method:: setWatermark(str) :param str: String with information about the copyright. :rtype: string Set information about the file e.g. the date of copyright. .. py:method:: showCurrentStepTime(step) :param step: Time step in seconds. Sets the current time step. .. py:method:: forecastZone(id) :param id: ID of a forecast zone. :rtype: string Returns the forecast zone in kml format. Set image size ^^^^^^^^^^^^^^ .. py:method:: setDisplayRect(lat, lon, height, width) :param lat: Latitude value. :param lon: Longitude value. :param height: Height of the rectangle. :param widht: Width of the rectangle. Sets the visible region of the map from bottom-left corner, width and height. The aspect ratio needs to be similar to the selected output size to fit. .. py:method:: setSize(width, height) :param width: The width of the output image. :param height: The height of the output image. Sets the size of the output image. .. py:method:: setMegapixel(megaPixel) :param megaPixel: Number of mega pixel (floating point). Sets the image size to approximately megaPixel. .. TODO:: All variables and functions should be checked against source code for completeness!