NAME
Tempest - Flexible temperature-map/heat-map generator
DESCRIPTION
Tempest is implemented natively in multiple programming languages, including Perl 5. This implementation is "pure" Perl, meaning that there is no C or XS code to configure or compile. Installation entails the steps for any modern CPAN module:
perl Makefile.PL
make
make test
make installVERSION
Version 2009.07.15_1 (alpha release)
Tempest API Version 2009.07.15
SYNOPSIS
This module exposes the Tempest API through class instantiation:
use Tempest;
# Create new instance
$heatmap = new Tempest(
'input_file' => 'screenshot.png',
'output_file' => 'heatmap.png',
'coordinates' => [ [0,10], [2,14], [2,14] ],
));
# Configure as needed
$heatmap->set_image_lib( Tempest::LIB_GD );
# Generate and write heatmap image
$heatmap->render();CONSTANTS
These constants can be assigned to the image_lib property to specify use of a given image library for all image manipulations.
LIB_MAGICK
For forcing use of Image::Magick support.
LIB_GD
For forcing use of GD support.
PROPERTIES
Required Properties
input_file
The generated heatmap will share the same dimensions as this image, and - if indicated - will be overlaid onto this image with a given opacity.
output_file
The generated heatmap will be written to this path, replacing any existing file without warning.
coordinates
The contained x,y coordinates will mark the center of all plotted data points in the heatmap. Coordinates can - and in many cases are expected to - be repeated.
Optional Properties
plot_file
This image, expected to be greyscale, is used to plot data points for each of the given coordinates. Defaults to a bundled image, if none is provided.
color_file
This image, expected to be a true color vertical gradient, is used as a color lookup table and is applied to the generated heatmap. Defaults to a bundled image, if none is provided.
overlay
If true, the heatmap is overlaid onto the input image with a given opacity before being written to the filesystem. Defaults to True.
opacity
Indicates with what percentage of opaqueness to overlay the heatmap onto the input image. If 0, the heatmap will not be visible; if 100, the input image will not be visible. Defaults to b<50>.
image_lib
Indicates which supported image manipulation library should be used for rendering operations. Defaults to the first available from the following:
METHODS
new
Class constructor, accepts a hash of named arguments corresponding to the class' own getter and setter methods.
$heatmap = new Tempest(
'input_file' => 'screenshot.png',
'output_file' => 'heatmap.png',
'coordinates' => [ [0,10], [2,14], [2,14] ],
);render
Initiates processing of provided arguments, and writes a heatmap image to the filesystem. Returns True on success.
die('Rendering failed') if ! $heatmap->render();version
Returns the version number of the current release.
die('Outdated') if $heatmap->version() lt '2009.06.15';api_version
Returns the version number of the currently supported Tempest API.
die('API is outdated') if $heatmap->api_version() lt '2009.06.15';Setters
Each setter method assigns a new value to its respective property. The setters also return the current class instance, so they can be 'chained'.
For example, if we wanted to change the image_lib used for image processing, and immediately render the resulting heatmap:
# render heatmap with Image::Magick support
$heatmap ->set_image_lib( Tempest::LIB_MAGICK ) ->render();Getters
Each getter method returns the current value of its respective property.
For example, if we wanted to retrieve the coordinates to be rendered and immediately output them with the Data::Dumper module:
use Data::Dumper;
print Dumper( $heatmap->get_coordinates() );has_image_lib
Returns true value if the given image library is available.
die('GD is unavailable') if ! $heatmap->has_image_lib(Tempest::LIB_GD);DESTROY
Class destructor, destroys the class instance. Normally not invoked directly.
# free up resources
$heatmap->DESTROY();COPYRIGHT & LICENSE
Copyright 2009 Evan Kaufman, all rights reserved.
This program is released under the MIT license.
http://www.opensource.org/licenses/mit-license.php