Export

Bulletins

TOAST provides the possibility for creating and disseminating tsunami bulletins whose content is based on data related to an incident (like earthquake origin), to one or several simulations (like forecast zones warning level) or tide gauge observations. Bulletins are generated using so-called templates.

You can disseminate a bulletin in following ways:

  1. Via Menu ‣ File ‣ Export to execute a template

  2. Via button Disseminate in a Live Tab

Hint

The Disseminate button can be renamed using liveTab.$name.buttonText. Technically, clicking the button executes the ClearSilver functions save and addScript.

Note

If 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 HTML, 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 ClearSilver Syntax and the configuration in Templates configuration. Live tabs allow the display and dissemination (export) of associated templates and appear as additional tabs in the Main panel.

General scheme

Templates can be defined and registered using 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 Arrivals perspective. The snapshot of a map in a bulletin shows by default the snapshot as selected in the Map perspective.

Live Tabs configuration

A Live Tab displays data related to an incident and results of the active simulation(s) formatted in a way as encoded in the selected template.

../_images/live_tab_example.png

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: 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 liveTab.$name.buttonText and the title of the live tab (liveTab.$name.title). Keep in mind that the export only works if a storage location has been set in the template.

Note

If 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 scconfig + Live tab profile),

  • add the template profile name(s) to it and

  • register it at liveTabs.

Following parameters can be configured in a live tab profile:

Consult hovertips in scconfig for more information on the parameters.

As an example:

liveTab.ptwc.title = PTWC
liveTab.ptwc.templ = ptwc_ocean, ptwc_region
liveTabs = ptwc

Templates configuration

Templates define how the data related to an incident and of the active simulations is visualized and disseminated. They are added and removed in the same way as live tabs:

  1. Add a template profile (using scconfig + Template profile),

  2. configure the parameter and

  3. register the template profile at templates.types.

Following parameters can be configured in a template profile:

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 Live Tabs configuration.

Figure Live Tab PTWC with selected template ptwc_ocean illustrates an example of a bulletin generated with a template.

Template file examples

The TOAST template file examples are located at: /home/sysop/seiscomp/share/toast/templates and the example scripts at: /home/sysop/seiscomp/share/toast/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:

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: Live Tab PTWC with selected template ptwc_ocean:

<?cs set:countries = ""
?><?cs each:item = Arrivals
?><?cs if:item.T1Time || item.OTA
?><?cs if:item.Country && ( string.find(countries, item.Country) == -1 )
?><?cs if:countries == ""
?><?cs set:countries = item.Country
?><?cs else
?><?cs set:countries = countries + ", " + item.Country
?><?cs /if
?><?cs /if
?><?cs /if
?><?cs /each
?><?cs set:path = "/tmp/toast/" + strftime(origin.time, "%Y/%m/%d/") + ID
?><?cs var:setCurrentDir(path)
?><?cs var:save("bulletin.html")
?><?cs var:setSize(400,300)
?> <?cs var:addScript("@DATADIR@/toast/scripts/disseminate.sh " + ID)
?><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
    <head>
        <meta content="text/html; charset=utf-8" http-equiv="content-type">
        <title>Tsunami Watch Bulletin</title>
    </head>
    <body>
        <h2>
        Ocean-Wide Tsunami Watch Bulletin (shallow, undersea earthquake)
        </h2>
        <p>
        </p>
        <table>
            <tr><td>Tsunami bulletin number&#160;</td><td><?cs var:ID ?></td></tr>
            <tr><td>Agency ID</td> <td><?cs var:agencyID ?></td></tr>
            <tr><td>Issued at</td> <td><?cs var:strftime(creationTime, "%F %T") ?></td></tr>
        </table>
        <p>
        This bulletin is for all areas of the <?cs var:origin.region ?>
        </p>
        <p>
        ... An ocean-wide tsunami watch is in effect ...
        </p>
        <p>
        A tsunami watch is in effect for <b><?cs var:countries ?></b>. For other areas of the <?cs var:region ?> region, this message is an advisory only.
        </p>
        <p>
        An earthquake has occurred with these preliminary parameters<br>
        </p>
        <table>
            <tr>
                <td>Origin time&#160;</td>
                <td><?cs var:strftime(origin.time, "%F %T") ?></td>
            </tr>
            <tr>
                <td>Epicenter</td>
                <td> <?cs var:strfcoord(origin.latitude, "%.3F&deg; %c") ?> <?cs var:strfcoord(origin.longitude, "%.3F&deg; %C") ?></td>
            </tr>
            <tr>
                <td>Region</td>
                <td><?cs var:origin.region ?></td>
            </tr>
            <tr>
                <td>Magnitude</td>
                <td><?cs var:float(origin.magnitude, 1) ?> <?cs var:origin.magnitude.type ?></td>
            </tr>
        </table>
        <h3>Evaluation</h3>
        <p>
        Earthquakes of this size have the potential to generate a widespread destructive tsunami that can affect coastlines across the entire <?cs var:region ?>.
        </p>
        <p>
        However - it is not known that a tsunami was generated. This watch is based only on the earthquake evaluation. Authorities in the region should take appropriate action in response to the possibility of a widespread destructive tsunami.
        </p>
        <p>
        Due to only limited sea level data from the region it is not possible for this center to rapidly confirm nor evaluate the strength of a tsunami if one has been generated.
        </p>
        <h3>Simulation results</h3>
        <p>Estimated maximum sealevel surface height and initial tsunami wave arrival times. Actual arrival times may differ and the initial wave may not be the largest. The time between successive tsunami waves can be five minutes to one hour.
        </p>
        <table>
            <tr><td><img src="<?cs var:addGrid("SSH max", "*", 0, true)
                            ?><?cs var:setOriginSymbol("circle", false)
                            ?><?cs var:setGradientProfile("DefaultProfile")
                            ?><?cs var:renderMeta("ptwc_ocean_sshmax.png", true) ?>" alt = ""></td>
                <td><img src="<?cs var:addGrid("Arrival times", "*", 0, true)
                            ?><?cs var:addGrid("Arrival lines", "*", 0, false)
                            ?><?cs var:setOriginSymbol("circle", false)
                            ?><?cs var:setRenderOptions("mapProjection=Rectangular, mapZoomLevel=5.0, showMap=true, showGlobalGeoFeature=true, showGrid=true")
                            ?><?cs var:renderMeta("ptwc_ocean_arrivaltimes.png", true) ?>" alt = ""></td></tr>
            <tr><td>Maximum Sealevel Surface Height</td> <td>Arrival Times</td></tr>
        </table>
        <br />
        <table border="1">
            <tr>
                <th>POI</th>
                <th>Location</th>
                <th>Country</th>
                <th>ETA</th>
                <th>OTA</th>
                <th>OTM</th>
                <th>OTMSSH(m)</th>
                <th>OTP(min)</th>
                <th>Runup(m)</th>
            </tr>
            <?cs each:item = Arrivals ?><?cs if:(item.T1Time || item.OTA) && ge(item.Runup, "0.25")
            ?><tr>
                    <td><?cs var:item.POI ?></td>
                    <td><table border="0" width="100%">
                        <col width="50%">
                        <col width="50%">
                        <tr>
                            <td align="right"><?cs var:strfcoord(item.Location.latitude, "%.3F%c") ?>&#160;</td>
                            <td align="right"><?cs var:strfcoord(item.Location.longitude, "%.3F%c") ?></td>
                        </tr>
                      </table>
                    </td>
                    <td><?cs var:item.Country ?></td>
                    <td><?cs var:item.T1Time ?></td>
                    <td align="right"><?cs var:item.OTA ?></td>
                    <td align="right"><?cs var:item.OTM ?></td>
                    <td align="right"><?cs var:float(item.OTMSSH, 2) ?></td>
                    <td align="right"><?cs var:item.OTP ?></td>
                    <td align="right"><?cs var:float(item.Runup, 2) ?></td>
               </tr><?cs /if
            ?><?cs /each ?>
        </table>
        <p>
        This will be the only bulletin issued by the <?cs var:agencyID ?> for this event unless additional information becomes available.
        </p>
    </body>
</html>

ClearSilver Syntax

Basically, the bulletins are generated based on templates which are filled with data related to an incident, like earthquake origin, simulation results and forecast zone warning levels. To achieve this, TOAST uses a fast and language-neutral 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: Template file examples above.

Each ClearSilver command starts with the opening tag <?cs and ends with the closing tag ?>.

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 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:

<?cs var:origin.time ?>

Common variables

agencyID

The id of the agency.

availableTime

Returns the available simulation duration.

creationTime

The creation time and date of the bulletin.

ID

The ID of the event.

testMode

Indicates if the test mode is enabled or disabled.

Origin parameters

origin.depth

The depth of the earthquake in km.

origin.latitude

The latitude coordinate of the epicenter in degrees.

origin.longitude

The longitude coordinate of the epicenter in degrees.

origin.magnitude

Magnitude of the earthquake.

origin.magnitude.type

Magnitude type of the earthquake.

origin.region

The region of the earthquake.

origin.time

The origin time.

Grid rectangle coordinates

Access the corner coordinates of the last getGrid() export.

grid.box.top

Latitude coordinate of the grid rectangle’s top edge.

grid.box.left

Longitude coordinate of the grid rectangle’s left edge.

grid.box.bottom

Latitude coordinate of the grid rectangle’s bottom edge.

grid.box.right

Longitude coordinate of the grid rectangle’s right edge.

Map rectangle coordinates

Access the corner coordinates of the TOAST Map perspective.

map.box.top

Latitude coordinate of the map rectangle’s top edge.

map.box.left

Longitude coordinate of the map rectangle’s left edge.

map.box.bottom

Latitude coordinate of the map rectangle’s bottom edge.

map.box.right

Longitude coordinate of the map rectangle’s right edge.

Datasets

Nearest cities

A record of information of the nearest cities.

NearestCities.[0..n - 1]
NearestCities.[i].azimuth
NearestCities.[i].distance
NearestCities.[i].name
NearestCities.[i].lat
NearestCities.[i].lon

Note

The data set does not contain data until the function nearestCities() has been called.

Arrivals
Arrivals.[0..n - 1].[column name]

The i-th value of the arrivals overview. For instance: Arrivals.0.POI.

Forecast Zones
ForecastZones.[0..n - 1].[column name]

The i-th value of the forecast zones overview. For instance: ForecastZones.0.Name.

Simulations
simulations.[0..n - 1]

Returns the i-th simulation.

simulations.[i].id

The simulation ID.

simulations.[i].type

The simulation backend used for the simulation.

simulations.[i].source.depth

The depth in km of the simulation earthquake.

simulations.[i].source.latitude

The latitude coordinate of epicenter in degree of the simulation earthquake.

simulations.[i].source.longitude

The longitude coordinate of the epicenter in degree of the simulation earthquake.

simulations.[i].source.magnitude

The magnitude of the simulation earthquake.

simulations.[i].source.region

The region of the simulation earthquake.

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:

<?cs var:setCurrentDir("/tmp/toast") ?>

The TOAST specific functions are listed below.

Common functions

addTimeSpan(time, seconds)
Parameters
  • time – The time string.

  • seconds – The number of seconds as integer value.

Return type

String

Adds n seconds to the given time.

currentTime()
Return type

String

Returns the current time in UTC.

fill(in, width, ch, align)
Parameters
  • in – The Input string.

  • width – The field width of the output.

  • ch – The fill character which is used when the result is padded to the field width.

  • align – Alignment of the output.

Return type

String

Fills the input string with characters according the alignment(0 = left, 1 = right, 2 = center).

float(in, int precision)
Parameters
  • in – The input string.

  • precision – The precision of the output.

Return type

String

Formats floating point numbers.

ge(arg1, arg2)
Return type

Boolean

Returns true if arg1 is greater than or equal to arg2.

gt(arg1, arg2)
Return type

Boolean

Returns true if arg1 is greater than arg2.

le(arg1, arg2)
Return type

Boolean

Returns true if arg1 is less than or equal to arg2.

localTime()
Return type

String

Converts give time from UTC to local time.

lt(arg1, arg2)
Return type

Boolean

Returns true if arg1 is less than arg2.

strfazi(azimuth)
Parameters

azimuth – Azimuth.

Return type

String

Prints the geographic direction.

strfcoord(in, fmt)
Parameters
  • in – Latitude/ longitude value.

  • fmt – The format string.

Return type

String

Formats coordinates.

strftime(in, fmt)
Parameters
  • in – The input string.

  • fmt – The format string. See the strftime man page for available format flags.

Return type

String

Formats a given time.

toLower(in)
Parameters

in – The input string.

Return type

String:

Converts the given input string to lower case.

toLocalTime(in)
Parameters

in – The input string.

Return type

String:

Converts given time from UTC to local time.

toUpper(in)
Parameters

in – The input string.

Return type

String:

Converts the given input string to upper case.

Functions with relation to bulletins

isLive()
Return type

bool

Returns whether the template is displayed in one of the live tabs.

useLocalTime(time)
Parameters

time – The input time.

Return type

bool

Returns whether the time is changed to local time.

nearestCities(lat, lon, maxDist, minPopulation, maxCount)
Parameters
  • lat – Position for which the nearest cities are to be searched.

  • lon – Position for which the nearest cities are to be searched.

  • maxDist – Maximum distance from position to city.

  • minPopulation – Minimum population of the city.

  • maxCount – Maximum number of cities.

Fills the dataset Nearest cities

loadGradient(profile, gradient)
Parameters
  • profile – String: The name of the gradient profile.

  • 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:

<?cs var:loadGradient("DefaultProfile", "Forecast zones") ?>
<?cs each:item = grad.DefaultProfile.Forecastzones ?>
    <?cs var:item.color ?> <?cs var:item.text ?>
<?cs /each ?>
loadJSON(filename)
Parameters

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:

<?cs var:loadJSON("@DATADIR@/toast/templates/training_definitions.json") ?>
<?cs if:testMode ?> Description: <?cs var:description ?>
    <?cs each:zone = testForecastZones ?>
        Name: <?cs var:zone.name ?>
        Code: <?cs var:zone.code ?>
    <?cs /each ?>
<?cs /if ?>

for the JSON file training_definitions.json:

{
    "description": "Test Description",
    "testForecastZones": [
        {
            "name": "Zone 1",
            "code": "1"
        },
        {
            "name": "Zone 2",
            "code": "2"
        }
    ]
}
loadTranslation(filename)
Parameters

filename – String: The filename of the translation map file in INI format.

Loads translation map from file.

Set paths and save bulletins

save(filename)
Parameters

filename – Output file name.

Saves the content of the bulletin to the file with the given filename.

saveArrivalLines(simType, filename, prettyPrint)
Parameters
  • simType – Simulation type. Example: “EasyWave2”. Use “*” for all types.

  • filename – Filename of the output GeoJSON file.

  • prettyPrint – Pretty print JSON output (false/true).

Saves arrival lines of the selected simulation(s) to a file in GeoJSON format. Example:

<?cs var:saveArrivalLines("/tmp/arrivallines.geojson", "*", false) ?>
resolvePath(path)
Parameters

path – Path which can contain SeisComP-variables.

Returns absolute path with resolved SeisComP-variables. Example:

<?cs set:dataToast = resolvePath("@DATADIR@/toast/") ?>
setCurrentDir(path)
Parameters

path

Changes the current working directory to the directory given in path. If the directory doesn’t exit, it is created.

tmpFile(template)
Parameters

template – Template which may contain the characters ‘XXXXX’.

Return type

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

addScript(filename)
Parameters

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

render(fileName, showLink)
Parameters
  • fileName – Output file.

  • showLink – Indicates whether a link to the result is returned or not.

Return type

String

Renders the current rendering stack and saves the result as an image to the given filename.

renderMeta(fileName, showLink)
Parameters
  • fileName – Output file.

  • showLink – Indicates whether a link to the result is returned or not.

Return type

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.

getGrid(type, simType, step, fileName)
Parameters
  • type – Type of the grid. Currently available: “SSH max”, “SSH”, “Arrival times”.

  • simType – Simulation type. Example: “EasyWave2”. Use “*” for all types.

  • step – Time step.

  • 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 grid.box.left, grid.box.right, grid.box.top and grid.box.bottom to the grid coordinates.

Note

See function saveArrivalLines to export arrival lines in GeoJSON format.

Configure images

addGrid(type, simType, step, config)
Parameters
  • type – Type of the grid. Currently available: “SSH max”, “SSH”, “Arrival times”, “Arrival lines”.

  • simType – Simulation type. Example: “EasyWave2”. Use “*” for all types.

  • step – Time step in seconds.

  • 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. Find supported grids below:

Plugin

Grids

EasyWave2

Arrival lines, Arrival times, SSH, SSH max

Supported variables for the config parameter:

Variable

Type

showLegend

bool

legendTitle

string

legendTextAlign

‘left’, ‘right’, ‘center’

legendFontSize

int

legendSpacing

int

legendOrientation

‘horizontal’, ‘vertical’

addLayer(name, config)
Parameters
  • type – Name of the layer.

  • config – Configuration.

Adds a layer to the rendering stack. Supported layers are given below.

Layer

Config options

forecast zones

see supported config parameters fo addGrid, additionally: gradient - string, gradientProfile - string, drawFilled: bool, drawInactive: bool, inactiveFillColor - string, inactiveLineColor - string, defaultLineColor - string, brush - string

setOriginSymbol(shape, fill)
Parameters
  • shape – Name of the shape. Available shapes are circle (black border as in map view), circle-seiscomp (red border as in SeisComP) and star. The default shape is circle.

  • fill – Indicates whether the symbol should be filled or not (default: filled).

Sets the origin symbol of the map.

setGradientProfile(name)
Parameters

name – Gradient profile name.

Set the gradient profile to the given name.

For more information on color gradients, see: Color profiles and gradients configuration.

setRenderOptions(config)
Parameters

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

setScenarioColors(colors)
Parameters

colors (string (list separated by ',', e.g. "white, red")) – List of colors.

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.

alignLegends(inout, orientation, align)
Parameters
  • inout – Legends inside or outside of the image (“in”,”out” or “” (default: inside)).

  • orientation – Horizontal or vertical legend (“horizontal”, “vertical” or “” (default: vertical)).

  • 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.

setGlobalLayerConfig(str)
Parameters

str – String with information about how to show the legend text.

Return type

string

See layer configuration for more detail.

setWatermark(str)
Parameters

str – String with information about the copyright.

Return type

string

Set information about the file e.g. the date of copyright.

showCurrentStepTime(step)
Parameters

step – Time step in seconds.

Sets the current time step.

forecastZone(id)
Parameters

id – ID of a forecast zone.

Return type

string

Returns the forecast zone in kml format.

Set image size

setDisplayRect(lat, lon, height, width)
Parameters
  • lat – Latitude value.

  • lon – Longitude value.

  • height – Height of the rectangle.

  • 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.

setSize(width, height)
Parameters
  • width – The width of the output image.

  • height – The height of the output image.

Sets the size of the output image.

setMegapixel(megaPixel)
Parameters

megaPixel – Number of mega pixel (floating point).

Sets the image size to approximately megaPixel.