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 install

VERSION

Version 2010.09.26

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_GMAGICK

For forcing use of Graphics::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 2010 Evan Kaufman, all rights reserved.

This program is released under the MIT license.

http://www.opensource.org/licenses/mit-license.php

ADDITIONAL LINKS

Tempest on Google Code:

http://code.google.com/p/image-tempest/

cpanm Tempest

perl -MCPAN -e shell
install Tempest