.. _toast_export: Create warning bulletins and other output using templates ========================================================= .. _toast_bulletins: Bulletin templates ------------------ |toast| 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) and observations (like tide gauge or GNSS). Bulletins are generated using so-called templates. A template is a blueprint for a bulletin. But it can also be used to generate other kind of output like a tsunami simulation video. The template technology is based on :ref:`ClearSilver `. All variables and functions in a template are evaluated by the |toastg| in order to create and render the bulletin. 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 or video stream and other. This is achieved by triggering external scripts upon dissemination. Live tabs allow to display and disseminate (export) templates. They appear as additional :ref:`tabs ` in the :ref:`toast_main_panel`. The configuration of templates and Live tabs is described in :ref:`toast_bulletin_config`. Note that templates are configured at the |toasts|, while the Live tabs are configured at the |toastg|. .. _toast_dissemination: Dissemination ~~~~~~~~~~~~~ You can disseminate a bulletin in following ways: #. Via button *Disseminate* in a :ref:`Live tab `. Per default, this disseminates all templates of the Live tab. See also the configuration options below. #. Via :menuselection:`Menu --> File --> Export templates`. This disseminates exactly one template. Upon dissemination, the :ref:`ClearSilver functions ` *save* and *addScript* (if they are used within the template) are executed. The former saves the rendered template and the latter can trigger any kind of external script. Here are some settings related to dissemination which can be configured in the |toastg|. * :confval:`liveTab.$name.buttonText`: Change the button text for this Live tab (default is *Disseminate*). * :confval:`confirmationRequired`: If it is set, before dissemination (that is, before the bulletins are saved and before the external scripts in the templates are executed), the additional dialog: "Do you really want to continue?" pops up. * :confval:`alwaysShowAdditionalOptions`: If it is set, before dissemination the dialog "Execute with additional options" pops up. If it is not set, then the dialog pops up only after long mouse click. * :confval:`disseminationSelectionBehavior`: This configures the pre-selection of the templates in the dialog from above. .. note:: As :confval:`confirmationRequired` was introduced before :confval:`alwaysShowAdditionalOptions` and in order not the change behavior, by default former is *True* and latter is *False*. However, in most cases it is more useful to configure them in the opposite way as latter dialog offers more options. .. _toast_dissemination_counter: Dissemination counter ~~~~~~~~~~~~~~~~~~~~~ Every template has a dissemination or revision counter per incident. Each time the template is disseminated, the counter is increased by 1. The count is stored in the database at the |toasts| and shared by all |toastg| instances. It is accessed using the *revision* variable, see: :ref:`ClearSilver variables `. .. _toast_template_examples: Template file examples ~~~~~~~~~~~~~~~~~~~~~~ The |toast| 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 |toast| update: .. code-block:: sh sysop@host:~$ cp $SEISCOMP_ROOT/share/toast/templates/ptwc_ocean.html.example $SEISCOMP_ROOT/share/toast/templates/ptwc_ocean.html Here is the example bulletin PTWC Ocean. See below for the template code. .. _fig-template_example: .. figure:: media/toast/export/live_tab_example.png :align: center :width: 18 cm Live tab PTWC (undocked) with selected template PTWC Ocean .. hint:: 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`. This is the template code *ptwc_ocean.html*, which generates the bulletin shown :ref:`above `: .. include:: media/toast/export/ptwc_ocean.html :literal: .. _note-test_mode: .. note:: If :ref:`toast_test_mode` is active, a template can only be rendered if the ClearSilver attribute *testMode* is present somewhere in the template. 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 can be added or the dissemination while in test mode can be directed to a different target. .. _toast_template_editor: Template editor ~~~~~~~~~~~~~~~ The template editor can be used to modify the bulletins of the current incident. It is launched by double-click or :menuselection:`right-click --> Edit` on a template in the :ref:`template tree panel `. *Apply* pushes the template to the database, *Save* additionally closes the window, and *Export...* allows to save the template as text file on the file system. .. _fig-template_editor: .. figure:: media/toast/export/template_editor.png :align: center :width: 18 cm |toast| template editor. .. _note-templates-permanent: .. note:: The templates are stored in the database together with an incident when an incident is created. Changes affect only the current incident. In order to make changes available for new incidents, the modified template has to be saved on the file system at the location where it is imported by the |toasts|. The |toasts| has to be restarted afterwards. After the |toastg| is restarted, the new templates are used for future incidents. .. _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, |toast| 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 |toast| 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. |toast| defines additional substitutions (variables and functions) listed below. The variables can be used in a template in the following way:: See also: :ref:`Template variables configuration ` for the variables defined on an incident-basis. Includes ~~~~~~~~ ClearSilver supports to include templates which allows for example to share parts between several templates. In contrast to the default ClearSilver implementation, |toast| tries to load the requested resource from the available template tree. The function expects the path in the template tree as an argument. Here is an example that includes the template *Definitions* at the base of the tree: .. _clearsilver_variables: 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:: revision The *dissemination* or *revision* counter. It is specific per incident and per bulletin. Is increased by 1 at each dissemination. Saved in the database and shared across GUIs. .. 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. .. py:attribute:: origin.type The source type of the origin, e.g., earthquake. .. py:attribute:: origin.typeComment Provides additional information about the source type, e.g., the name of a volcano 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. Threat levels for provinces """"""""""""""""""""""""""" .. py:attribute:: provinceThreatLevels.[0..n - 1] .. py:attribute:: provinceThreatLevels.[i].name .. py:attribute:: provinceThreatLevels.[i].province[0..m -1] .. py:attribute:: provinceThreatLevels.[i].province[j].name .. py:attribute:: provinceThreatLevels.[i].province[j].threatLevel .. py:attribute:: provinceThreatLevels.[i].province[j].threatLevelName .. py:attribute:: provinceThreatLevels.[i].province[j].T1Time Contains the i-th country and j-th province name, threat level number and threat level name. .. note:: The data set does not contain data until the function :py:func:`computeProvinceThreatLevels` has been called. Functions ~~~~~~~~~ As already mentioned ClearSilver also supports functions. Here an example how to call a function in a template:: The |toast| specific functions are listed below. Common functions ^^^^^^^^^^^^^^^^ .. py:method:: computeProvinceThreatLevels(options) :param options: Mandatory string with key=value pairs. Fills the dataset `Threat levels for provinces`_. It aggregates the threat level over forecast zones within provinces for all countries. Sorting of the countries and provinces is alphabetically. Currently the only option is *useInactive* which can be *true* or *false*. If the options string is empty, *false* is used. If *true*, the lowest threat level is assumed for the inactive forecast zones. Here is an example how to use it: .. code-block:: none - - .. 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:: threatLevelAsText(in) :param in: Threat level number (as string or integer). :rtype: String Returns the name corresponding to the threat level number as defined in the threat level configuration. .. py:method:: toLower(in) :param in: The input string. :rtype: String: Converts the given input string to lower case. .. py:method:: toUpper(in) :param in: The input string. :rtype: String: Converts the given input string to upper case. Time related functions ^^^^^^^^^^^^^^^^^^^^^^ .. py:method:: addTimeSpan(dateTime, seconds) :param dateTime: 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:: 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:: 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:: tzFormat(dateTimeZone, fmt) :param dateTimeZone: Localized time as string with format "%F %T %Z" representing date, time and timezone. :param fmt: The output format. See the strftime man page for available format flags. :rtype: Time as string in format as requested in fmt. Formats date, time and timezone. Note: This function can be used with localized timestamps only. Example: .. code-block:: none .. py:method:: tz2tz(dateTime, timeZoneIn, timeZoneOut) :param dateTime: String with format "%F %T" (yyyy-MM-dd HH:mm:ss) representing date and time. :param timeZoneIn: Input time zone. :param timeZoneOut: Output time zone. :rtype: String in format "%F %T" as above. Converts given datetime from one time zone to another. Time zones are defined on system level. They can be listed in a system console using: :code:`timedatectl list-timezones`. 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 |toast|. .. 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!