NAME

GD::3DBarGrapher - Create 3D bar graphs using GD

SYNOPSIS

use GD::3DBarGrapher qw(creategraph);
      
my @data = (
    ['Apples', 28],
    ['Pears',  43],
    ...etc 
);

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

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

DESCRIPTION

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.

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.

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       => '',          # uses gdGiantFont unless a true type
                              # font is specified
  tsize       => 11,          # font point size
  tfontcol    => 'black',     # COLOUR NAME; font colour

  # axis labels

  xltext      => '',          # x-axis label text
  yltext      => '',          # y-axis label text
  lfont       => '',          # uses gdLargeFont unless a true type
                              # font is specified
  lsize       => 10,          # font point size
  lfontcol    => 'midblue',   # COLOUR NAME; font colour

  # axis values

  vfont       => '',          # uses gdSmallFont unless a true type
                              # font is specified
  vsize       => 8,           # font point size
  vfontcol    => 'black',     # COLOUR NAME; font colour
  
);

Notes on options:

1. 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

2. Overall graph width and height can exceed the preferred values, depending on number of items to graph and the values specified for various settings like bwidth, bminspace, etc

3. 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'

4. Only options that default to empty can be defined as empty

Image Map

The creategraph function returns XHTML code for the image and an associated image map, 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 and I may (or may not) fix them! Contact swarhurst _at_ cpan.org

AUTHOR

3DBarGrapher is copyright (c) 2008 S.I.Warhurst and is distributed under the same terms and conditions as Perl itself. See the Perl Artistic license:

http://www.perl.com/language/misc/Artistic.html

SEE ALSO

GD