view release on metacpan or  search on metacpan

README.pod  view on Meta::CPAN

=head1 NAME

ANSI::Heatmap - render heatmaps to your terminal

=head1 SYNOPSIS

 my $map = ANSI::Heatmap->new(
    half => 1,
    min_x => 0, max_x => 49,
    min_y => 0, max_y => 49,
    swatch => 'blue-red',
 );

 for (1..2000) {
     my $x = int(rand(50));
     my $y = int(rand(50));
     $map->inc($x, $y);
 }

 print $map;

 $map->interpolate(1);
 $map->width(25);
 $map->height(25);
 $map->swatch('grayscale');
 print $map;

 my $data = $map->data;
 # Mess with the data...
 print $map->render($data);

 # Custom swatch
 $map->swatch([0x10 .. 0x15]);

=head1 DESCRIPTION

Produce cutting-edge ANSI heatmaps using 256 colours and weird Unicode
characters! Perfect for 3D (2D + intensity) data.

=head1 METHODS

=head2 new ( [ARGS] )

C<ARGS> may be a hash or hashref accepting the following keys, which
also have getter/setter methods:

=over 4

=item min_x, max_x ( INT )

Specify the smallest and largest X-axis value to include. If not
provided, defaults to the smallest/largest values passed to C<set>
or C<inc>. Can be used to crop the map or ensure it keeps a fixed
size even if some values are unset.

To make automatic again, set to C<undef>.

=item min_y, max_y ( INT )

Ditto for the Y-axis.

=item min_z, max_z ( FLOAT )

Ditto for intensity; useful for keeping a fixed intensity across
multiple heatmaps.

The default C<min_z> value is 0, unless negative intensities are
used.

=item swatch ( STR | ARRAYREF )

Set the colour swatch; see C<swatch> below.

=item half ( BOOL )

A boolean indicating if the map should be rendered in half-height
mode using special characters. On most terminals, this means the
X and Y axis will be scaled identically.

Off by default.

=item width, height ( INT )

Specify the width/height of the map in characters. Defaults to
using the min_I<axis> and max_I<axis> values to determine the
width/height.

=item interpolate ( BOOL )

If width/height is not a nice multiple of the input data and
this flag is set, perform bilinear interpolation (instead of
nearest neighbour). This is a trade off; interpolated data is
blurrier, but retains a linear relationship with the original
data. Off by default.

=back

=head2 set ( X, Y, Z )

Set the heatmap intensity for the given X and Y co-ordinate.

Currently, only integer values for X and Y are supported.

=head2 get ( X, Y )

Return the heatmap intensity for the given X and Y co-ordinate,
or 0 if unset.

=head2 inc ( X, Y )

Increase the intensity at the given co-ordinate by 1.

=head2 to_string

Return a string containing the ANSI heatmap. If C<half> is set,
this string contains wide characters, so you may need to: