NAME

Image::Heatmap - Build heatmap images

DESCRIPTION

Will effortlessly convert latitude/longitude coordinates into a graphical heatmap of the geographical region relative the number of points outlined.

http://is.gd/jvew are two examples of such images built by early versions of this module.

METHODS

new

Will instantiate and return a blessed scalar reference to an integer representing the 'object id' (incremented unique integer for each object).

Does not use any 3rd party modules such as Moose or Class::Accessor to obtain good object management. Albeit a potentially better design, I simply didn't want to mess with it.

process

Will generate the heatmap, saving a file of chosen type (based off file suffix) to the location defined in 'output' (see ATTRIBUTES)

ATTRIBUTES

Will define the number of processes to use for the image processing. Will only add each plot to the full image with the processes, where the final image will be generated with only a single process. Furthermore, being the module will iterate over the set twice (for reasons I will leave out), the first iteration will, too, only be processed in single-thread mode.

If one (1) process is selected, only one process will be used throughout the use of this module. If > 1 is required, there will be n + 1, where the parent will fork the number of processes requested and block on their completion.

statement

Will accept the statement handle the module will use. At the time of this writing, this is the only method of giving a list of lat/long to the module (see TODO).

The module will assume the statement handle to take zero bind parameters and assume (at least) two column names: 'latitude' and 'longitude', respectively. A defficiency of these requirements will kill the processing.

    my $image = Image::Heatmap->new();
    my $dbh   = DBI->new( 'dsn', 'user', 'pass', {} );

    # Note that because the requirement of the named columns, if the columns of
    # the table do not match, you should select them as named columns.
    my $sth   = $dbh->prepare('select lat AS latitude, long AS longitude from table');

geo_list

Can be an array reference of hash references with each hash contianing two keys: latitude and longitude.

    [
        {
            'latitude'  => 0,
            'longitude' => 0,
        },
    ]

This is an alternative method of than statement, but will be accessed after statement. Therefore, if both attributes are set, the statement call will be used.

    # No longer have the need for statement handle requirements
    my $image = Image::Heatmap->new();
    $image->geo_list( [ { 'latitude' => 0, 'longitude' => 0 } ] );

map

A string representng the readable location of the mapping image the plots will be layered upon.

tmp_dir

Default: /tmp/

Used primarily when using multiple-processes, will cache some images along the way in the specified directory.

output

Default: heatmap.png

The literal path to the heatmap image. Will be of the type specified by it's file suffix.

parent

Used by the module, will hold the process id of the parent process.

thumbnail

OPTIONAL

The literal path to the heatamp thumbnail image.

thumbnail_scale

OPTIONAL

The scale of the thumbnail, relative to the size of the map.

colors

Default: colors.png

The semi-literal path to the color swatch that will be used for the plots. If the file cannot be found, File::Find will be used to hunt it down within the directory root of the module its self. 'colors.png' is provided in this module.

plot_base

Default: bolilla.png

The semi-literal path to the plot that will be used as the basis for each plot added to the heatmap. If the file cannot be found, File::Find will be used to hunt it down within the directory root of the module. 'bolilla.png' is provided in this distribution and is a 64px square image.

plot_size

Default: 64

The size, in pixels, of the plot image that will be used. Will scale the image at 'plot_base' to be a square with a width and height the size defined here.

image_width

The width of the image that will be mapped. May be defined, but will otherwise be taken from the demensions defined by the image.

image_height

The height of the image that will be mapped. May be defined, but will otherwise be taken from the demensions defined by the image.

zoom

Default: 1

Will zoom the view 'n' times the size of the image.

As, by default, the module will plot relative to the entire planet, zooming is useful (in conjunction with {x,y}_adjust) to view a particular area of Earth rather then the planet as a whole.

x_adjust

Will adjust the view by 'n' pixels relative to the x pan of a cartesian plane.

Useful with the zoom factor when concentrating on a particular area on Earth rather than the planet as a whole.

y_adjust

Will adjust the view by 'n' pixels relative to the y pan of a cartesian plane.

Useful with the zoom factor when concentrating on a particular area on Earth rather than the planet as a whole.

width

Will define the width, in pixels, of the plot area. Will default to the width of the mapped image.

height

Will define the height, in pixels, of the plot area. Will default to the height of the mapped image.

transparent_bg

By default, this is disabled.

    my $heat = Image::Heatmap->new();
    $heat->transparent_bg(1);

Rather than the standard, default background of the off-gray, will attempt to code the background fully transparent. It will do so by using the color in coordinates 0,0 to determine the background color and apply transparency to all pixels that match the same color exactly.

transparent_version

There are numerous supported methods of forcing backgrounds to be transparent depending on the version of PerlMagik you have backing this module. Depending on this, there are two methods available for doing so; one more efficient than the other. Both are the same in that they take the "magic wand" apprach to backgrounding, finding the common colors in the corners of the image and making all simliar colors transparent.

The older and less efficient approach can be enabled such as:

    my $heat = Image::Heatmap->new();
    $heat->transparent_bg(1);
    $heat->transparent_bg( Image::Heatmap::TRANSPARENT_V1 );

The newer and more efficient approach can be enabled such as:

    my $heat = Image::Heatmap->new();
    $heat->transparent_bg(1);
    $heat->transparent_bg( Image::Heatmap::TRANSPARENT_V2 );

The latter of the examples is defaulted.

contrast

Will adjust the contrast of the final image. 0 is default, 3 is normal and 10 is a LOT.

    my $heat = Image::Heatmap->new();
    $heat->constrast(3);

EXAMPLES

    use Image::Heatmap;
    use DBI;

    my $heatmap = Image::Heatmap->new();
    my $dbh     = DBI->connect( 'dsn', 'username', 'password', {} );
    my $sth     = $dbh->prepare('select latitude, lon AS longitude from table');

    $heatmap->statement( $sth );
    $heatmap->process();

    $heatmap->tmp_dir('/tmp'); 
    $heatmap->output('/tmp/heatmap.gif');
    $heatmap->process();

    $heatmap->output('/tmp/heatmap.jpg');
    $heatmap->process();

    $heatmap->output('/tmp/heatmap.png');
    $heatmap->process();

TODO

$VERSION > 1: There are a few known bugs and missing unit tests that prevent me from making this module's $VERSION >= 1. It is my goal to fix this and release it as a 'production ready' module.

AUTHOR

Trevor Hall, <wazzuteke@cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.