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

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

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

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

  # 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

_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

SEE ALSO