Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  IMAGER::GRAPH (3)

.ds Aq ’


Imager::Graph - Perl extension for producing Graphs using the Imager library.



  use Imager::Graph::Sub_class;
  my $chart = Imager::Graph::Sub_class->new;
  my $img = $chart->draw(data=> \@data, ...)
    or die $chart->error;
  $img->write(file => image.png);


Imager::Graph provides style information to its base classes. It defines the colors, text display information and fills based on both built-in styles and modifications supplied by the user to the draw() method.
new This is a simple constructor. No parameters required.
set_graph_size($size) Sets the size of the graph (in pixels) within the image. The size of the image defaults to 1.5 * $graph_size.
set_image_width($width) Sets the width of the image in pixels.
set_image_height($height) Sets the height of the image in pixels.
add_data_series([8, 6, 7, 5, 3, 0, 9], ’Series Name’); Adds a data series to the graph. For Imager::Graph::Pie, only one data series can be added.
set_labels([’label1’, ’label2’ ... ]) Labels the specific data points. For line/bar graphs, this is the x-axis. For pie graphs, it is the label for the wedges.
set_title($title) Sets the title of the graph. Requires setting a font.
set_font($font) Sets the font to use for text. Takes an Imager::Font object.
set_style($style_name) Sets the style to be used for the graph. Imager::Graph comes with several pre-defined styles: fount_lin (default), fount_rad, mono, primary_red, and primary.
error Returns an error message. Only valid if the draw() method returns false.
draw Creates a new image, draws the chart onto that image and returns it.

Optionally, instead of using the api methods to configure your chart, you can supply a data parameter in the format required by that particular graph, and if your graph will use any text, a font parameter

You can also supply many different parameters which control the way the graph looks. These are supplied as keyword, value pairs, where the value can be a hashref containing sub values.

The style parameter will selects a basic color set, and possibly sets other related parameters. See STYLES.

 my $font = Imager::Font->new(file => ImUgly.ttf);
 my $img = $chart->draw(
                 data    => \@data,
                 font    => $font,
                 title   => {
                                 text  => "Hello, World!",
                                 size  => 36,
                                 color => FF0000

When referring to a single sub-value this documentation will refer to ’title.color’ rather than ’the color element of title’.

Returns the graph image on success, or false on failure.


The currently defined styles are:
primary a light grey background with no outlines. Uses primary colors for the data fills.
primary_red a light red background with no outlines. Uses primary colors for the data fills.

Graphs drawn using this style should save well as a gif, even though some graphs may perform a slight blur.

This was the default style, but the red was too loud.

mono designed for monochrome output, such as most laser printers, this uses hatched fills for the data, and no colors. The returned image is a one channel image (which can be overridden with the channels parameter.)

You can also override the colors used by all components for background or drawing by supplying fg and/or bg parameters. ie. if you supply <fg=FF0000’, channels=>3>> then the hash fills and anything else will be drawn in red. Another use might be to set a transparent background, by supplying <bg=’00000000’, channels=>4>>.

This style outlines the legend if present and outlines the hashed fills.

fount_lin designed as a pretty style this uses linear fountain fills for the background and data fills, and adds a drop shadow.

You can override the value used for text and outlines by setting the fg parameter.

This is the default style.

fount_rad also designed as a pretty style this uses radial fountain fills for the data and a linear blue to green fill for the background.

Style API

To set or override styles, you can use the following methods:


Each graph type has a number of features. These are used to add various items that are displayed in the graph area.

Features can be controlled by calling methods on the graph object, or by passing a features parameter to draw().

Some common features are:
show_legend() Feature: legend <features, legend>

adds a box containing boxes filled with the data fills, with the labels provided to the draw method. The legend will only be displayed if both the legend feature is enabled and labels are supplied.

show_outline() Feature: outline

If enabled, draw a border around the elements representing data in the graph, eg. around each pie segments on a pie chart, around each bar on a bar chart.

show_labels() Feature: labels

labels each data fill, usually by including text inside the data fill. If the text does not fit in the fill, they could be displayed in some other form, eg. as callouts in a pie graph.

For pie charts there isn’t much point in enabling both the legend and labels features.

For other charts, the labels label the independent variable, while the legend describes the color used to plot the dependent variables.

show_drop_shadow() Feature: dropshadow

a simple drop shadow is shown behind some of the graph elements.

reset_features() Unsets all of the features.

Note: this disables all features, even those enabled by default for a style. They can then be enabled by calling feature methods or by supplying a feature parameter to the draw() method.

Additionally, features can be set by passing them into the draw() method, named as above:
o if supplied as an array reference, then any element nofeaturename will disable that feature, while an element featurename will enable it.
o if supplied as a scalar, it is treated as if it were a reference to an array containing only that scalar.
o if supplied as a hash reference, then a reset key with a true value will avoid inheriting any default features, a key feature with a false value will disable that feature and a key feature with a true value will enable that feature.
Each graph also has features specific to that graph.


When referring to a single sub-value this documentation will refer to ’title.color’ rather than ’the color element of title’.

Normally, except for the font parameter, these are controlled by styles, but these are the style parameters I’d mostly likely expect you want to use:
font the Imager font object used to draw text on the chart.
back the background fill for the graph. Default depends on the style.
size the base size of the graph image. Default: 256
width the width of the graph image. Default: 1.5 * size (384)
height the height of the graph image. Default: size (256)
channels the number of channels in the image. Default: 3 (the ’mono’ style sets this to 1).
line the color used for drawing lines, such as outlines or callouts. Default depends on the current style. Set to undef to remove the outline from a style.
title the text used for a graph title. Default: no title. Note: this is the same as the title=>{ text => ... } field.
halign horizontal alignment of the title in the graph, one of ’left’, ’center’ or ’right’. Default: center
valign vertical alignment of the title, one of ’top’, ’center’ or ’right’. Default: top. It’s probably a bad idea to set this to ’center’ unless you have a very short title.
text This contains basic defaults used in drawing text.
color the default color used for all text, defaults to the fg color.
size the base size used for text, also used to scale many graph elements. Default: 14.


In most cases you will want to use just the styles, but you may want to exert more control over the way your chart looks. This section describes the options you can use to control the way your chart looks.

Hopefully you don’t need to read this.
back The background of the graph.
fg Used to define basic background and foreground colors for the graph. The bg color may be used for the background of the graph, and is used as a default for the background of hatched fills. The fg is used as the default for line and text colors.
font The default font used by the graph. Normally you should supply this if your graph as any text.
line The default line color.
text defaults for drawing text. Other textual graph elements will inherit or modify these values.
color default text color, defaults to the fg color.
size default text size. Default: 14. This is used to scale many graph elements, including padding and leader sizes. Other text elements will either use or scale this value.
font default font object. Inherited from font, which should have been supplied by the caller.
title If you supply a scalar value for this element, it will be stored in the text field.

Defines the text, font and layout information for the title.
color The color of the title, inherited from text.color.
font The font object used for the title, inherited from text.font.
size size of the title text. Default: double text.size
valign The horizontal and vertical alignment of the title.

legend defines attributes of the graph legend, if present.
size text attributes for the labels used in the legend.
patchsize the width and height of the color patch in the legend. Defaults to 90% of the legend text size.
patchgap the minimum gap between patches in pixels. Defaults to 30% of the patchsize.
patchborder the color of the border drawn around each patch. Inherited from line.
valign the horizontal and vertical alignment of the legend within the graph. Defaults to ’right’ and ’top’.
padding the gap between the legend patches and text and the outside of its box, or to the legend border, if any.
outsidepadding the gap between the border and the outside of the legend’s box. This is only used if the legend.border attribute is defined.
fill the background fill for the legend. Default: none
border the border color of the legend. Default: none (no border is drawn around the legend.)
orientation The orientation of the legend. If this is vertical the the patches and labels are stacked on top of each other. If this is horizontal the patchs and labels are word wrapped across the image. Default: vertical.

For example to create a horizontal legend with borderless patches, darker than the background, you might do:

  my $im = $chart->draw
    legend =>
      patchborder => undef,
      orientation => horizontal,
      fill => { solid => Imager::Color->new(0, 0, 0, 32), }

callout defines attributes for graph callouts, if any are present. eg. if the pie graph cannot fit the label into the pie graph segement it will present it as a callout.
size the text attributes of the callout label. Inherited from text.
line the color of the callout lines. Inherited from line
outside the length of the leader on the inside and the outside of the fill, usually at some angle. Both default to the size of the callout text.
leadlen the length of the horizontal portion of the leader. Default: callout.size.
gap the gap between the callout leader and the callout text. Defaults to 30% of the text callout size.
label defines attributes for labels drawn into the data areas of a graph.
size The text attributes of the labels. Inherited from text.
dropshadow the attributes of the graph’s drop shadow
fill the fill used for the drop shadow. Default: ’404040’ (dark gray)
off the offset of the drop shadow. A convenience value inherited by offx and offy. Default: 40% of text.size.
offy the horizontal and vertical offsets of the drop shadow. Both inherited from
filter the filter description passed to Imager’s filter method to blur the drop shadow. Default: an 11 element convolution filter.
outline describes the lines drawn around filled data areas, such as the segments of a pie chart.
line the line color of the outlines, inherited from line.
fills a reference to an array containing fills for each data item.

You can mix fill types, ie. using a simple color for the first item, a hatched fill for the second and a fountain fill for the next.


Internally rather than specifying literal color, fill, or font objects or literal sizes for each element, Imager::Graph uses a number of special values to inherit or modify values taken from other graph element names.

    Specifying colors

You can specify colors by either supplying an Imager::Color object, by supplying lookup of another color, or by supplying a single value that Imager::Color::new can use as an initializer. The most obvious is just a 6 or 8 digit hex value representing the red, green, blue and optionally alpha channels of the image.

You can lookup another color by using the lookup() function, for example if you give a color as lookup(fg) then Imager::Graph will look for the fg element in the current style (or as overridden by you.) This is used internally by Imager::Graph to set up the relationships between the colors of various elements, for example the default style information contains:

   legend =>{

So by setting the fg color, you also set the default text color, since each text element uses lookup(text.color) as its value.

    Specifying fills

Fills can be used for the graph background color, the background color for the legend block and for the fills used for each data element.

You can specify a fill as a color value or as a general fill, see Imager::Fill for details.

You don’t need (or usually want) to call Imager::Fill::new yourself, since the various fill functions will call it for you, and Imager::Graph provides some hooks to make them more useful.
o with hatched fills, if you don’t supply a ’fg’ or ’bg’ parameter, Imager::Graph will supply the current graph fg and bg colors.
o with fountain fill, you can supply the xa_ratio, ya_ratio, xb_ratio and yb_ratio parameters, and they will be scaled in the fill area to define the fountain fills xa, ya, xb and yb parameters.
As with colors, you can use lookup(name) or lookup(name1.name2) to have one element to inherit the fill of another.

Imager::Graph defaults the fill combine value to normal. This doesn’t apply to simple color fills.

    Specifying numbers

You can specify various numbers, usually representing the size of something, commonly text, but sometimes the length of a line or the size of a gap.

You can use the same lookup mechanism as with colors and fills, but you can also scale values. For example, ’scale(0.5,text.size)’ will return half the size of the normal text size.

As with colors, this is used internally to scale graph elements based on the base text size. If you change the base text size then other graph elements will scale as well.

    Specifying other elements

Other elements, such as fonts, or parameters for a filter, can also use the lookup(name) mechanism.


Only useful if you need to fix bugs, add features or create a new graph class.
_error($message) Sets the error field of the object and returns an empty list or undef, depending on context. Should be used for error handling, since it may provide some user hooks at some point.

The intended usage is:

  some action
    or return $self->_error("error description");

You should almost always return the result of _error() or return immediately afterwards.

_style_defs() Returns the style defaults, such as the relationships between line color and text color.

Intended to be over-ridden by base classes to provide graph specific defaults.

$self->_style_setup(\%opts) Uses the values from %opts, the custom style set by methods, the style set by the style parameter or the set_style() method and the built in chart defaults to build a working style.

The working style features member is also populated with the active features for the chart.

The working style is stored in the _style member of $self.

$self->_get_thing($name) Retrieve some general ’thing’.

Supports the ’lookup(foo)’ mechanism.

Returns an empty list on failure.

$self->_get_number($name) Retrieves a number from the style. The value in the style can be the number, or one of two functions:
lookup(newname) Recursively looks up newname in the style.
scale(value1,value2) Each value can be a number or a name. Names are recursively looked up in the style and the product is returned.
$self->_get_integer($name) Retrieves an integer from the style. This is a simple wrapper around _get_number() that rounds the result to an integer.

Returns an empty list on failure.

_get_color($name) Returns a color object of the given name from the style hash.

Uses Imager::Color->new to translate normal scalars into color objects.

Allows the lookup(name) mechanism.

Returns an empty list on failure.

_translate_fill($what, $box) Given the value of a fill, either attempts to convert it into a fill list (one of <color=$color_value, filled=>1>> or <fill={ fill parameters }>>), or to lookup another fill that is referred to with the ’lookup(name)’ mechanism.

This function does the fg and bg initialization for hatched fills, and translation of *_ratio for fountain fills (using the $box parameter).

Returns an empty list on failure.

_data_fill($index, $box) Retrieves the fill parameters for a data area fill.
_get_fill($name, $box) Retrieves fill parameters for a named fill.
_get_line($name) Return color (and possibly other) parameters for drawing a line with the _line() method.
_make_img() Builds the image object for the graph and fills it with the background fill.
_text_style($name) Returns parameters suitable for calls to Imager::Font’s bounding_box() and draw() methods intended for use in defining text styles.

Returns an empty list on failure.

Returns the following attributes: font, color, size, aa, sizew (optionally)

_text_bbox($text, $name) Returns a bounding box for the specified $text as styled by $name.

Returns an empty list on failure.

_line_style($name) Return parameters suitable for calls to Imager’s line(), polyline(), and box() methods.

For now this returns only color and aa parameters, but future releases of Imager may support extra parameters.

_composite() Returns a list of style fields that are stored as composites, and should be merged instead of just being replaced.
_line(x1 => $x1, y1 => $y1, ..., style => $style) Wrapper for line drawing, implements styles Imager doesn’t.

Currently styles are limited to horizontal and vertical lines.

_box(xmin ..., style => $style) A wrapper for drawing styled box outlines.
_feature_enabled($feature_name) Check if the given feature is enabled in the work style.


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


Tony Cook <>


Imager::Graph is licensed under the same terms as perl itself.


Addi for producing a cool imaging module. :)
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 GRAPH (3) 2012-05-07

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.