General InformationFirst a disclaimer. I am not a programmer. Anyone who is and looks at this code will instantly recognize that. This script was basically begun as a way to teach myself some PHP and image manipulation. I am well aware that there are probably numerous ways to do what I've done here much more efficiently and I encourage the real programmers out there who look at this script and see a way to make it better to provide some input. Now that that is out of the way....
This script generates a graphical weather image in GIF, PNG or JPG format created from a user supplied background image and data file. This script supports true type fonts and built-in GD fonts.
To utilize this script you should understand the following basic concepts:
- What file paths are, absolute and relative.
- How to make your weather station software parse and upload a template file.
- How to include an image file on a web page.
Additionally, if you wish to modify the text locations, customize the data points displayed, etc., you should have at least a basic understanding of PHP scripting, and a basic understanding of x,y coordinates within images.
Our scripts are free in both the license and monetary sense. However, if you would like show your appreciation for the time and effort that has gone into creating these scripts, you may do so by clicking the button below. It will take you to PayPal but you do not have to have a PayPal account to donate. You can use your regular Visa, MasterCard, etc.
|6.3||10/25/2008||Bug Fix: Fixed a bug that caused failure of generation of the "Data Currently Unavailable" image. Bug Fix: Replaced mb_convert_case with strtoupper due to compatibility issues seen by some users.|
|6.2||8/15/2008||Bug Fix: Fixed a bug that was seen when running PHP5 that caused all images to use the settings for the default text locations|
|6.1||6/27/2007||Consolidated base image creation into a simpler function.|
The script has been renamed as wxgraphic to respect the registered trademark "Weather Sticker" which belongs to Weather Underground. This change has resulted in a number of significant impacts particularly if you are attempting to upgrade the script from an older version:
Added transparency support. This support adds two new parameters:
|5.3||7/30/2006||Added PHP_verify.php to archive to facilitate verification of PHP installations on user servers. Created this web site with additional script information.|
|5.2||7/27/2006||Added a 100px X 100px image size for forum avatars.|
|5.1||7/9/2006||Fixed a problem (typo) for some of the VWS current conditions icon paths.|
Moved the icon placement parameters out into the config.txt file to make it easier to control placement of the icon. I meant to do this in 4.0 but somehow overlooked it.
Made it possible to choose your image format with a single parameter in config.txt. Options are gif, png, or jpeg.
Current conditions icons now supported for VWS! To use this feature the following tags are added to the template file:
^climate_cconds1^,^vst144^,^vst145^ Thanks to Gordon C. @ oldlineweather.com for coming up with the list of possible values for ^climate_cconds1^ and making this possible! Added some functionality to handle conditions where the data file is not present. Since its possible that the data file could be in the process of being uploaded at the time we try to get it, we can end up with a situation where we have no data. This can result in either script errors or blank images. The script is now much more robust in dealing with problems pulling the data file. Specifically:
|4.1||1/30/2006||Changed the banner size to the standard 468px X 60px ad banner size. The larger 500px X 80px banner is still retained but is now called with: "type=banner_big". Moved the image text color definitions into the config.txt to make them easier to modify. Corrected requirements to reflect PHP release 4.3.0 or higher. Bug Fix: corrected typo on windy.gif icon mapping.|
|4.0||11/15/2005||Broke configuration out into a separate file: config.txt. This should make modification and updating the script a bit easier. The config.txt file also contains the data writing functions to make modifying them a bit easier. Bug Fix: Corrected clientraw.txt wind conversions. Values were being converted from MPH when they should have been converted from knots. I knew the values were knots but for some reason I was in a fit of "braindeadness" when writing those functions. Bug Fix: fixed misplaced ";" in case statement Bug Fix: fixed issue relating to not quoting $_REQUEST globals seen in PHP 5.X Bug Fix: removed a line I left in by accident that was outputting: St. James City, FL Current Weather Conditions on the banner. (Oops!) Slight modification to barometric trends for WD clientraw.txt slightly to line it up better with WD values. Added a "Requirements" section to README.txt|
|3.1||11/10/2005||Bug Fix: fixed a minor bug that was causing error log entries if current conditions icon was not being used.|
|3.0||11/9/2005||Added support for Weather Display clientraw.txt file. Because of the nature of the clientraw.txt file additional user configuration parameters specific to it have been added to handle unit and time conversion. Added a changing current conditions icon. This currently only works if using Weather Display clientraw.txt Bug Fix: Fixed a failure to destroy one of the temporary images used for final image creation.|
|2.4||10/19/2005||Changed provided default and banner.gif to remove the sun and cloud from the images. The sun and cloud image that was included on those images was created by Kevin Reed at TNET Services, Inc. and were not part of the public domain. It was never my intention to create the impression that I created that graphic nor was it my intention to violate Mr. Reed's rights with regard to that image so it has been removed to avoid any appearance of such.|
|2.3||10/19/2005||Added two new parameters to make controlling wind chill and heat index display easier. Code slightly modified to accommodate this.|
|2.2||10/5/2005||Bug fix: Still wasn't happy with the way wind units were being handled so it was "robustified". Wind units now display if type is banner, but don't display if type is deafult to conserve horizontal space. Added gust values to default image creation and data template files.|
|2.1||10/4/2005||Bug fix: Fixed color allocation issue if gif pallette is already filled. Bug fix: Fixed problem where "Calm" was showing as "Calmmph". Slight modification to internal functionality to make expansion a bit easier.|
|2.0||10/3/2005||Added support for TrueType fonts. Added wind units parameter. Made positioning text a little more intuitive by changing the method to center both horizontally and vertically on the supplied x,y coordinates.|
|1.1||10/2/2005||Added user definable measurement unit parameters. Eliminated white space between values and units to make display a bit more compact. Tweaked value locations on banner style graphic.|
- Banner Style
- Big Banner Style
- Discussion Forum Avatar Style
Restrictions and Requirements
- Your server must support PHP release 4.3.0 or higher with GD support.
- Your server must support GD release 2.0.28 or higher (provides GIF support).
- Your weather software must support the creation of a data file for upload to your site that fits the requirements specified in the Data File section below.
Installing the Weather Graphics Script
Installation is pretty simple:
- Download the script.
- Unpack/unzip the archive.
- Copy the appropriate data template file to the location that suits the weather station software you use.
- Enable processing and upload of the template file to the location you want on the server in your weather station software.
- Verify that the template file is being processed an uploaded to the server.
- Create a directory on your server that can be accessed with a URL, in your document root or subdirectory of it. The file can be placed in an existing directory if desired.
Set the following parameters in the file config.txt to match your specific configuration. Refer to the Configuration section for details:
$curr_cond_icon If you are using Weather Display clientraw.txt additional parameters should be defined. If you are not using clientraw.txt you do not need to set these parameters: $time_format
Copy the following files to the directory you want to run the script from:
default.gif, default.png, or default.jpeg
banner.gif, banner.png, or banner.jpeg
banner_big.gif, banner_big.png, or banner_big.jpeg
The font file you want to use if using a TrueType font.
Copy current conditions icons to a subdirectory called "/icons" if you are using them.
To run the weather graphic script on your server you must configure it's variables properly to match your sites configuration and define the variables for how you want the script to work.
General Configuration Parameters
$data_file_path - defines the path to the data file. The path can be absolute or relative. If your are using Weather Display clientraw.txt supply the path to it.
NOTE: This is NOT a URL!
Example: $data_file_path = '/home/yourdir/weather/datafile.txt';
$image_format - Defines the format of the output image. The script supports 3 image formats: GIF, PNG, and JPEG
Set $image_format for each as follows:
for GIF: $image_format = 'gif';
for PNG: $image_format = 'png';
for JPEG: $image_format = 'jpeg';
Example: $image_format = 'gif';
$font_file - $font_file is a path (not a URL) to a TrueType font file. If the font file already exists on the server, supply the path to it here. If the font file does not exist on the server, you will need to upload it to the server and set the path to the appropriate location. If you upload a font file to the same directory as wxgraphic.php you can use the relative path './fontfilename.ttf' . If you want to use the default GD fonts set the value to 'none'.
Example: $font_file = './arial.ttf';
$barom_units - This parameter defines the exact text used to for barometer units. It does not affect any barometer measurement values or conversions. It is simply a text value to allow you to modify how units are displayed on the graphic.
Example: $barom_units = 'in/Hg';
$rain_units - This parameter defines the exact text used to for rain units. It does not affect any rain measurement values or conversions. It is simply a text value to allow you to modify how units are displayed on the graphic.
Example: $rain_units = 'in';
$degree_units - This parameter defines the exact text used to for measurements presented in degrees (temperature and dew point). It does not affect any measurement values or conversions. It is simply a text value to allow you to modify how units are displayed on the graphic.
Example: $degree_units = '°F';
$wind_units - This parameter defines the exact text used to for wind speed units. It does not affect any wind speed measurement values or conversions. It is simply a text value to allow you to modify how units are displayed on the graphic.
Example: $wind_units = 'mph';
$wind_chill_threshold - Defines the value at which the wind chill value will be displayed. If the current wind chill value is less than or equal to this value, the wind chill value will be displayed. To prevent wind chill values from being displayed at all, simply set this to a value you know you will never see (-200 for example).
Example: $wind_chill_threshold = '60';
$heat_index_threshold - Defines the value at which the heat value will be displayed. If the current heat index value is greater than or equal to this value, the heat index value will be displayed. To prevent heat index values from being displayed at all, simply set this to a value you know you will never see (200 for example).
Example: $heat_index_threshold = '70';
$curr_cond_icon - Defines whether or not a current conditions icon will be displayed on the graphic. The current conditions icon is only supported if you are using Weather Display clientraw.txt or VWS. Set this paramter to any value other than 'yes' to prevent the current conditions icon from displaying. For more information, see the Current Conditions Icon section below.
Example: $curr_cond_icon = 'yes';
$default_icon_x - Defines the x coordinate on the default graphic of the upper left pixel of the current conditions icon. For more information, see the Current Conditions Icon section below.
Example: $default_icon_x = '2';
$default_icon_y - Defines the y coordinate on the default graphic of the upper left pixel of the current conditions icon. For more information, see the Current Conditions Icon section below.
Example: $default_icon_y = '2';
$banner_icon_x - Defines the x coordinate on the banner graphic of the upper left pixel of the current conditions icon. For more information, see the Current Conditions Icon section below.
Example: $banner_icon_x = '300';
$banner_icon_y - Defines the y coordinate on the banner graphic of the upper left pixel of the current conditions icon. For more information, see the Current Conditions Icon section below.
Example: $banner_icon_y = '2';
$banner_big_icon_x - Defines the x coordinate on the banner_big graphic of the upper left pixel of the current conditions icon. For more information, see the Current Conditions Icon section below.
Example: $banner_icon_x = '2';
$banner_Big_icon_y - Defines the y coordinate on the banner_big graphic of the upper left pixel of the current conditions icon. For more information, see the Current Conditions Icon section below.
Example: $banner_icon_y = '2';
$avatar_icon_x - Defines the x coordinate on the avatar graphic of the upper left pixel of the current conditions icon. For more information, see the Current Conditions Icon section below.
Example: $avatar_icon_x = '2';
$avatar_icon_y - Defines the y coordinate on the avatar graphic of the upper left pixel of the current conditions icon. For more information, see the Current Conditions Icon section below.
Example: $avatar_icon_y = '2';
Weather Display clientraw.txt Specific Parameters
If you are not using Weather Display's clientraw.txt as your data file, you may ignore these settings.
Because the values in Weather Display's clientraw.txt file do not reflect your settings in Weather Display for units, it is necessary to provide conversion of those values into the units you want to use (°C converted to °F for example). The following parameters define those conversions.
Additionally, because these values are being converted/calculated within the script, it is necessary to define the precision of the values. Simply put, precision parameters define how many decimal places will be shown. Keep in mind that these values represent the maximum number of decimal places to display. If a precision is set to '2' and there is only one decimal place in the value, only one decimal place will be displayed.
$time_format - Defines the time format. There are two possible values:
'AMPM' - 12 hour or AM/PM times
'24HR' - 24 hour times
Example: $time_format = 'AMPM';
$temp_conv - Defines the temperature units of measurement. Also applies to dew point. There are two possible values:
'F' - Farenheight
'C' - Celcius
Example: $temp_conv = 'F';
$temp_prec - The number of decimal places to show for temperature measurements. Also applies to dew point.
Example: $temp_prec = '1';
$wind_conv - Defines the wind units of measurement. There are three possible values:
'MPH' - miles/hour
'KPH' - kilometers/hour
'KTS' - knots
Example: $wind_conv = 'MPH';
$wind_prec - The number of decimal places to show for wind measurements.
Example: $wind_prec = '1';
$barom_conv - Defines the barometric pressure units of measurement. There are two possible values:
'INCHES' - inches of mercury (
'MB' - millbars or hPa
Example: $barom_conv = 'INCHES';
$barom_prec - The number of decimal places to show for barometric pressure measurements.
Example: $barom_prec = '2';
$rain_conv - defines the rain units of measurement. There are two possible values:
'INCHES' - inches
'MM' - millimeters
Example: $rain_conv = 'INCHES';
$rain_prec - The number of decimal places to show for rain measurements.
Example: $rain_prec = '2';
The script supports image creation in the following formats:
GIF, PNG, and JPEG.
Select the image format by setting $image_format in config.txt to one of the following values:
$image_format = 'gif';
$image_format = 'png';
$image_format = 'jpeg';
Your background and icon images must match the selected format. Copies of all background and icon images in all three formats are provided in the archive.
The script assumes the following background images are available:
- 150px X 150px background image for the default graphic named "default.gif", "default.png", or "default.jpeg"
- 468px X 60px background image for the standard banner named "banner.gif","banner.png", or "banner.jpeg"
- 500px X 80px background image for the big banner named "banner_big.gif", "banner_big.png", or "banner_big.jpeg"
- 100px X 100px background image for the avatar named "avatar.gif", "avatar.png", or "avatar.jpeg"
To change the size of the image, simply create a new background image in the dimensions you want then pload the resized background image to your script directory. You will most likely have to move the text around on the image to make it fit the new size properly.
You can move items around on the images by modifying the writing functions write_default(), write_banner(), write_banner_big(), and write_avatar(), in config.txt. If you are using the current conditions icon feature you must also account for the space that the icon will occupy. Please refer to the section Current Conditions Icon below for more details.
If the background image does not meet the above criteria for blank space you will have to make changes to the script in the sections that draw the data onto the background image.
Data Template File
The script requires a text data file in the following format:
time,date,temp,heat index,wind chill,humidity,dew point,barometer,barometer trend,wind speed,wind direction,todays rain
VWS users should use the following format if they wish to include a current conditions icon:
time,date,temp,heatindex,wind chill,humidity,dew point,barometer,barometer trend,wind speed,wind direction,todays rain,currentconditions,sunrise,sunset
The currentconditions parameter must be one of the ^climate_ccondsx^ tags from VWS. The default in the provided example template is ^climate_cconds1^.
Weather Display users have the option of using the clientraw.txt file directly. If using clientraw.txt no additional template file is required.
Data is written into an array called $data. Individual data points are then referenced as $data for time, $data for date, etc., so adding additional parameters is a matter of adding them to your template and then calling them with the proper reference.
NOTE: If you add additional parameters to the graphics you will need to add the parameter names to the following global declaration of the following functions in config.txt:
- write_default() at line 186
- write_banner() at line 230
- write_banner_big() at line 274
- write_avatar() at line 318
clientraw.txt data points are referenced by their order in the clientraw.txt file. See the clientrawdescription.txt file included with Weather Display for more information.
Data file templates are provided in the archive for most of the popular weather station software packages.
$data_file defines the path to the data file. This path is NOT A URL!! To avoid confusion it is recommended that you use an absolute file path. If you are comfortable with the concept, a relative path can be used as well.
If the script is unable to get the data file it will output an image in the proper format indicating that no data was available. The text of this message can be modified at line 69 of wxgraphic.php
Current Conditions Icon
All of the graphics support the inclusion of a current conditions icon embedded within the generated graphic. Current conditions icons are 25px X 25px in size. Icon position is controlled by the following parameters in config.txt:
These values represent the location upper left pixel of the icon within the graphics. For example:
$default_icon_y = '2';
will place the icon on the default graphic with the upper left pixel located at x = 2 and y = 2 on the default background image. Since the icon image is 25px X 25px the icon will fill a square on the image whose corners will be located at:
UL: x = 2, y = 2
UR: x = 27, y = 2
LL: x = 2, y = 27
LR: x = 27, y = 27
Keep the boundaries of the icon in mind so that the icon does not overwrite any of your data on the image.
If you wish to use the current conditions icon on your graphic, $curr_cond_icon in config.txt should be set to:
$curr_cond_icon = 'yes';
Setting to any other value or leaving it blank will turn off the current conditions icon.
A group of default icons has been provided in the script archive. You are free to substitute your own icons. While some of them are decent, I'm no graphics artist so it certainly won't hurt my feelings if you don't want to use them! :)
Icons should be 25px X 25px and should be saved in GIF, PNG or JPEG format to match the format selected in config.txt and should use the same names as the provided icons. If you wish to make them a different size, format, or name them something else you will need to make modifications to the script.
Below is a list of the included icon images:
day_clear.gif, day_clear.png, day_clear.jpeg
day_cloudy.gif, day_cloudy.png, day_cloudy.jpeg
day_heavy_rain.gif, day_heavy_rain.png, day_heavy_rain.jpeg
day_light_rain.gif, day_light_rain.png, day_light_rain.jpeg
day_mostly_sunny.gif, day_mostly_sunny.png, day_mostly_sunny.jpeg
day_partly_cloudy.gif, day_partly_cloudy.png, day_partly_cloudy.jpeg
day_rain.gif, day_rain.png, day_rain.jpeg
day_snow.gif, day_snow.png, day_snow.jpeg
day_tstorm.gif, day_tstorm.png, day_tstorm.jpeg
night_clear.gif, night_clear.png, night_clear.jpeg
night_cloudy.gif, night_cloudy.png, night_cloudy.jpeg
night_heavy_rain.gif, night_heavy_rain.png, night_heavy_rain.jpeg
night_light_rain.gif, night_light_rain.png, night_light_rain.jpeg
night_partly_cloudy.gif, night_partly_cloudy.png, night_partly_cloudy.jpeg
night_rain.gif, night_rain.png, night_rain.jpeg
night_snow.gif, night_snow.png, night_snow.jpeg
night_tstorm.gif, night_tstorm.png, night_tstorm.jpeg
fog.gif, fog.png, fog.jpeg
haze.gif, haze.png, haze.jpeg
mist.gif, mist.png, mist.jpeg
sleet.gif, sleet.png, sleet.jpeg
snow.gif, snow.png, snow.jpeg
tornado.gif, tornado.png, tornado.jpeg
windy.gif, windy.png, windy.jpeg
Which icon is displayed for WD clientraw is defined in the section of wxgraphic.php at line 228 marked:
// CURRENT CONDITIONS ICONS FOR clientraw.txt
Which icon is displayed for VWS is defined in the section of wxgraphic.php at line 307 marked:
// CURRENT CONDITIONS ICONS FOR VWS
Weather Display clientraw.txt Functionality
As noted above, if you are using Weather Display's clientraw.txt file as your data source, there are additional parameters you must configure in the script. This is necessary because unlike the html tags generated by the various weather software packages (including Weather Display), clientraw.txt does not take into account your unit preference settings. For example, temperature readings in clientraw.txt are always in °C even if your have your Weather Display preferences set to display in °F.
In order to make it possible to make the values appear in the units you desire you must therefore set those units in the script. Additionally, because the units are converted via mathematical functions, you must specify the precision (number of decimal places) you wish to see in the final display.
Do not confuse these settings with the unit settings $barom_units, $rain_units, $degree_units, and $wind_units! The unit settings do not control conversion. They are there to make it possible for you display, or not display units as you choose.
The script can use TTF fonts or the built-in default fonts found in the GD image manipulation library. Use of TTF font requires the user to provide a valid path to the font file. If the file does not currently exist on the server it must be uploaded. Be sure to upload the font file as binary!
The script checks to verify that the PHP installation supports TrueType fonts and applies the user defined font to text written to the image. If TrueType is not supported in the PHP installation, or no font has been specified, the script defaults to the built-in GD fonts.
The font is determined by the setting for $font_file. This parameter has one special value: none. If defined as:
$font_file = 'none';
the script will use the default GD fonts.
$font_file should be defined as a path to the appropriate TTF font file that you want to use. As with $data_file this value is NOT A URL!! The file can be located anywhere on your server, but the script has to be able to find it. If you place the font file in the same directory as the script, it can be defined with the following relative path:
$font_file = './arial.ttf';
substituting the desired font file name for "arial.ttf".
Text Writing Functions
The functions that write the current conditions text onto the background image are found in the config.txt file and are located at the following lines in config.txt:
write_default() at line 182
write_banner() at line 225
write_banner_big() at line 269
write_avatar() at line 314
To move text around on the image you need to understand how the text writing function works. The function that writes the text onto the background image is imagecenteredtext(). It takes the supplied x,y coordinates, and centers the supplied text on them. So the x,y position you provide represents the center of the text.
imagecenteredtext() must be passed the following parameters in the following order:
imagecenteredtext(x, y, text, font size (GD default), TTF font size, color, angle)
x = x coordinate where the text will be centered (horizontal placement)
y = y coordinate where the text will be centered (vertical placement)
text = the text to be written
size = font size for built-in GD fonts (1,2,3,4, or 5)
ttfsize = font size for ttf fonts. 8 = 8pt
color = color as defined in the allocate colors section. Default colors available are red, green, blue, black, and white.
angle = for ttf fonts, determines the angle (direction) for the text.
You must pass all parameters! If you aren't using a parameter, just plug a '' into it's position.
If you wish to add additional parameters to the graphics, you must also add those parameters to the global declarations in the writing functions in config.txt at the following locations:
write_default() at line 186
write_banner() at line 230
write_banner_big() at line 274
write_avatar() at line 318
Text colors are defined in config.txt in the define_colors() function. By default there are five colors defined as follows:
Colors are defined in define_colors() using the imagecolorallocate() function as follows:
imagecolorallocate(image, red, green, blue);
image = "$img" This will always be the value in this script.
red = red component 0-255
green = green component 0-255
blue = blue component 0-255
You can modify the existing colors by simply changing the rgb components for the $color1 - $color5 variables.
You may add additional colors if you like but you will need to add the new variables to the global declarations in both the define_colors() function and the image writing functions (see Text Writing Functions above for locations).
The script supports the use of transparent backgrounds for GIF and PNG images. Transparency is not supported for JPEG.
To use transparency set the value of the color in the background image that you want to be transparent using it's RGB values in the define_colors() function found in config.txt
Do not set the transparency in your source image. The image should be saved in your image editor without any transparency. If you set the transparency in the source image you will get strange results. The script will set the color you chose in the variable "$trans_color" as the transparent color of the output image.
Anti-aliasing and transparency
Anti-aliasing for the purposes of this script refers to smoothing of the text that is written onto the graphic. Anti-aliasing and transparency often don't play well together because of the way that anti-aliasing works. In very simple terms, anti-aliasing of black text on a white background "blends" the black of the text into the white of the background. This isn't a big deal if the background of the web page that the transparent image appears on is the same or close to the transparent color (background) of the image. If it's not you see a "halo" affect which makes your graphic look bad and in some case the text unreadable.
The real problem here is that graphics drawing engine the script uses (GD), always anti-aliases TrueType fonts by default. If you aren't using a TrueType font, this is a non-issue since the built-in fonts are not anti-aliased.
To help you avoid this problem you can turn off the anti-aliasing by setting the parameter $anti_alias to 'off':
$anti_alias = 'off';
There is a trade-off in doing this though. Your text will look not be as smooth or look as good. The severity of this degradation is dependent upon the font being used but all fonts will exhibit some amount of degradation.
Here are some examples to illustrate:
Transparent color: RGB: 250,250,250
Transparent color: RGB: 250,250,250
Transparent color: RGB: 250,0,0
Transparent color: RGB: 250,0,0
Can't get the script to run? Continually getting an error message? Here's some troubleshooting tips:
|No image or error message displayed||Your server doesn't support PHP.||Your server must support PHP for the script to work. To verify PHP support upload the included PHP_verify.php file to your server and call it by URL.|