NAME

Imager::Graph::Pie - a tool for drawing pie charts on Imager images

SYNOPSIS

  use Imager::Graph::Pie;

  my $chart = Imager::Graph::Pie->new;
  # see Imager::Graph for options
  my $img = $chart->draw(labels=>['first segment', 'second segment'],
			 data=>[ $first_amount, $second_amount ],
			 size=>[$width, $height])

DESCRIPTION

Imager::Graph::Pie is intender to make it simple to use Imager to create good looking pie graphs.

Most of the basic layout and color selection is handed off to Imager::Graph.

$graph->draw(...)

Draws a pie graph onto a new image and returns the image.

You must at least supply a data parameter and should probably supply a labels parameter.

The data parameter should be a reference to an array containing the data the pie graph should present.

The labels parameter is a reference to an array of labels, corresponding to the values in data.

FEATURES

As described in Imager::Graph you can enable extra features for your graph. The features you can use with pie graphs are:

legend

adds a legend to your graph. Requires the labels parameter

labels

labels each segment of the graph. If the label doesn't fit inside the segment it is presented as a callout.

labelspc

adds the percentage of the pie to each label.

labelspconly

the segments are labels with their percentages only.

allcallouts

all labels are presented as callouts

pieblur

the segments are blurred, as a substitute for anti-aliased arcs

outline

the pie segments are outlined.

dropshadow

the pie is given a drop shadow.

EXAMPLES

Assuming:

# from the Netcraft September 2001 web survey
# http://www.netcraft.com/survey/
my @data   = qw(17874757  8146372   1321544  811406 );
my @labels = qw(Apache    Microsoft iPlanet  Zeus   );

my $pie = Imager::Graph::Pie->new;

First a simple graph, normal size, no labels:

my $img = $pie->draw(data=>\@data)
  or die $pie->error;

label the segments:

# error handling omitted for brevity from now on
$img = $pie->draw(data=>\@data, labels=>\@labels, features=>'labels');

just percentages in the segments:

$img = $pie->draw(data=>\@data, features=>'labelspconly');

add a legend as well:

$img = $pie->draw(data=>\@data, labels=>\@labels,
                  features=>[ 'labelspconly', 'legend' ]);

and a title, but move the legend down, and add a dropshadow:

$img = $pie->draw(data=>\@data, labels=>\@labels,
                  title=>'Netcraft Web Survey',
                  legend=>{ valign=>'bottom' },
                  features=>[ qw/labelspconly legend dropshadow/ ]);

something a bit prettier:

# requires Imager > 0.38
$img = $pie->draw(data=>\@data, labels=>\@labels,
                  style=>'fount_lin', features=>'legend');

suitable for monochrome output:

# requires Imager > 0.38
$img = $pie->draw(data=>\@data, labels=>\@labels,
                  style=>'mono', features=>'legend');

INTERNAL FUNCTIONS

These are used in the implementation of Imager::Graph, and are documented for debuggers and developers.

_consolidate_segments($data, $labels, $total)

Consolidate segments that are too small into an 'others' segment.

_pieblur($img, $cx, $cy, $radius)

Blurs the pie as a substitute for anti-aliased segments.

_fit_text($cx, $cy, $name, $text, $radius, $begin, $end)

Attempts to fit text into a pie segment with its center at ($cx, $cy) with the given radius, covering the angles $begin through $end.

Returns a list defining the bounding box of the text if it does fit.

AUTHOR

Tony Cook <tony@develop-help.com>

SEE ALSO

Imager::Graph(3), Imager(3), perl(1)

cpanm Imager::Graph

perl -MCPAN -e shell
install Imager::Graph