view release on metacpan or  search on metacpan

lib/GD/3DBarGrapher.pm  view on Meta::CPAN

		else{
			$image->line($fromx,$pixposf,$tox,$pixpost,$temp);
			$pixposf++;
			$pixpost++;
		}

		# adjust RGB values
		foreach $rgb (qw/R G B/) {
			if($column ne ''){
				if ($pixposf == ($fromy-$height)) {
					$clrs{$rgb}{clr} = $c2{$rgb};
				}
				elsif ( $fromy-$pixposf >= $clrs{$rgb}{pxctr} ) {
					$clrs{$rgb}{pxctr} += $clrs{$rgb}{pix};
					$clrs{$rgb}{clr}   += $clrs{$rgb}{adj};
				}
			}
			else{
				if ($pixposf == ($fromy+$height)-1) {
					$clrs{$rgb}{clr} = $c2{$rgb};
				}
				elsif ( $pixposf-$fromy >= $clrs{$rgb}{pxctr} ) {
					$clrs{$rgb}{pxctr} += $clrs{$rgb}{pix};
					$clrs{$rgb}{clr}   += $clrs{$rgb}{adj};
				}
			}
		}
	}
	
}

1;

# -----------------------------------------------------------------------------
# DOCUMENTATION
# -----------------------------------------------------------------------------

=head1 NAME

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

=head1 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);

=head1 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.

=head1 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:

=over 5

=item 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

=item 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

=item 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'

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

=head1 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>

=head1 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

=head1 AUTHOR

3DBarGrapher is copyright (c) 2009 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

=head1 SEE ALSO

L<GD>

=cut