Weather graphic generator v6.3 Copyright (C) 2005 Anole Computer Services, LLC scripts@anolecomputer.com License ------- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. =============================================================================== **************************************************************************** *** *** *** NOTE: for more detailed information about this script, please visit: *** *** http://scripts.anolecomputer.com/wxgraphic/ *** *** *** **************************************************************************** General Description ------------------- First 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 in much more efficient ways and I am 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 an image in GIF, PNG or JPG format created from a user supplied background image and data file. If no background image is used a simple box with a one pixel black frame is created. This script supports true type fonts and built-in GD fonts. Obviously, since this is a PHP script, your server needs to support PHP. To utilize this script you should understand the following basic concepts: 1) What file paths are, absolute and relative. 2) How to make your weather station software parse and upload a template file. 3) 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. =============================================================================== Requirements ------------------- This script requires the following to function: PHP release 4.3.0 or higher with GD support. GD release 2.0.28 or higher (provides GIF support). =============================================================================== Installing the script --------------------- To install the script: 1) Unpack/unzip the archive. 2) Copy the appropriate data template file to the location that suits the weather station software you use. 3) Enable processing and upload of the file to the location you want on the server. 4) Verify that the file is being processed an uploaded to the server. 5) Create a directory on your server that can be accessed with a URL, ie, in your document root or subdirectory of it. The file can be placed in an existing directory if desired. 6) Set the following parameters in the file config.txt to match your specific configuration. Refer to the Notes section for details: $data_file $image_format $font_file $barom_units $rain_units $degree_units $wind_units $wind_chill_threshold $heat_index_threshold $curr_cond_icon ** YOU MUST SET $data_file, $image_format AND $font_file PROPERLY OR THE ** SCRIPT WILL NOT WORK!!! 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 $temp_conv $temp_prec $wind_conv $wind_prec $barom_conv $rain_conv $rain_prec 7) Copy the following files to the directory you want to run the script from: wxgraphic.php config.txt default.gif, default.png, or default.jpg banner.gif, banner.png, or banner.jpg banner_big.gif, banner_big.png, or banner_big.jpg 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. =============================================================================== Using The Script ---------------- Once installed you use the script by calling it in an tag with the appropriate URL. The default graphic type is a 150px X 150px square. To generate the banners or avatar, add a type value to the URL query string: To display the default graphic: To display the banner graphic: To display the big banner graphic: To display the avatar graphic: =============================================================================== Image Format ------------ 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: GIF: $image_format = 'gif'; PNG: $image_format = 'png'; JPEG: $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. =============================================================================== Data 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[0] for time, $data[1] 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 68 of wxgraphic.php =============================================================================== 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. 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. 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. =============================================================================== Background Images ----------------- The script assumes the following background images are available: 1) 150px X 150px background image for the default named "default.gif" "default.png", or "default.jpeg" 2) 468px X 60px background image for the standard banner named "banner.gif" "banner.png", or "banner.jpeg" 3) 500px X 80px background image for the big banner named "banner_big.gif" "banner_big.png", or "banner_big.jpeg" 4) 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 Icons" below for more details. If the background image does not meet the above criteria for blank space you will have to make changes to config.txt in the sections that draw the data onto the background image. =============================================================================== Current Conditions Icons ------------------------ * NOTE: This feature is currently only works if you are using Weather Display * clientraw.txt as your data file, or a VWS version that includes the * ^climate_cconds1^ tag. All graphics support the inclusion of a current conditions icon embedded within the generated graphic. Current conditions iconsare 25px X 25px in size. Icon position is controlled by the following parameters in config.txt: $default_icon_x $default_icon_y $banner_icon_x $banner_icon_y $banner_big_icon_x $banner_big_icon_y $avatar_icon_x $avatar_icon_y These values represent the location upper left pixel of the icon within the graphics. For example: $default_icon_x = '2'; $default_icon_y = '2'; will place the icon on the default image 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 197 marked: // CURRENT CONDITIONS ICONS FOR clientraw.txt Which icon is displayed for VWS is defined in the section of wxgraphic.php at line 276 marked: // CURRENT CONDITIONS ICONS FOR VWS =============================================================================== TrueType Fonts -------------- 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". =============================================================================== Wind Chill and Heat Index ------------------------- The script takes the wind chill and heat index parameters from the data file and determines whether to output them based upon the values set for $wind_chill_threshold and $heat_index_threshold. If the wind chill value is <= $wind_chill_threshold, wind chill will be included in the graphic. If the heat index value is >= $heat_index_threshold, heat index will be included in the graphic. If neither criteria is met no data is written into that area of the graphic. =============================================================================== The Text Writing Functions and Parameters ---------------------------------------- The text writing functions are found in the config.txt file. If you wish to move things 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 image. imagecenteredtext() must be passed the following parameters in the following order: imagecenteredtext(x, y, text, font size (GD default), TTF font size, color, angle) where: 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 220 write_banner() at line 265 write_banner_big() at line 310 write_avatar() at line 354 =============================================================================== Colors ------ Colors are defined in config.txt in the define_colors() function. By default there are five colors defined as follows: $color1: red $color2: green $color3: blue $color4: black $color5: white Colors are defined in define_colors() using the imagecolorallocate() function as follows: imagecolorallocate(image, red, green, blue); where: image = image variable. Will always be "$img". 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 above for locations). =============================================================================== Transparency ------------ 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 IMPORTANT! 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 becuase 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. To see some examples of the various affects of transparency and anti-aliasing you can visit: http://scripts.anolecomputer.com/wxgraphic/ =============================================================================== Release Notes ------------- 6.3 - Bug Fix: Fixed a bug that caused failure of generation of the \ "Data Currently Unavailble" image. Bug Fix: Replaced mb_convert_case with strtoupper due to compatibilty issues seen by some users. 6.2 - 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 - Consolidated base image creation into a simpler function. 6.0 - The script has been renamed to respect the registered trademark "Weather Sticker" which belongs to Weather Underground. Transparency is now turned off by default. 5.5 - Bug Fix: corrected typo in config.txt where "$anti-alias" should have been "$anti_alias" 5.4 - Added transparency support. This support adds two new parameters: $trans_color $anti_alias Modified the clientraw precision values so that they will have an impact on non-converted values. Corrected avatar.jpeg file name in archive. 5.3 - Added PHP_verify.php to archive to facilitate verification of PHP installations on user servers. Created new web site with additional script information located at: http://scripts.anolecomputer.com/wxgraphic/ 5.2 - Added a 100px X 100px image size for forum avatars. 5.1 - Fixed a problem (typo) for some of the VWS current conditions icon paths. 5.0 - 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: * If the data file is not found on the first attempt it will try again after a two second sleep. * If the data file is not found on the second attempt it will try again after another two second sleep. * If the data file is not found on the third attempt an image in the appropriate size (default, banner, banner_big) will be output indicating that there was no data available. Corrected some problems with icon images names. Corrected text locations in the default images so they'll look a bit better initially. 4.1 - 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 - 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 - Bug Fix: fixed a minor bug that was causing error log entries if current conditions icon was not being used. 3.0 - 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 - Changed provided default.gif 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 - Added two new parameters to make controlling wind chill and heat index display easier. Code slightly modified to accommodate this. 2.2 - 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 default to conserve horizontal space. Added gust values to default image creation and data template files. 2.1 - 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 - 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 - 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. 1.0 - Initial Release