PHPMapper - Simple Library to Shade in Areas on a Map

PHPMapper – Simple Library to Shade in Areas on a Map

Preview

PHPMapper is an open source PHP library for drawing a map with areas shaded by varying degrees of intensity based on data given as a simple list (e.g.: MN: 5, WI: 12, MI: 23). It exports a PNG image in a configurable size and color.

The project is written in clean and well documented PHP 5 object oriented source code and can be quickly deployed into your project. It is ideal for generating images for us in reporting and analytics.

Data can be loaded programmatically or from a comma separated values (CSV) source file.

Download and Installation

The source code for the library can be found on Github.

Download / View Source

If your project uses a PHP autoloader (Zend Framework, etc.), you may wish to remove the require_once statements for better performance. A autoload.sh script automates this process — just run it on the bash shell.

Example Code

Using the library is pretty straight forward. It supports loading data either by chaining method calls to the object or from a CSV file through the PHPMapper_Import_CSV class.

PHPMapper_Import_CSV Example:

require_once 'PHPMapper.php';

$data = new PHPMapper_Import_CSV('/path/to/file.csv', true);

// Name/value columns from the headers in the CSV file
$data->map(PHPMapper::REGION, 'header1') // State (e.g.: MN)
      ->map(PHPMapper::VALUE, 'header2');

// Draw a red image, 500 pixels wide
$obj = new PHPMapper('us');
$obj->setColor('FF0000')
    ->setWidth(500)
    ->import($data)
    ->draw();

Election Mode

Preview

The PHPMapper_Election class was added to allow PHPMapper to draw images suitable for reporting winners in multiple data series (e.g.: election results). This class supports a number of options such as “too close to call”, unlimited parties and shading to reflect the level of victory.

PHPMapper_Election extends PHPMapper, so all its parent methods are available in either class.

PHPMapper_Election Example:

$data = new PHPMapper_Election();
$data->setWidth(1000)
    ->addParty('Republicans', '994444')
    ->addParty('Democrats', '446099')
    ->setTooCloseToCallColor('c0c0c0')
    ->addItem('Republicans', 'MN', 104566)->addItem('Democrats('MN', 988546)
    ->addItem('Republicans', 'WI', 876253)->addItem('Democrats('MN', 1219238)
    ->draw();

Adding Custom Maps

Although the project currently includes only a United States map, adding additional maps is easy. All that’s needed is a large PNG file (ideally one created from a vector file). Each region/item on the map should be colored RGB(x, x, x) where X = an incrementing number, counting from 1. The ids and item names should stored in a CSV file and both files should be saved in the maps/ directory (see the us.* files for a better example).

License

I have released the project under the BSD License (http://www.opensource.org/licenses/bsd-license.php). You can use the library as you like for free of charge. I would appreciate attribution.