File: README.txt

           The Brainhandles.com PHP HeatMap Class
                      by Greg Bulmash
		    http://www.brainhandles.com/?p=2640
			   Copyright © 2011 Greg Bulmash
			   
       Licensed for use under Creative Commons 3.0 By
	     http://creativecommons.org/licenses/by/3.0/
    Must be attributed to Greg Bulmash of Brainhandles.com
==============================================================

VERSION 0.5.0 BETA

Table of Contents:
	1: Introduction
	2: How it works
	3: Usage
		3.1: Setting the image dimensions [*required*]
		3.2: Importing coordinates arrays [*required*]
		3.3: Setting the overlay path [*required*]
		3.4: Setting the images path [*optional*]	
		3.5: Sample code
		3.6: How to overlay images
	4: Release notes

1: INTRODUCTION	

The Brainhandles heatmap class is a tool to make plasma style heatmaps that you can overlay onto images to represent concentrations of incidence on a grid. This can be used to display hotspots of click activity on a web page or hotspots of criminal activity on a street map.

There are some scripts like this, but most are either not in PHP, use ImageMagick, or have complicated APIs. This script is based on "The definitive heatmap" at Corunet.com. That was written in Ruby with ImageMagick. Despite not knowing Ruby, I ported it to PHP and got it working.

I realized that a lot of people on shared hosting might not have ImageMagick or might have to invoke ImageMagick with shell commands (which is not good for security), so I ported that to using the GD2 library that's almost always included in PHP installs. That was fun because GD doesn't have a multiply blend, so I had to figure out how to simulate one with GD.

I added a few features for error checking, different methods of data import, and this is the result. 

2: HOW IT WORKS

You feed the heatmap class three pieces of information:

	1. The dimensons of your base image.
	2. The location you want the overlay image saved to.
	3. A set of coordinates without incidence (it will count incidence) or a set of coordinates with incidence.
	
A base image with your dimensions is created. Dark dots are overlaid onto it, using a multiply blend, so that when they overlap they darken in those spots. That image is then colorized based on the colors.png strip in the graphics folder included with the distribution. The color range is coldest at the top, hottest at the bottom. You can customize that image with your own gradient if you want.

3: USAGE

3.1: Setting the image dimensions [*required*]

	You use the setDims(width,height) method where width and height are integers representing the image's size in pixels.
		
3.2: Importing coordinates arrays [*required*]

	You feed the coordinate/incidence data to the class in one of the following two manners.

	1: importData($array) method
		
		This method requires you to present an array of x and y coordinates. Each key's value is an array with "x" and "y" keys that have integer values, representing a point on the grid.
		
		You might construct it like this:
			$array[0] = array("x"=>30,"y"=>40);
			$array[1] = array("x"=>139,"y"=>216);
			$array[2] = array("x"=>5,"y"=>19);

		Duplicates are allowed and encouraged because the method will count the incidence of points. This is basically the "raw clickstream". 

	2: setArray($array) method

		This method is for data where you've already counted the incidence. Each key is an X by Y coordinate in the form of ("20x40") and its value is an array with "x", "y" , and "count" keys that have integer values, representing that point on the grid and its incidence. You might construct it like this...
		
			$array["20x40"]["x"] = 20;
			$array["20x40"]["y"] = 40;
			$array["20x40"]["count"] = 18;

3.3: Setting the overlay path [*required*]

	You have to tell the class where to write your heatmap image and what to call it. 
	
	You use the setOverlay([path],[filename.jpg]) method to give it the directory where you want the image written and the filename to use. 

3.4: Setting the images path [*optional*]	
	The images path is where you keep the dot.png and colors.png graphic files that came with this class and will be used to generate your overlay. You can either hardcode it into the class by changing the $imagespath value in the variable declarations at the top of the class, or you can feed the path to the class at runtime using the setImagesPath([path]) method.

	Why would you want to set that value at runtime? One reason would be you created multiple colors.png strips so you can customize the colors of the heatmap, and you want to select the strip dynamically.

3.5: Sample code

	Assuming you want to create a 500x500 overlay and your point and incidence data is in an array called $pointv.
	
		include('path/to/heatclass.php');
		$bubba = new bhHeatmap();
		$bubba->setDims(500,500);
		$bubba->setImagesPath("/path/to/graphics/");
		$bubba->setOverlay("/path/to/overlays/","testimage.jpg");
		$bubba->setArray($pointv);
		$bubba->makeMap();
	
	If all goes well, you'll have an overlay image.
		
3.6: How to overlay images

	When the overlay image is created, you'll want to overlay it on top of another image so the plasmaish splotches have some context. The best way is to use CSS to put it on top of the image at only partial opacity.
	
	 <div id="photo" style="height:500;width:500px;background-image:url('base.jpg')"><img src="overlays/overlay.jpg" height=500 width=500 style="padding:0px;margin:0px;opacity:.55;filter:alpha(opacity=55)"></div>

	 Different browsers need different CSS indicators for opacity, so it's best to use both:

		opacity:.55;               
		filter:alpha(opacity=55);
	
	For the first, select a value between 0 and 1.0, for the second a value between 0 and 100. Experiment until you find a value you like.
	
4: Release notes

	This is the first release, so there are no notes about updates or changes.
	
	POSSIBLE FUTURE UPDATES: 
		* Methods to interpolate lat/long points to X/Y coordinates on a map image.
		* Bugfixes
		* Speed Improvements
	
	If you really like the class, you can send me compliments and praise at burgerguy@gmail.com. 
	
	If you need help, please put your request in the comments section for this class on my blog at brainhandles.com so other people can benefit from being able to read your question and its answer.