| Imager::Graph - Perl extension for producing Graphs using the Imager library. |
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.
set_graph_size($size)set_image_width($width)set_image_height($height)set_title($title)set_font($font)set_style($style_name)draw() method returns false.
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:
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.
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.
You can override the value used for text and outlines by setting the
fg parameter.
This is the default style.
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()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()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()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()a simple drop shadow is shown behind some of the graph elements.
reset_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:
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.
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:
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.
Defines the text, font and layout information for the title.
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), }
},
...);
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.
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.
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 the Imager::Fill manpage 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.
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.
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.
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)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()Intended to be over-ridden by base classes to provide graph specific defaults.
_style_setup(\%opts)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.
_get_thing($name)Supports the 'lookup(foo)' mechanism.
Returns an empty list on failure.
_get_number($name)lookup(newname)scale(value1,value2)_get_integer($name)_get_number() that rounds the result to an integer.
Returns an empty list on failure.
_get_color($name)Uses Imager::Color->new to translate normal scalars into color objects.
Allows the lookup(name) mechanism.
Returns an empty list on failure.
<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.
_get_line($name)_line() method.
_make_img()_text_style($name)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)
Returns an empty list on failure.
_line_style($name)box() methods.
For now this returns only color and aa parameters, but future releases of Imager may support extra parameters.
_composite()Currently styles are limited to horizontal and vertical lines.
_feature_enabled($feature_name)
Imager::Graph::Pie(3), Imager(3), perl(1).
Tony Cook <tony@develop-help.com>
Imager::Graph is licensed under the same terms as perl itself.
Addi for producing a cool imaging module. :)
| Imager::Graph - Perl extension for producing Graphs using the Imager library. |