.. _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. 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:`dissemination.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:`dissemination.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:`dissemination.selectionBehavior`: This configures the pre-selection of the templates in the dialog from above. * :confval:`dissemination.selectionMode`: This configures if in the template dialog only one or multiple templates can be selected. .. note:: :confval:`dissemination.confirmationRequired` is by default *True* and :confval:`dissemination.alwaysShowAdditionalOptions` is by default *False*. However, in some 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 in a template using the *revision* variable, see :py:attr:`revision`. .. _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 arrivals 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 templates of 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: http://clearsilver.net/docs/ .. _ClearSilver syntax: http://clearsilver.net/docs/man_templates.hdf .. _ClearSilver basics: http://clearsilver.net/docs/template_basics.hdf .. _ClearSilver HDF: http://clearsilver.net/docs/man_hdf.hdf Bulletins in |toast| are generated based on templates that are filled with data related to an :term:`incident`, such as earthquake origin, simulation results, and forecast zone warning levels. To achieve this, |toast| uses a fast and language-neutral :term:`HTML` template system called :term:`ClearSilver`. The data used to fill these templates is stored in a structured format called :term:`HDF` (Hierarchical Data Format). HDF organizes information like a tree, using parent and child nodes. This structure makes it easy to access nested values inside a template. A template defines the structure and layout of the output (e.g., a bulletin), while the HDF provides the content that is inserted into that structure. This separation between content and presentation helps keep the output logic clean, reusable, and maintainable. The ClearSilver template syntax supports variable substitution, conditionals, loops, functions, and local variables. Each ClearSilver command starts with the opening tag ``. Below, we describe the specific |toast| template variables and functions that can be used in template definitions. For more details about ClearSilver, refer to the `ClearSilver documentation`_, especially the sections on `ClearSilver HDF`_ and `ClearSilver syntax`_. See also the :ref:`toast_template_examples`. .. _note-export: .. note:: A visible template in a LiveTab is executed when a simulation is made active (for example by double click) but is also updated by other actions like a change in map position or zoom level or by an event update. .. note:: Some functions like *save* and *addScript* are only executed if the template is disseminated either by :menuselection:`File -> Export` or the *Disseminate* button, see `Dissemination`_. The *isLive* function can be used to explicitly determine whether a template is executed within a LiveTab or by export/dissemination. .. _toast_cs_variables: Variables ~~~~~~~~~ |toast| defines variables and data sets, which are stored in the :term:`HDF`. They can be accessed in the template as follows:: Incident variables ^^^^^^^^^^^^^^^^^^ .. py:attribute:: incidentVar.[name] The content of the incident variable with the name 'name', see :ref:`Template variables configuration ` for more information. 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:: incidentID The ID of the incident. .. py:attribute:: OTAAvail :type: 1 oder 0 Indicates if at least one station with an :term:`OTA` value is available, see :ref:`toast_arrivals_perspective` and :ref:`toast_waveform_picker` for more informations. .. py:attribute:: OTMAvail :type: 1 oder 0 Indicates if at least one station with an :term:`OTM` value is available, see :ref:`toast_arrivals_perspective` and :ref:`toast_waveform_picker` for more informations. .. 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 :type: 1 oder 0 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 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. Template information ^^^^^^^^^^^^^^^^^^^^ Access the configured template information, see :ref:`Template configuration `. .. py:attribute:: templ.id The ID of the template. .. py:attribute:: templ.path The path of the template in the template tree .. py:attribute:: templ.name The template name. .. py:attribute:: templ.parent The parent path of the template in the template tree. Triggering template information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Access the triggering template information, see :ref:`Template configuration `. .. py:attribute:: triggeringTempl.id The ID of the triggering template .. py:attribute:: triggeringTempl.path The path of the triggering template in the template tree .. py:attribute:: triggeringTempl.name The triggering template name. .. py:attribute:: triggeringTempl.parent The parent path of the triggering template in the template tree .. py:attribute:: triggeringTempl.revision The revision of the triggering template .. note:: These variables are only available in a secondary template, see :ref:`Adding secondary templates ` for more information. Common data sets ^^^^^^^^^^^^^^^^ Arrivals """""""" .. py:attribute:: Arrivals.[0..n - 1].[column name] The i-th value of the arrivals overview, for instance Arrivals.0.POI. Dissemination History """"""""""""""""""""" .. py:attribute:: DissHistory.[0..n - 1] Returns the i-th disseminated bulletin. .. py:attribute:: DissHistory.[i].Path The path of the i-th disseminated bulletin in the template tree, for instance DissHistory.0.Path. .. py:attribute:: DissHistory.[i].Revision The revsion of the i-th disseminated bulletin, for instance DissHistory.0.Revision. .. py:attribute:: DissHistory.[i].Time The dissemination time of the i-th disseminated bulletin, for instance DissHistory.0.Time. 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. Generated Data sets ^^^^^^^^^^^^^^^^^^^ 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. .. note:: The data set does not contain data until the function :py:meth:`getGrid` has been called. Forecast Points """"""""""""""" .. py:attribute:: ForecastPoints.[zone ID]-[point ID].[column name] The forecast point with point ID assigned to forecast zone with ID 'zone ID', for instance ForecastPoints.61056-6100067.Name. .. note:: The data set does not contain data until the function :py:meth:`addForecastPoints` has been called. 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:meth:`nearestCities` has been called. Threat levels for one province """""""""""""""""""""""""""""" .. py:attribute:: provinceThreatLevel.name .. py:attribute:: provinceThreatLevel.threatLevel .. py:attribute:: provinceThreatLevel.threatLevelName .. py:attribute:: provinceThreatLevel.T1Time .. py:attribute:: provinceThreatLevel.[ThreatLevel].[0..n-1] .. py:attribute:: provinceThreatLevel.[ThreatLevel].[i].startPoint .. py:attribute:: provinceThreatLevel.[ThreatLevel].[i].endPoint .. py:attribute:: provinceThreatLevel.[ThreatLevel].[i].region Contains province threat level for one province. .. note:: The data set does not contain data until the function :py:meth:`computeProvinceThreatLevel` has been called. 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 .. py:attribute:: provinceThreatLevels.[i].province[j].[ThreatLevel].[0..p-1] .. py:attribute:: provinceThreatLevels.[i].province[j].[ThreatLevel].[k].startPoint .. py:attribute:: provinceThreatLevels.[i].province[j].[ThreatLevel].[k].endPoint .. py:attribute:: provinceThreatLevels.[i].province[j].[ThreatLevel].[k].region 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:meth:`computeProvinceThreatLevels` has been called. Mapped forecast zones """"""""""""""""""""" .. py:attribute:: MappedForecastZones.[0..n - 1].ID .. py:attribute:: MappedForecastZones.[0..n - 1].MappedID .. py:attribute:: MappedForecastZones.[0..n - 1].Place .. py:attribute:: MappedForecastZones.[0..n - 1].MappedPlace The i-th mapped forecast zone for which a mapping is available. .. note:: The data set does not contain data until the function :py:meth:`mapForecastZones` has been called. Functions ~~~~~~~~~ ClearSilver provides many built-in functions, see `ClearSilver documentation`_ for more details. In addition, |toast| defines several custom functions, which are listed below. Here an example how to call a function in a template:: Common functions ^^^^^^^^^^^^^^^^ .. 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, 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:: 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: Datetime string [#timeInputFormat]_ :param seconds: The number of seconds as integer value :rtype: String with format "%F %T" (yyyy-MM-dd HH:mm:ss) Adds n seconds to the given time. .. py:method:: compareTime(time1, time2, operator) :param time1: The first time value :param time2: The second time value :param operator: The operator, possible options: "<", "<=", ">", ">=", "lt", "le", "gt", "ge" :rtype: int (1 if comparision was successful, 0 otherwise) Compares two time strings. .. 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: Datetime string [#timeInputFormat]_ :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: Datetime string representing UTC date and time [#timeInputFormat]_ :rtype: String in same format Converts given time from UTC to local time (system time). .. py:method:: tzFormat(dateTimeZone, fmt) :param dateTimeZone: Localized datetime as string representing date, time and timezone :param fmt: The output format, see the strftime man page for available format flags :rtype: Time 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: Date time string [#timeInputFormat]_ :param timeZoneIn: Input time zone :param timeZoneOut: Output time zone :rtype: String in format "%F %T" 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 .. [#timeInputFormat] Valid datetime input formats are "%FT%T.%f%Z", "%F %T.%f%Z", "%F %T %Z", "%F %T.%f %Z", "%FT%T" and "%F %T" Functions for generating data set nodes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:method:: addForecastPoints(config) :param config: - Configuration options with key=value pairs. The following options can be used: ================== ============================================================ Option Description ================== ============================================================ threatLevel Two options: *calc* or *fromZone*. If fromZone is used, the threat level of the forecast point is the threat level of the zone. If calc is used the threat level is calculated from the forecast point values. Defaut: false prefix The output prefix deletePrev If true the previously added ForecastPoints data set is remove. If false the forecast points are added to the data set ForecastPoints. zoneID The zone ID for which the forecast points are extracted. country The assigned country of the forecast points province The assigned province of the forecast points names Predefined name list of forecast points ================== ============================================================ Fills the data set `Forecast points`_. .. note:: Forecast points can be extracted via the zone ID. If this is not given, country, province and names can be used as filters. Please note that there may be a large number of forecast points. Adding all points will significantly reduce the performance of the template evaluation. .. py:method:: computeProvinceThreatLevel(config) :param config: - Configuration options with key=value pairs ================== ============================================================ Option Description ================== ============================================================ useInactive If *true*, the lowest threat level is assumed for the inactive forecast zones. Defaut: false coastLineStart Defines name of the Forecast Zone table column that is used as coast line start. coastLineEnd Defines name of the Forecast Zone table column that is used as coast line end. regions Defines name of the Forecast Zone table column that is used as region column(s). t1TimeThreatLevels Semicolon separated list. T1 aggreation only takes into account the forecast zones with the given threat levels. threatLevels Semicolon separated list. A extra calculation will be added for the combined given Threat Levels. province Only forecast zones with the given province(s) are taken into account. country Only forecast zones of the given coutries(s) are taken into account. ================== ============================================================ Fills the data set `Threat levels for one province`_. It aggregates the threat level over forecast zones within provinces for all countries. Here is an example how to use it: .. code-block:: none Highest Threat Level in : Coastal line and regions under threat: to (); .. py:method:: computeProvinceThreatLevels(config) :param config: - Configuration options with key=value pairs ================== ============================================================ Option Description ================== ============================================================ useInactive If *true*, the lowest threat level is assumed for the inactive forecast zones. Defaut: false coastLineStart Defines name of the Forecast Zone table column that is used as coast line start. coastLineEnd Defines name of the Forecast Zone table column that is used as coast line end. regions Defines name of the Forecast Zone table column that is used as region column(s). t1TimeThreatLevels Semicolon separated list. T1 aggreation only takes into account the forecast zones with the given threat levels. threatLevels Semicolon separated list. A extra calculation will be added for the combined given Threat Levels. ================== ============================================================ Fills the data set `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. Here is an example how to use it: .. code-block:: none - - .. py:method:: loadGradient(profile, gradient) :param profile: The name of the gradient profile :param gradient: The kind of the gradient Stores the gradient values in the data set variable `grad`. This variable can be iterated over. Useful to generate a legend in HTML. Example: .. code-block:: none .. py:method:: loadJSON(filename) :param filename: The filename of the JSON file Loads a JSON file and makes the content available as variables in the data set, so that the content can also be accessed iteratively. 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:: mapForecastZones(...) Maps ID and place of Forecast Zones to values defined in a data set node `Mapping`. Fills the data set `Mapped forecast zones`_. .. note:: The data set must contain a mapping node (Mapping). .. 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 data set `Nearest cities`_. Variables and data sets manipulators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:method:: hdfCategorize(nodeName, config) :param nodeName: Node that children should be categorized :param options: - Configuration options - a comma separated list with '=' to assign the value to the variable. ================== ============================================================ Option Description ================== ============================================================ category The category node name prefix The name of the new data set node. sortBy The sort column. columns Semicolon separated list. Defines the columns that should be considered in the new category node. threatLevelFilter The categorization only takes into account the forecast zones with the given threat levels. ================== ============================================================ Categorizes a data set node based on the grandchild node. This creates a new data set node. The child nodes can have a different order. A restricted list of children can be transferred from the old structure. It can also be filtered according to the threat level. .. py:method:: hdfDump(nodeName) :param nodeName: Node to dump (name or empty string) Dumps the data set node and its children to stdout. If no node name is specified, the entire data set is dumped. .. py:method:: hdfGetVar(nodeName) :param nodeName: The node name :rtype: String Returns the value of a node. This method is very usefull if the node name is set dynamically in the template. .. py:method:: hdfGetPrevVar(nodeName) :param nodeName: The node name :rtype: String Returns the value of a node from the data set of the previous dissemination run of this template .. py:method:: hdfSetVar(nodeName, prefix, value) :param nodeName: Node that children should be categorized :param prefix: Node prefix :param value: The new value Sets the value of a node in the data set. .. py:method:: hdfWriteFile(node, childName) :param name: Node whose child objects are to be sorted :param childName: Node value used for sorting Writes the data set node and its children to the given file. If no node name is specified, the entire data set is used. .. py:method:: hdfPrevWriteFile(nodeName, filename) :param nodeName: Node name for export or empty :param filename: Output file name Writes the data set node and its children of the previous dissemination run to the given file. If no node name is specified, the entire data set is used. .. py:method:: hasChanged(name) :param name: Variable name :return: * "0" if both values are equal * "1" if both values are set but are distinct * "-1" if the value is not set at all * "-2" if the value is not set in the current context * "-3" if the value is not set in the previous context :rtype: int Compares the variable content of the current template context with the variable content of the previously disseminated bulletin context. .. py:method:: hasChangedRecursive(name) :param name: Dataset name :return: * "0" if both datasets are equal * "1" if any node in the datasets is distinct * "-1" if the datasets root node is not set at all * "-2" if the datasets root node is not set in the current context * "-3" if the datasets root node is not set in the previous context :rtype: int Recursively compares datasets of current template context with the dataset in the previously dissminated bulletin context. Others ^^^^^^ .. py:method:: gfContains(filename, name, lat, lon) :param filename: Filename of the GeoJSON or BNA file :param name: Geo feature name :param lat: Geo coordinate :param lon: Geo coordinate :rtype: Int ("1" if coordinate is contained by a geofeature, else "0") Tests if a geo coordinate is contained by a particular geofeature defined in a GeoJSON or BNA file and identified by a name. .. py:method:: gfsContains(filename, lat, lon) :param filename: Filename of the GeoJSON or BNA file :param lat: Geo coordinate :param lon: Geo coordinate :rtype: Int ("1" if coordinate is contained by a geofeature, else "0") Tests if a geo coordinate is contained by any geofeature defined in a GeoJSON or BNA file .. py:method:: gfName(filename, lat, lon) :param filename: Filename of the GeoJSON or BNA file :param lat: Geo coordinate :param lon: Geo coordinate :rtype: String Looks up polygon name for a geo coordinate. .. py:method:: isLive() :rtype: Boolean Returns whether the template is displayed in a Live tab. .. py:method:: loadTranslation(filename) :param filename: The filename of the translation map file in INI format Loads translation map from file. See also function :py:func:`translate`. .. py:method:: setLineLength(length) :param length: The text line length Sets the maximum text line length. .. py:method:: httpGET(url, timeout) :param url: The URL :param timeout: The request timeout in seconds Requests data via HTTP/GET .. 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:: translate(str, prefix) :param str: The string to translate. :param str: A prefix :rtype: The translated word if a translation is available, otherwise the str. Translates a given string based on the translation loaded with :py:func:`loadTranslation`. Set paths and save bulletins ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:method:: resolvePath(path) :param path: Path which can contain |scname| variables Returns the absolute path with resolved |scname| variables. Example: :: .. 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, for example "*" for all types or "EasyWave2" :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:: setCurrentDir(path) :param path: The absolute 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 for the temporary filename. :returns: Filename :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. A temporary file has a static part of the name and a part that is calculated so that it is unique. If it contains 'XXXXXX', this part will be replaced by a auto-generated portion of the filename. 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. .. _toast_secondary_templates: Secondary templates ^^^^^^^^^^^^^^^^^^^ Secondary templates can be added for evaluation after the main template has been processed. These templates share the same :term:`HDF` file structure (see :ref:`ClearSilver `) as the main template. This means the main template receives the HDF and can, for example, add variables to it. The modified HDF then serves as input for the first secondary template. That template can further modify the data, and its resulting HDF is passed on to the next secondary template, and so on. Keep this behavior in mind when working with secondary templates: It can be especially useful for disseminating multiple templates for different channels simultaneously - for example, sending both an email and an SMS at the same time. .. note:: Secondary templates are only evaluated during dissemination. They are ignored in live preview (see :ref:`Live tab `). .. py:method:: addTemplate(filename) :param filename: The path of the template in the template tree Adds a secondary template Generate images ^^^^^^^^^^^^^^^ .. py:method:: getGrid(type, simType, step, fileName) :param type: Type of the grid; currently available: "SSH max", "SSH", "Arrival times" :param simType: Simulation type, for example "*" for all types or "EasyWave2" :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. .. py:method:: render(fileName, showLink) :param fileName: Output file :param showLink: Indicates whether a link to the result is returned or not :rtype: The link to the resulting image as string if showLink is set to true 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: The link to the resulting image as string if showLink is set to true 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. .. note:: See function *saveArrivalLines* to export arrival lines in GeoJSON format. Configure images ^^^^^^^^^^^^^^^^ .. py:method:: addGrid(type, simType, step, config) :param type: Name of the grid; possible options: "SSH max", "SSH", "Arrival times", "Arrival lines" :param simType: Simulation type, for example "*" for all types or "EasyWave2" :param step: Time step in seconds. :param config: - Configuration of the grid. A comma separated list with '=' to assign the value to the variable (for example "legendTitle=Arrival times, arrivalFontSize=10, legendOrientation='vertical'"). Supported variables for the config parameter are: .. _tab-cs_image_layer_params: ================= ========================================== Variable Type ================= ========================================== showLegend bool legendTitle string legendTextAlign 'left', 'right', 'center' legendFontSize int legendFontBold bool legendSpacing int legendOrientation 'horizontal', 'vertical' legendReverseText string gradient string gradientProfile string arrivalFontSize int (available for layer 'Arrival lines') ================= ========================================== Adds a grid to the rendering stack. .. py:method:: addLayer(type, config) :param type: Name of the layer; possible options: "forecast zones", "geofeature". :param config: - In addition to the general configuration options (see :ref:`supported config parameters for addGrid `), the following are also available for the individual layers: =============== ============================================================ Layer Config options =============== ============================================================ forecast zones gradient (string), gradientProfile (string), drawFilled (bool), drawInactive (bool), drawInactiveColorized (bool), inactiveFillColor (string), inactiveLineColor (string), defaultLineColor (string), brush (string) geofeature file (string), dir (string), renderAsVector (bool) =============== ============================================================ Adds a layer to the rendering stack. .. py:method:: addOriginImage(config) :param config: - Configuration options as comma separated list with '=' as separator to assign the value to the variable (for example "mapZoomLevel=8.0,imageSize=30 21"). The following parameters influence both the size of the image and its position on the image: ==================== ============= ================== Option Type Example ==================== ============= ================== mapCenter number number 0 -180 mapZoomLevel number 1 imageSize number number 140 180 imagePos number number 321 123 ==================== ============= ================== Renders a small image on the rendered image (image-in-image). This map only shows the origin of the incident and no other layers or grids .. 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 options as comma separated list with '=' as separator to assign the value to the variable (for example "mapProjection=Rectangular, mapZoomLevel=8.0"). Supported options: ==================== ============= ================== ================== Option Type Default Value Example ==================== ============= ================== ================== backgroundColor string white encodeBase64 bool true false gridDist number number 15 15 10 20 imageQuality number 100 mapCenter number number |toastg| map value -5.0 100.0 mapProjection string |toastg| map value Rectangular mapZoomLevel number |toastg| map value 8.0 showCities bool false true showGlobalGeoFeature bool true false showGrid bool true true showGrayScale bool false false showMap bool true true showTimeStamp bool true true showOriginTime bool false true ==================== ============= ================== ================== Sets the rendering options for the next generated image. .. py:method:: setScenarioColors(colors) :param colors: List of colors, for example "white, red" :type colors: string (comma-separated list) 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 the configuration for all layers. :rtype: String Sets the global layer configuration, which applies to all layers and grids for future generated images. This configuration serves as the default for all layers and grids but can be overridden for individual layers using the funtions :py:func:`addLayer` or :py:func:`addGrid`. See :ref:`layer configuration ` for more detail. .. note:: This configuration is not applied to images generated with the function :py:func:`getGrid`. .. py:method:: setWatermark(str) :param str: The watermark text :rtype: String Customizes the generated images with the given text. This can be used for adding copyright information. .. py:method:: showCurrentStepTime(enable) :param enable: Indicates if the current step should be shown :deprecated: Please use :py:meth:`setRenderOptions`. Enable the current time step in the image. .. py:method:: forecastZone(id) :param id: ID of a forecast zone :rtype: string Returns the forecast zone in kml format. .. py:method:: useLocalTime(enable) :param enable: Indicates if local time should be used Set the time indicating the time step of the image to local time. By default the time is shown in UTC. Set image size ^^^^^^^^^^^^^^ .. py:method:: setDisplayRect(lat, lon, height, width) :param lat: The bottom-left position :param lon: The bottom-left position :param height: Height of the rectangle :param width: 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:: setDisplayCoords(minLat, minLon, maxLat, maxLon) :param minLat: The top-left position :param minLon: The top-left position :param maxLat: The bottom-right position :param maxLon: The bottom-right position Sets the visible region of the map from the top-left to the bottom-right corner. 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. Includes ^^^^^^^^ ClearSilver supports to include templates which allows, for example, to share parts between several templates. In contrast to the default ClearSilver implementation, |toast| also 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::