PHP Classes
elePHPant
Icontem

Brainhandles Heatmap: Generate heatmap images from a set of points

Recommend this page to a friend!
  Info   Screenshots Screenshots   View files View files (4)   DownloadInstall with Composer Download .zip   Reputation   Support forum (1)   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2011-08-16 (5 years ago) RSS 2.0 feedNot yet rated by the usersTotal: 375 All time: 6,403 This week: 916Up
Version License PHP version Categories
mapclass_distrib 0.5.0Free To Use But R...5PHP 5, Graphics
Description Author

This class can generate plasma style heatmap images from a set of points.

It takes the coordinates of a set of points and generates an heatmap image to overlay on top of another that represents the incidence of input points in each are by using hotter colors to denote areas with greater point incident.

The class generates the heatmap image and saves it to a file in JPEG format. It can be used to overlay on a page by using CSS opacity attributes to make visible any background graphics or page elements.

Innovation Award
PHP Programming Innovation award nominee
September 2011
Number 4


Prize: One book of choice by Packt
Heatmaps are a form of images that allow to clearly see the intensity of a certain measure over another graphic that can be for instance a map or some other two dimensional graphic.

This class makes it easier to generate heatmap overlay images in PHP from a set of heatmap data points.

Manuel Lemos
Picture of Greg Bulmash
Name: Greg Bulmash <contact>
Classes: 1 package by
Country: United States United States
Innovation award
Innovation award
Nominee: 1x

Details
           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.
Screenshots  
  • demo.jpg
  Files folder image Files  
File Role Description
Accessible without login Image file colors.png Photo Support image for creating the final image
Accessible without login Image file dot.png Photo Support graphics file needed for creating final image
Accessible without login Plain text file README.txt Doc. ReadMe file with instructions and sample code
Accessible without login Plain text file heatclass.php Class Main Class File

 Version Control Unique User Downloads Download Rankings  
 0%
Total:375
This week:0
All time:6,403
This week:916Up