reference.md

Table of Contents

• Table of Contents
• Product definition
  • Product configuration
    • Shared attributes
      • Time intervals
      • Clipping and margins
      • Output formatting
    • Product level attributes
    • Views
    • Layers
      • BackgroundLayer
      • MapLayer
      • LocationLayer
      • IsobandLayer
      • IsolineLayer
        • isolines-attribute
      • IsolabelLayer
      • SymbolLayer
        • mindistance and priority
      • ArrowLayer
      • NumberLayer
      • NullLayer
      • CloudCeilingLayer
      • StreamLayer
      • LegendLayer
      • TimeLayer
      • TagLayer
      • WKTLayer
      • TranslationLayer
      • WindRoseLayer
      • PostGISLayer
      • IceMapLayer
      • FinnishRoadObservationLayer
        • Algorithm to deduce weather condition symbol
      • PresentWeatherObservationLayer
        • Algorithm to deduce present weather symbol
    • Structure definitions
      • Attribute structure
      • AttributeSelection structure
      • Projection structure
      • Defs structure
      • Smoother structure
    • Sampling structure
      • Heatmap structure
      • Isoband structure
      • Intersection structure
      • Isoline structure
      • Isofilter structure
      • LegendLabels structure
      • LegendSymbols structure
      • Text structure
      • Map structure
      • MapStyles structure
      • MapFeature structure
      • Positions structure
      • Label structure
      • Location structure
      • Observation structure
      • Station structure
      • WindRose structure
      • Connector structure
      • Filters structure
• Using dynamically created grids
  • Introduction
  • Grids with the same timestamp
  • Grids calculated over multiple timesteps
  • Functions
• Generic querystring options
• WMS GetMap and GetCapabilities configuration
  • WMS layer variants
• Configuration
  • Main configuration file
  • Plugin configuration file

Product definition

Product configuration

There can be thousands of different products defined for the Dali plugin. Each product has its own configuration file, which is used in order to define values for the attributes needed when constructing the final image. The table below shows an example of a product configuration file and the image that is returned when this product is requested.

Product configuration file

Produced image

{ // *** Product "title": "MyRedMap", "projection": { "xsize": 300, "ysize": 550, "crs": "EPSG:2393", "bboxcrs": "EPSG:4326", "cy": 64.8, "cx": 25.4, "resolution": 2.5 }, "views": [ { // *** View 1 "layers": [ { // **** Layer 1 : Light blue background "layer_type": "background", "attributes": { "stroke": "none", "fill": "rgb(190,230,255)" } }, { // *** Layer 2 : Red map with black borders "layer_type": "map", "map": { "schema": "natural_earth", "table": "europe_country_wgs84" }, "attributes": { "class": "Europe", "stroke": "black", "stroke-width": "0.5", "fill": "rgb(255,0,0)" } } ] } ] }

f

The product configuration files are written in Java Script Object Notation (JSON). In order to create your own product configuration files you just need to know what attributes are used on different configuration levels, i.e., what attributes can be given on the product level, on the view level and on the layer level. These attributes are described flater in this chapter.

The attribute description for each attribute consists of the attribute name, the attribute type, the default value and a short description of the attribute usage. In the attribute description the attribute type can be defined in the following ways:

Type	Description
(string)	A string with no default value. Not giving a value to the string may be considered as an error if the title for the SVG is not defined, or if no default symbol name is given for a legend.
string	A string. Usually this variable needs to be defined, for example, qid to give an ID to isobands. The string may also have a default value, for example, the default separator for the LegendLabels is an "en dash" (Unicode 2013).
Structure	When the type is a structure name then the attribute value is defined as a structure, or the value is a reference to a such structure. For example "projection" -attribute is defined to be the type of Projection structure, which means that it contains a list of attributes defined for the Projection structure.
[Structure]	An array of structures. The type of the structure is defined inside the brackets. For example an attribute which type is [Layer] contains an array of Layer structures.
{string:string}	A map from names to values.
{string:string:string}	A map from principal names to a map of name-value pairs.

Shared attributes

There are some upper level attributes that can be used also on the lower level in the hierarchy. For example, some attributes defined on the product level are visible also on the view and layer levels. These levels can directly use these upper level attribute values or override the values with their own values. These attributes can be overridden also by the request parameters. For example, the "language" attribute can be overridden by using the "language" parameter in the request.

The table below contains a list of attributes that are shared from the top level to the lower levels.

Shared attributes 

Name	Type	Default value	Description
language	(string)	config:language	Language code. The code does not need to follow ISO 639-1 or other similar standards, it is merely a code name.
customer	(string)	config:customer	The customer name. The customer setting defines the subdirectory in the Dali configuration directory from which the JSON, CSS and SVG includes are taken, unless an absolute path is given for a JSON include.
producer	(string)	config:model	The producer name to be used when querying data from QEngine.
tz	(string)	UTC	The timezone used for parsing time (but not origintime)
time	(string)		The time in any string format recognized by the MacGyver time parser (ISO-format, SQL, timestamps, epoch times, offsets from current time).
time_offset	(int)		The time offset in minutes to be added to the time. The principal time is usually set at the top most level (Product), and a time_offset is then used to modify it for different views of data.
interval_start	(int)		Time in minutes backward from time+time_offset. Used for selecting an interval of observations.
interval_end	(int)		Time in minutes forward from time+time_offset. Used for selecting an interval of observations.
origintime	(string)		The querydata origintime in any string format recognized by the MacGyver time parser (ISO-format, SQL, timestamps, epoch times, offsets from current time).
projection	Projection		The Projection structure.
xmargin	int	0	X-margin in pixels for clipping out features.
ymargin	int	0	Y-margin in pixels for clipping out features.
clip	bool	false	Whether each layer should be placed into a rectangular clipPath.

Time intervals

Normally the "valid time" for the data is time + time_offset. If a time interval is defined, it is producer dependent how the settings are interpreted. Most layers ignore the settings, and the settings are ignored for all forecasts. For lightning data the interval is true, all flashes in the interval are picked. For other observations only the latest one in the time interval will be selected. For this reason interval_end is usually not needed for observations either.

Clipping and margins

Normally any point strictly outside the layer rectangle will be omitted. However, if the image will be tiled, this may produce images where symbols or text appear only in one tile, and the rest of the symbol is cut off from the adjacent tile. The layer effective bounding box may be expanded using the setting "margin", which sets both the x-margin and y-margin, or directly by setting "xmargin" and/or "ymargin".

For observations any point inside the expanded area will be included. Typically one would expand the layer by half the size of any symbol needed in the image, be it a symbol, a number or whatever. The marging has an effect also on geometries. For example if one wishes to draw isolines with a line a few pixels wide, the margings should be expanded accordingly.

For tiled images expanding the area has no discernible effect, since the clipping will be automatic since the rendered image is still the expected size and does not include the margins. However, if one has multiple views in a single image, one should set "clip" to true to make sure none of the layers leak outside their respective areas. Using a clipPath slows rendering down a little, hence it is not on by default.

Output formatting

PNG output formatting can be tuned using the following settings inside a top level "png" tag:

Name	Type	Default value	Description
quality	(double)	10	The PNG compression level. 10=good, 20=poor
errorfactor	(double)	2.0	Tuning parameter for color reduction. Must be greater than 1.0
maxcolors	(int)	0	Desired maximum number of colors in the palette. Zero implies no maximum, and palette fitting will be fully adaptive
truecolor	(bool)	false	Set to avoid color reduction completely

Product level attributes

The product level is the highest structural level used in the product configuration file. The product attributes are used in order to define product level properties for the current product. On the other hand, the product attributes define the substructures related to the current product.

The table below contains a list of attributes that can be defined for the product.

Product 

Name	Type	Default value	Description
svg_tmpl	(string)	config:templates	The CTPP2 template to be used for generating the SVG image. The default template is selected automatically based on the selected image format.
qid	(string)	-	An identifier for the product. Usually this can be left empty.
width	(int)	projection.xsize	The width of the SVG image. If the product contains only one view with no transformations, the default value will be taken from the Product projection xsize variable.
height	(int)	projection.ysize	The height of the SVG image. If the product contains only one view with no transformations, the default value will be taken from the Product projection ysize variable.
title	(string)	-	The title of the generated SVG image.
attributes	Attributes	-	The SVG image attributes for the product level <g>...</g> group.
defs	Defs	-	The SVG image header definitions such as styles, symbols, paths not to be drawn directly etc. This information is defined as the Defs structure, which is described in the next section.
views	[View]	-	An array of the View structures used in the SVG image. Usually a product has only one View structure which shares the projection defined on the product level.

Views

A product can contain several views that are merged together into single image / product. The product level attribute "views" are used in order to define an array of the View structures for the product. Each view must have its own View structure in this array. The View structure is used in order to define the view level attributes and the lower level structures (i.e. layers).

The table below contains a list of attributes that can be defined in the View structure.

View

Name	Type	Default value	Description
qid	(string)	-	An identifier for the view. Normally something simple such as "view1" or "v1".
attributes	Attributes	-	The SVG attributes for the View level ... group.
layers	[Layer]	-	An array of the Layer structures needed in order to construct the view.

Layers

A view can contain several layers that are merged together into single view. The view level attribute "layers" are used in order to define an array of the Layer structures for the view. Each layer must have its own Layer structure in this array. The Layer structure is used in order to define layer level properties. The most important attribute on the layer level is the "layer_type" attribute, which defines the type of the current layer. At the same time it defines indirectly which layer module the Dali plugin should use to create an image for the current layer. On the other hand, the layer type tells us which other attributes we should define for the current layer. In other words, if the layer type is for example "isoband" then we should define on this level also all isoband layer related attributes. All the layers share some common attributes. In addition, each layer type has its own attributes. The table below contains a list of attributes that are common in all layers.

Layer

Name	Type	Default Value	Description
qid	(string)	-	An identified for the layer. Normally something simple such as "layer1" or "t2mlayer" or just "l1".
css	(string)	-	An external CSS file to be included into the style section. E.g., "isobands/temperature.css".
attributes	Attributes	-	The SVG attributes for the Layer level top SVG tag. Often the tag is <g>, but may be any other tag too for example when layer_type=tag is used.
layer_type	(string)	"tag"	The type of the layer.
			Value	Layer
			background	BackgroundLayer
			map	MapLayer
			location	LocationLayer
			isoband	IsobandLayer
			isoline	IsolineLayer
			isolabel	IsolabelLayer
			symbol	SymbolLayer
			arrow	ArrowLayer
			number	NumberLayer
			null	NumllLayer
			cloudceiling	CloudCeilingLayer
			stream	StreamLayer
			legend	LegendLayer
			time	TileLayer
			tag	TagLayer
translation	TranslationLayer
windrose	WindRoseLayer
postgis	PostGISLayer
icemap	IceMApLayer
minresolution	(double)	-	Minimum resolution of the projection for the layer to be generated at all.
maxresolution	(double)	-	Maximum resolution of the projection for the layer to be generated at all.

Notice that the term "resolution" used above might be a little bit misleading in this case, since it refers to the number of kilometers represented by one pixel. Hence the higher the resolution the worse the accuracy of the image actually is. The actual condition to be satisfied is minresolution <= resolution < maxresolution, where one or both of the limits may be missing.

BackgroundLayer

The background layer is used to create a background for the current view. So it is usually the lowest layer in the view.

The table below shows a simple example on the usage of the background layer.

Product configuration file	Produced image layer
{ // *** Product "title": "MyLightBlueBackground", "projection": { "xsize": 300, "ysize": 550, "crs": "EPSG:2393", "bboxcrs": "EPSG:4326", "cy": 64.8, "cx": 25.4, "resolution": 2.5 }, "views": [ { // *** View 1 "layers": [ { // **** Layer 1 : Light blue background "layer_type": "background", "attributes": { "stroke": "none", "fill": "rgb(190,230,255)" } } ] } ] }

The background layer has no attributes than the generic Layer or Properties attributes. The layer exists merely to obtain the "xsize" and "ysize" attribute values for a rectangle element so that the background can be filled with a value.

MapLayer

The table below shows a simple example on the usage of the map layer.

Product configuration file	Produced image layer
{ // *** Product "title": "MyMap", "projection": { "xsize": 300, "ysize": 550, "crs": "EPSG:2393", "bboxcrs": "EPSG:4326", "cy": 64.8, "cx": 25.4, "resolution": 2.5 }, "views": [ { "layers": [ { "layer_type": "map", "map": { "schema": "natural_earth", "table": "europe_country_wgs84" }, "attributes": { "class": "Europe" } } ] }] }

The table below contains a list of attributes that can be defined for the map layer in addition to the common layer attributes.

MapLayer

Name	Type	Default value	Description
map	Map	-	The Map structure
precision	double	1.0	Precision of SVG coordinates
styles	[MapStyles]	-	Optional regional styling based on forecast values

LocationLayer

The location layer can be used to point specific locations in the image. For example, we can create an image layer that shows all important cities by using predefined symbols. It is also possible to use different symbols based on some information. For example, we can use a red square symbol for cities with population over a million and a red circle symbol for cities with population less than a million, but more than fifty thousand.

The table below shows a simple example on the usage of the location layer.

Product configuration file

Produced image layer

{ // *** Product "title": "MyCities", "projection": { "xsize": 300, "ysize": 550, "crs": "EPSG:2393", "bboxcrs": "EPSG:4326", "cy": 64.8, "cx": 25.4, "resolution": 2.5 }, "views": [ { // *** View 1 "attributes": { "id": "view1" }, "layers": [ { // *** Layer 1 : Map "layer_type": "map", "map": { "schema": "natural_earth", "table": "europe_country_wgs84" }, "attributes": { "class": "Europe" } }, { // *** Layer 2: Cities "qid": "cities", "layer_type": "location", "keyword" : "ely_cities", "css": "maps/map.css", "symbols": { "default": [ { "hilimit": 1000000, "symbol": "city" }, { "lolimit": 1000000, "symbol": "bigcity" }], "PPLC": [ { "symbol": "capital" } ] } } ] } ] }

The table below contains a list of attributes that can be defined for the location layer in addition to the common layer attributes.

LocationLayer

Name	Type	Default value	Description
keyword	string	-	The geonames keyword.
mindistance	double	30	Minimum distance between location symbols.
countries	(string) or string	-	Allowed country isocodes.
symbol	(string)	-	Default symbol.
symbols	[AttributeSelection] or {string:[AttributeSelection]}	-	Symbol selection based on population, or a map from feature codes to symbol selection.

IsobandLayer

The isoband layer can be used to add filled contours (= isobands) to the view. Isobands can be used for presenting several kinds of data such as temperatures, rain amounts, cloudiness, ice cover, flash heatmap etc.

The tables below show simple examples on the usage of the isoband layer.

Product configuration file

Produced image layer

{ // *** Product "title": "MyCloudiness", "projection": { "xsize": 300, "ysize": 550, "crs": "EPSG:2393", "bboxcrs": "EPSG:4326", "cy": 64.8, "cx": 25.4, "resolution": 2.5 }, "views": [ { // *** View 1 "layers": [ { // *** Layer 1 : Cloudiness "layer_type": "isoband", "isobands": "json:isobands/cloudiness.json", "css": "isobands/cloudiness.css", "parameter": "TotalCloudCover", "multiplier": 0.0898, "offset" : -0.49, "attributes": { "shape-rendering": "crispEdges" } } ] } ] }

/td>

Product configuration file

Produced image layer

{ // *** Product "title" : "Lightning heatmap for 15 minute period", "abstract" : "Lightning heatmap for 15 minute period", "interval_start": 15, "interval_end": 15, "projection": { "crs": "EPSG:4326", "cx" : 25, "cy" : 65, "resolution" : 5, "xsize": 500, "ysize": 500 }, "producer": "flash", "views": [{ "layers": [ { "qid": "l", "layer_type": "isoband", "parameter": "peak_current", "isobands": "json:isobands/heatmap.json", "css": "isobands/heatmap.css", "attributes": { "shape-rendering": "crispEdges" }, "heatmap" : { "resolution" : 10, "radius" : 10, "kernel" : "exp", "deviation" : 10.0 } }, { "qid": "l1", "layer_type": "map", "map": { "schema": "natural_earth", "table": "admin_0_countries", "minarea": 100 }, "attributes": { "id": "europe_country_lines", "fill": "none", "stroke": "#222", "stroke-width": "0.3px" } } ] }] }

The table below contains a list of attributes that can be defined for the isoband layer in addition to the common layer attributes.

IsobandLayer

Name	Type	Default Value	Description
parameter	(string)	-	The parameter name for the isobands.
level	double	linear	The querydata level value. By default the first level is used.
interpolation	(string)	"linear"	The interpolation method.
			Value	Description
			linear	Values are interpolated linearly.
			midpoint|nearest|discrete	Nearest point value is used.
			logarithmic	Logarithmic interpolation. Useful mostly for logarithmic parameters such as precipitation rate, which may have sharp peaks near strong showers.
			isobands	[Isoband]	-	An array if Isoband structures./td>
autoqid	(string)	-	Pattern for generating a qid for each isoband, for example "temperature_{}_{}"|
autoclass	(string)	-	Pattern for generating a class for each isoband, for example "Temperature_{}_{}"|
precision	(double)	1.0	Precision of SVG coordinates./td>
unit_conversion	(string)	-	Name of desired unit conversion defined in the configuration file.
multiplier	(double)	-	A multiplier for valid data values for unit conversion purposes.
offset	(double)	0.0	An offset for valid data values for unit conversion purposes.
smoother	Smoother	-	Smoother settings for the 2D grid data.
sampling	Sampling	-	Sampling settings for the 2D grid data.
extrapolation	int	0	How many grid cells to extrapolate data into regions with unknown values
minarea	double	-	Mimimum area for polygons, including holes
areaunits	(string)	km^2	Units for minarea setting. km^2 or px^2
isofilter	Isofilter	-	Lowpass filter for isolines/isobands. Preferable to smoother settings when data resolution is high.
heatmap	Heatmap	-	Heatmap settings.
inside	Map	-	Intersect isoband with the map
outsider	Map	-	Substract map from isoband.
intersect	[Intersection] or Intersection	-	Alternate isoband(s) with which to intersect.
closed_range	bool	true	True if the last isoband is a closed interval. For example for percentages one would want range 90 <= x <= 100 instead of 90 <= x < 100.
validate	bool	false	True if the geometries are to be validated (slow, for debugging purposes)
strict	bool	false	In strict mode invalid geometries cause an error. Extra information will be dumped to the journal and attached to the thrown exception
desliver	bool	false	True if sliver polygons are to be removed

In automatic qid and class generation "." will be replaced by ",", since "." is reserved for JSON paths. If both the lower limit and upper limit are undefined, "nan" will be used to fill the pattern. If only the lower limit is missing, "-inf" will be used. If only the upper limit is missing, "inf" will be used.

IsolineLayer

The isoline layer can be used to add isolines to the view. Isolines can be used to present several kinds of data like pressure variations, altitude variations, etc.

The table below shows a simple example on the usage of the isoline layer.

Product configuration file

Produced image layer

{ // *** Product "title": "MyPressure", "projection": { "xsize": 300, "ysize": 550, "crs": "EPSG:2393", "bboxcrs": "EPSG:4326", "cy": 64.8, "cx": 25.4, "resolution": 2.5 }, "views": [ { // *** View 1 "layers": [ { // *** Layer 1 : Map "layer_type": "map", "map": { "schema": "natural_earth", "table": "europe_country_wgs84" }, "attributes": { "class": "Europe" } }, { // *** Layer 2 : Isoline "layer_type": "isoline", "isolines": "json:isolines/pressure.json", "css": "isolines/pressure.css", "parameter": "Pressure", "attributes" : { "class" : "Pressure" } } ] } ] } }

The table below contains a list of attributes that can be defined for the isoline layer in addition to the common layer attributes.

IsolineLayer

Name	Type	Default value	Description
parameter	(string)	-	The parameter name for the isolines.
level	(double)	-	The querydata level value. By default the first level is used.
interpolation	linear	(string)	linear or logarithmic
isolines	[Isoline]	-	An array of Isoline structures or set of parameters which define how array of Isoline structures are generated (see. isolines-attribute below)
autoqid	(string)	-	Pattern for generating a qid for each isoline, for example "temperature_{}"
autoclass	(string)	-	Pattern for generating a class for each isoline, for example "Temperature_{}"
precision	(double)	1.0	Precision of SVG coordinates.
unit_conversion	(string)	-	Name of desired unit conversion. Unit conversions are listed in the configuration file.
multiplier	(double)	1.0	A multiplier for valid data values for unit conversion purposes.
offset	(double)	0.0	An offset for valid data values for unit conversion purposes.
smoother	Smoother	-	Smoother settings for the 2D grid data.
sampling	Sampling	-	Sampling settings for the 2D grid data.
extrapolation	int	0	How many grid cells to extrapolate data into regions with unknown values.
minarea	double	-	Minimum area for closed linestrings in km^2.
areaunits	(string)	km^2	Units for minarea setting. km^2 or px^2
inside	Map	-	Intersect isoband with a map
outside	Map	-	Substract map from isoband
intersect	[Intersect] or Intersect	-	Alternate isoband(s) with which to intersect.
validate	bool	false	True if the geometries are to be validated (slow, for debugging purposes)
strict	bool	false	In strict mode invalid geometries cause an error. Extra information will be dumped to the journal and attached to the thrown exception
desliver	bool	false	True if sliver polygons are to be removed

In automatic qid/class generation "." will be replaced by ",", since "." is reserved for JSON path definitions.

isolines-attribute

Isolines are defined by using isolines-attribute. There are two alternative ways to define the attribute

1. Define explicitly array of Isoline structures

Example:

"isolines":
{
[
    {
        "qid": "pressure_950",
        "value": 950,
	"attributes": {}
    },
    {
        "qid": "pressure_960",
        "value": 960,
	"attributes": {}
    },
    {
        "qid": "pressure_970",
        "value": 970,
	"attributes": {}
    },
    {
        "qid": "pressure_980",
        "value": 980,
	"attributes": {}
    },
    {
        "qid": "pressure_990",
        "value": 990,
	"attributes": {}
    },
    {
        "qid": "pressure_1000",
        "value": 1000,
	"attributes": {}
    },
    {
        "qid": "pressure_1010",
        "value": 1010,
	"attributes": {}
    },
    {
        "qid": "pressure_1020",
        "value": 1020,
	"attributes": {}
    },
    {
        "qid": "pressure_1030",
        "value": 1030,
	"attributes": {}
    },
    {
        "qid": "pressure_1040",
        "value": 1040,
	"attributes": {}
    },
    {
        "qid": "pressure_1050",
        "value": 1050,
	"attributes": {}
    },
]
}

2. Define set of parameters which are used to generate Isoline structures. The following parameters must be defined:

Name	Type	Description	Note	Example
qidprefix	string	Prefix of isoline layer id.	optional, default value is 'isoline_'	qidprefix="pressure_isoline_"
startvalue	int/double	Value of first Isoline.		startvalue=900
endvalue	int/double	Value of last Isoline		endvalue=1100
interval	int/double	The interval between two successive Isolines.		interval=10
except	int/double or array of ints/doubles	The interval is not shown if it is divisible by except value(s) (modulo-operator)	optional	except=5 or except=[3,5]

Example:

                {
		    "qid": "l4",
                    "layer_type": "isoline",
                     "isolines": 
		    {  
			"qidprefix": "isoline_main_", 
			"startvalue": 900, 
			"endvalue": 1100,
			"interval": 5
		    },
                    "css": "isolines/pressure.css",
                    "parameter": "Pressure",
		    "attributes":
		    {
			"fill": "none",
			"stroke": "#333",
			"stroke-width": "1.5px"
		    }
                },
                {
		    "qid": "l5",
                    "layer_type": "isoline",
                    "isolines": 
		    {  
			"qidprefix": "isoline_sub_", 
			"startvalue": 900, 
			"endvalue": 1100,
			"interval": 2,
			"except": 5
		    },
                    "css": "isolines/pressure.css",
                    "parameter": "Pressure",
		    "attributes":
		    {
			"fill": "none",
			"stroke": "red",
			"stroke-dasharray": "10,5",
			"stroke-width": "1.0px"
		    }
		}

IsolabelLayer

The isolabel layer is derived from the isoline layer, and thus inherits all its settings. The settings below are then available for positioning isovalues on the isolines. It is also possible to refer to the isolines that would be generated by an isoband layer, or to list to generate isovalues explicitly without referring to another layer.

IsolabelLayer

Name	Type	Default value	Description
label	Label	-	Label settings including the orientation
angles	[double]	[0,-45,45,180]	Orientations in which local maxima are searched for suitable label positions.
upright	bool	false	Optionally turn labels upright if their angle is outside -90...90
max_angle	double	60	Allow label angles only in range -60...60
min_isoline_length	double	150	Minimum length of the isoline in pixels for placing any labels
min_distance_other	double	20	Minimum distance to labels on isolines with another value
min_distance_same	double	50	Minimum distance to labels on isolines with the same value
min_distance_same	double	200	Minimum distance to labels on the same isoline segment
max_curvature	double	90	Maximum local curvature change at the label position
stencil_size	int	5	Search N adjacent points when looking for extrema and calculating the local curvature.
isovalues	[double]	-	Array of isovalue to be used.
isobands	[Isoband]	-	Array of isoband structures. All potential values will be extracted and inserted to the isovalues array.
isolines	[Isoline]	-	Array of isoline structures. All values will be extracted and inserted to the isovalues array.

The isovalues parameter may also be a JSON object with start, stop and step (default=1) doubles.

SymbolLayer

The symbol layer can be used to add different kinds of symbols to the view. The symbols are added at the given locations and the type of the symbol depends on the value of the field defined by the "parameter" attribute. The actual symbol figures are stored in the file systems s SVG images.

The table below shows a simple example on the usage of the symbol layer.

Product configuration file

Produced image layer

{ // *** Product "title": "MyWeatherSymbols", "refs": { "myprojection": "json:maps/finlandprojection.json", "finland": { "schema": "natural_earth", "table": "finland_country_wgs84", "minarea": 100, "mindistance": 1 } }, "projection": "ref:refs.myprojection", "views": [ { "attributes": { "id": "view1" }, "layers": [ { "layer_type": "map", "map": { "schema": "natural_earth", "table": "finland_country_wgs84", "minarea": 80, "mindistance": 5 }, "attributes": { "id": "europe_country_lines", "fill": "none", "stroke": "#666", "stroke-width": "0.5pt" } }, { "layer_type": "symbol", "css": "symbols/weather.css", "symbols": "json:symbols/weather.json", "parameter": "weathersymbol", "scale": 1.25, "positions": { "layout": "latlon", "locations": [ { "longitude": 24.93417, "latitude": 60.17556 }, { "longitude": 28.27838, "latitude": 61.02292 }, { "longitude": 21.85943, "latitude": 61.57477 }, { "longitude": 25.60742, "latitude": 62.20806 }, { "longitude": 27.89568, "latitude": 62.94718 }, { "longitude": 23.13066, "latitude": 63.83847 }, { "longitude": 27.40756, "latitude": 64.13355 }, { "longitude": 24.56371, "latitude": 65.73641 }, { "longitude": 28.15806, "latitude": 67.29250 }, { "longitude": 24.15138, "latitude": 67.60517 }, { "longitude": 27.02881, "latitude": 68.90596 } ], "dx": -20, "dy": -20 } }] }] }

The table below contains a list of attributes that can be defined for the symbol layer in addition to the common layer attributes.

SymbolLayer 

Name	Type	Default value	Description
parameter	(string)	-	The parameter for the symbols.
unit_conversion	(string)	-	Name of desired unit conversion. Unit conversions are listed in the configuration file.
multiplier	(double)	1.0	A multiplier for valid data values for unit conversion purposes.
offset	(double)	0.0	An offset for valid data for unit conversion purposes.
level	(double)	-	The querydata level value. By default the first level is used.
positions	Positions	-	The positions for the symbols.
minvalues	int	0	Minimum required number of valid values (or return error response)
maxdistance	double	5	Maximum distance for a station to be accepted close enough to the position.
dx	(int)	-	Common positional adjustment for all symbols.
dy	(int)	-	Common positional adjustment for all symbols.
scale	(double)	-	Scale factor for the symbols.
symbol	(string)	-	The default symbol. This is mostly useful for marking all the positions with a single symbol.
symbols	[AttributeSelection]	-	The symbols for different data values.
mindistance	int	-	Minimum distance in pixels between symbols.
priority	string or integer array	-	Priority order of symbols.
rendering_order	string	"normal"	Rendering order of the symbol is normal or reverse with respect to priority

Note that assigning a proper scale for symbols with CSS or SVG attributes alone is difficult. Using the scale-attribute eases the scaling of the symbols.

mindistance and priority

Allowed priority values

Value	Description
min	Symbols with smallest value are drawn first.
max	Symbols with biggest value are drawn first.
extrema	Symbols with biggest mean deviation drawn first.
none	Symbols are treated equally, there is no priority order.
[83,82,81]	Symbols with values 83,82,81 are drawn first in the order given, the rest have no priority order.

Symbols are drawn on the map starting from the highest priority. If there already is a symbol nearby on the map (mindistance parameter), the symbol is not shown. Regarding mindistance and priority parameters the same logic is applied in Arrow-, Number- and CloudCeilingLayers.

ArrowLayer

The arrow layer is usually used for showing wind directions on the map. Technically it can be used for showing all kinds of directions.

The table below shows a simple example on the usage of the arrow layer.

Product configuration file

Produced image layer

{ // *** Product "title": "MyWindDirections", "projection": { "xsize": 300, "ysize": 550, "crs": "EPSG:2393", "bboxcrs": "EPSG:4326", "cy": 64.8, "cx": 25.4, "resolution": 2.5 }, "views": [ { // *** View 1 "layers": [ { // *** Layer 1 : Map "layer_type": "map", "map": { "schema": "natural_earth", "table": "europe_country_wgs84" }, "attributes": { "class": "Europe" } }, { // *** Layer 2 :Wind arrows "layer_type": "arrow", "css": "arrows/windarrow.css", "direction": "WindDirection", "speed": "WindSpeedMS", "attributes": { "id": "wind_arrows", "class": "WindArrow", "mask": "url(#windlegendmask)" }, "arrows": "json:arrows/windarrow.json", "positions": { "x": 5, "y": 5, "dx": 30, "dy": 30, "ddx": 15 } } ] } ] }

The table below contains a list of attributes that can be defined for the arrow layer in addition to the common layer attributes.

ArrowLayer 

Name	Type	Default value	Description
direction	(string)	-	The parameter name for the arrow direction.
speed	(string)	-	The parameter name for speed, if one is needed.
u	(string)	-	The parameter name for the U-component of the speed vector.
v	(string)	-	The parameter name for the V-component of the speed vector.
fixeddirection	(double)	-	Fixed direction value for testing purposes.
fixedspeed	(double)	-	Fixed speed value for testing purposes.
level	(double)	-	The querydata level value. By default the first level is used.
symbol	(string)	-	The default symbol for the arrows. May be overridden in the arrows-definitions. The special value "windbarb" has not yet been implemented.
scale	(double)	-	Scale factor for the symbols
unit_conversion	(string)	-	Name of desired unit conversion. Unit conversions are listed in the configuration file.
multiplier	(double)	-	Multiplier for the speed parameter
offset	(double)	-	Offset for the speed parameter
minrotationspeed	(double)	-	Minimum required speed for the arrow to be rotated at all
dx	(int)	-	Common positional adjustment for all arrows.
dy	(int)	-	Common positional adjustment for all arrows.
southflop	boolean	false	Set to true if the arrow symbol should be flipped horizontally in the southern hemisphere (used for wind barbs).
northflop	boolean	false	Set to true if the arrow symbol should be flipped horizontally in the northern hemisphere.
flip	boolean	false	Set to true if the arrow symbol should always be flipped vertically.
positions	Positions	-	Arrow position generation definitions.
minvalues	int	0	Minimum required number of valid values (or return error response)
maxdistance	double	5	Maximum distance for a station to be accepted close enough to the position.
arrows	[AttributeSelection]	-	SVG attribute selection for speed dependent arrows.
mindistance	int	-	Minimum distance in pixels between arrows.
rendering_order	string	"normal"	Rendering order of the symbol is normal or reverse with respect to priority
priority	string or integer array	-	Priority order of arrows.

Note: A direction parameter is sufficient to draw arrows. An additional speed component may be defined to style the arrows depending on the speed. Both U- and V-components must be specified if used, but these cannot be used simultaneously with the direction and speed parameters.

NumberLayer

The number layers is used to add numerical values for temperatures, pressures, rain amounts, etc. in the view.

The table below shows a simple example on the usage of the number layer.

Product configuration file

Produced image layer

{ // *** Product "title": "Temperature Overlay", "refs": { "myprojection": "json:maps/finlandprojection.json" }, "projection": "ref:refs.myprojection", "views": [ { // *** View 1 "layers": [ { // *** Layer 1 : Map "layer_type": "map", "map": { "schema": "natural_earth", "table": "europe_country_wgs84" }, "attributes": { "class": "Europe" } }, { // *** Layer 2 : Numbers "layer_type": "number", "css": "numbers/numbers.css", "parameter": "Temperature", "attributes": { "class": "Number", "mask" : "url(#legendmask)" }, "label": "json:numbers/integers.json", "positions": { "x": 20, "y": 18, "dx": 30, "dy": 30, "ddx": 15 } } ] } ] }

The table below contains a list of attributes that can be defined for the number layer in addition to the common layer attributes.

NumberLayer 

Name	Type	Default value	Description
parameter	(string)	-	The parameter name for the numbers.
level	(double)	-	The querydata level value. By default the first level is used.
positions	Positions	-	The positions for the numbers.
minvalues	int	0	Minimum required number of valid values (or return error response)
maxdistance	double	5	Maximum distance for a station to be accepted close enough to the position.
label	Label	-	Label definitions.
numbers	[AttributeSelection]	-	SVG attribute selection based on the value of the label.
unit_conversion	(string)	-	Name of desired unit conversion. Unit conversions are listed in the configuration file.
multiplier	(double)	1.0	A multiplier for valid data values for unit conversion purposes.
offset	(double)	0.0	An offset for valid data for unit conversion purposes.
mindistance	int	-	Minimum distance in pixels between numbers.
rendering_order	string	"normal"	Rendering order of the symbol is normal or reverse with respect to priority
priority	string or integer array	-	Priority order of numbers.

NullLayer

Null layers are merely placeholders for definitions which will be inserted into the block if a suitable STYLES option is used and the qid settings match. Sample use cases for null layers include

• enabling numbers over isobands
• enabling symbols over the underlying image
• enabling arrows over isobands
• enabling isolabels over isobands

CloudCeilingLayer

The cloud_ceiling layer is used for cloud ceiling observations (ie. the height of the base of the lowest clouds when the cloud amount is more than falf of the sky: broken, overcast or obscured)

The table below shows a simple example on the usage of the cloud_ceiling layer.

Product configuration file

Produced image layer

{ "title": "Cloud Ceiling", "abstract": "Cloud ceiling from FMI's AWS-stations", "producer": "observations_fmi", "interval_start": 15, "interval_end": 0, "language": "fi", "projection": {}, "views": [{ "qid": "v1", "attributes": { "id": "view1" }, "layers": [ { "qid": "finland", "layer_type": "map", "map": { "schema": "natural_earth", "table": "admin_0_countries", "where": "iso_a2 IN ('FI','AX')" }, "attributes": { "id": "finland_country", "fill": "rgb(255, 255, 204)" } }, { "qid": "finland-roads", "layer_type": "map", "map": { "schema": "esri", "table": "europe_roads_eureffin", "where": "cntryname='Finland'", "lines": true }, "attributes": { "class": "Road" } }, { "qid": "borders", "layer_type": "map", "css": "maps/map.css", "map": { "lines": true, "schema": "esri", "table": "europe_country_wgs84", "mindistance": 2.5, "minarea": 10 }, "attributes": { "class": "Border", "id": "BorderMap" } }, { "qid": "cities", "layer_type": "location", "keyword": "ely_cities", "css": "maps/map.css", "symbols": { "default": [ { "symbol": "city" } ] } }, { "qid": "cloud_ceiling_observations", "layer_type": "cloud_ceiling", "keyword": "synop_fi", "priority": "min", "mindistance": 35, "attributes": { "fill": "rgba(0,0,255,1.00)", "font-family": "Verdana", "font-size": "16px", "text-anchor": "middle", "stroke": "#000000", "stroke-width": 0.5 }, "label": { "padding_char": "0", "padding_length": 3, "missing": "-", "multiple": 100, "dx": 6, "dy": -10, "rounding": "towardzero" } } ] }] }

The cloudceiling layer is inherited from number layer so the same attributes are available. Label object has two new attributes 'padding_char' and 'padding_length' to format numbers.

StreamLayer

The streamline layer is used for visualizing directional parameters such as wind direction, wave direction, ice drift direction etc.

The table below contains a list of attributes that can be defined for the streamline layer in addition to the common layer attributes.

StreamLayer 

Name	Type	Default value	Description
parameter	(string)	-	The parameter name for the direction.
u	(string)	-	Alternative U-component parameter for the direction.
v	(string)	-	Alternative V-component parameter for the direction.
min_length	(int)	5	Minimum generated stream line length in pixels.
max_length	(int)	2048	Maximum generated stream line length in pixels.
line_length	(int)	32	Length of a stream line segment in pixels.
xstep	(int)	20	Streamline start point step size in x-direction.
ystep	(int)	20	Streamline start point step size in y-direction.
precision	(double)	1.0	Precision of the generated coordinates.

LegendLayer

The legend layer can be used to define legends for the colors or symbols used in the product.

The table below shows a simple example on the usage of the legend layer.

Product configuration file

Produced image layer

{ // *** Product "title": "MyLegendLayer", "refs": { "myprojection": { "xsize": 300, "ysize": 550, "crs": "EPSG:2393", "bboxcrs": "EPSG:4326", "cy": 64.8, "cx": 25.4, "resolution": 2.5 } }, "defs": { "styles": { ".Label": { "font": "Arial", "font-size": 9 }, ".Units": { "font": "Arial", "font-size": 11 } }, "layers": [ { "tag": "symbol", "attributes": { "id": "rect" }, "layers": [ { "tag": "rect", "attributes": { "width": "14", "height": "12"} } ] }, { "tag": "symbol", "attributes": { "id": "uptriangle" }, "layers": [ { "tag": "path", "attributes": {"d": "M0 12,7 0,14 12Z"} } ] } ] }, "projection": "ref:refs.myprojection", "views": [ { // *** View 1 "layers": [ { // *** Layer 1 : Wind speed labels "layer_type": "legend", "x": 10, "y": 10, "dx": 0, "dy": 12, "isobands": "json:isobands/wind.json", "symbols": { "css": "isobands/wind.css", "symbol": "rect", "start": "uptriangle", "attributes": {"stroke": "black", "stroke-width": "0.5"} }, "labels": { "type": "lolimit", "dx": 18, "dy": 14, "conversions": { "32": "> 32" } }, "attributes": { "transform": "translate(-7 0)", "id": "windlegend", "class": "Label" }, "layers": [ { "tag": "text", "cdata": "m/s", "attributes": { "x": 28, "y": 12, "class": "Units" } } ] } ] } ] }

The table below contains a list of attributes that can be defined for the legend layer in addition to the common layer attributes.

LegendLayer 

Name	Type	Default value	Description
x	int	10	X-coordinate of the first legend symbol.
y	int	10	Y-coordinate of the first legend symbol.
dx	int	0	X-coordinate offset to the next legend symbol.
dy	int	20	Y-coordinate offset to the next legend symbol.
symbols	LegendSymbols	-	Symbols to be used in the legend.
labels	LegendLabels	-	Label definitions for the legend.
isobands	[Isoband]	-	An array if Isobands structures from which to generate the legend

TimeLayer

The time layer can be used in order to add the date and time information into the view.

The table below shows a simple example on the usage of the time layer.

Product configuration file

Produced image layer

{ // *** Product "title": "MyTimeLayer", "projection" : { "crs": "EPSG:3067", "bboxcrs": "WGS84", "xsize": 320, "ysize": 384, "x1": 11.2, "x2": 31.5, "y1": 53.2, "y2": 66.5 }, "views": [ { // *** View 1 "layers": [ { // *** Layer 1 "layer_type" : "time", "timestamp" : "origintime", "timezone" : "UTC", "format" : "%d.%m.%Y/%H:%M:%S", "x" : 140, "y" : 120, "attributes": { "text-anchor": "middle", "font-size": 18 } } ] } ] }

The table below contains a list of attributes that can be defined for the time layer in addition to the common layer attributes.

TimeLayer 

Name	Type	Default value	Description
timezone	(string)	UTC	The time zone for the timestamp.
prefix	(string)	-	Prefix for the full string to be printed.
suffix	(string)	-	Suffix for the full string to be printed.
timestamp	(string) or [string]	validtime	Type of the timestamp. Valid values are "validtime", "origintime", "starttime", "endtime" and "wallclock". "now" is an alias for "wallclock". A duration can be shown instead by selecting one of "time_offset", "interval_start", "interval_end", "leadtime", "leadhour", an ISO time duration string or a signed integer with a time indicator suffix
format	(string) or [string]	"%Y-%m-%d %H:%M"	Format of the timestamp. See Boost time formatting flags.
x	(int)	-	X-position of the timestamp. If the value is negative then the position is counted from the right edge.
y	(int)	-	Y-position of the timestamp. If the value is negative then the position is counted from the bottom edge.

Both timestamp and format may be arrays, in which case their lengths should match. The formatted strings will be concatenated to the prefix and the suffix will be appended to the result. This feature can be used to print strings such as origintime + leadtime, starttime - endtime etc.

Times and time durations are formatted according to Boost.Date_time time formatter flag specifications.

TagLayer

The tag layer can be used to add different kinds of SVG elements such as lines, rectangles, circles, text, etc. in the view.

The table below shows a simple example on the usage of the tag layer.

Product configuration file	Produced image layer
{ // *** Product "title": "MyTagDemo", "width": 500, "height": 500, "views": [ { // *** View 1 "attributes": { "id": "view1" }, "layers": [ { // *** Layer 1: Yellow box with black borders "layer_type" : "tag", "tag" : "rect", "attributes" : { "x" : 150, "y" : 150, "width" : 200, "height" : 200, "fill" : "yellow", "stroke" : "black" } }, { // *** Layer 2 : Hello world text "layer_type" : "tag", "tag" : "text", "cdata" : "Hello world", "attributes" : { "x" : 250, "y" : 250, "font-size" : 18, "text-anchor" : "middle" } } ] } ] }
	Produced SVG file
	<svg width="500" height="500" xmlns="http://www.w3.org/2000/svg"     xmlns:xlink="http://www.w3.org/1999/xlink"> <title>MyTagDemo</title> <defs>    <style type="text/css"<>![CDATA[ ]]></style> </defs> <g> <g id="view1"> <rect fill="yellow" height="200" style="stroke:black" width="200" x="150" y="150"/> <text font-size="18" style="text-anchor:middle" x="250" y="250">Hello world</text> </g> </g> </svg>

The table below contains a list of attributes that can be defined for the tag layer in addition to the common layer attributes.

TagLayer 

Name	Type	Default value	Description
tag	(string)	-	The SVG tag to generate, for example "text" or "g".
cdata	(string)	-	The CDATA section for the tag. This should not be used if the tag is stand-alone.

WKTLayer

The WKT layer can be used insert an arbitrary geometry into the image in the Well Known Text format.

The table below shows a simple example on the usage of the WKT layer.

{
    "title": "WKT data",

    "projection":
    {
        "xsize": 500,
        "ysize": 500,
        "crs": "EPSG:3035",
        "bboxcrs": "WGS84",
        "cx": 25,
        "cy": 60,
        "resolution": 10
    },
    "views": [
        {
            "qid": "v1",
            "layers": [
                {
                    "qid": "mymap",
                    "layer_type": "map",
                    "map":
                    {
                        "lines": true,
                        "schema": "natural_earth",
                        "minarea": 50,
                        "table": "admin_0_countries"
                    },
                    "attributes":
                    {
                        "id": "europe",
                        "stroke": "#333",
                        "stroke-width": "0.5px",
                        "fill": "none"
                    }
                },
                {
                    "layer_type": "wkt",
                    "qid": "test1",
                    // non segmented box around Finland
                    "wkt": "POLYGON((30 60, 30 70, 20 70, 20 60, 30 60))",
                    "attributes":
                    {
                        "fill": "none",
                        "stroke": "black",
                        "stroke-width": 1
                    }
                },
                {
                    "layer_type": "wkt",
                    "qid": "test2",
                    // a bit bigger box with segmentation to 100 km resolution
                    "wkt": "POLYGON((40 50, 40 75, 10 75, 10 50, 40 50))",
                    "resolution": 100,
                    "attributes":
                    {
                        "fill": "none",
                        "stroke": "red",
                        "stroke-width": 1
                    }
                },
                {
                    "layer_type": "wkt",
                    "qid": "test3",
                    // biggest box with segmentation to 20 pixel resolution
                    "wkt": "POLYGON((50 40, 50 80, 0 80, 0 40, 50 40))",
                    "relativeresolution": 20,
                    "attributes":
                    {
                        "fill": "none",
                        "stroke": "green",
                        "stroke-width": 1
                    }
                }
            ]
        }
    ]
}

The table below contains a list of attributes that can be defined for the WKT layer in addition to the common layer attributes.

WKTLayer 

Name	Type	Default value	Description
wkt	(string)	-	The Well Known Text for the geometry.
precision	(double)	1.0	Precision of printed SVG coordinates.
resolution	(double)	-	The segmentation resolution in kilometers.
relativeresolution	(double)	-	The segmentation resolution in pixels.

By default the WKT is not segmented into smaller linesegments. However, if the CRS of the image is not geographic, long straight lines in the WKT will not curve as expected unless the WKT is segmented into multiple parts in a resolution suitable for the output image. In the example above the black WKT is not segmented at all, the red one is segmented to 100 km resolution, and the green one to 20 pixel resolution.

TranslationLayer

The translation layer can be used to create products that support multiple languages. When a product is requested we can use "language" parameter to define which language to use. In this case the "language" parameter overrides the value of the "language" attribute in the product file.

The table below shows a simple example on the usage of the translation layer.

Product configuration file	Produced image layer
{ // *** Product "title": "MyTranslationDemo ", "language": "en", "projection": { "crs": "data", "xsize": 500, "ysize": 500 }, "attributes": { "filter": "url(#shadow)" }, "views": [ { "qid": "v1", "attributes": { "id": "view1" }, "layers": [ { "layer_type": "translation", "translations": { "en": "Hello World!", "fi": "Moro maailma!" }, "attributes": { "x": "250", "y": "250", "font-family": "Verdana", "font-weight": "bold", "font-size": "55", "fill": "yellow", "stroke": "black", "text-anchor": "middle", "filter": "url(#shadow)" } } ] } ] }

The table below contains a list of attributes that can be defined for the translation layer in addition to the common layer attributes.

TranslationLayer 

Name	Type	Default value	Description
tag	string	"text"	The SVG tag to be used.
translations	{string:string}	-	The text to be selected for the active language. The language code is the key, the value is the translation.

WindRoseLayer

The windrose layer can be used to add "wind roses" into the view. A wind rose shows the average wind speed for different directions over the given time interval.

The table below shows a simple example on the usage of the windrose layer.

Product configuration file

Produced image layer

{ "projection": ..., "defs": ..., "views": [ { "layers": [ { "layer_type": "windrose", "timezone": "UTC", "starttimeoffset": -12, "endtimeoffset": 12, "css": "wind/windrose.css", "windrose": { "minpercentage": 3, "radius": 30, "sectors": 8, "symbol": "windrose", "attributes": { "class": "WindRose" }, "connector": { "startoffset": 2, "endoffset": 30, "attributes": { class": "RoseConnector" } }, "parameter": "max_t(WindSpeed)", "limits": [ { "hilimit": 8,"attributes": { "class": "LightWind" } }, { "lolimit": 8, "hilimit": 14, "attributes": { "class": "ModerateWind" } }, { "lolimit": 14, "attributes": { "class": "HeavyWind" } } ] }, "observations": [ { "parameter": "mean_t(T)", "label": { "dx": 25, "dy": 16, "suffix": " °C" }, "attributes": { class": "RoseTemperature"} }, { "parameter": "mean_t(ws_10min)", "label": { "dx": 25, "dy": 3, "suffix": " m/s" }, "attributes": { "class": "RoseMeanWind"} }, { "parameter": "max_t(ws_10min)", "label": { "dx": 25, "dy": -10, "suffix": " m/s" }, "attributes": { "class": "RoseMaxWind"} } ], "stations": [ { "fmisid": 100908, "longitude": 23, "latitude": 61, "symbol": "station", "attributes": { "class": "StationMarker"}, "title": { "text": "Utö, "dx": -10, "dy": -26, "attributes": { "class": "StationName" } } }, { "fmisid": 101673, "longitude": 25.3, "latitude": 63.8, "symbol": "station", "attributes": { "class": "StationMarker" }, "title": { "text": "Ulkokalla", "dx": -20, "dy": -26, "attributes": { "class": "StationName" } } } ] } ] } ] }

The table below contains a list of attributes that can be defined for the windrose layer in addition to the common layer attributes.

WindRoseLayer 

Name	Type	Default value	Description
timezone	string	"UTC"	The time zone used for the time settings.
starttimeoffset	int	0	Defines the (backward) time period with respect to the valid time of the actual time set for the layer.
endtimeoffset	int	24	Defines the (backward) time period with respect to the valid time of the actual time set for the layer.
windrose	WindRose	-	Wind rose appearance definitions.
stations	[Station]	-	The stations to use for the observations.
observations	[Observation]	-	The observations to be used.

PostGISLayer

The PostGIS layer can be used to create image layers based on data queried from the PostGIS database.

The table below shows a simple example on the usage of the PostGIS layer.

Product configuration file

Produced image layer

{ // *** Product "title": "Ice map", "projection": { "crs": "EPSG:2393", // YKJ "bboxcrs": "WGS84", "xsize": 800, "ysize": 800, "resolution": 1.75, "cx": 19, "cy": 60 }, "views": [ { // *** View 1 "attributes": { "id": "view1"}, "layers": [ { // *** Layer 1: Ice map "layer_type": "postgis", "lines": false, "pgname": "icemap", "schema": "icemap", "table": "seaice", "time_column": "publicationdate", "time_truncate": "day", "geometry_column": "geom", "css": "ice/icemap.css", "filters": "json:ice/icemap.json", "attributes": { "id": "iceareas" } }, { // *** Layer 2 : Country borders "layer_type": "map", "enable": "png", "map": { "lines": true, "schema": "natural_earth", "table": "europe_country_wgs84", "minarea": 20, "mindistance": 5 }, "attributes": { "id": "europe_country_line", "class": "Border" } } ] } ] }

The table below contains a list of attributes that can be defined for the PostGIS layer in addition to the common layer attributes.

PostGISLayer 

Name	Type	Default value	Description
lines	boolean	false	Should the data be handled as if it would be stroked or filled. This will alter how the data will be clipped to the view - polygons will either be preserved for filling or cut into polylines for stroking.
pgname	(string)	-	Identifier of PostGIS database. The GIS-engine configuration file defines connection info (host,database,username,password) for pgname.
schema	(string)	-	The database schema used in the database query.
table	(string)	-	The database table used in the database query.
geometry_column	(string)	-	The name of the geometry column in the specified schema.table
time_column	string	-	The name of the time column in the specified schema.table.
time_truncate	string	-
filters	Filters	-
precision	(double)	1.0	Precision of printed SVG coordinates.

IceMapLayer

IceMapLayer inherits database-related functionality such as PostGISLayer definitions and filters from the PostGISLayer.

The table below shows a simple example on the usage of the PostGIS layer.

Product configuration file

Produced image layer

{ // *** Product "title": "Ice map", "projection": { "crs": "EPSG:2393", // YKJ "bboxcrs": "WGS84", "xsize": 800, "ysize": 800, "resolution": 1.75, "cx": 19, "cy": 60 }, "views": [ { "attributes": { "id": "view1"}, "layers": [ { "layer_type": "postgis", "pgname": "icemap", "schema": "icemap", "table": "seaice", "time_column": "publicationdate", "time_truncate": "day", "geometry_column": "geom", "css": "ice/icemap.css", "filters": "json:ice/icemap.json", "attributes": { "id": "iceareas" } }, { "qid": "l3-", "enable": "png", "layer_type": "map", "map": { "lines": true, "schema": "natural_earth", "table": "europe_country_wgs84", "minarea": 20, "mindistance": 5 }, "attributes": { "id": "europe_country_line", "class": "Border" } } ] } ] }

The table below contains a list of attributes that can be defined for the ice map layer in addition to the common layer attributes.

IceMapLayer 

Name	Type	Default Value	Description
attribute_columns	(string)	-	Comma-separated list of columns in specified schema.table.
first_name_column	string	-	Column name in specified schema.table. Primary name of the location, e.g. 'Helsinki'. This is used by 'named_location'-layer.
second_name_column	(string)	-	Column name in specified schema.table.Secondary name of the location, e.g. 'Helsingfors'. This is used by 'named_location'-layer.
symbol	A symbol. Position of symbol is fetched from database		The first parameter for PostGreSQL DATE_TRUNC-function. Supported values are 'minute', 'hour', 'day', 'week' ,'month', 'year'. If time_truncate is defined it is applied to requested datetime.
layer_subtype	(string)	"geometry"	Specifies the actual layer type. Full list of supported types is listed in the table below. If layer_subtype is missing geometry type is assumed.
			Name	Description
			symbol	A symbol. Position of symbol is fetched from database.
			named_location	Location with name. Position of location is fetched from database. symbol-property can be defined to mark the location on map. first_name_column, second_name_column can be defined to show location name on map.
			coordinate_grid	Coordinate grid. Grid is drawn on requested geometry. If result set contains no geometry, grid is drawn on whole.
			degree_of_pressure	Degree of pressure for ice.
			mean_temperature	Ellipse type of label, where we have background ellipse and text written on .
			label	Rectangle type of label, where we have a background rectangle and text written on it. Attributes for background rectangle and foreground text is defined in filters' 'attribute' and 'text_attribute' sections. '*'-character is a wildcard-character: The beginning of the name can be anything, as long as it ends with 'label'-string.
			temperature_isotherm_label	Same as *label except that position (fetched from database) of label is modified a bit.
symbol	string	-	Name of file containing the symbol-definition in SVG-format. This is needed only if value of layer_subtype-property is 'symbol'. The requested geometry determines the position of the symbol.
pattern	string	0.0	Name of the file containing the pattern definition in SVG-format. The pattern is applied on the requested geometry, for example diagonal hatching on polygonal area.
precision	(double)	1.0	Precision of printed SVG coordinates.

FinnishRoadObservationLayer

FinnishRoadObservationLayer can be used to show weather conditions at road weather stations all over Finland.

The table below shows a simple example on the usage of FinnishRoadObservationLayer layer. Note! synop-font must be used to show the weather symbols correctly.

Product configuration file

Produced image layer

{ "title": "Road observations", "producer": "road", "timestep": 15, "language": "fi", "projection": { }, "views": [ { "qid": "v1", "attributes": { "id": "view1" }, "layers": [ { "qid": "finland", "layer_type": "map", "map": { "schema": "natural_earth", "table": "admin_0_countries", "where": "iso_a2 IN ('FI','AX')" }, "attributes": { "id": "finland_country", "fill": "rgb(255, 255, 204)" } }, { "qid": "finland-roads", "layer_type": "map", "map": { "schema": "natural_earth", "table": "europe_roads_eureffin", "where": "cntryname='Finland'", "lines": true }, "attributes": { "fill": "none", "stroke": "rgb(150,150,150)", "stroke-width": "0.6px" } }, { "tag": "g", "layers": [ { "qid": "l4", "layer_type": "map", "map": { "schema": "natural_earth", "table": "admin_0_countries", "minarea": 100 }, "attributes": { "id": "europe_country_lines", "fill": "none", "stroke": "#222", "stroke-width": "0.3px" } }, { "qid": "road_weather_stations_observations", "layer_type": "finnish_road_observation", "keyword": "road_weather_stations_master", "mindistance": 20, "attributes": { "font-family": "synop", "font-style": "normal", "font-weight": "normal", "font-size": 48 } } ] } ] } ] }

The table below contains a list of attributes that can be defined for finnish road observation layer.

FinnishRoadObservationLayer

Name	Type	Default value	Description
positions	Positions	-	The positions for the symbols.
label	Label	-	Label definitions.
maxdistance	double	5	Maximum distance for a station to be accepted close enough to the position.
mindistance	int	-	Minimum distance in pixels between symbols.
missing	int	106	Synop-font symbol for missing observations. Zero disables showing missing values.

Algorithm to deduce weather condition symbol

Step 1) Get the following parameters at requested timestep:

1. Mean air temperature (ILMA) of the observations from previous 24 hours
2. Precipitation type (SADE) of the nearest observation, maximum 20 minutes away
3. Precipitation form (RST) of the nearest observation, maximum 20 minutes away

Step 2) Get symbol for each station by using the following function, where 'r' is precipitation type and 'rform' is precipitation form:

if (r == 1)
    {
      if (rform == 9) return 51;         // drizzle, not freezing, intermittent, slight
      if (rform == 10) return 52;        // rain, not freezing, intermittent, slight
      if (rform == 11) return 53;        // intermittent fall of snowflakes, slight
      if (rform == 18) return 213;       // drizzle, freezing, slight
      if (rform == 19) return 223;       // rain, freezing, slight
    }
  if (r == 2)
    {
      if (rform == 9) return 209;        // drizzle, not freezing, intermittent, moderate
      if (rform == 10) return 219;       // rain, not freezing, intermittent, moderate
      if (rform == 11) return 229;       // intermittent fall of snowflakes, moderate
      if (rform == 18) return 214;       // drizzle, freezing, moderate or heavy
      if (rform == 19) return 224;       // rain, freezing, moderate or heavy
    }
  if (r == 3)
    {
      if (rform == 9) return 212;       // drizzle, not freezing, continous, heavy
      if (rform == 10) return 222;      // rain, not freezing, continous, heavy
      if (rform == 11) return 232;      // continous flall of snowflakes, heavy
      if (rform == 18) return 214;      // drizzle, freezing, moderate or heavy
      if (rform == 19) return 224;      // rain, freezing, moderate or heavy
    }
  if (rform == 13) return 225;          // rain or drizzle and snow, slight
  if (rform == 14) return 244;          // shower(s) of snow pellets or snow hail
  if (rform == 15) return 233;          // ice needles (with or without fog) 
  if (rform == 16) return 234;          // snow grains (with or without fog)
  if (rform == 17) return 236;          // ice pellets (sleet)

  // r 4,5,6 are redundant but re-check in case there is no match in the the cases above
  if (r == 4) return 53;        // intermittent fall of snowflakes, slight
  if (r == 5) return 229;       // intermittent fall of snowflakes, moderate
  if (r == 6) return 232;      // continous flall of snowflakes, heavy

Step 3) Get priority for each station by using the following function, where symbol is the symbol of the station and t2m is mean temperature of the station:

 if(t2m <= 0)
	{
	  // WINTER: t2m < 0
	  switch (symbol)
		{
		case 106:
		  return 0;
		  break;
		case 53:
		case 229:
		  return 1; 
		  break;
		case 232:
		case 233:
		case 234:
		case 236:
		case 244:
		  return 2; 
		  break;
		case 225:
		  return 5;
		  break;
		case 51:
		case 213:
		  return 6;
		  break;
		case 209:
		  return 7;
		  break;
		case 52:
		case 212:
		case 214:
		case 223:
		  return 8;
		  break;
		case 219:
		  return 9;
		  break;
		case 222:
		case 224:
		  return 10;
		  break;
		}

	}
  else if(t2m < 10)
	{
	  // SPRING OR AUTUMN: 0 > t2m < 10
	  switch (symbol)
		{
		case 106:
		  return 0;
		  break;
		case 51:
		case 52:
		case 53:
		case 213:
		case 223:
		case 225:
		  return 1;        // slight
		  break;
		case 209:
		case 219:
		case 229:
		case 233:
		case 234:
		case 236:
		case 244:
		  return 2;     // moderate
		  break;
		case 212:
		case 214:
		case 222:
		case 224:
		case 232:
		  return 4;      // heavy
		  break;
		}
	}
  else
	{
	  // SUMMER: t2m >= 10
	  switch (symbol)
		{
		case 51:
		case 52:
		case 106:
		  return 0;
		  break;
		case 209:
		case 219:
		  return 1;
		  break;
		case 212:
		case 222:
		  return 2;
		  break;
		case 213:
		  return 3;
		  break;
		case 214:
		  return 4;
		  break;
		case 225:
		  return 5;
		  break;
		case 53:
		case 223:
		  return 6;
		  break;
		case 224:
		case 229:
		  return 7;
		  break;
		case 232:
		  return 8;
		  break;
		case 233:
		case 234:
		case 236:
		case 244:
		  return 9;
		  break;
		}
	}

Step 4) Show stations on the map starting from the highest priority. If there already is a station nearby on the map (mindistance parameter), don't show the station.

PresentWeatherObservationLayer

PresentWeatherObservationLayer can be used to show present weather conditions at Automatic Weather Stations (AWS).

The table below shows a simple example on the usage of PresentWeatherObservationLayer layer. Note! synop-font must be used to show the weather symbols correctly.

Product configuration file

Produced image layer

{ "title": "Present weather observations", "producer": "opendata", "timestep": 10, "language": "fi", "projection": { }, "views": [ { "qid": "v1", "attributes": { "id": "view1" }, "layers": [ { "qid": "finland", "layer_type": "map", "map": { "schema": "natural_earth", "table": "admin_0_countries", "where": "iso_a2 IN ('FI','AX')" }, "attributes": { "id": "finland_country", "fill": "rgb(255, 255, 204)" } }, { "qid": "finland-roads", "layer_type": "map", "map": { "schema": "natural_earth", "table": "europe_roads_eureffin", "where": "cntryname='Finland'", "lines": true }, "attributes": { "fill": "none", "stroke": "rgb(150,150,150)", "stroke-width": "0.6px" } }, { "tag": "g", "layers": [ { "qid": "l4", "layer_type": "map", "map": { "schema": "natural_earth", "table": "admin_0_countries", "minarea": 100 }, "attributes": { "id": "europe_country_lines", "fill": "none", "stroke": "#222", "stroke-width": "0.3px" } }, { "qid": "wawa_observations", "layer_type": "present_weather_observation", "keyword": "synop_fi", "paramater": "WW_AWS", "mindistance": 20, "attributes": { "font-family": "synop", "font-style": "normal", "font-weight": "normal", "font-size": 48 } } ] } ] } ] }

The table below contains a list of attributes that can be defined for present weather observation layer.

PresentWeatherObservationLayer

Name	Type	Default value	Description
positions	Positions	-	The positions for the symbols.
label	Label	-	Label definitions.
maxdistance	double	5	Maximum distance for a station to be accepted close enough to the position.
mindistance	int	-	Minimum distance in pixels between symbols.
missing	int	106	Synop-font symbol for missing observations. Zero disables showing missing values.

Algorithm to deduce present weather symbol

Step 1) Get WaWa code (ww_aws) for the desired timestep

Step 2) Get symbol for each station by using the following get_symbol(float wawa-code) function:

float convert_possible_wawa_2_ww(float theValue)
{
    static const float wwCodeArray[100] =   
{0, 1, 2, 3, 4, 5, 0, 0, 0, 0,
 10, 0,13, 0, 0, 0, 0, 0,18, 0,
 28,21,20,21,22,24,29, 0, 0, 0,
 42,41,43,45,47,48, 0, 0, 0, 0,
 61,63,65,61,65,71,75,66,67, 0,
 50,51,53,55,56,57,57,58,59, 0,
 60,61,63,65,66,67,67,68,69, 0,
 70,71,73,75,79,79,79,77,78, 0,
 80,80,81,81,82,85,86,86, 0,89,
 92,17,93,96,17,97,99, 0, 0, 8};

    if(theValue >= 100 && theValue <= 199)
        return wwCodeArray[static_cast(theValue-100)];
    return theValue;
}

int get_symbol(float wawa)
{
  float value = convert_possible_wawa_2_ww(wawa);
  if(value != kFloatMissing && value > 3)
	{
	  if(value == 99)
		return 48; // synop fontin viimeinen arvo 255 osuu synop arvolle 98, onneksi myös 99 löytyy fontista, mutta sen sijainti on vain 48
	  else
		return (157 + value);
	}
  return 106; // Missing symbol 'Z'
}

Step 3) Get priority for each station by using the following function:

int get_symbol_priority(int symbol)
{
  switch (symbol)
	{
	case 106:
	  return 0;
	  break;
	case 170:
	case 171:
	case 172:
	case 173:
	  return 1;
	  break;
	case 162:
	case 163:
	case 164:
	case 165:
	case 167:
	case 168:
	case 169:
	case 174:
	case 177:
	case 178:
	case 179:
	case 180:
	case 181:
	case 182:
	case 183:
	case 184:
	case 185:
	case 186:
	case 198:
	case 207:
	case 208:
	case 213:
	case 215:
	case 217:
	case 218:
	case 227:
	case 235:
	case 242:
	case 244:
	case 246:
	case 248:
	case 249:
	case 250:
	case 251:
	  return 5;
	  break;
	case 187:
	case 188:
	case 189:
	case 193:
	case 195:
	case 197:
	case 199:
	case 200:
	case 209:
	case 210:
	case 219:
	case 220:
	case 225:
	case 228:
	case 229:
	case 233:
	case 234:
	case 236:
	case 237:
	case 240:
	  return 7;
	  break;
	case 161:
	case 175:
	case 211:
	case 216:
	case 221:
	case 223:
	case 230:
	case 231:
	case 238:
	case 252:
	case 253:
	  return 8;
	  break;
	case 201:
	case 202:
	case 203:
	case 204:
	case 205:
	case 206:
	case 212:
	case 239:
	case 241:
	case 243:
	case 245:
	case 247:
	  return 9;
	  break;
	case 166:
	case 176:
	case 190:
	case 191:
	case 192:
	case 194:
	case 196:
	case 214:
	case 222:
	case 224:
	case 226:
	case 232:
	case 254:
	case 255:
	case 48:
	  return 10;
	  break;
	}
  
  return 0;
}

Structure definitions

The product, view and layer definitions contain several attributes of type structure. This section defines attributes used in these structures.

Attribute structure

The Attributes structure is used to define attributes for the current Scalable Vector Graphics (SVG) element. This structure has quite many elements such as Product, View, Layer, etc. In this way we can define the drawing colors or the line widths that are used when the related SVG element is created.

The Attribute definitions are just plain mappings from strings to strings, i.e.. the attribute names and values are directly copied into the related XML element in the SVG file.

Using an attribute name or a value that is not in the the SVG specification may result in errors in the SVG file created.

The Attributes structure can contain one or several attribute definitions. For example:

	"attributes":
	{
   		"stroke": "black",
   		"stroke-width": "0.1"
	}

If the attribute value is a number, it can be given without the quotation marks. For example:

	"attributes":
	{
    		"stroke": "black",
    		"stroke-width": 0.1
	}

However, it should be noted that the number will then also be printed as a number into the SVG properties. In this particular case it would be wiser to use the string form, since the number 0.1 is not exactly an IEEE-754 number, and we actually get something a bit different in the output. Note that the integers in general are safe to be used without quotes.

AttributeSelection structure

Sometimes there is a need to use different SVG attributes and symbols according to field values that are used for the image drawing. For example, if there is sunny weather in location X and rainy weather in location Y, we probably want to use different weather symbols and SVG attributes for these locations in our weather map.

The AttributeSelection structure encapsulates an Attributes structure, a symbol and its usage condition in the same structure. The usage condition defines when the symbol and the attributes can be used. There is usually one AttributeSelection structure available for each condition. For example, if we have a data field that can have five different values then we probably have the AttributeSelection structure for each of these values.

The table below contains a list of attributes that can be defined in the AttributeSelection structure.

AttributeSelection 

Name	Type	Default value	Description
value	(double)	-	The value to be matched.
lolimit	(double)	-	The lower limit to be matched.
hilimit	(double)	-	The upper limit to be matched.
symbol	(string)	-	The symbol name to be associated with the match.
attributes	Attributes	-	The SVG attributes associated with the match.

EXAMPLE: Selecting a precipitation symbol according to a value:

	[
       		 {
            		"value": 0,
            		"symbol": "drizzle"
        	},
        	{
            		"value": 1,
            		"symbol": "rain"
        	},
        	...
        	{
            		"value": 6,
            		"symbol": "hail"
        	}
	]

EXAMPLE: Selecting a weather symbols and attributes:

	[
        	{
            		"value": 1,
            		"symbol": "sunny",
            		"attributes":
            		{
             			"class": "Sunny"
            		}
      		},
     		{
            		"value": 2,
            		"symbol": "partly_cloudy",
            		"attributes":
            		{
             			"class": "PartlyCloudy"
            		}
      		},
       	 ...
	]

EXAMPLE: Selecting attributes according to a value range:

	[
        	{
            		"lolimit": 3,
            		"hilimit": 5,
            		"attributes":
            		{
             			"class": "ModerateWindArrow_3_5"
            		}
        	},
      		{
 	     		"lolimit": 5,
            		"hilimit": 7,
            		"attributes":
            		{
             			"class": "ModerateWindArrow_5_7"	
            		}
        	},
      		{
            		"lolimit": 7,
            		"hilimit": 10,
            		"attributes":
            		{
             			"class": "FreshWindArrow_7_10"
           		}
      		},
        	...
	]

Projection structure

The Projection structure can be used to define a projection for a product, views or layers. The "projection" attribute is one of the shared attributes that is inherited from top to down in the product hierarchy. So, if the "projection" attribute is defined on the product level then all the views and the layers are using it, unless they do not override the value of this attribute.

The table below contains a list of attributes that can be defined in the Projection structure.

Projection

Name	Type	Default value	Description
crs	(string)	-	The projection description as understood by GDAL, or "data" implying the projection of the selected producer.
bboxcrs	(string)	-	The projection description for defining the bounding box coordinates only. If not defined, the bounding box coordinates are expected to be in the same projection as the image.
xsize	(int)	-	Width of the projection in pixels.
ysize	(int)	-	Height of the projection in pixels.
x1	(double)	-	Bottom left X-coordinate of the bounding box.
y1	(double)	-	Bottom left Y-coordinate of the bounding box.
x2	(double)	-	Top right X-coordinate of the bounding box.
y2	(double)	-	Top right Y-coordinate of the bounding box.
cx	(double)	-	Center coordinate of the bounding box.
cy	(double)	-	Center coordinate of the bounding box.
resolution	(double)	-	The resolution of the image in kilometers. A resolution of 2.5 means one pixel is approximately 2.5 kilometers in the projection used. The description is not valid if the projection is geographic (latlon) instead of geometric.

The bounding box of the projection can be defined in the following ways:

1. Bounding box with corners A bounding box is defined using the corner points and it should consist of "x1", "y1", "x2", "y2" and either "xsize" or "ysize". If both "xsize" and "ysize" are given, the aspect of the image may become distorted.

2. Bounding box with a center point A bounding box is defined using a center coordinate and it should consist of "cx", "cy", "resolution" and both "xsize" and "ysize".

3. Bounding box from data If "crs" = "data" is given and the a bounding box coordinates are not given, the bounding of the data will be used. The size still has to be defined separately.

CRS definitions

OGR/GDAL supports numerous ways to define a spatial reference. Currently OGRSpatialReference::SetFromUserInput supports the following methods:

1. Well Known Text definition - passed on to importFromWkt().
2. "EPSG:n" - number passed on to importFromEPSG().
3. "EPSGA:n" - number passed on to importFromEPSGA().
4. "AUTO:proj_id,unit_id,lon0,lat0" - WMS auto projections.
5. "urn:ogc:def:crs:EPSG::n" - ogc urns
6. PROJ.4 definitions - passed on to importFromProj4().
7. Filename - file read for WKT, XML or PROJ.4 definition.
8. Well known name accepted by SetWellKnownGeogCS(), such as NAD27, NAD83, WGS84 or WGS72.
9. WKT (directly or in a file) in ESRI format should be prefixed with ESRI:: to trigger an automatic morphFromESRI().
10. "IGNF:xxx" - "+init=IGNF:xxx" passed on to importFromProj4().

Defs structure

The Defs structure is used to define header information such as styles, symbols, paths not to be drawn directly, etc. for the generated SVG image.

The table below contains a list of attributes used in this structure.

Defs

Name	Type	Default value	Description
qid	(string)	-	An identifier for the definitions section. Usually this can be left empty, unless the query string is to be used, or some times when path data is generated into the definitions section to avoid conflicting names with the paths in the body section.
styles	{string:string:string}	-	A map from CSS class names such as ".Temperature" to a map of attribute name-value pairs. This is mostly useful when testing different styles before exporting the settings to a CSS file, or if the style is so particular to the current product that it is not desirable to put it into a shared external file.
layers	[Layer]	-	An array of Layer structures which generate content to the header only. Many layers change their behavior when defined in the definitions section. For example, normally the IsobandLayer module would generate both path data into the definitions section and a respective use-tag into the body section. In the definitions section no use-tag will be generated.

Smoother structure

Currently only the 2D Savitzky-Golay filters are supported. The filter is good at preserving local minima and maxima if at least the degree 2 is used. Larger sizes with degree 2 tend to smooth data well while preserving extrema, higher degrees preserve original data better.

The table below contains a list of attributes used in this structure.

Smoother

Name	Type	Default value	Description
size	int	-	Size of the filter. Implies 2*N+1 adjacent points are used in the weighted mean.
degree	int	-	Degree of the polynomial to fit to the data.

Sampling structure

Data to be contoured may be interpolated to another resolution. When used for temperature and topographic data is available, this may be used to provide higher apparent resolution by applying a lapse rate correction to the temperature. The desired resolution may be absolute or relative to the image resolution.

Name	Type	Default value	Description
resolution	double	-	Desired resolution in kilometers per pixel
relativeresolution	double	-	Desired relative resolution with respect to the resolution of the image resolution.
minresolution	double	-	Minimum resolution for applying sampling
maxresolution	double	-	Maximum resolution for applying sampling

Heatmap structure

Heatmap settings for "flash" producer's data. Currently parameter's (e.g. peak power) values are not used when building heatmap (they could be used for weighting). Heatmap library (https://github.com/lucasb-eyer/heatmap) supports use of custom kernels for stamp generation. Currently three kernels are implemented.

The table below contains a list of attributes used in this structure.

Heatmap

Name	Type	Default value	Description
resolution	int	-	Heatmap resolution.
radius	int	-	Stamp radius.
kernel	(string)	exp	Stamp generation: linear, sqrt or exp (standard deviation).
deviation	(double)	10.0	Deviation for exp.

Isoband structure

The table below contains a list of attributes used in the Isoband structure.

Isoband

Name	Type	Default value	Description
qid	string	-	The identifier for the isoband.
lolimit	(double)	-	The low limit value for the isoband. If omitted, -infinity is implied.
hilimit	(double)	-	The high limit value for the isoband. If omitted, +infinity is implied.
value	(double)	-	Set both low and high limits for the isoband. Usually used for discrete data with nearest neighbour interpolation.
attributes	Attributes	-	The SVG attributes for the isoband. Usually only a class is given.
label	(Text)	-	Translatable label for the isoband.

If both lolimit and hilimit are omitted, the missing values isoband will be generated.

Intersection structure

The table below contains a list of attributes used in the Intersection structure.

Intersection

Name	Type	Default value	Description
lolimit	(double)	-	The low limit value for the intersecting isoband. If omitted, -infinity is implied.
hilimit	(double)	-	The high limit value for the intersecting isoband. If omitted, +infinity is implied.
level	(double)	-	The level from which to pick the intersecting isoband.
producer	(string)	-	The model from which to take the isoband, if not the same model as in the isoband itself.
parameter	string	-	The parameter whose isoband is used to intersect the actual isoband.
smoother	(Smoother)	-	How to smoothen the intersecting isoband.
unit_conversion	(string)	-	Name of desired unit conversion. Unit conversions are listed in the configuration file.
multiplier	(double)	1.0	A multiplier for valid data values for unit conversion purposes.
offset	(double)	0.0	An offset for valid data for unit conversion purposes.

Note: Intersections work also for observation data. Instead of logical geometry operations the values are merely compared to the limits. For example, one may choose to render observed wind speed only when temperature is below zero.

Isoline structure

The table below contains a list of attributes used in the Isoline structure.

Isoline

Name	Type	Default value	Description
qid	string	-	The identifier for the isoline.
value	double	-	The isoline value. The default is NaN, which means calculating the line between missing and valid data.
attributes	Attributes	-	The SVG attributes for the isoline. Often omitted completely, and the IsolineLayer
level attributes are used instead commonly for all isolines.

Isofilter structure

Isolines and isobands can be smoothened by postprocessing the calculated polygons with a low pass filter.

Isofilter

Name	Type	Default value	Description
type	string	none	Smoother type: none, average, linear, gaussian, tukey. Gaussian filtering seems to work best.
radius	double	0	Filtering distance along the isoline in pixels. Zero disables filtering. Depending on the roughness of the data good values tend to be in the range 10-30 pixels.
iterations	integer	1	Number of passes. Zero disables filtering. Using 2-3 passes tends to remove small details better than simply increasing the radius.

Note that zooming into an image reduces the amount of smoothing since the set radius now covers a smaller area of the original data, and hence original details can be seen better.

LegendLabels structure

The table below contains a list of attributes used in the LegendLabels structure.

LegendLabels

Name	Type	Default Value	Description
type	(string)	"range"	Legend label type.
			Value	Description
			none	No labels will be generated.
			lolimit	The lower limit of the isoband will be used, unless the lolimit is missing.
			hilimit	The upper limit of the isoband will be used, unless the hilimit is missing.
			range	A range of values will be used. If lolimit is missing, "< hilimit" is used. If hilimit is missing, "> lolimit" is used. If both limits are missing, the text "MISSING" is returned. Otherwise a label of the form "lolimit...hilimit" is used where the string separating the limits is configurable separately.
format	(string)	-	printf-type format for the labels. Normally not needed, but if decimals are involved it may be best to define a format such as "%.1f" since not all numbers (such as 0.1) can be represented exactly as IEEE-754 numbers.
dx	int	30	X-coordinate offset from the respective legend symbol.
dy	int	30	Y-coordinate offset from the respective legend symbol. Depending on the type of the legend, one may often have to define this value to be the height of the respective symbol plus possibly half of the used font size.
separator	(string)	"\u2013" (endash)	The string separating the isoband lolimit and hilimit when type=range is used.
conversions	{string:string}	-	Conversions from automatically generated labels to alternate strings. Typically one may wish to change the values at the bottom and at the top of the legend to strings such as "< lolimit" or "> hilimit". The value may also be a map from language codes to translations.
attributes	Attributes	-	The SVG attributes for the labels.

LegendSymbols structure

The table below contains a list of attributes used in the LegendSymbols structure.

LegendSymbols

Name	Type	Default value	Description
css	(string)	-	External CSS file to be included for the symbols.
symbol	(string)	-	The default symbol for the legend.
start	(string)	-	The optional symbol to be used for the start of the legend.
end	(string)	-	The optional symbol to be used for the end of the legend.
missing	(string)	-	The optional symbol to be used for missing values. If not defined, no symbol will be generated for the isoband nor the respective label, meaning no translation will be necessary for the "MISSING" label.
attributes	Attributes	-	The extra SVG attributes for the symbol beyond the ones defined in the isoband.

Text structure

The text structure is used to define translatable strings with optional styling attributes. The structure may for example be used to define fixed labels for isobands.

Text

Name	Type	Default value	Description
(any string)	string	-	Translation for specific language
default	(string)	-	The default translation
attributes	Attributes	-	The extra SVG attributes for the translation

Map structure

The table below contains a list of attributes used in the Map structure.

Map

Name	Type	Default value	Description
schema	string	""	The database schema.
table	string	""	The database table.
where	string	""	The optional where clause for the PostGIS query. For example "cntryname='Finland'"
lines	boolean	false	Should the data be handled as if it would be stroked or filled. This will alter how the data will be clipped to the view - polygons will either be preserved for filling or cut into polylines for stroking.
minarea	double	-	Minimum area for polygons in square kilometers. For Finland useful values are around 10-100.
mindistance	double	-	Feature generalization tolerance in kilometers. For Finland useful values are around 1-4.

MapStyles structure

Individual map features can be styled based on a forecast value assigned for the area. For example, one can colour regions based on the forecast warning level for the area.

The table below contains a list of attributes used in the MapStyles structure.

MapStyles

Name	Type	Default value	Description
field	string	""	The database field used to identify the region (region number or name).
parameter	string	""	The forecast parameter name.
features	[MapFeature]	-	Optional mapping from field names to station numbers. If omitted, database field must be a region number
attributes	AttributeSelection	-	Mapping from forecast value to presentation attributes

Note: Optional FeatureMapping attributes override common MapLayer attributes, and attributes based on the actual data value override both.

MapFeature structure

Feature mappings are used to make database shape names to region numbers to be picked from forecast data. Feature mappings are not needed if the database contains region numbers directly. However, feature mappings can also be used to style individual regions.

The table below contains a list of attributes used in the MapFeature structure.

MapFeature

Name	Type	Default value	Description
value	string	-	The value of the database field to be mapped to a region number, typically the name of the region
number	int	-	The region number to be picked from the forecast.
attributes	[Attributes]	-	Region specific presentation attributes

Note: Optional FeatureMapping attributes override common MapLayer attributes, and attributes based on the actual data value override both.

Positions structure

The Positions structure can be used to define a list of positions which are needed in quite many layers. For example, in the NumberLayer this structure defines positions for the printed number, in the SymbolLayer it defines positions for the symbols and in the ArrowLayer it defines positions for the arrows.

The table below contains a list of attributes used in this structure.

Positions

uint

Name	Type	Default Value	Description
layout	(string)	grid	Layout type. If can have one of the following values:
			Value	Description
			grid	This layout places symbols in a fixed step pixel grid. Sometimes not the best choice for arrow-layers, experts prefer graticule-layouts.
			data	This layout places symbols at the coordinates defined by the used querydata or the stations themselves if observations are used.
			keyword	This layout places symbols at the coordinates of the locations associated with the given database keyword.
			station	This layout places symbols at the stations listed by the user.
			latlon	This layout places symbols at the locations listed by the user.
			graticule	This layout places symbols along the edges of a NxN graticule grid with a fixed step size in degrees.
graticulefill	This layout places symbols along the edges of a NxN graticule grid plus inside the graticule cell while satisfying the set minimum distance condition. This layout is recommended for arrow-layers.
xmargin	uint	0	Extra margin for coordinate generation
ymargin	uint	0	Extra margin for coordinate generation
x	uint	5	Grid layout: X-coordinate of the first number
y	uint	5	Grid layout: Y-coordinate of the first number
dx	uint	20	Grid layout: X-coordinate offset to the next number on the same row
	uint	-	Other layouts: X-coordinate adjustment for the selected position
dy	20		Grid layout: Y-coordinate offset to the next number on the next row
	uint	-	Other layouts: Y-coordinate adjustment for the selected position
ddx	uint	0	Grid layout: X-coordinate adjustment for the next row in grid layout
size	uint	10	Graticule/GraticuleFill layout: size of the graticule cell in degrees
step	uint>/td>	1	Graticule layout: step size for the graticule in degrees
mindistance	double	50	GraticuleFill layout: minimum distance between parallel and meridian symbols in pixels
keyword	string	-	Keyword layout: the database keyword
stations	XXXXX	-	Station layout: the user listed stations
locations	XXXXX	-	LatLon layout: the user listed locations
direction	string	-	Direction parameter. Specify a direction parameter or both "u" and "v" attributes
u	string	-	U-component of the direction parameter
v	string	-	V-component of the direction parameter
directionoffset	int	0	Extra displacement in the direction of the specified parameter
rotate	int	0	Extra rotational displacement
outside	Map	-	Only coordinates outside this shape will generate output
inside	Map	-	Only coordinates inside this shape will generate output
intersect	[Intersection] or Intersection	-	Isobands in which the positions must be

Note: The direction is positive for wind. For currents one may use "rotate"=90 or a negative "directionoffset". If an extra rotation is desired, it is recommended to use a negative offset.

If the layout is not "data" and the producer refers to observations, the generated candidate locations will be snapped to the nearest stations if the "maxdistance" condition set for the layer is satisfied. This way one may for example place candidate points into a grid and get an evenly distributed sample of the full set of stations.

The margins can be used to generate point locations outside the image area. This is useful for example if the symbols to be placed at the locations can be expected to overflow to adjacent WMS tiles. xmargin and ymargin can be set simultaneously using the "margin" setting.

Label structure

The table below contains a list of attributes used in the Label structure.

Label

Name	Type	Default value	Description
dx	int	0	X-coordinate offset of the number from the actual coordinate.
dy	int	0	Y-coordinate offset of the number from the actual coordinate.
unit_conversion	(string)	-	Name of desired unit conversion. Unit conversions are listed in the configuration file.
multiplier	double	1	Multiplier for the number for unit conversion purposes.
offset	double	0	Offset for the number for unit conversion purposes.
missing	string	"-"	Label for missing values. No text is output if the value is empty.
precision	int	0	Number of decimals.
multiple	double	0	If nonzero, round value to multiple of set value
rounding	string	"tonearest"	Rounding mode: tonearest, towardzero, upward or downward.
locale	string	-	Locale for printing the number, for example fi_FI.
prefix	string	""	Prefix for the number.
suffix	string	""	Suffix for the number, usually for units.
plusprefix	string	""	Prefix replacing the sign for non-negative numbers.
minusprefix	string	""	Prefix replacing the sign for negative numbers.
orientation	string	"horizontal"	Horizontal or auto. Currently used only by IsolabelLayer
padding_char	string	-	Padding character for numbers.
padding_length	int	-	Padding length for numbers. Padding is done if length of number is shorter than padding_length.

Note: signed prefixes are needed in aviation charts where negative temperatures are typically shown without a sign. In the exceptional case where positive numbers are actually needed, they are displayed using a plus sign or a "PS"-prefix.

Location structure

The table below contains a list of attributes used in the Location structure.

Location

Name	Type	Default value	Description
longitude	double	-	The longitude of the coordinate.
latitude	double	-	The latitude of the coordinate.
dx	int	-	X-coordinate adjustment for the location.
dy	int	-	Y-coordinate adjustment for the location.

Observation structure

The table below contains a list of attributes used in the Observation structure.

Observation

Name	Type	Default value	Description
parameter	string	-	The parameter name of the observation.
label	Label	-	How to render the observed value.
attributes	Attributes	-	SVG rendering attributes for the generated text.

Station structure

The table below contains a list of attributes used in the Station structure.

Station

Name	Type	Default value	Description
fmisid	(int)	-	fmisid of the station.
wmo	(int)	-	wmo-number of the station.
lpnn	(int)	-	LPNN-number of the station (Finland only)
geoid	(int)	-	geonames database identifier for the station
longitude	(double)	-	The longitude for the location of the wind rose. Default is to place the wind rose at the station coordinates.
latitude	(double)	-	The latitude for the location of the wind rose. Default is to place the wind rose at the station coordinates.
symbol	(string)	-	An optional symbol to be placed at the station.
attributes	Attributes	-	The SVG rendering attributes for the symbol
title	Title	-	The title for the wind rose.
dx	(int)	-	Station specific positional adjustment for the symbol attached to the station.
dy	(int)	-	Station specific positional adjustment for the symbol attached to the station.

WindRose structure

The table below contains a list of attributes used in the WindRose structure.

WindRose

Name	Type	Default value	Description
minpercentage	int	0	Required percentage of observations for a sector to be shown. This can be used to prevent very small sectors which are irrelevant.
radius	int	20	The radius of the wind rose.
sectors	int	8	The number of wind direction sectors in the wind rose
symbol	(string)	-	The symbol for the wind rose, usually either a circle or omitted.
attributes	Attributes	-	The SVG attributes for the symbol.
connector	(Connector)	-	How to connect the wind rose to the location of the station.
parameter	(string)	-	The wind direction parameter name.
limits	AttributeSelection	-	SVG styling based on the average wind speed in the sector.

Connector structure

The table below contains a list of attributes used in the Connector structure.

Connector

Name	Type	Default value	Description
startoffset	int	0	Start offset for the connecting line. Usually zero, unless a symbol is placed at the station.
endoffset	int	0	End offset for the connecting line. Usually matches the radius of the wind rose.
attributes	Attributes	-	The SVG rendering attributes for the connecting line.

Filters structure

The table below contains a list of attributes used in the Filter structure.

Filters

Name	Type	Default value	Description
where	(string)		WHERE condition to be appended to the database query
attributes	Attributes		SVG-attributes for geometry
text_attributes	Attributes		SVG-attributes for text

Using dynamically created grids

Introduction

A layer usually contains the "parameter" attribute definition, which refers to the grid data that is needed in order to draw the current layer. Typically the value of the "parameter" attribute is a parameter name that points to fixed grid data, which means that this data is pre-calculated. In this case the biggest drawback is that if we want to get grids that are calculated differently then we need a pre-calculation process that calculates these grids and stores them in such way that they can be accessed.

Luckily now there is a way to caculate new grids on the fly and use their data as they were fixed grids. The basic idea is that the "parameter" attibute can contain a function that defines how the new grid should be calculated. This feature is available only for producers that use grid-engine.

There are two different ways to create new grids:

1. We can create new grids that uses data from other grids that have the same timestamp.
2. We can create grids that uses data from multiple timesteps. For example, calculating max temperature values for a day.

Grids with the same timestamp

Here are some examples that calculate a new grid from other grids that have the same timestamp:

The new grid contains maximum values from 3 ensemble grids (1,3,5):

    "parameter" : "MAX{Temperature:MEPS:1093:6:0:3:1;Temperature:MEPS:1093:6:0:3:3;Temperature:MEPS:1093:6:0:3:5}"

The new grid contains average values counted from 14 ensemble grids (1-14):

    "parameter" : "AVG{Temperature:MEPS:1093:6:0:3:1-14}"

The new grid contains probability percentage that the values in 14 ensemble grids (1-14) are below zero (= in range -1000 .. 0):

   "parameter": "IN_PRCNT{-1000;0;Temperature:MEPS:1093:6:0:3:1-14}"

Grids calculated over multiple timesteps

The basic idea is that, we can have multiple timesteps before and after the requested time. The timestep size (in minutes) can be used in order to calculate timestamp for the requested data. The requested data is expressed in timestep index range (not actual time lengths). The index number 0 refers to the requested time, the first timestep before the requested time is refered with the index number -1, and the first timestep after the requested time is refered with the index number 1. If functions require additional parameters (like value range), these parameters are added after the timestep range and timestep size defintions.

Here are some examples:

The new grid contains maximum values from the previous 24 timesteps.Timestep size = 60 minutes, range of grid indexes = [-23 .. 0] counted from the requested time.

    "parameter" : "/MAX{Temperature;-23;0;60}"

The new grid contains probability percentage that the temperature drops below the zero (= is in range -1000..0) during the following 48 hours.

    "parameter": "/IN_PRCNT{Temperature;0;47;60;-1000;0}"

Functions

Dynamic grid caculation uses C++ or LUA functions for creating new grids. C++ functions are faster than LUA functions and that's why we try to implement most common functions with C++. At least the following functions are currently available for producing new grids:

    AVG		=> Calculate average/mean values.
    MAX		=> Calculate maximum values.
    MIN		=> Calculate minimum values.
    MUL		=> Multiplies grid values with a multiplyer. This can be used also for dividing grid values (i.e. multiplier = 1/divider).
    SUM		=> Add 1-N grids together. If there are additional numbers in the function then these numbers are added to each grid value.
    IN_PRCNT	=> Returns the probability percent that the value in the given grids is inside the given value range.
    OUT_PRCNT	=> Returns the probability percent that the value in the given grids is outside the given value range.

Generic querystring options

• format=svg|png|pdf|ps|xml|geojson|kml image/png|image/svg+xml|text/xml - output format for Dali or WMS
• quiet=1 - do not print stack traces on errors
• debug=1 - debug mode
• printjson=1 - print fully expanded JSON to the terminal
• printhash=1 - print generated CTPP2 object to the terminal
• optimizesize=1 - optimize output for size ** remove display=none layers and views from the SVG output

WMS GetMap and GetCapabilities configuration

A product definition may at the top level include the following settings which directly affect WMS GetCapabilities and GetMap requests:

WMS settings

Name	Type	Default value	Description
hidden	(bool)	false	If true the WMS will not appear in GetCapabilities responses but GetMap requests continue to work.
title	Text	-	Obligatory title for the WMS layer
name	string	-	Name of the WMS layer. By default the name is deduced from the path of the configuration file.
abstract	(Text)	-	Abstract for the layer.
keywords	(list of strings)	-	Keywords for the layer.
opaque	(int)	0	Is the WMS layer opaque.
queryable	(int)	0	Does the layer support GetFeatureInfo requests.
cascaded	(int)	0	How many times the layer has been cascaded.
no_subsets	(int)	0	Can only the full bounding box be requested.
fixed_width	(int)	0	Nonzero implies the size cannot be changed.
fixed_height	(int)	0	Nonzero implies the size cannot be changed

WMS layer variants

In meteorology it is common to have multiple weather models with the same parameters available. For example for temperature the WMS layer settings would typically differ only in the name, title and abstract, and the product settings in the name of the producer and occasionally the name of the weather parameter (road temperature, ground temperature).

In such cases one use the same JSON file for the product settings, and define how the different variants are change in the settings. Below is an example how one might define some variants. It is also possible to change individual settings deeper in the JSON structure as long as a qid has been set. Substitutions then work as if the setting has been changed via the qid using a querystring. For example if a IsobandLayer layer has a qid with value temp_layer, one can change the parameter used by the layer by using temp_layer.parameter=SomeTemperature in the querystring, or by using "temp_layer.parameter": "SomeTemperature" in the variant settings.

Sample variant configuration
{
    "parameter": "Temperature", // default
    "producer": "pal", // default

    // all variants to be generated
    "variants":
    [
	{
	    "name": "fmi:pal:temperature",
	    "title": "FMI Forecast Temperature",
	    "abstract": "Terrain corrected temperature using atmospheric lapse rate and terrain elevation produced by FMI."
	},
	{
	    "name": "fmi:pal:dailymeantemperature",
	    "parameter": "DailyMeanTemperature",
	    "producer": "daily00",
	    "title": "FMI Forecast Mean Temperature",
	    "abstract": "Daily mean temperature produced by FMI."
	},
	{
	    "name": "fmi:roadmodel:roadtemperature",
	    "parameter": "RoadTemperature",
	    "producer": "roadmodel_skandinavia_pinta",
	    "title":
	    {
    		"en": "Roadmodel Troad",
     		"fi": "Tienpintalämpötila"
	    },
	    "abstract":
	    {
		    "en": "Road temperature produced by roadmodel",
    		"fi": "Tiesäämallin laskema tienpintalämpötila"
	    }
	}
    ],

    // Common settings
    "projection": {},
    "styles":
    [
	...
    ],
    "views":
    [
	...
    ]
}

Configuration

In order to use the Dali plugin you need to edit two configuration files. These files are the main configuration file of the SmartMet Server environment and the Dali plugin specific configuration file.

Main configuration file

The main configuration file is named as "smartmet.conf". The main purpose of this configuration file is to define which plugins and engines need to be loaded when the server is started. In addition, it defines which configuration files these plugins and engines are using.

In order to use the Dali plugin you need to do the following steps:

1. Check that there is the "dali" entry listed in the "plugins" attribute. If not, you should add it.

	plugins = ["dali"]

2. Check that the "engines" attribute contains all required engines such as AuthEngine, Contour, GeoEngine, GIS, ObsEngine, QEngine". Notice that the "geoengine" entry must be before the "obsengine" entry because of some linking reasons such as the ObsEngine uses the GeoEngine's functions.

	engines = ["authengine","contour","geoengine","gis","obsengine","qengine"]

3. Check that there is a dedicated configuration entry for the Dali plugin. In this entry you can disable or enable the usage of the Dali plugin. In addition, we can define the name and path of the configuration file for the Dali plugin.

		dali:
		{
			disabled = false;
			configfile = "/etc/smartmet/plugins/dali.conf"
		}

Plugin configuration file

As described in the previous section, the filename and the location of the Dali configuration file was defined in the main configuration file.

The table below describes the configuration attributes that we can define in this file.

Attribute		Description
url		The URL (or actually the URL path) of the native interface (for example "/dali")
model		The default value for the "model" attribute if this is not defined in the product configuration file or given in the HTTP request
language		The default value for the "language" attribute if this is not defined in the product configuration file or given in the HTTP request.
customer		The default value for the "customer" attribute if this is not defined in the HTTP request
root		The root directory of the Dali product information
templatedir		The directory of the CTTP template files
template		The name of the CTTP template file (without the ".c2t" ending)
wmsurl		The URL (or actually the URL path) of the WMS interface (for example "/wms")
wmsroot		The root directory of the WMS product information
wmsversion		The WMS version number (e.g., "1.3.0")
wmsmapformats		The WMS format definition (e.g.,, "image/svg+xml,image/png")
unit_conversion		Map of unit conversion names to multiplier/offset values
regular_attributes		The list of the supported SVG attributes
presentation_attributes		The list of the supported SVG presentation attributes
cache	memory_bytes	The maximum size of the memory cache (in bytes)
	filesystem_bytes	The maximum size of the file cache (in bytes)
	directory