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()

all labels are presented as callouts

show_only_label_percentages()

only show the percentage, not the labels.

show_label_percentages()

adds the percentage of the pie to each label.

Additionally, arguments can be added to draw() :

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

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>

SEE ALSO

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