view release on metacpan or  search on metacpan

lib/Tempest.pm  view on Meta::CPAN

use strict;
use warnings;
use version;

use Carp;
use File::Basename;

=head1 NAME

Tempest - Flexible temperature-map/heat-map generator

=head1 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

=head1 VERSION

Version 2010.09.26

Tempest API Version 2009.07.15

=cut

our $VERSION = qv('2010.09.26');
our $API_VERSION = qv('2009.07.15');

=head1 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();

=head1 CONSTANTS

These constants can be assigned to the C<image_lib> property to specify use
of a given image library for all image manipulations.

=head3 C<LIB_MAGICK>

For forcing use of L<Image::Magick|Image::Magick> support.

=head3 C<LIB_GMAGICK>

For forcing use of L<Graphics::Magick|Graphics::Magick> support.

=head3 C<LIB_GD>

For forcing use of L<GD|GD> support.

=cut

use constant LIB_MAGICK => 'Image::Magick';
use constant LIB_GMAGICK => 'Graphics::Magick';
use constant LIB_GD => 'GD';

=head1 PROPERTIES

=head2 Required Properties

=head3 C<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.

=cut

my %input_file;

=head3 C<output_file>

The generated heatmap will be written to this path, replacing any
existing file without warning.

=cut

my %output_file;

=head3 C<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.

=cut

my %coordinates;

=head2 Optional Properties

=head3 C<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.

=cut

my %plot_file;

=head3 C<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.

=cut

my %color_file;

=head3 C<overlay>

lib/Tempest.pm  view on Meta::CPAN

            # ..call their setters
            eval('$self->set_' . $param_name . '($params{$param_name})');
        }
    }
    
    return $self;
}

=head2 C<render>

Initiates processing of provided arguments, and writes a heatmap image
to the filesystem.  Returns B<True> on success.

    die('Rendering failed') if ! $heatmap->render();

=cut

sub render {
    my $self = shift;
    
    my $lib_name = ucfirst(lc($image_lib{$self}));
    $lib_name =~ s/\W//g;
    
    my $result = eval('require Tempest::'.$lib_name.'; return Tempest::'.$lib_name.'::render($self);');
    croak($@) if $@;
    return $result;
}

=head2 C<version>

Returns the version number of the current release.

    die('Outdated') if $heatmap->version() lt '2009.06.15';

=cut

sub version {
    return $VERSION;
}

=head2 C<api_version>

Returns the version number of the currently supported Tempest API.

    die('API is outdated') if $heatmap->api_version() lt '2009.06.15';

=cut

sub api_version {
    return $API_VERSION;
}

=head2 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 C<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();

=head2 Getters

Each getter method returns the current value of its respective property.

For example, if we wanted to retrieve the C<coordinates> to be rendered and
immediately output them with the L<Data::Dumper|Data::Dumper> module:

    use Data::Dumper;
    print Dumper( $heatmap->get_coordinates() );

=cut

sub set_input_file {
    my $self = shift;
    my $input_file = shift;
    
    if(-r $input_file) {
        $input_file{$self} = $input_file;
    }
    else {
        croak("Image '$input_file' is not readable");
    }
    
    return $self;
}

sub get_input_file {
    my $self = shift;
    return $input_file{$self};
}


sub set_output_file {
    my $self = shift;
    my $output_file = shift;
    
    if((! -e $output_file) || -w $output_file) {
        $output_file{$self} = $output_file;
    }
    else {
        croak("Image '$output_file' is not writable");
    }
    
    return $self;
}

sub get_output_file {
    my $self = shift;
    return $output_file{$self};
}


sub set_coordinates {
    my $self = shift;
    my $coordinates = shift;
    
    # verify an array of 2-element arrays
    if(ref($coordinates) ne 'ARRAY') {