NAME

ANSI::Heatmap - render heatmaps to your terminal

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]);

DESCRIPTION

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

METHODS

new ( [ARGS] )

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

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 set or 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 undef.

min_y, max_y ( INT )

Ditto for the Y-axis.

min_z, max_z ( FLOAT )

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

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

swatch ( STR | ARRAYREF )

Set the colour swatch; see swatch below.

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.

width, height ( INT )

Specify the width/height of the map in characters. Defaults to using the min_axis and max_axis values to determine the width/height.

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.

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.

get ( X, Y )

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

inc ( X, Y )

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

to_string

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

 binmode STDOUT, ':utf8';

or

 use open OUT => ':utf8';

before printing anything (in this case) to STDOUT.

data

Returns the heatmap data, cropped, scaled and normalised with intensity values between 0 and 1.

Expressed as an arrayref of arrayrefs indexed by Y and then X co-ordinate.

render ( DATA )

Manually render heatmap data as returned by data. Useful if you want to do any custom processing.

swatch ( [ARRAYREF | STRING] )

Set the colour swatch that decided how the heatmap will look. A string alias can be provided, or an arrayref of numeric values from 0..255 declaring the colour indexes to use from least intensive to most.

With no arguments, returns thw swatch as an arrayref.

Defaults to a traditional 'thermography' blue -> red swatch ('blue-red'). Another valid option is 'grayscale'.

swatch_names

Returns an list of string swatch aliases.

AUTHOR

Richard Harris <richardjharris@gmail.com>

COPRIGHT AND LICENSE

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

cpanm ANSI::Heatmap

perl -MCPAN -e shell
install ANSI::Heatmap