/ 
Imager-Graph-0.12
++
 / Imager::Graph::Pie
Tony Cook

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>

SEE ALSO

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