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(
                         data => [ $first_amount, $second_amount ],
                         size => 350);

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. If you supply a "labels" parameter, you must supply a "font" 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:

show_callouts_onAll_segments(): Feature: allcallouts.
all labels are presented as callouts
show_only_label_percentages(): Feature: labelspconly
only show the percentage, not the labels.
show_label_percentages(): Feature: labelspc
adds the percentage of the pie to each label.

Inherited features:

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.
outline: the pie segments are outlined.
dropshadow: the pie is given a drop shadow.

PIE CHART STYLES

The following style values are specific to pie charts:

Controlling callouts, the "callout" option:

color - the color of the callout line and the callout text.
font, size - font and size of the callout text
outside - the distance the radial callout line goes outside the pie
leadlen - the length of the horizontal callout line from the end of the radial line.
gap - the distance between the end of the horizontal callout line and the label.
inside - the length of the radial callout line within the pie.

The outline, line option controls the color of the pie segment outlines, if enabled with the "outline" feature.

Under "pie":

•: maxsegment - any segment below this fraction of the total of the segments will be put into the "others" segment. Default: 0.01

The top level "otherlabel" setting controls the label for the "others" segment, default "(others)".

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 i_planet  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:

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

suitable for monochrome output:

  $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.
_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>