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 2009.10.31_1 (beta 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_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

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/

CPAN RT