/ 
Imager-Heatmap-0.03
River stage zero No dependents
/ Imager::Heatmap

NAME

Imager::Heatmap - Perl extension for drawing Heatmap using Imager

SYNOPSIS

use Imager::Heatmap;
my $hmap = Imager::Heatmap->new(
    xsize  => 640,        # Image width
    ysize  => 480,        # Image height
    xsigma => 10,         # Sigma value of X-direction
    ysigma => 10,         # Sigma value of Y-direction
);

# Add point datas to construct density matrix
$hmap->insert_datas(@piont_datas); # @point_datas should be: ( [ x1, y1, weight1 ], [ x2, y2, weight2 ] ... )

$hmap->insert_datas(...); # You can call multiple times to add large data that cannot process at a time.

# After adding datas, you could get heatmap as Imager instance.
my $img = $hmap->draw;

# Returned image is 4-channels image. So you can overlay it on other images.
$base_img->rubthrough( src => $hmap->img );  # Overlay on other images(see Imager::Transformations)

# And you can access probability density matrix using matrix method if you like.
# In case, maybe you would like to create some graduations which be assigned to color of heatmap and its value.
$hmap->matrix;

DESCRIPTION

Imager::Heatmap is a module to draw heatmap using Imager.

This module calculates probability density matrix from input data and map a color for each pixels to represent density of input data.

METHODS

new()

Create a blessed object of Imager::Heatmap. You can specify some options as follows. See the accessors description for more details about each parameters.

$hmap = Imager::Heatmap->new(xsize => 300, ysize => 300);

Options

o xsize (required)

X-direction size of heatmap image.

o ysize (required)

Y-direction size of heatmap image.

o xsigma (optional, default: 1.0)

Sigma value of X-direction.

o ysigma (optional, default: 1.0)

Sigma value of Y-direction.

o correlation (optional, default: 0.0)

Correlation between X and Y.

xsize()

Set/Get the X-direction size of heatmap image. Constructed matrix will invalidated after call this method as "Setter".

$hmap->xsize(100);
$xsize = $hmap->xsize;

ysize()

Set/Get the Y-direction size of heatmap image. Constructed matrix will invalidated after call this method as "Setter".

$hmap->ysize(100);
$ysize = $hmap->ysize;

xsigma()

Set/Get the Sigma value of X-direction. This value represents the standard deviation of X-direction. This value should be positive number. You will see the heatmap that amplicifed for X-direction if you increment this number.

$hmap->xsigma(10.0);
$xsigma = $hmap->xsigma;

ysigma()

Set/Get the Sigma value of Y-direction. This value represents the standard deviation of Y-direction. This value should be positive number. You will see the heatmap that amplicifed for Y-direction if you increment this number.

$hmap->ysigma(10.0);
$ysigma = $hmap->ysigma;

correlation()

Set/Get the correlation coefficient of XY; This value represents correlation between X and Y. This value should be the number between -1 and 1. (includeing -1 and 1)

$hmap->correlation(0.5);
$correlation = $hmap->correlation;

insert_datas()

Construct the matrix that represents probability density of each pixels of image. This method may be take a while if the datas are large.

$hmap->insert_datas([ $x1, $y1, $weight1 ], [ $x2, $y2 ], ...);

Each element of array should contain x([0]), y([1]), and optionally weight([2]) as follows:

@insert_datas = ( [ x1, y1, weight1 ], [ x2, y2, weight2 ] ... );

The default value of weight is 1.

x and y will implicitly cast to integer in XS, so it doesn't make any sense specifying real numbers to these parameters.

weight can be a real number.

draw()

Draw a heatmap from a constructed probability density matrix and return it.

my $img = $hmap->draw;

Rerturn value is blessed object of Imager. It is created as following options($self is blessed object of Imager::Heatmap)

my $img = Imager->new(
    xsize    => $self->xsize,
    ysize    => $self->ysize,
    channels => 4,
);

matrix()

Get the processed probability density matrix.

$matrix = $hmap->matrix;

Return value is flat array. You can access the value of pixel(x,y) as follows:

$pixel_value = $matrix->[$y * $hmap->xsize + $x];

2-dimensional Probability Desnsity Matrix

Imager::Heatmap calculates probability density matrix of input datas.

You can find the equation used to calculate 2-dimensional probability density matrix at following location:

http://en.wikipedia.org/wiki/Multivariate_normal_distribution#Bivariate_case

SEE ALSO

Imager(3), Imager::Transformations(3)

The equation used to calculate 2-dimensional probability density matrix: Multivariate normal distribution - Wikipedia, the free encyclopedia http://en.wikipedia.org/wiki/Multivariate_normal_distribution#Bivariate_case

AUTHOR

Yuto KAWAMURA(kawamuray), <kawamuray.dadada@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Yuto KAWAMURA(kawamuray)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.3 or, at your option, any later version of Perl 5 you may have available.