/ 
Imager-Graph-0.12
River stage one • 2 direct dependents • 2 total dependents
/ Imager::Graph

NAME

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

SYNOPSIS

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');

DESCRIPTION

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.

STYLES

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:

set_image_background
set_channels
set_line_color
set_title_font_size
set_title_font_color
set_title_horizontal_align
set_title_vertical_align
set_text_font_color
set_text_font_size
set_graph_background_color
set_graph_foreground_color
set_legend_font_color
set_legend_font
set_legend_font_size
set_legend_patch_size
set_legend_patch_gap
set_legend_horizontal_align
set_legend_vertical_align
set_legend_padding
set_legend_outside_padding
set_legend_fill
set_legend_border
set_legend_orientation
set_callout_font_color
set_callout_font
set_callout_font_size
set_callout_line_color
set_callout_leader_inside_length
set_callout_leader_outside_length
set_callout_leader_length
set_callout_gap
set_label_font_color
set_label_font
set_label_font_size
set_drop_shadow_fill_color
set_drop_shadow_offset
set_drop_shadowXOffset
set_drop_shadowYOffset
set_drop_shadow_filter
set_outline_color
set_data_area_fills
set_data_line_colors

FEATURES

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:

  • if supplied as an array reference, then any element nofeaturename will disable that feature, while an element featurename will enable it.

  • if supplied as a scalar, it is treated as if it were a reference to an array containing only that scalar.

  • 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.

COMMON PARAMETERS

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.

BEYOND STYLES

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.

bg
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

halign
valign

The horizontal and vertical alignment of the title.

legend

defines attributes of the graph legend, if present.

color
font
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.

halign
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.

color
font
size

the text attributes of the callout label. Inherited from text.

line

the color of the callout lines. Inherited from line

inside
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.

color
font
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.

offx
offy

the horizontal and vertical offsets of the drop shadow. Both inherited from dropshadow.off.

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.

HOW VALUES WORK

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:

text=>{
       color=>'lookup(fg)',
       ...
      },
legend =>{
          color=>'lookup(text.color)',
          ...
         },

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.

  • with hatched fills, if you don't supply a 'fg' or 'bg' parameter, Imager::Graph will supply the current graph fg and bg colors.

  • 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.

INTERNAL METHODS

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.

SEE ALSO

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

AUTHOR

Tony Cook <tonyc@cpan.org>, Patrick Michaud

LICENSE

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

BLAME

Addi for producing a cool imaging module. :)