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.

cpanm Imager::Heatmap

perl -MCPAN -e shell
install Imager::Heatmap