Perl 3D Bar Graphs and Charts

Bar graph created by Perl 3DBarGrapher Actual graph created by 3DBarGrapher

3DBarGrapher is a Perl module for creating professional looking 3D bar graphs and charts for use in a variety of applications. Features include:

  • Customisable colours, fonts and dimensions
  • Bar or column 3D graphs
  • Gradient fill option for columns and plot area background
  • Random bar colour feature to easily make multiple graphs
    on the same page more distinct
  • XHTML image map output to enable displaying of values when
    moving mouse cursor over the bars (see adjacent example)

Requirements:
Perl and the GD module are needed to run 3DBarGrapher. Development versions were ActivePerl 5.8.4.810 and GD 2.16 but it will likely function correctly with earlier and later releases.[1]

License:
3DBarGrapher is copyright © 2007-2012 S.I.Warhurst and provided free under the same terms and conditions as Perl itself. See the Perl Artistic License.

Download: Download Perl 3DBarGrapher

Documentation

Usage:

use GD::3DBarGrapher qw(creategraph); # or require "3dbargrapher.pl"; if using in '.pl' form
    
my @data = (
['Apples', 28],
['Pears',  43],
...etc 
);

my %options = (
'file' => 'mygraph.jpg',
);

my $imagemap = creategraph(\@data, \%options);

The data to graph must be passed in a multidimensional array where column 0 is the x-axis name of the item to graph and column 1 is it's associated numerical value.

Graph options are passed in a hash and override the defaults listed below. At minimum the 'file' option must be included and specify the full path and filename of the graph to create.

There is only one function in the 3dBarGrapher module and that is creategraph which will return image map XHTML for use in a web page displaying the graph.

Options:

my %options = (

# colours

black       => { R => 0,   G => 0,   B => 0   },
white       => { R => 255, G => 255, B => 255 },
vltgrey     => { R => 245, G => 245, B => 245 },
ltgrey      => { R => 230, G => 230, B => 230 },
midgrey     => { R => 180, G => 180, B => 180 },
midblue     => { R => 54,  G => 100, B => 170 },

# file output details

file        => '',          # file path and name; file extension
                            # can be .jpg|gif|png
quality     => 9,           # image quality: 1 (worst) - 10 (best)
                            # Only applies to jpg and png
# main image properties

imgw        => 400,         # preferred width in pixels
imgh        => 320,         # preferred height in pixels
iplotpad    => 8,           # padding between axis vals & plot area
ipadding    => 14,          # padding between other items
ibgcol      => 'white',     # COLOUR NAME; background colour
iborder     => '',          # COLOUR NAME; border, if any

# plot area properties

plinecol    => 'midgrey',   # COLOUR NAME; line colour
pflcol      => 'vltgrey',   # COLOUR NAME; floor colour
pbgcol      => 'ltgrey',    # COLOUR NAME; back/side colour
pbgfill     => 'gradient',  # 'gradient' or 'solid'; back/side fill
plnspace    => 25,          # minimum pixel spacing between divisions
pnumdivs    => 6,           # maximum number of y-axis divisions

# bar properties

bstyle      => 'bar',       # 'bar' or 'column' style
bcolumnfill => 'gradient',  # 'gradient' or 'solid' for columns
bminspace   => 18,          # minimum spacing between bars
bwidth      => 18,          # width of bar
bfacecol    => 'midblue',   # COLOUR NAME or 'random'; bar face,
                            # 'random' for random bar face colour
# graph title

ttext       => '',          # title text
tfont       => '',          # defaults to gdGiantFont; can specify
                            # true type font for better quality
tsize       => 11,          # font point size
tfontcol    => 'black',     # COLOUR NAME; font colour

# axis labels

xltext      => '',          # x-axis label text
yltext      => '',          # y-axis label text
lfont       => '',          # defaults to gdLargeFont; can specify
                            # true type font for better quality
lsize       => 10,          # font point size
lfontcol    => 'midblue',   # COLOUR NAME; font colour

# axis values

vfont       => '',          # defaults to gdSmallFont; can specify
                            # true type font for better quality
vsize       => 8,           # font point size
vfontcol    => 'black',     # COLOUR NAME; font colour

);

Notes on options:

  • Options commented with "COLOUR NAME" expect the name of one of the default colours above, or you can define your own colours by adding new lines in the same format
  • Overall graph width and height can exceed the specified values, depending on number of items to graph and the values passed for various settings like bwidth, bminspace, etc
  • For better text quality it is recommended to specify true type fonts for options tfont, lfont & vfont. The full path and font file name must be included, eg: 'c:/windows/fonts/verdana.ttf'
  • Only options that default to empty can be defined as empty

Image Map: The creategraph function returns XHTML code for the image and associated image map, which looks something like this:

<img src="mygraph.jpg" width="400" height="320" border="0" usemap="#mygraphjpg1179003059" />
<map name="mygraphjpg1179003059" id="mygraphjpg1179003059">
<area shape="rect" coords="67,123,112,245" href="#" title="Apples: 28" />
<area shape="rect" coords="112,75,158,245" href="#" title="Pears: 43" />
...etc
</map>

Bugs: There aren't any known ones but feel free to report any you find to and I may (or may not Wink!) fix them!

[1] An issue was recently observed with GD 2.41 on Windows whereby, when specifying a font such as "c:/windows/fonts/verdana.ttf", no text was drawn. 'gd' default fonts were OK. This was solved by updating GD to the latest version.