version 1.0, 2013-05-27  

veleta

  1. Introduction
  2. How it works
  3. Installation
  4. Usage
  5. SVG browser compatibility
  6. For wview users
  7. Copyright
  8. Thanks
  9. Author

1. Introduction

veleta is a PHP script for generating general-purpose SVG gauges.

It was developed as a procedure to generate all the gauges needed for the veleta.info site with a single script.

veleta.info weather station is connected to a Linux box running wview

[top]

2. How it works

Basically veleta consists of a couple of functions that return a gauge or a compass in SVG.

It accepts a set of parameters allowing to represent the variable value, the variable name, the unit and to configure the gauge.

Even though the original idea was oriented to weather variables, it can be easily adapted to represent any other type of variable.

[top]

3. Installation

Simply save the veleta.php script in a directory accesible from your php code.

After that, include it on your php code with:

include ('[path-to-veleta-script]/veleta.php');

In this guide it is assumed that all readings are available from the weather station and they can be assigned to PHP variables.

A word about installation along wview

wview pulls the weather station every few minutes and after each the data collection it performs a bunch of actions.

Among them, it generates html documents based on customisable templates. It is posible to create user-defined templates other than html.

One of the generated documents is parameterlist.htm. It contains all latest readings and derived variables.

Based on this, veleta.info uses a PHP template (parameterlist.phpx) that produces a PHP document (parameterlist.php) after generation cycle.

The php template as well as an example of a generated parameterlist.php is included in the package.

To get it working please read the wview manual about custom templates

You can then include the resulting parameterlist.php wherever you need it to make use of any of their data.

[top]

4. Usage

4.1 Compass

$svgCompass = svgCompass($windDirection, $windSpeed, $varName, $varUnit);

Where $windDirection and $windSpeed can be obtained from the weather station.

$varName is the name of the variable, for example "Wind" or "Viento". $varUnit is the unit for he wind speed, for example "km/h" or "kt".

Compass example

Let's assume that our weather station gives a wind direction of 90° (East) and a wind speed of 35 km/h and that both values are stored into $windDirection and $windSpeed respectively.

$svgCompass = svgCompass($windDirection, $windSpeed, "Wind", "km/h");

This would produce the following SVG image (in this guide it has been converted into SVG for browser compatibility issues):

4.2 Gauge

To get a svg gauge call the function svgGauge

$svgGauge = svgGauge($val,$loVal,$hiVal,$varName,$varUnit,$scaleLowest,$scaleHighest,$scaleInc,$scalelong,$scaleMid,$angStart,$angEnd);
echo $svgGauge;

Parameters related to the weather variable to be displayed:

$val         // Main value to be displayed (e.g. Current temperature, humidity, etc.), typically provided by the weather station
$loVal       // Low value (e.g. low temperature, low humidity, etc.), typically provided by the weather station . Set it to 'no' if not needed
$hiVal       // High value (e.g. high temperature, high humidity, etc.), typically provided by the weather station. Set it to 'no' if not needed
$varName     // The name of the variable (Temperature, Humidity, etc)
$varUnit     // The unit of measure (°C, %, km/h, etc)

Parameters related to the configuration of the gauge :

$scaleLowest  // The lowest value displayed on the scale (for ex. -20 degrees)
$scaleHighest // The highest value displayed on the scale (for ex. 45 degrees)
$scaleInc     // The unit interval between short divisions of the scale (for ex. 1 degree)
$scalelong    // The number of divisions between two consecutive long divisions (for example 10 degrees)
$scaleMid     // True or False to add mid divisions
$angStart     // The angle of the dial for $scaleLowest (0° at 12 o'clock position. 9 o'clock = -90°)
$angEnd       // The angle of the dial for $scaleHighest (0° at 12 o'clock position. 3 o'clock = 90°)

Temperature gauge example

$varName = "Temperature";
$varUnit = "°C";

Gauge settings

$scaleLowest  =  -10; # The lowest value displayed on the scale
$scaleHighest =   50; # The highest value displayed on the scale
$scaleInc     =    1; # We want a division per degree
$scalelong    =   10; # A longer division each 10°. This defines the position of the scale labels as well
$scaleMid     = TRUE; # We want a slightest longer division every 5° (or $scalelong /2)
$angStart     = -150; # Start the scale 7 o'clock position = -150°
$angEnd       =  150; # End of the scale at 5 o'clock position = 150°

Assuming that the readings provided by the weather station are:

Temperature = 24°C
Hi Temperature = 29°C
Lo Temperature = 15°C

the function svgGauge would generate the following image:

Humidity gauge example

$varName = "Humidity";
$varUnit = "%";

Gauge settings

$scaleLowest  =     0; # The lowest value displayed on the scale
$scaleHighest =   100; # The highest value displayed on the scale
$scaleInc     =     2; # We want a division each 2%
$scalelong    =     5; # A longer division each 10% 
$scaleMid     = FALSE; # We don't want mid divisions
$angStart     =  -120; # Start the scale 8 o'clock position = -120°
$angEnd       =   120; # End of the scale at 4 o'clock position = 120°

Assuming that the readings provided by the weather station are:

Humidity = 65
Hi Humidity = 90%
Lo Humidity = 30%

the function svgGauge would generate the following image:

[top]

5. SVG browser compatibility

Not all browsers are SVG compatible. This represents an important problem when serving SVG based images.

The solution adopted at veleta.info is the conversion of the SVG images into PNG.

The weather station is pulled every 5 minutes aproximately.

A shell script called post-generate.sh is fired after every data collection. Therefore, it can be used to run any action needed on completion of every data collection.

In the veleta site, a command has been added that launches the PHP script svg2png.php. This one exports the SVG images to corresponding PNG files.

The actual conversion is achieved via Inkscape

svg2png.php does basically the following:

1. Collect latest weather data
2. Call svgCompass and svgGauge to get the SVG code
3. Save the SVG resulting gauges into the corresponding files
4. Call Inkscape to export the saved SVG to PNG

Collecting the latest weather data depends on your system and weather station.

In the case of veleta.info, all latest readings and derived data are stored in a document called parameterlist.php that is generated by wview as explained before

svg2png.php

<?php

include ('parameterlist.php');       # This document contains the latest readings
include ('veleta.php');              # The veleta script

// Temperature

$varName      =  "Temperature";
$varUnit      =  "°C";
$scaleLowest  =  -10; # The lowest value displayed on the scale
$scaleHighest =   50; # The highest value displayed on the scale
$scaleInc     =    1; # We want a division per degree
$scalelong    =   10; # A longer division each 10°. This defines the position of the scale labels as well
$scaleMid     = TRUE; # We want a slightest longer division every 5° (or $scalelong /2)
$angStart     = -150; # Start the scale 7 o'clock position = -150°
$angEnd       =  150; # End of the scale at 5 o'clock position = 150°

# $outsideTemp,$lowOutsideTemp,$hiOutsideTemp are variables contained in parameterlist.php

$svg = svgGauge($outsideTemp,$lowOutsideTemp,$hiOutsideTemp,$varName,$varUnit,
	        $scaleLow,$scaleHi,$scaleInc,$scaleLong,$scaleMid,$angStart,$angEnd);

// Wiht Connvert (from ImageMagick)

$tmpFile = tempnam(sys_get_temp_dir(),'tempSVG-');
file_put_contents($tmpFile,$svg);

header("Content-Type: image/png");
$command = "/usr/bin/convert $tmpFile  png:-";
$img = passthru($command, $result);
unlink($tmpFile);

//Humidity

# Accordingly....
?>

[top]

6. Copyright

Copyright © 2011 Luis Rosety Gil. License EUPL. Use at your own risk. [top]

7. Thanks

Special thanks to all who expressed their compliments for the gauges design. Without it, I would not be writing this lines now.

Thanks to the wview developers who made such a good product.

Thanks to M.T. Carrasco Benitez (ca AT dragoman DOT org) for his wise advise on giving shape to this document and for improving the code.

[top]

8. Author

Name: Luis Rosety Gil
Website: veleta.info