/ 
Imager-Graph-0.01
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::SubClass;
my $chart = Imager::Graph::SubClass->new;
my $img = $chart->draw(data=>..., ...)
  or die $chart->error;

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.

For best results you need a version of Imager after 0.38. At the time of writing this is only available via CVS:

cvs -d :pserver:anoncvs@cvs.imager.perl.org:/u02/cvsroot login
cvs -d :pserver:anoncvs@cvs.imager.perl.org:/u02/cvsroot co Imager

This provides extra file format support, fountain (gradient), hatch and image fills, and masked images.

new

This is a simple constructor. No parameters required.

error

Returns an error message. Only value if the draw() method returns false.

draw

Creates a new image, draws the chart onto that image and returns it.

Typically you will need to 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 $img = $graph->draw(data=>\@data,
                       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_red

a light red background with no outlines. Uses primary colors for the data fills. This style is compatible with all versions of Imager.

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

This is the default style.

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.

This and following styles require versions of Imager after 0.38.

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.

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.

FEATURES

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

legend

adds a box containing boxes filled with the data filess, 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.

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. There usually isn't much point in including both labels and a legend.

dropshadow

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

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 hatcheed 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 it's 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.)

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.

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. To use a general fill you need a version of Imager after 0.38.

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.

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.

_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 to build a customized hash describing the way the graph should be drawn.

$self->_get_thing($name)

Retrieve some general 'thing'.

Supports the 'lookup(foo)' mechanism.

$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 looks up in the style and the product is returned.

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

_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).

_data_fill($index, $box)

Retrieves the fill parameters for a data area fill.

_get_fill($index, $box)

Retrieves fill parameters for a named fill.

_make_img()

Builds the image object for the graph and fills it with the background fill.

_composite()

Returns a list of style fields that are stored as composites, and should be merged instead of just being replaced.

SEE ALSO

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

AUTHOR

Tony Cook <tony@develop-help.com>

BLAME

Addi for producing a cool imaging module. :)