=head1 NAME ANSI::Heatmaps - 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 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 or C. 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. =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 value is 0, unless negative intensities are used. =item swatch ( STR | ARRAYREF ) Set the colour swatch; see C 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 and max_I 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 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. =head2 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. =head2 render ( DATA ) Manually render heatmap data as returned by C. Useful if you want to do any custom processing. =head2 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'. =head2 swatch_names Returns an list of string swatch aliases. =head1 AUTHOR Richard Harris =head1 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.