Weathermap v0.97b Configuration Reference

http://www.network-weathermap.com/manual/latest/pages/config-reference.html

PHP Weathermap v0.97b

Copyright © 2005-2013 Howard Jones, [e-mail]. (Website)

Configuration Reference

This page is automatically compiled, and documents all the configuration directives that are available in PHP Weathermap v0.97b.

Introduction

Node-specific Configuration Directives

*COLORICON INFOURL LABEL LABELANGLE LABELFONT LABELOFFSET MAXVALUE NODE NOTES OVERLIBCAPTION OVERLIBGRAPH OVERLIBHEIGHT OVERLIBWIDTH POSITION SET TARGET TEMPLATE USEICONSCALE USESCALE ZORDER

Link-specific Configuration Directives

ARROWSTYLEBANDWIDTH BWFONT BWLABEL BWLABELPOS BWSTYLE *COLOR COMMENTFONT COMMENTPOS COMMENTSTYLE DUPLEX INBWFORMAT INCOMMENT INFOURL ININFOURL INNOTES INOVERLIBCAPTION INOVERLIBGRAPH LINK LINKSTYLE NODES NOTES OUTBWFORMAT OUTCOMMENT OUTINFOURL OUTNOTES OUTOVERLIBCAPTION OUTOVERLIBGRAPH OVERLIBCAPTION OVERLIBGRAPH OVERLIBHEIGHT OVERLIBWIDTH SET SPLITPOS TARGET TEMPLATE USESCALE VIA VIASTYLE WIDTH ZORDER

Global Configuration Directives

BACKGROUND*COLOR *FONT FONTDEFINE HEIGHT HTMLOUTPUTFILE HTMLSTYLE HTMLSTYLESHEET IMAGEOUTPUTFILE IMAGEURI INCLUDE KEYPOS KEYSTYLE KILO MAXTIMEPOS MINTIMEPOS SCALE SET TIMEPOS TITLE TITLEPOS WIDTH

Node-specific Configuration Directives

NODE

NODE nodename

The initial definition of a NODE. This must come before any other configuration related to this node.

The 'nodename' is used in link definitions to specify which nodes the link joins. The nodename is must be a single word, with no spaces.

There is one special node name, 'DEFAULT', which allows for the setting of defaults. All nodes that are defined after this one in the configuration file will use the parameters of this node as a starting point. For this reason, it is best to define the DEFAULT node at the top of the configuration file, if you intend to use it.

Change History

0.7

Added DEFAULT node.

TEMPLATE

TEMPLATE nodename

By default, each new node starts with the same set of properties. You can change the default properties by defining a node called DEFAULT.

You can also use the TEMPLATE keyword to make a node inherit it's settings from any other node. The node you use must be defined earlier in the config file than where you use it.

You can make template-only nodes that are not visible in the map, by not including aNODES line in the node. Template nodes can also use templates, to build up a hierarchy of 'types'.

NOTE: The TEMPLATE line should be the first line in the NODE definition, as it will copy the configuration over the top of anything else you have already defined for thatNODE.

Examples

NODE Templates in use - with template-only nodes

NODE server            

Change History

0.96

Added template support

POSITION

POSITION x-coord y-coord

POSITION nodename x-coord y-coord

Specifies where to place the node on the map. Coordinates are in pixel units, with the origin at the top-left of the map.

Optionally, you can also specify another node that the coordinates are relative to. This allows you to have 'sub-nodes' that follow a master node around as you alter the map. Relative nodes can be relative to other relative nodes, as long as the node at the end of the chain is not relatively positioned!

Examples

Example of a 'sub-node', that will be 20 pixels above the main node, wherever that gets moved to. It is used to show additional information about the main node.

                NODE main_node POSITION 200 320 LABEL MAIN                NODE sub_node POSITION main_node 0 -20 LABEL {nodes:main_node:invalue}            

Change History

0.9

Add relative position from other nodes.

LABEL

LABEL labeltext

Specifies a label for the node. Everything to the end of the line is used.

If the node has an ICON defined as well, then you can specify the position of the label relative to the node's centre-point by usingLABELOFFSET.

The text for the label can contain special tokens to show map data.

This is drawn using the font specified by LABELFONT in the colours specified by LABELFONTCOLOR, LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR.

Change History

0.9

Added 'special token' support.

TARGET

TARGET targetspec

TARGET targetspec targetspec

TARGET targetspec - targetspec

TARGET targetspec n* targetspec

TARGET "targetspec"

Specifies where to look for the current "throughput" information for this NODE. You can also specify multiple targets, which will then be added together to make the aggregate result which is then displayed. Specify the targets on oneTARGET line, seperated with a space. If a targetspec starts with a '-', then it's value will besubtracted from the final result instead.

Also, if a targetspec starts with a number, then a *, then it's used a scaling factor on the result. You can do basic maths with this, especially if you remember that multiplying by a number below 1 is the same as dividing by 1 divided by that number (0.5* is the same as divide by 2).

For both the '-' and '*' options, there must be no spaces between any modifiers and the actual target string after it.

It's important to note, especially for NODEs, that the value that is used does not have to be bandwidth. You can use data for temperature, session-counts, CPU usage or anything else you can get data for.

The actual contents of the targetspec depend on the data source plugins that are available.The standard plugins are documented here.

To help with filenames that can contain spaces, or for the external script data source, you can enclose the entire targetspec in double-quotes (") to show that it is a single targetspec.The quotes must be around the whole targetspec, including any prefixes.

Examples

Using multiple data sources for one link

TARGET link1a.rrd link1b.rrd            

Taking the input from one file, and output from another

TARGET poot.rrd:-:DS1 poot2.rrd:DS0:-            

Change History

0.96

Added quotes option for targets with spaces.

0.96

Added scale factors for all datasources.

0.91

Added 'negative' datasources.

0.9

Added plugin data sources, node targets, and added new plugins.

0.8

Added ability to specify multiple targets. Added tab-delimited data source. Added 'ignore' DS name.

0.5

Added ability to specify DS names.

USESCALE

USESCALE scalename

USESCALE scalename {in,out}

Specify which SCALE to use to decide the colour of this node.

After the percentage usage is calculated (using BANDWIDTH/MAXVALUE and data from theTARGET line), the colour is decided by looking up the percentage against thisSCALE. If there is no USESCALE line, then the default scale is used.

If you also specify 'absolute', then no percentage calculation is performed. The raw values from theTARGET line are just looked up in the named SCALE.

For nodes, you can also specify a scalename of 'none'. This stops the node's colour from changing at all. This is useful if you want to use theTARGET line to fetch data that is used in the LABEL or ICON of the node, for example, without changing the colour of the node itself.

You can also change the colour of the ICON associated with a NODE according to a different SCALE, by using USEICONSCALE.

Change History

0.97

Added absolute scale support.

0.95

Added USEICONSCALE.

0.9

Added named scales and USESCALE.

MAXVALUE

MAXVALUE max-value

MAXVALUE max-in-value max-out-value

Specifies the maximum value(s) for the node, in the same way that BANDWIDTH does for a LINK. These are used to calculate the percentage usage value, which in turn is used to decide theNODE's colour, if it has a TARGET defined.

The default value is 100, which has the effect of not changing the input value ( (n/100)*100 = n ).

Change History

0.9

Added TARGET and MAXVALUE for nodes.

ICON

ICON iconimagefile

ICON maxwidth maxheight iconimagefile

ICON none

Specifies an icon to use for the node.

The filename can either be a full path to the image, or a relative one.

The icon file must be in PNG, JPEG or GIF format. Alpha-transparency within the icon should be honoured by Weathermap for PNG icons, to create irregular shapes.

If you specify the word 'none' as the icon filename, then no icon is used. This is useful if you have specified anICON in the DEFAULT NODE, and want to override that for a few special cases.

There are some special icon filenames that can be used to generate an icon image without using an external file. These allrequire you to specify a maxwidth and maxheight which are then used as the size of the icon. The 'magic filenames' are:

• 'box' - to produce a square cornered box.
• 'rbox' - to produce a round-cornered box
• 'round' - to produce a circle or ellipse.
• 'inpie' & 'outpie' - to produce a pie-chart of either the in or out value relative to it's maximum. The colouring options on this are likely to change in a future version.
• 'nink' - to produce a circular 'yin-yang'-style symbol, with each half showing the in and out values. The colouring options on this are likely to change in a future version.

The colours for these "artificial icons" are specified using the AICONFILLCOLOR and AICONOUTLINECOLOR keywords.

The second form allows you to specify a maximum width and height for the icon. If the PNG file that you specify is bigger or smaller than this size, then it is automatically scaled up (or down) in proportion, so that it fits into a box of the size you specify.

The size of the icon image is used by LABELOFFSET to decided how far to move the label, if you use compass-point offsets.

The text for the filename can contain special tokens to select an icon based on map data.

You can adjust the colour of the icon according to a SCALE, by using USEICONSCALE, if you are using the PHP GD library (the function required is not present in the main GD library).

Change History

0.96

Added inpie, outpie and nink.

0.95

Added Artificial Icon support - round, rbox and box.

0.95

Added Icon colourising support.

0.9

Added 'special token' support.

0.9

Added JPEG and GIF support.

0.9

Added special icon 'none', and automatic scaling.

USEICONSCALE

USEICONSCALE scalename

USEICONSCALE scalename {in,out}

Specify which SCALE to use to decide the colour of the icon for this node.

After the percentage usage is calculated (using BANDWIDTH/MAXVALUE and data from theTARGET line), the colour is decided by looking up the percentage against thisSCALE. If there is no USEICONSCALE line, then no scale is used, and the icon colour does not change.

Hint: This facility works best when you start with greyscale images.

NOTE: Prior to 0.97, Icon colourising used the PHP imagefilter() function. This function isonly available in the version of GD that is bundled with PHP, and not with the official GD library. Several popular operating systems (e.g. Debian/Ubuntu) use the official GD library rather than the bundled PHP library. If you know that youdo have the imagefilter function, and you prefer the 'old-style' coloring, then you can addSET use_imagefilter 1 in the top section of your map config file, to useimagefilter instead.

Change History

0.97

Removed dependency on imagefilter

0.95

Added USEICONSCALE.

LABELOFFSET

LABELOFFSET compass-point

LABELOFFSET x-offset y-offset

If you specify an ICON, and also a LABEL, then you will find that the label is often hard to read. LABELOFFSET allows you to move the position of the LABEL, so that it's not directly over the centre of the node anymore.

You can specify a compass-point (e.g. LABELOFFSET S). The compass-point method takes the size of the ICON, and uses that as the offset distance in the direction you specify. This way, you can change your icon for something of a different size, and not need to change all your offsets. You can use the main 8 points of the compass: N, E, S, W, NE, SE, NW, SW.

The compass points, relative to the node's bounding-box..

For more control, you can specify an integer offset for the x and y positions of the label (e.g.LABELOFFSET -10 -20) instead.

Change History

0.7

Originally added LABELOFFSET

LABELANGLE

LABELANGLE angle

Specifies a rotation angle of the label for a node. Allowed angles are 0, 90, 180 and 270 degrees. The rotation is around the centre of the label, after anyLABELOFFSET has been applied.

The LABELFONT must be a TrueType font for angles other than 0 (the default) as these are the only font type to support rotating text.

Rotated label, usingLABELANGLE 90 andLABELOFFSET E

Change History

0.95

Added LABELANGLE.

LABELFONT

LABELFONT fontnumber

Specify the font used for drawing the LABEL.

Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using theFONTDEFINE directive.

The built-in GD fonts.

Change History

0.7

Global NODEFONT became per-node LABELFONT.

0.6

Originally added NODEFONT.

*COLOR

LABELFONTCOLOR red green blue

LABELFONTSHADOWCOLOR red green blue

LABELBGCOLOR red green blue

LABELOUTLINECOLOR red green blue

AICONOUTLINECOLOR red green blue

AICONFILLCOLOR red green blue

Specify the colours used for drawing the LABEL.

red, green and blue are numbers from 0 to 255.

LABELFONTSHADOWCOLOR,LABELBGCOLOR and LABELOUTLINECOLOR have an additional option - 'none' - which stops that element of theLABEL being drawn. LABELFONTSHADOWCOLOR defaults to 'none'.

LABELFONTCOLOR has an additional option 'contrast', which will select either black or white depending on the currentLABELBGCOLOR. This is especially useful if you are using a SCALE to change the colour of your NODE LABELs.

AICONOUTLINECOLOR andAICONFILLCOLOR are used to colour an 'artificial ICON' if one is defined for this node. To allow the artifical icon to also follow the colour of theLABELBGCOLOR when you are using a SCALE, you can also specify 'copy' as the colour for AICONFILLCOLOR. See ICON for more about artificial icons.

Change History

0.95

Added 'contrast' and 'copy' options.

0.95

Added AICONFILLCOLOR and AICONOUTLINECOLOR.

0.8

Added LABELFONTCOLOR, LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR.

INFOURL

INFOURL url

Creates a hyperlink in the HTML output.

If you are using the HTML output facility, then a link is added to the <map> section of the HTML so that when you click on the node, you are taken to the url specified here.

OVERLIBGRAPH

OVERLIBGRAPH url

OVERLIBGRAPH url url...

Creates a popup image in the HTML output.

If you are using the HTML output facility, and HTMLSTYLE is set to 'overlib', then a link is added to the <map> section of the HTML so that when you move the mouse pointer over the the node, a box will pop up containing the image that you specify. Typically used to link to historical data in your network monitoring system.

You can also specify more than one url, in which case the images are 'stacked' one after another in the popup box.

If a NOTES line is also specified for a node, then the image(s) specified here appears with theNOTES text underneath it.

You can influence how Weathermap positions the popup box, using the OVERLIBWIDTH and OVERLIBHEIGHT keywords.

Examples

Typical use of OVERLIBGRAPH

OVERLIBGRAPH http://www.yoursite.net/mrtg/router1-cpu-daily.png            

Change History

0.95

Added multiple URL support

OVERLIBWIDTH

OVERLIBWIDTH imagewidth

Specify the width, in pixels of the graph image referred to by OVERLIBGRAPH line.

This is an optional extra that allows the OverLib library to make a better job of positioning the 'popup' image so that it doesn't appear off the edge of the screen. Typically, you would use this once, in the DEFAULTNODE. If you use this, you must also use OVERLIBHEIGHT, for either to have any effect.

Change History

0.7

Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.

OVERLIBHEIGHT

OVERLIBHEIGHT imagewidth

Specify the width, in pixels of the graph image referred to by OVERLIBGRAPH line.

This is an optional extra that allows the OverLib library to make a better job of positioning the 'popup' image so that it doesn't appear off the edge of the screen. Typically, you would use this once, in the DEFAULTNODE. If you use this, you must also use OVERLIBWIDTH, for either to have any effect.

Change History

0.7

Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.

OVERLIBCAPTION

OVERLIBCAPTION caption text

Specify the caption used for the popup HTML 'window' if you have also specified anOVERLIBGRAPH line. By default, this is the name of the NODE.

The text for the caption can contain special tokens to show map data.

Change History

0.9

Originally added OVERLIBCAPTION.

NOTES

NOTES notes text

Specifies the text or HTML notes for a node.

The notes text appears in a popup box when the user hovers their mouse over the node. If anOVERLIBGRAPH is specified too, then the text appears below the graph.

The map HTMLSTYLE must be set to 'overlib' to enable any of the mouse-hover functionality.

Change History

0.9

Originally added NOTES.

SET

SET hintname hintvalue

Specifies a value for a hint variable.

Hint Variables allow the user to pass settings to the internals of Weathermap that wouldn't normally need to be changed, or that aren't part of the core Weathermap application. Examples are: small rendering changes, parameters for datasources plugins and similar.

Hint Variables are either Global for the map, or assigned to a specific link or node.

There is more about Hint Variables in the Advanced Topics section.

Change History

0.9

Originally added SET.

ZORDER

ZORDER z-coord

Specifies the order in which to draw this item on the map.

By default, all nodes are drawn above all links. There are some situations where you might like to change this, for example if you use aNODE as a background image, and you want links to show in front of that image.

By default, all nodes have a Z coordinate of 600, and all links have 300. The map legend is at 1000, which cannot be changed (you can move everything else above it, if you like, of course). Items are drawn from lowest Z up to highest Z, so if you want a particular node to appear underneath the default links, you can use 'ZORDER 250' to do that.

Change History

0.96

Added Z-ordering support.

Link-specific Configuration Directives

LINK

LINK linkname

The first line of a LINK definition.

The linkname must be unique within the map, and must not contain spaces. The only place it currently appears is in the small title-bar of a popup graph if you specify anOVERLIBGRAPH without an OVERLIBCAPTION, however.

There is one special link name, 'DEFAULT', which allows for the setting of defaults. All links that are defined after this one in the configuration file will use the parameters of this link as a starting point. For this reason, it is best to define the DEFAULT link at the top of the configuration file, if you intend to use it.

TEMPLATE

TEMPLATE linkname

By default, each new link starts with the same set of properties. You can change the default properties by defining a link called DEFAULT.

You can also use the TEMPLATE keyword to make a link inherit it's settings from any other link. The link you use must be defined earlier in the config file than where you use it.

You can make template-only links that are not visible in the map, by not including aNODES line in the link. Template links can also use templates, to build up a hierarchy of 'types'.

NOTE: The TEMPLATE line should be the first line in the LINK definition, as it will copy the configuration over the top of anything else you have already defined for thatLINK.

Examples

LINK Templates in use - with template-only links

LINK bigpipe WIDTH 8 ARROWSTYLE classic                LINK smallpipe WIDTH 3 ARROWSTYLE compact                # this link uses the bigpipe template, so it doesn't need any            formatting/styling commands LINK a_real_link TEMPLATE bigpipe NODES rtr1 rtr2            

Change History

0.96

Added template support

NODES

NODES nodename{:compassoffset} nodename{:compassoffset}

NODES nodename{:compassoffset}{percentage} nodename{:compassoffset}{percentage}

NODES nodename{:xoffset:yoffset} nodename{:xoffset:yoffset}

NODES nodename{:angle}r{radius} nodename{:angle}r{radius}

These are the NODEs that this link joins. There can be only two. They are the 'nodename's from theNODE line for each node.

Optionally, you can add an offset after a nodename, to move the location of that end of the link. This can help with crowded areas of the map, and also in making parallel links. Valid offsets can be numeric values, to indicate the relative position in pixels from the centre of the node, or are named after compass-points: N,S,E,W,NE,NE,SE,SW. The compass points describe locations around the edge of the box that contains the node. You can also specify a percentage after the compass point, to be a certain proportion of the way from the centre. The percentage must be two digits. Finally, you can also use polar coordinates to specify offsets, with an angle in degrees and a radius in pixels from the centre point. 0 degrees is straight up.

The order of the nodes is significant. When reading data sources, the flow from the first node to the second is considered 'out' and from second-to-first is 'in'.

The compass points, relative to the node's bounding-box..

The default - node centre to node centre.

Using compass points - NODES node1:E node2:W

Using compass points with percentages - NODES node1:E50 node2:W50

Using polar offsets - NODES node1:45r20 node2:225r20

Using offsets to make parallel links- NODES node1:NE50 node2:NW50 for one link andNODES node1:SE50 node2:SW50 for the other.

Examples

Defining a simple link

LINK mylink NODES node1 node2            

Two parallel links, using offsets

LINK firstlink NODES node1:E node2:E                LINK secondlink NODES node1:W node2:W            

Two parallel links, using percentage compass offsets to bring the links closer together

LINK firstlink NODES node1:E50 node2:E50                LINK secondlink NODES node1:W50 node2:W50            

An offset link using pixel offsets

LINK firstlink NODES node1:-10:10 node2:20:12            

An offset link using polar coordinates

LINK firstlink NODES node1:45r20 node2:225r20            

Change History

0.96

Added polar offsets.

0.96

Added fractional compass offsets.

0.9

Added numeric pixel offsets.

0.8

Added ability to specify node offset.

TARGET

TARGET targetspec

TARGET targetspec targetspec

TARGET targetspec - targetspec

TARGET targetspec n* targetspec

TARGET "targetspec"

Specifies where to look for the current throughput information for this LINK. You can also specify multiple targets, which will then be added together to make the aggregate bandwidth which is then displayed. Specify the targets on oneTARGET line, seperated with a space. If a targetspec starts with a '-', then it's value will besubtracted from the final result instead.

Also, if a targetspec starts with a number, then a *, then it's used a scaling factor on the result. You can do basic maths with this, especially if you remember that multiplying by a number below 1 is the same as dividing by 1 divided by that number (0.5* is the same as divide by 2).

For both the '-' and '*' options, there must be no spaces between any modifiers and the actual target string after it.

The actual contents of the targetspec depend on the data source plugins that are available.The standard plugins are documented here.

To help with filenames that can contain spaces, or for the external script data source, you can enclose the entire targetspec in double-quotes (") to show that it is a single targetspec.The quotes must be around the whole targetspec, including any prefixes.

Examples

Using multiple data sources for one link

TARGET link1a.rrd link1b.rrd            

Taking the input from one file, and output from another

TARGET poot.rrd:-:DS1 poot2.rrd:DS0:-            

Change History

0.96

Added quotes option for targets with spaces.

0.96

Added scale factors for all datasources.

0.91

Added 'negative' datasources.

0.9

Added plugin data sources, node targets, and added new plugins.

0.8

Added ability to specify multiple targets. Added tab-delimited data source. Added 'ignore' DS name.

0.5

Added ability to specify DS names.

USESCALE

USESCALE scalename

USESCALE scalename percent

USESCALE scalename absolute

Specify which SCALE to use to decide the colour of this link.

After the percentage usage is calculated (using BANDWIDTH and data from the TARGET line), the colour is decided by looking up the percentage against thisSCALE. If there is no USESCALE line, then the default scale is used.

If you also specify 'absolute', then no percentage calculation is performed. The raw values from theTARGET line are just looked up in the named SCALE.

Change History

0.97

Added absolute scale support.

0.9

Added named scales and USESCALE.

WIDTH

WIDTH width

Specifies the width of this link when drawn. The width value can be any positive number (including non-integers).

The actual width of the final link arrow will be roughly 2*width+1 pixels, due to the way links are drawn, and rounding errors as the internal floating-point values are finally forced onto an integer pixel-grid.

What it actually does is calculate a centre-line (or spine), divide that up into so many segments, and then at each point along the spine, find the normal (90 degrees to the direction of the line). Then stepWIDTH pixels along the normal in each direction to get a point to draw. This apparently-complex scheme is required to allow forVIAs - both angled and curved links have special handling, and regular straight links are treated as curved links with noVIA by default.

Change History

0.97a

Added non-integer widths. Retconned explanation.

BANDWIDTH

BANDWIDTH max-bandwidth

BANDWIDTH max-in-bandwidth max-out-bandwidth

Specifies the maximum throughput of this link, in bits per second.

This is used to calculate the percentage utilisation, which in turn is used to make the colour for the link arrow, and optionally the label on the link.

The second form allows you to have 'asymmetric' links, like an ADSL, where the first number is the maximum bandwidth from node1 to node2 and the second is the maximum from node2 to node1, as they are given in theNODES line.

Bandwidths can also use K,M,G and T suffixes to specify large values. Also see theKILO global option though.

Examples

A typical ADSL line (as seen from the CPE)

BANDWIDTH 2M 256K            

Change History

0.9

Added MAXVALUE as a synonym to match NODE MAXVALUE. No change in functionality.

0.5

Added support for decimals in BANDWIDTH specifications.

0.4

Added support for K,M,G,T suffixes on bandwidth specs. Changed bandwidth from bytes to bits.

DUPLEX

DUPLEX full

DUPLEX half

'half' indicates that the bandwidth specified by the BANDWIDTH keyword is half-duplex rather than the default full.

This means that the percentages calculated are calculated as (in+out)/max instead of (in/max) and (out/max) separately.

Change History

0.95

Added DUPLEX.

BWLABEL

BWLABEL formatname

Specifies the type of 'bandwidth' label shown on each link.

The default is 'percent', but you can also have 'none', 'unformatted' or 'bits'. 'bits' shows the actual bandwidth, formatted using K,M,T,G suffixes where appropriate. 'unformatted' takes the value from theTARGET and displays it without any formatting - this can be useful for mapping things other than bandwidth. 'none' hides the bandwidth label altogether.

Change History

0.8

Added unformatted format.

0.7

Changed from global BWLABELS to per-link BWLABEL.

INBWFORMAT

INBWFORMAT string

Specifies a custom string to use for the inbound data BWLABEL bandwidth labels.

This command is intended as an advanced alternative to the BWLABEL command, for situations where you want more control over the content of the labels.

Instead of using bits, percent, etc, you can use any string in the label. Most importantly, the text for the label can containspecial tokens to show map data. In most normal situations you need to use the tokens, or the label won't do much useful

There is also a matching OUTBWFORMAT command to do the ame job for the outbound bandwidth label.

Examples

Providing more information in the bwlabel

INBWFORMAT {link:this:inpercent}% of            {link:this:max_bandwidth_in:%k}b/sec            

Change History

0.94

Added INBWFORMAT.

OUTBWFORMAT

OUTBWFORMAT string

Specifies a custom string to use for the outbound data BWLABEL bandwidth labels.

See the INBWFORMAT entry for more information.

Change History

0.94

Added OUTBWFORMAT.

BWSTYLE

BWSTYLE formatname

Specifies the style used to draw the box around the 'bandwidth' label shown on each link.

Two styles are currently available: 'classic' leaves the box horizontal, regardless of the direction of the link. 'angled' rotates the box to follow the directiong of the link arrow.

The BWFONT must be a TrueType font as these are the only font type to support rotating text.

To change the contents of the label, use BWLABEL or INBWFORMAT/OUTBWFORMAT.

Classic label style

Angled label style

Change History

0.92

Added BWSTYLE.

BWLABELPOS

BWLABELPOS inposition outposition

Specifies the position of the 'bandwidth' labels shown on each link.

The two position values are percentages along the link arrow, from the first to the second node. ThereforeBWLABELPOS 75 25 is the default.

Weathermap will produce a warning if the outpostion is greater than the inposition. In most cases, you have probably made a mistake, but if you have a good reason to do this, then you can disable that warning using'SET nowarn_bwlabelpos 1' in the top section of you map config file.

Change History

0.96

Added warning for proably-wrong positions

0.9

Added BWLABELPOS

BWFONT

BWFONT fontnumber

Specify the font used for drawing the BWLABEL boxes.

Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using theFONTDEFINE directive.

The built-in GD fonts.

INCOMMENT

INCOMMENT string

Specifies a comment for the input side of a LINK.

The link comment appears as text running alongside the link arrow. The font used is governed byCOMMENTFONT and the colour by COMMENTFONTCOLOR.

The text for the comment can contain special tokens to show map data.

The COMMENTFONT must be a TrueType font as these are the only font type to support rotating text.

Change History

0.9

Added link comments

OUTCOMMENT

OUTCOMMENT string

Specifies a comment for the output side of a LINK.

The link comment appears as text running alongside the link arrow. The font used is governed byCOMMENTFONT and the colour by COMMENTFONTCOLOR.

The text for the comment can contain special tokens to show map data.

The COMMENTFONT must be a TrueType font as these are the only font type to support rotating text.

Change History

0.9

Added link comments

COMMENTFONT

COMMENTFONT fontnumber

Specify the font used for drawing the INCOMMENT and OUTCOMMENT text.

Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using theFONTDEFINE directive.

For Link Comments, you must define a TrueType font. These are the only font that can rotate text through any angle, as required by comments. You can change the colour used to render the font withCOMMENTFONTCOLOR

Change History

0.9

Added link comments

COMMENTPOS

COMMENTPOS inposition outposition

Specify the position along the link used for drawing the INCOMMENT and OUTCOMMENT text.

The positions are specified as a percentage position along the link, like BWLABELPOS. The default positions are equivalent to COMMENTPOS 95 5.

Change History

0.92

Added COMMENTPOS

COMMENTSTYLE

COMMENTSTYLE edge

COMMENTSTYLE center

Specify whether link comments run along the outside edge of the link, or down the centre of the link arrow.

'edge' comment style

'center' comment style

Change History

0.96

Added COMMENTSTYLE

SPLITPOS

SPLITPOS position

Specify the position of the 'split' between the in and out arrows in a link. position is a percentage, and defaults to 50.

Change History

0.95

Added SPLITPOS

*COLOR

OUTLINECOLOR red green blue

BWOUTLINECOLOR red green blue

BWFONTCOLOR red green blue

BWBOXCOLOR red green blue

COMMENTFONTCOLOR red green blue

Specify the colours used for drawing the link.

red, green and blue are numbers from 0 to 255.

OUTLINECOLOR,BWOUTLINECOLOR and BWBOXCOLOR have an additional option - 'none' - which stops that element of the link being drawn.

COMMENTFONTCOLOR also has an extra option - 'contrast' - which will choose black or white, depending on the colour of the link. This is most useful withCOMMENTSTYLE center.

The colours are used as follows:

• OUTLINECOLOR is the colour of the line around the edge of the arrow.
• BWOUTLINECOLOR is the colour of the line surrounding the 'bandwidth label' box
• BWBOXCOLOR is the background colour for the same box
• BWFONTCOLOR is the colour used for text within that box
• COMMENTFONTCOLOR is the colour used for the text produced byINCOMMENT and OUTCOMMENT, along the side of a link arrow

COMMENTFONTCOLOR contrast withCOMMENTSTYLE center

Change History

0.96

Added COMMENTFONTCOLOR contrast.

0.93

Added correction - COMMENTCOLOR was shown instead of COMMENTFONTCOLOR.

0.9

Added COMMENTCOLOR.

0.8

Added OUTLINECOLOR, BWOUTLINECOLOR, BWFONTCOLOR and BWBOXCOLOR.

INFOURL

INFOURL url

Creates a hyperlink in the HTML output.

If you are using the HTML output facility, then a link is added to the <map> section of the HTML so that when you click on the (weathermap) link, you are taken to the url specified here.

It is also possible to specify the INFOURL for the 'in' and 'out' halves of a link individually, using ININFOURLand OUTINFOURL.

Change History

0.95

Added IN/OUT support

ININFOURL

ININFOURL url

ININFOURL url

Same as INFOURL, but specifies a hyperlink for only the 'in' side of a link.

Change History

0.95

Added IN/OUT support

OUTINFOURL

OUTINFOURL url

OUTINFOURL url

Same as INFOURL, but specifies a hyperlink for only the 'out' side of a link.

Change History

0.95

Added IN/OUT support

OVERLIBGRAPH

OVERLIBGRAPH url

Creates a popup image in the HTML output.

If you are using the HTML output facility, and HTMLSTYLE is set to 'overlib', then a link is added to the <map> section of the HTML so that when you move the mouse pointer over the the (weathermap) link, a box will pop up containing the image that you specify. Typically used to link to historical data in your network monitoring system.

You can also specify more than one url, in which case the images are 'stacked' one after another in the popup box.

If a NOTES line is also specified for a link, then the image specified here appears with theNOTES text underneath it.

It is also possible to specify the OVERLIBGRAPH for the 'in' and 'out' halves of a link individually, using INOVERLIBGRAPH and OUTOVERLIBGRAPH.

You can influence how Weathermap positions the popup box, using the OVERLIBWIDTH and OVERLIBHEIGHT keywords.

Examples

Typical use of OVERLIBGRAPH

OVERLIBGRAPH http://www.yoursite.net/mrtg/router1-link2-daily.png            

Change History

0.95

Added multiple URL support

0.95

Added IN/OUT support

0.0pre

Odd fact: This command, and the accompanying code to generate overlib imagemaps, were the first modification I ever made to the GRNET perl weathermap, and was what got me interested in writing my own version.

INOVERLIBGRAPH

INOVERLIBGRAPH url

INOVERLIBGRAPH url url...

Same as OVERLIBGRAPH, but specifies a pop-up graph for only the 'in' side of a link.

Change History

0.95

Added multiple URL support

0.95

Added IN/OUT support

OUTOVERLIBGRAPH

OUTOVERLIBGRAPH url

OUTOVERLIBGRAPH url url...

Same as OVERLIBGRAPH, but specifies a pop-up graph for only the 'out' side of a link.

Change History

0.95

Added multiple URL support

0.95

Added IN/OUT support

OVERLIBWIDTH

OVERLIBWIDTH imagewidth

Specify the width, in pixels of the graph image referred to by OVERLIBGRAPH line.

This is an optional extra that allows the OverLib library to make a better job of positioning the 'popup' image so that it doesn't appear off the edge of the screen. Typically, you would use this once, in the DEFAULT link. If you use this, you must also use OVERLIBHEIGHT, for either to have any effect.

Change History

0.7

Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.

OVERLIBHEIGHT

OVERLIBHEIGHT imagewidth

Specify the width, in pixels of the graph image referred to by OVERLIBGRAPH line.

This is an optional extra that allows the OverLib library to make a better job of positioning the 'popup' image so that it doesn't appear off the edge of the screen. Typically, you would use this once, in the DEFAULT link. If you use this, you must also use OVERLIBWIDTH, for either to have any effect.

Change History

0.7

Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.

OVERLIBCAPTION

OVERLIBCAPTION caption text

Specify the caption used for the popup HTML 'window' if you have also specified anOVERLIBGRAPH line. By default, this is the name of the LINK.

The text for the caption can contain special tokens to show map data.

Change History

0.9

Originally added OVERLIBCAPTION.

INOVERLIBCAPTION

INOVERLIBCAPTION caption text

Same as OVERLIBCAPTION, but specifies a pop-up graph caption for only the 'in' side of a link.

Change History

0.95

Added multiple URL support

0.9

Originally added OVERLIBCAPTION.

OUTOVERLIBCAPTION

OUTOVERLIBCAPTION caption text

Same as OVERLIBCAPTION, but specifies a pop-up graph caption for only the 'out' side of a link.

Change History

0.95

Added multiple URL support

0.9

Originally added OVERLIBCAPTION.

NOTES

NOTES notes text

Specifies the text or HTML notes for a link.

The notes text appears in a popup box when the user hovers their mouse over the link. If anOVERLIBGRAPH is specified too, then the text appears below the graph.

The map HTMLSTYLE must be set to 'overlib' to enable any of the mouse-hover functionality.

It is also possible to specify the NOTES for the 'in' and 'out' halves of a link individually, using INNOTES and OUTNOTES.

Change History

0.95

Added IN/OUT support

0.9

Originally added NOTES.

INNOTES

INNOTES url

INNOTES notes text

Same as NOTES, but specifies a text box for only the 'in' side of a link.

Change History

0.95

Added IN/OUT support

OUTNOTES

OUTNOTES url

OUTNOTES notes text

Same as NOTES, but specifies a pop-up text box for only the 'out' side of a link.

Change History

0.95

Added IN/OUT support

VIA

VIA x-coord y-coord

VIA nodename x-offset y-offset

Specify an additional point that a link must pass through.

A link normally goes in a straight line between the two nodes listed in the NODES configuration line. If you need it to go around something else, or to seperate two parallel links so that the bandwidth labels are all visible, you can make the link curve.

If you specify multiple VIA lines, then the link will pass through each in turn, in the order they are specified.

You can choose between curved or angled links with VIASTYLE.

Any VIA can also be specified relative to a NODE on the map. This makes it easier to have curves keep the intended shape as you re-organise a map.

Change History

0.96

Added angled VIAs.

0.95

Added relative-positioned VIA.

0.8

Originally added VIA.

VIASTYLE

VIASTYLE curved

VIASTYLE angled

When using VIA to define a non-straight LINK, you can choose to have a curved link, where the curve passes through eachVIA point, or an angled link where each VIA point is a 'corner'. The default is for a curved link.

CurvedVIA

AngledVIA

Change History

0.96

Added 'angled' style, and VIASTYLE.

LINKSTYLE

LINKSTYLE oneway

LINKSTYLE twoway

Specifies the whether the link should be drawn with one or two arrows.

A 'standard' (twoway) link has two arrows - one for inbound data and one for outbound data. In some situations (e.g. round-trip latency), you might only want an arrow in one direction.

One-way arrows only show the outbound BWLABEL, but they show it in the standard position - 25% of the way along. Change the position of the label withBWLABELPOS as usual (you still need to specify two positions in the BWLABELPOS line, however).

Change History

0.94

Added LINKSTYLE.

ARROWSTYLE

ARROWSTYLE stylename

ARROWSTYLE width length

Specifies the style of arrowhead used for drawing links.

The default is 'classic' which has a wide arrowhead. You can also choose 'compact' which gives narrower heads.

Finally, you can get finer control by adjusting the size yourself. The width and length of the head are in units of link-width.

Classic is equivalent to '4 2' and Compact is equivalent to '1 1'.

Classic arrow style

Compact arrow style

Change History

0.8

Added custom numeric form.

0.7

First added.

SET

SET hintname hintvalue

Specifies a value for a hint variable.

Hint Variables allow the user to pass settings to the internals of Weathermap that wouldn't normally need to be changed, or that aren't part of the core Weathermap application. Examples are: small rendering changes, parameters for datasources plugins and similar.

Hint Variables are either Global for the map, or assigned to a specific link or node.

There is more about Hint Variables in the Advanced Topics section.

Change History

0.9

Originally added SET.

ZORDER

ZORDER z-coord

Specifies the order in which to draw this item on the map.

By default, all nodes are drawn above all links. There are some situations where you might like to change this, for example if you use aNODE as a background image, and you want links to show in front of that image.

By default, all nodes have a Z coordinate of 600, and all links have 300. The map legend is at 1000, which cannot be changed (you can move everything else above it, if you like, of course). Items are drawn from lowest Z up to highest Z, so if you want a particular node to appear underneath the default links, you can use 'ZORDER 250' to do that.

Change History

0.96

Added Z-ordering support.

Global Configuration Directives

BACKGROUND

BACKGROUND imagefile

Specify an PNG, JPEG or GIF image file to be used as a background image.

Any WIDTH and HEIGHT specifications will be ignored - the map will take the size of the background.

Change History

0.9

Added JPEG and GIF support for backgrounds.

WIDTH

WIDTH map-width

Specifies the width of the map image in pixels.

If a BACKGROUND is specified, and the imagefile is successfully loaded, then any WIDTH specified is ignored. If neither a BACKGROUND or WIDTH is specified, then the default WIDTH is 800 pixels.

HEIGHT

HEIGHT map-height

Specifies the height of the map image in pixels.

If a BACKGROUND is specified, and the imagefile is successfully loaded, then any HEIGHT specified is ignored. If neither a BACKGROUND or HEIGHT is specified, then the default HEIGHT is 600 pixels.

HTMLOUTPUTFILE

HTMLOUTPUTFILE htmlfile

This specifies the name of the HTML file that will be generated.

The equivalent command-line option takes precedence over this configuration line, if both are used. If you are generating maps using the Cacti plugin, then this directive is ignored.

Change History

0.7

Added HTMLOUTPUTFILE.

HTMLSTYLESHEET

HTMLSTYLESHEET URL

Specifies a CSS stylesheet to reference, when generating HTML.

When HTML output is enabled, this allows you to include your own CSS stylesheet in the result, allowing for customisation of the output without needing to use awk/perl/etc to modify the HTML.

If you are generating maps using the Cacti plugin, then this directive is ignored.

Added HTMLSTYLESHEET.

IMAGEOUTPUTFILE

IMAGEOUTPUTFILE imagefile

This specifies the name of the PNG, JPEG or GIF file that will be generated. The format chosen is based on the file-extension.

The equivalent command-line option takes precedence over this configuration line, if both are used.

If you are generating maps using the Cacti plugin, then this directive is ignored. You can set the output format in the Cacti Settings page.

Change History

0.9

Added JPEG and GIF support.

0.7

Added IMAGEOUTPUTFILE.

IMAGEURI

IMAGEURI image-uri

If you are generating output files using HTMLOUTPUTFILE and IMAGEOUTPUTFILE that are in a different directory to the weathermap installation, then the HTML will probably contain an incorrect IMG tag. This keyword allows you to replace the IMG SRC attribute in the HTML output with a corrected one.

The equivalent command-line option (--image-uri) takes precedence over this configuration line, if both are used.

If you are generating maps using the Cacti plugin, then this directive is ignored, as the filename and uri are calculated instead.

Change History

0.96

Added IMAGEURI.

FONTDEFINE

FONTDEFINE fontnumber gdfontfile

FONTDEFINE fontnumber ttffontfile fontsize

Defines a custom font to be used for text within the map.

By default, the GD library used by Weathermap has 5 fonts, numbered 1-5. FONTDEFINE allows you to define new font numbers, and link them to fonts in two other formats.

The first format is 'GD fonts', which are a bitmapped format used by GD alone. They are not scalable, and are also platform-specific (they use a different byte-order depending on the host). You should specify the full filename including any extensions.

The second format is TrueType fonts, which are scalable, standard and generally a lot nicer! This time, you need to specify the size that the font should be rendered at. The size is in pixels. You can load the same font into multiple fontnumbers with different sizes to use in different parts of a map.

The freetype library used in PHP makes a somewhat complex set of rules for where it will search for truetype fonts. The two easiest options are:

• Use the full absolute path to your .ttf file
• Keep your .ttf files in the Weathermap directory, and use the first part of the filename only, with no '.ttf' on the end.

If you have a font in the Weathermap directory as above and it's not loading, also try: ./FontName.ttf

The full set of rules is available here

Regardless of the format, the newly defined font can be used anywhere that you'd normally use a font number (for example,BWFONT or KEYFONT).

Examples

Defining a new Truetype font, with the font file in the weathermap directory

FONTDEFINE 10 VeraBd 16            

Change History

0.8

First added FONTDEFINE

*FONT

TITLEFONT fontnumber

KEYFONT fontnumber

TIMEFONT fontnumber

Specify the fonts used for various text.

Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using theFONTDEFINE directive.

The built-in GD fonts.

Change History

0.8

Originally added TITLEFONT.

0.7

Originally added TIMEFONT.

0.6

Originally added KEYFONT.

*COLOR

BGCOLOR red green blue

TIMECOLOR red green blue

TITLECOLOR red green blue

KEYTEXTCOLOR red green blue

KEYOUTLINECOLOR red green blue

KEYBGCOLOR red green blue

Specify the colours used for drawing the global elements of the map.

red, green and blue are numbers from 0 to 255.

Change History

0.8

Added TIMECOLOR, TITLECOLOR, KEYTEXTCOLOR, KEYOUTLINECOLOR and KEYBGCOLOR.

0.7

Added BGCOLOR.

TIMEPOS

TIMEPOS x-pos y-pos

TIMEPOS x-pos y-pos formatstring

Specifies where to draw the timestamp on the map.

If no TIMEPOS line is given, then the timestamp is drawn in the top-right corner. To hide it completely, set y to be-200 or so.

You can optionally specify an additional parameter to change the text of the timestamp. This text can contain special tokens which are substituted with parts of the current time. The default timestamp text isCreated: %b %d %Y %H:%M:%S. The tokens used are those accepted by the PHP strftime function. For a full list see thePHP manual page.

You can control the font used to draw the timestamp with TIMEFONT, and the colour that it is drawn in, using TIMECOLOR.

Change History

0.6

Added ability to change text.

0.5

Originally added TIMEPOS

MINTIMEPOS

MINTIMEPOS x-pos y-pos

MINTIMEPOS x-pos y-pos formatstring

Specifies where to draw the 'oldest data' timestamp on the map.

The data collection part of weathermap collects a timestamp for each piece of data, alongside the actual data. This is intended to signify the time that the data was actually valid - it would be the file modification date if it was a text file, or the current time if it was a live SNMP query. The minimum and maximum of these times are collated, and can be shown on the map withMINTIMEPOS and MAXTIMEPOS.

If no MINTIMEPOS line is given, then the timestamp is not drawn.

You can optionally specify an additional parameter to change the text of the timestamp. This text can contain special tokens which are substituted with parts of the current time. The default timestamp text isOldest Data: %b %d %Y %H:%M:%S. The tokens used are those accepted by the PHP strftime function. For a full list see thePHP manual page.

You can control the font used to draw the timestamp with TIMEFONT, and the colour that it is drawn in, using TIMECOLOR.

Change History

0.96

Originally added MINTIMEPOS

MAXTIMEPOS

MAXTIMEPOS x-pos y-pos

MAXTIMEPOS x-pos y-pos formatstring

Specifies where to draw the 'newest data' timestamp on the map.

The data collection part of weathermap collects a timestamp for each piece of data, alongside the actual data. This is intended to signify the time that the data was actually valid - it would be the file modification date if it was a text file, or the current time if it was a live SNMP query. The minimum and maximum of these times are collated, and can be shown on the map withMINTIMEPOS and MAXTIMEPOS.

If no MAXTIMEPOS line is given, then the timestamp is not drawn.

You can optionally specify an additional parameter to change the text of the timestamp. This text can contain special tokens which are substituted with parts of the current time. The default timestamp text isNewest Data: %b %d %Y %H:%M:%S. The tokens used are those accepted by the PHP strftime function. For a full list see thePHP manual page.

You can control the font used to draw the timestamp with TIMEFONT, and the colour that it is drawn in, using TIMECOLOR.

Change History

0.96

Originally added MAXTIMEPOS

TITLE

TITLE titlestring

Specifies the title text.

The TITLE is shown in file-selectors for both the editor and the Cacti plugin. If you'd like the title to be shown on the map too, then addTITLEPOS line also.

TITLEPOS

TITLEPOS x-pos y-pos

TITLEPOS x-pos y-pos headingstring

Specifies the position of the title text.

If no TITLEPOS line is given, then no title is drawn. You can optionally specify an additional parameter, to change the title. Any text after the second coordinate is taken as a newTITLE.

You can control the font used to draw the title with TITLEFONT, and the colour that it is drawn in, using TITLECOLOR.

Change History

0.8

Originally added TITLEPOS.

KILO

KILO number

Specifies base value for kilo, mega and giga abbreviations.

Both BANDWIDTH and BWLABEL can use K,M,G,T as abbreviations for thousands, millions and so on. You can define what the multiple used is. The default is 1000.

Change History

0.4

Originally added KILO.

HTMLSTYLE

HTMLSTYLE formatname

Specifies the HTML output style.

When HTML output is enabled, there are two variations, which you can choose between. 'static' is a basic HTML page with client-side imagemap, but no 'pop up' graphs. 'overlib' adds the use of the OverLib library to the page, so that pop up graphs can work, too. This requires Javascript, which is why 'static' is the default.

SCALE

SCALE min max red green blue

SCALE scalename min max red green blue

SCALE min max red green blue red2 green2 blue2

SCALE scalename min max red green blue red2 green2 blue2

SCALE min max red green blue tagtext

SCALE scalename min max red green blue tagtext

SCALE min max red green blue red2 green2 blue2 tagtext

SCALE scalename min max red green blue red2 green2 blue2 tagtext

SCALE min max none

Defines one 'span' within the link colour-coding table.

SCALE is used to specify howNODEs and LINKs are colour-coded according to their percent usage. If the percentage usage falls between min and max then the colour specified by red, green and blue is used to colour the link. Colour values are between 0 and 255. Percentages are between 0 and 100, obviously.

In combination with the 'absolute' option of USESCALE, you can also use raw data from TARGET lines. Just use the absolute values for min and max in SCALE lines. In this format, min and max can use the same abbreviations for mega, giga etc asBANDWIDTH and MAXVALUE can.

If you specify two colours on the line (the third and fourth forms above), then the colour chosen for the link will be calculated as a proportion between the two colours. You can avoid specifying manySCALE lines this way.

If you specify the word 'none' instead of a colour, then a transparent colour is used for that range of values.

Without a scalename, the SCALE line will add a definition to the scale named 'DEFAULT'. If you define any other named scales, you can then use theUSESCALE directive to specify that a particular NODE or LINK use your new scale.

With any of the formats, you can specify a 'tag' on the end of the line. When the colour is decided for the 'in' and 'out' parts of aNODE or LINK, then a special SET variable is defined called {node:this:inscaletag} (or outscaletag, or link:this...) which contains the tagtext from theSCALE line that matched. You can use this to do things like choose an icon, or change the label of a node or link based on a percentage. There are examples of this (and most other node-related formatting things) in the suite-1.conf map found in the random-bits/ folder of the weathermap distribution.

If you don't add any SCALE lines to a configuration file, then a default set is added for you, but as soon as you add one, you'll need to make enough to cover the whole 0-100 range to get nice colours. Any percentage not matched bySCALE rules is rendered in grey.

You can specify a colour for an exact percentage (e.g. zero) by using that value for both the min and max values. The scale lines are sorted by min then max, and scanned from top to bottom. The first match wins.

To show a legend in the map for a given SCALE, you should use KEYPOS and KEYSTYLE.

You can also apply SCALEs to colorise ICON images. You do this using USEICONSCALE.

Examples

Setting up a (very simple) colour scale. Colours run smoothly from green to red.

SCALE 0 100 0 255 0 255 0 0            

The default scale set

SCALE 1 10 140 0 255 SCALE 10 25 32 32 255 SCALE 25 40 0 192 255            SCALE 40 55 0 240 0 SCALE 55 70 240 240 0 SCALE 70 85 255 192 0 SCALE 85 100            255 0 0            

Change History

0.97

Added absolute scale support.

0.96

Added 'none' colour option.

0.95

Added USEICONSCALE.

0.95

Added scale tags.

0.9

Added named scales.

0.9

Added considtently sorted scales.

0.8

Added interpolated scale colours.

0.5

Changed to allow min and max to be fractional.

KEYPOS

KEYPOS x-pos y-pos

KEYPOS x-pos y-pos headingstring

KEYPOS scalename x-pos y-pos

KEYPOS scalename x-pos y-pos headingstring

Specifies the position of the key, or legend, that shows what each colour-range in a scale means. If a scalename is not given, then "DEFAULT" is assumed. If noKEYPOS line is given for a scale, then no legend is drawn - handy if you have many many colour ranges. You can also hide any legend by giving it a position with negative coordinates.

You can optionally specify an additional parameter, to change the heading above the colours in the key. This can be used to change the language of the map, for example. If a scalename is given, then youmust also specify a title - there is no useful default title for non-DEFAULT scales.

You can control the font used to draw the key with KEYFONT, and the colours that it is drawn in, using KEYTEXTCOLOR, KEYBGCOLOR and KEYOUTLINECOLOR.

Change History

0.9

Added support for multiple SCALEs.

0.6

Added ability to change text.

KEYSTYLE

KEYSTYLE stylename

KEYSTYLE stylename size

KEYSTYLE scalename stylename

KEYSTYLE scalename stylename size

Specifies the style of the key, or legend, that shows what each colour-range means. If a scalename is not given, then "DEFAULT" is assumed. Valid stylenames are: 'classic', 'horizontal', 'vertical', 'inverted' and 'tags'.

Classic has a line for each SCALE range defined. 'vertical' and 'horizontal' are fixed-size, showing a continuous block from 0-100% usage, which is much more useful when gradientSCALEs are used, or when you have a large number of SCALE lines in one scale. 'inverted' is the same as 'vertical', but with the zero point at the bottom, thermometer-style. Finally, 'tags' is the same style as 'classic', but instead of percentages, it shows the tag string from the end of theSCALE lines, if there are any.

For 'horizontal' and 'vertical' styles, you can optionally add an additional parameter, which specifies the longer dimension of the legend in pixels. That is, for a horizontal legend, it specifies the width. The other dimension is calculated from the size of the font used (see KEYFONT).

Classic Style

Horizontal Style

Vertical Style

Inverted Style

Tags Style

You can hide the percentage signs in the key, by setting key_hidepercent_scalename to 1

If you have a 0->0 line in your SCALE, then you can hide that in the key, by setting key_hidezero_scalename to 1

Examples

Hiding percentage signs, and the 'absolute zero' SCALE entry in a key.

SET key_hidezero_DEFAULT 1 SET key_hidepercent_DEFAULT 1            

Change History

0.96

Added tags and inverted styles.

0.92

Added hidepercent and hidezero SET variables.

0.9

Added support for multiple key styles (classic, horizontal, vertical).

SET

SET hintname hintvalue

Specifies a value for a hint variable.

Hint Variables allow the user to pass settings to the internals of Weathermap that wouldn't normally need to be changed, or that aren't part of the core Weathermap application. Examples are: small rendering changes, parameters for datasources plugins and similar.

Hint Variables are either Global for the map, or assigned to a specific link or node.

There is more about Hint Variables in the Advanced Topics section.

Examples

Enabling 'bulging link mode' in the link-rendering code.

SET link_bulge 1            

Enabling 'screenshot mode' to anonymise a map in 0.95 or newer.

SET screenshot_mode 1            

Disabling 'WMWARN50' messages from appearing

SET nowarn_WMWARN50 1            

Change History

0.9

Originally added SET.

INCLUDE

INCLUDE filename

Include the contents of an additional file within the current map configuration file.

Allows you to use a common set of definition across several map files. There are several restrictions:

• INCLUDE canonly be used in the 'global' section of the the map configuration file - that is, before the firstNODE or LINK.
• INCULDEd files must contain complete NODE or LINK definitions.
• If you intend to use the web-based editor, then you can't currently use any commands other thanNODE or LINK definitions - that is, no SCALEs or FONTDEFINEs etc.

The INCLUDE file can still be useful to define a set of standard templates that can then be used across maps. Some of the other restrictions will hopefully be lifted in a future version. The reason for the restrictions is that the way config files are read and written doesn't keep track of where a particular setting came from, apart from at the NODE/LINK level. This is also the reason why comments are 'lost' by the editor.

Change History

0.96b

Originally added INCLUDE.