Graph(3pm) User Contributed Perl Documentation Graph(3pm)
NAME
GD::Graph - Graph Plotting Module for Perl 5
SYNOPSIS
use GD::Graph::moduleName;
DESCRIPTION
GD::Graph is a perl5 module to create charts using the GD module. The
following classes for graphs with axes are defined:
"GD::Graph::lines"
Create a line chart.
"GD::Graph::bars" and "GD::Graph::hbars"
Create a bar chart with vertical or horizontal bars.
"GD::Graph::points"
Create an chart, displaying the data as points.
"GD::Graph::linespoints"
Combination of lines and points.
"GD::Graph::area"
Create a graph, representing the data as areas under a line.
"GD::Graph::mixed"
Create a mixed type graph, any combination of the above. At the
moment this is fairly limited. Some of the options that can be used
with some of the individual graph types won't work very well. Bar
graphs drawn after lines or points graphs may obscure the earlier
data, and specifying bar_width will not produce the results you
probably expected.
Additional types:
"GD::Graph::pie"
Create a pie chart.
DISTRIBUTION STATUS
Distribution has no releases since 2007. It has new maintainer starting
of 1.45 and my plan is to keep modules backwards compatible as much as
possible, fix bugs with test cases, apply patches and release new
versions to the CPAN.
I got repository from Martien without Benjamin's work, Benjamin
couldn't find his repository, so everything else is imported from CPAN
and BackPAN. Now it's all on github <https://github.com/ruz/GDGraph>.
May be at some point Benjamin will find his VCS backup and we can
restore full history.
Release 1.44_01 (development release) was released in 2007 by Benjamin,
but never made into production version. This dev version contains very
nice changes (truecolor, anti-aliasing and alpha support), but due to
nature of how GD and GD::Graph works authors had to add third optional
argument (truecolor) to all constructors in GD::Graph modules. I think
that this should be and can be adjusted to receive named arguments in
constructor and still be backwards compatible. If you were using that
dev release and want to fast forward inclusion of this work into
production release then contact ruz@cpan.org
Martien also has changes in his repository that were never published to
CPAN. These are smaller and well isolated, so I can merge them faster.
My goal at this moment is to merge existing versions together, get rid
of CVS reminders, do some repo cleanup, review existing tickets on
rt.cpan.org. Join if you want to help.
EXAMPLES
See the samples directory in the distribution, and read the Makefile
there.
USAGE
Fill an array of arrays with the x values and the values of the data
sets. Make sure that every array is the same size, otherwise GD::Graph
will complain and refuse to compile the graph.
@data = (
["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"],
[ 1, 2, 5, 6, 3, 1.5, 1, 3, 4],
[ sort { $a <=> $b } (1, 2, 5, 6, 3, 1.5, 1, 3, 4) ]
);
If you don't have a value for a point in a certain dataset, you can use
undef, and the point will be skipped.
Create a new GD::Graph object by calling the new method on the graph
type you want to create (chart is bars, hbars, lines, points,
linespoints, mixed or pie).
my $graph = GD::Graph::chart->new(400, 300);
Set the graph options.
$graph->set(
x_label => 'X Label',
y_label => 'Y label',
title => 'Some simple graph',
y_max_value => 8,
y_tick_number => 8,
y_label_skip => 2
) or die $graph->error;
and plot the graph.
my $gd = $graph->plot(\@data) or die $graph->error;
Then do whatever your current version of GD allows you to do to save
the file. For versions of GD older than 1.19 (or more recent than
2.15), you'd do something like:
open(IMG, '>file.gif') or die $!;
binmode IMG;
print IMG $gd->gif;
close IMG;
and for newer versions (1.20 and up) you'd write
open(IMG, '>file.png') or die $!;
binmode IMG;
print IMG $gd->png;
or
open(IMG, '>file.gd2') or die $!;
binmode IMG;
print IMG $gd->gd2;
Then there's also of course the possibility of using a shorter version
(for each of the export functions that GD supports):
print IMG $graph->plot(\@data)->gif;
print IMG $graph->plot(\@data)->png;
print IMG $graph->plot(\@data)->gd;
print IMG $graph->plot(\@data)->gd2;
If you want to write something that doesn't require your code to 'know'
whether to use gif or png, you could do something like:
if ($gd->can('png')) { # blabla }
or you can use the convenience method "export_format":
my $format = $graph->export_format;
open(IMG, ">file.$format") or die $!;
binmode IMG;
print IMG $graph->plot(\@data)->$format();
close IMG;
or for CGI programs:
use CGI qw(:standard);
#...
my $format = $graph->export_format;
print header("image/$format");
binmode STDOUT;
print $graph->plot(\@data)->$format();
(the parentheses after $format are necessary, to help the compiler
decide that you mean a method name there)
See under "SEE ALSO" for references to other documentation, especially
the FAQ.
METHODS
Methods for all graphs
GD::Graph::chart->new([width,height])
Create a new object $graph with optional width and height. Default
width = 400, default height = 300. chart is either bars, lines,
points, linespoints, area, mixed or pie.
$graph->set_text_clr(colour name)
Set the colour of the text. This will set the colour of the titles,
labels, and axis labels to colour name. Also see the options
textclr, labelclr and axislabelclr.
$graph->set_title_font(font specification)
Set the font that will be used for the title of the chart. See
"FONTS".
$graph->plot(\@data)
Plot the chart, and return the GD::Image object.
$graph->set(attrib1 => value1, attrib2 => value2 ...)
Set chart options. See OPTIONS section.
$graph->get(attrib1, attrib2)
Returns a list of the values of the attributes. In scalar context
returns the value of the first attribute only.
$graph->gd()
Get the GD::Image object that is going to be used to draw on. You
can do this either before or after calling the plot method, to do
your own drawing.
Note: as of the current version, this GD::Image object will always
be palette-based, even if the installed version of GD supports
true-color images.
Note also that if you draw on the GD::Image object before calling
the plot method, you are responsible for making sure that the
background colour is correct and for setting transparency.
$graph->export_format()
Query the export format of the GD library in use. In scalar
context, it returns 'gif', 'png' or undefined, which is sufficient
for most people's use. In a list context, it returns a list of all
the formats that are supported by the current version of GD. It can
be called as a class or object method
$graph->can_do_ttf()
Returns true if the current GD library supports TrueType fonts,
False otherwise. Can also be called as a class method or static
method.
Methods for Pie charts
$graph->set_label_font(font specification)
$graph->set_value_font(font specification)
Set the font that will be used for the label of the pie or the
values on the pie. See "FONTS".
Methods for charts with axes.
$graph->set_x_label_font(font specification)
$graph->set_y_label_font(font specification)
$graph->set_x_axis_font(font specification)
$graph->set_y_axis_font(font specification)
$graph->set_values_font(font specification)
Set the font for the x and y axis label, the x and y axis value
labels, and for the values printed above the data points. See
"FONTS".
$graph->get_hotspot($dataset, $point)
Experimental: Return a coordinate specification for a point in a
dataset. Returns a list. If the point is not specified, returns a
list of array references for all points in the dataset. If the
dataset is also not specified, returns a list of array references
for each data set. See "HOTSPOTS".
$graph->get_feature_coordinates($feature_name)
Experimental: Return a coordinate specification for a certain
feature in the chart. Currently, features that are defined are
axes, the coordinates of the rectangle within the axes; x_label,
y1_label and y2_label, the labels printed along the axes, with
y_label provided as an alias for y1_label; and title which is the
title text box. See "HOTSPOTS".
OPTIONS
Options for all graphs
width, height
The width and height of the canvas in pixels Default: 400 x 300.
NB At the moment, these are read-only options. If you want to set
the size of a graph, you will have to do that with the new method.
t_margin, b_margin, l_margin, r_margin
Top, bottom, left and right margin of the canvas. These margins
will be left blank. Default: 0 for all.
logo
Name of a logo file. Generally, this should be the same format as
your version of GD exports images in. Currently, this file may be
in any format that GD can import, but please see GD if you use an
XPM file and get unexpected results.
Default: no logo.
logo_resize, logo_position
Factor to resize the logo by, and the position on the canvas of the
logo. Possible values for logo_position are 'LL', 'LR', 'UL', and
'UR'. (lower and upper left and right). Default: 'LR'.
transparent
If set to a true value, the produced image will have the background
colour marked as transparent (see also option bgclr). Default: 1.
interlaced
If set to a true value, the produced image will be interlaced.
Default: 1.
Note: versions of GD higher than 2.0 (that is, since GIF support
was restored after being removed owing to patent issues) do not
support interlacing of GIF images. Support for interlaced PNG and
progressive JPEG images remains available using this option.
Colours
bgclr, fgclr, boxclr, accentclr, shadowclr
Drawing colours used for the chart: background, foreground (axes
and grid), axis box fill colour, accents (bar, area and pie
outlines), and shadow (currently only for bars).
All colours should have a valid value as described in "COLOURS",
except boxclr, which can be undefined, in which case the box will
not be filled.
shadow_depth
Depth of a shadow, positive for right/down shadow, negative for
left/up shadow, 0 for no shadow (default). Also see the
"shadowclr" and "bar_spacing" options.
labelclr, axislabelclr, legendclr, valuesclr, textclr
Text Colours used for the chart: label (labels for the axes or
pie), axis label (misnomer: values printed along the axes, or on a
pie slice), legend text, shown values text, and all other text.
All colours should have a valid value as described in "COLOURS".
dclrs (short for datacolours)
This controls the colours for the bars, lines, markers, or pie
slices. This should be a reference to an array of colour names as
defined in GD::Graph::colour ("perldoc GD::Graph::colour" for the
names available).
$graph->set( dclrs => [ qw(green pink blue cyan) ] );
The first (fifth, ninth) data set will be green, the next pink,
etc.
A colour can be "undef", in which case the data set will not be
drawn. This can be useful for cumulative bar sets where you want
certain data series (often the first one) not to show up, which can
be used to emulate error bars (see examples 1-7 and 6-3 in the
distribution).
Default: [ qw(lred lgreen lblue lyellow lpurple cyan lorange) ]
borderclrs
This controls the colours of the borders of the bars data sets.
Like dclrs, it is a reference to an array of colour names as
defined in GD::Graph::colour. Setting a border colour to "undef"
means the border will not be drawn.
cycle_clrs
If set to a true value, bars will not have a colour from "dclrs"
per dataset, but per point. The colour sequence will be identical
for each dataset. Note that this may have a weird effect if you are
drawing more than one data set. If this is set to a value larger
than 1 the border colour of the bars will cycle through the colours
in "borderclrs".
accent_treshold
Not really a colour, but it does control a visual aspect: Accents
on bars are only drawn when the width of a bar is larger than this
number of pixels. Accents inside areas are only drawn when the
horizontal distance between points is larger than this number.
Default 4
Options for graphs with axes.
options for bars, lines, points, linespoints, mixed and area charts.
x_label, y_label
The labels to be printed next to, or just below, the axes. Note
that if you use the two_axes option that you need to use y1_label
and y2_label.
long_ticks, tick_length
If long_ticks is a true value, ticks will be drawn the same length
as the axes. Otherwise ticks will be drawn with length
tick_length. if tick_length is negative, the ticks will be drawn
outside the axes. Default: long_ticks = 0, tick_length = 4.
These attributes can also be set for x and y axes separately with
x_long_ticks, y_long_ticks, x_tick_length and y_tick_length.
x_ticks
If x_ticks is a true value, ticks will be drawn for the x axis.
These ticks are subject to the values of long_ticks and
tick_length. Default: 1.
y_tick_number
Number of ticks to print for the Y axis. Use this, together with
y_label_skip to control the look of ticks on the y axis. Default:
5.
y_number_format
This can be either a string, or a reference to a subroutine. If it
is a string, it will be taken to be the first argument to a
sprintf, with the value as the second argument:
$label = sprintf( $s->{y_number_format}, $value );
If it is a code reference, it will be executed with the value as
the argument:
$label = &{$s->{y_number_format}}($value);
This can be useful, for example, if you want to reformat your
values in currency, with the - sign in the right spot. Something
like:
sub y_format
{
my $value = shift;
my $ret;
if ($value >= 0)
{
$ret = sprintf("\$%d", $value * $refit);
}
else
{
$ret = sprintf("-\$%d", abs($value) * $refit);
}
return $ret;
}
$graph->set( 'y_number_format' => \&y_format );
(Yes, I know this can be much shorter and more concise)
Default: undef.
y1_number_format, y2_number_format
As with y_number_format, these can be either a string, or a
reference to a subroutine. These are used as formats for graphs
with two y-axis scales so that independent formats can be used.
For compatibility purposes, each of these will fall back on
y_number_format if not specified.
Default: undef for both.
x_label_skip, y_label_skip
Print every x_label_skipth number under the tick on the x axis, and
every y_label_skipth number next to the tick on the y axis.
Default: 1 for both.
x_last_label_skip
By default, when x_label_skip is set to something higher than 1,
the last label on the axis will be printed, even when it doesn't
belong to the normal series that should be printed. Setting this to
a true value prevents that.
For example, when your X values are the months of the year (i.e.
Jan - Dec), and you set x_label_skip to 3, the months printed on
the axis will be Jan, Apr, Jul, Oct and Dec; even though Dec does
not really belong to that sequence. If you do not like the last
month to be printed, set x_last_label_skip to a true value.
This option has no effect in other circumstances. Also see
x_tick_offset for another method to make this look better.
Default: 0 for both
x_tick_offset
When x_label_skip is used, this will skip the first x_tick_offset
values in the labels before starting to print. Let me give an
example. If you have a series of X labels like
qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
and you set x_label_skip to 3, you will see ticks on the X axis for
Jan, Apr, Jul, Oct and Dec. This is not always what is wanted. If
you set x_tick_offset to 1, you get Feb, May, Aug, Nov and Dec, and
if you set it to 2, you get Mar, Jun Sep and Dec, and this last one
definitely looks better. A combination of 6 and 5 also works nice
for months.
Note that the value for x_tick_offset is periodical. This means
that it will have the same effect for each integer n in
x_tick_offset + n * x_label_skip.
Also see x_last_label_skip for another method to influence this.
x_all_ticks
Force a print of all the x ticks, even if x_label_skip is set to a
value Default: 0.
x_label_position
Controls the position of the X axis label (title). The value for
this should be between 0 and 1, where 0 means aligned to the left,
1 means aligned to the right, and 1/2 means centered. Default: 3/4
y_label_position
Controls the position of both Y axis labels (titles). The value for
this should be between 0 and 1, where 0 means aligned to the
bottom, 1 means aligned to the top, and 1/2 means centered.
Default: 1/2
x_labels_vertical
If set to a true value, the X axis labels will be printed
vertically. This can be handy in case these labels get very long.
Default: 0.
x_plot_values, y_plot_values
If set to a true value, the values of the ticks on the x or y axes
will be plotted next to the tick. Also see x_label_skip,
y_label_skip. Default: 1 for both.
box_axis
Draw the axes as a box, if true. Default: 1.
no_axes
Draw no axes at all. If this is set to undef, all axes are drawn.
If it is set to 0, the zero axis will be drawn, for bar charts
only. If this is set to a true value, no axes will be drawn at
all. Value labels on the axes and ticks will also not be drawn, but
axis lables are drawn. Default: undef.
two_axes
Use two separate axes for the first and second data set. The first
data set will be set against the left axis, the second against the
right axis. If more than two data sets are being plotted, the
use_axis option should be used to specify which data sets use which
axis.
Note that if you use this option, that you need to use y1_label and
y2_label, instead of just y_label, if you want the two axes to have
different labels. The same goes for some other options starting
with the letter 'y' and an underscore.
Default: 0.
use_axis
If two y-axes are in use and more than two datasets are specified,
set this option to an array reference containing a value of 1 or 2
(for the left and right scales respectively) for each dataset being
plotted. That is, to plot three datasets with the second on a
different scale than the first and third, set this to "[1,2,1]".
Default: [1,2].
zero_axis
If set to a true value, the axis for y values of 0 will always be
drawn. This might be useful in case your graph contains negative
values, but you want it to be clear where the zero value is. (see
also zero_axis_only and box_axes). Default: 0.
zero_axis_only
If set to a true value, the zero axis will be drawn (see
zero_axis), and no axis at the bottom of the graph will be drawn.
The labels for X values will be placed on the zero axis. Default:
0.
y_max_value, y_min_value
Maximum and minimum value displayed on the y axis.
The range (y_min_value..y_max_value) has to include all the values
of the data points, or GD::Graph will die with a message.
For bar and area graphs, the range (y_min_value..y_max_value) has
to include 0. If it doesn't, the values will be adapted before
attempting to draw the graph.
Default: Computed from data sets.
y1_max_value, y1_min_value, y2_max_value, y2_min_value
Maximum and minimum values for left (y1) and right (y2) axes when
two_axes is a true value. Take precedence over y_min_value and
y_max_value.
By default 0 of the left axis is aligned with 0 of the right axis,
it's not true if any of these options is defined.
Otherwise behaviour and default values are as with y_max_value and
y_min_value.
y_min_range, y1_min_range, y2_min_range
Minimal range between min and max values on y axis that is used to
adjust computed y_min_value and y_max_value.
NOTE that author of the feature implemented this for two_axes case
only, patches are wellcome to expand over one y axis.
If two_axes is a true value, then y1_min_range and y2_min_range
take precedence over y_min_range value.
Default: undef
axis_space
This space will be left blank between the axes and the tick value
text. Default: 4.
text_space
This space will be left open between text elements and the graph
(text elements are title and axis labels.
Default: 8.
cumulate
If this attribute is set to a true value, the data sets will be
cumulated. This means that they will be stacked on top of each
other. A side effect of this is that "overwrite" will be set to a
true value.
Notes: This only works for bar and area charts at the moment.
If you have negative values in your data sets, setting this option
might produce odd results. Of course, the graph itself would be
quite meaningless.
overwrite
If set to 0, bars of different data sets will be drawn next to each
other. If set to 1, they will be drawn in front of each other.
Default: 0.
Note: Setting overwrite to 2 to produce cumulative sets is
deprecated, and may disappear in future versions of GD::Graph.
Instead see the "cumulate" attribute.
correct_width
If this is set to a true value and "x_tick_number" is false, then
the width of the graph (or the height for rotated graphs like
"GD::Graph::hbar") will be recalculated to make sure that each data
point is exactly an integer number of pixels wide. You probably
never want to fiddle with this.
When this value is true, you will need to make sure that the number
of data points is smaller than the number of pixels in the plotting
area of the chart. If you get errors saying that your horizontal
size if too small, you may need to manually switch this off, or
consider using something else than a bar type for your chart.
Default: 1 for bar, calculated at runtime for mixed charts, 0 for
others.
Plotting data point values with the data point
Sometimes you will want to plot the value of a data point or bar above
the data point for clarity. GD::Graph allows you to control this in a
generic manner, or even down to the single point.
show_values
Set this to 1 to display the value of each data point above the
point or bar itself. No effort is being made to ensure that there
is enough space for the text.
Set this to a GD::Graph::Data object, or an array reference of the
same shape, with the same dimensions as your data object that you
pass in to the plot method. The reason for this option is that it
allows you to make a copy of your data set, and selectively set
points to "undef" to disable plotting of them.
my $data = GD::Graph::Data->new(
[ [ 'A', 'B', 'C' ], [ 1, 2, 3 ], [ 11, 12, 13 ] ]);
my $values = $data->copy;
$values->set_y(1, 1, undef);
$values->set_y(2, 0, undef);
$graph->set(show_values => $values);
$graph->plot($data);
Default: 0.
values_vertical
If set to a true value, the values will be printed vertically,
instead of horizontally. This can be handy if the values are long
numbers. Default: 0.
values_space
Space to insert between the data point and the value to print.
Default: 4.
values_format
How to format the values for display. See y_number_format for more
information. Default: undef.
hide_overlapping_values
If set to a true value, the values that goes out of graph space are
hidden. Option is EXPERIMENTAL, works only for bars, text still
can overlap with other bars and labels, most useful only with text
in the same direction as bars. Default: undef
Options for graphs with a numerical X axis
First of all: GD::Graph does not support numerical x axis the way it
should. Data for X axes should be equally spaced. That understood:
There is some support to make the printing of graphs with numerical X
axis values a bit better, thanks to Scott Prahl. If the option
"x_tick_number" is set to a defined value, GD::Graph will attempt to
treat the X data as numerical.
Extra options are:
x_tick_number
If set to 'auto', GD::Graph will attempt to format the X axis in a
nice way, based on the actual X values. If set to a number, that's
the number of ticks you will get. If set to undef, GD::Graph will
treat X data as labels. Default: undef.
x_min_value, x_max_value
The minimum and maximum value to use for the X axis. Default:
computed.
x_min_range
Minimal range of x axis.
Default: undef
x_number_format
See y_number_format
x_label_skip
See y_label_skip
Options for graphs with bars
bar_width
The width of a bar in pixels. Also see "bar_spacing". Use
"bar_width" If you want to have fixed-width bars, no matter how
wide the chart gets. Default: as wide as possible, within the
constraints of the chart size and "bar_spacing" setting.
bar_spacing
Number of pixels to leave open between bars. This works well in
most cases, but on some platforms, a value of 1 will be rounded off
to 0. Use "bar_spacing" to get a fixed amount of space between
bars, with variable bar widths, depending on the width of the
chart. Note that if "bar_width" is also set, this setting will be
ignored, and automatically calculated. Default: 0
bargroup_spacing
Number of pixels (in addition to whatever is specified in
"bar_spacing") to leave between groups of bars when multiple
datasets are being displayed. Unlike "bar_spacing", however, this
parameter will hold its value if "bar_width" is set.
Options for graphs with lines
line_types
Which line types to use for lines and linespoints graphs. This
should be a reference to an array of numbers:
$graph->set( line_types => [3, 2, 4] );
Available line types are 1: solid, 2: dashed, 3: dotted, 4: dot-
dashed.
Default: [1] (always use solid)
line_type_scale
Controls the length of the dashes in the line types. default: 6.
line_width
The width of the line used in lines and linespoints graphs, in
pixels. Default: 1.
skip_undef
For all other axes graph types, the default behaviour is (by their
nature) to not draw a point when the Y value is "undef". For line
charts the point gets skipped as well, but the line is drawn
between the points n-1 to n+1 directly. If "skip_undef" has a true
value, there will be a gap in the chart where a Y value is
undefined.
Note that a line will not be drawn unless there are at least two
consecutive data points exist that have a defined value. The
following data set will only plot a very short line towards the end
if "skip_undef" is set:
@data = (
[ qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct ) ],
[ 1, undef, 2, undef, 3, undef, 4, undef, 5, 6 ]
);
This option is useful when you have a consecutive gap in your data,
or with linespoints charts. If you have data where you have
intermittent gaps, be careful when you use this. Default value: 0
Options for graphs with points
markers
This controls the order of markers in points and linespoints
graphs. This should be a reference to an array of numbers:
$graph->set( markers => [3, 5, 6] );
Available markers are: 1: filled square, 2: open square, 3:
horizontal cross, 4: diagonal cross, 5: filled diamond, 6: open
diamond, 7: filled circle, 8: open circle, 9: horizontal line, 10:
vertical line. Note that the last two are not part of the default
list.
Default: [1,2,3,4,5,6,7,8]
marker_size
The size of the markers used in points and linespoints graphs, in
pixels. Default: 4.
Options for mixed graphs
types
A reference to an array with graph types, in the same order as the
data sets. Possible values are:
$graph->set( types => [qw(lines bars points area linespoints)] );
$graph->set( types => ['lines', undef, undef, 'bars'] );
values that are undefined or unknown will be set to "default_type".
Default: all set to "default_type"
default_type
The type of graph to draw for data sets that either have no type
set, or that have an unknown type set.
Default: lines
Graph legends (axestype graphs only)
At the moment legend support is minimal.
Methods
$graph->set_legend(@legend_keys);
Sets the keys for the legend. The elements of @legend_keys
correspond to the data sets as provided to plot().
If a key is undef or an empty string, the legend entry will be
skipped.
$graph->set_legend_font(font name);
Sets the font for the legend text (see "FONTS"). Default:
GD::gdTinyFont.
Options
legend_placement
Where to put the legend. This should be a two letter key of the
form: 'B[LCR]|R[TCB]'. The first letter indicates the placement
(Bottom or Right), and the second letter the alignment (Left,
Right, Center, Top, or Bottom). Default: 'BC'
If the legend is placed at the bottom, some calculations will be
made to ensure that there is some 'intelligent' wrapping going on.
if the legend is placed at the right, all entries will be placed
below each other.
legend_spacing
The number of pixels to place around a legend item, and between a
legend 'marker' and the text. Default: 4
legend_marker_width, legend_marker_height
The width and height of a legend 'marker' in pixels. Defaults: 12,
8
lg_cols
If you, for some reason, need to force the legend at the bottom to
have a specific number of columns, you can use this. Default:
computed
Options for pie graphs
3d If set to a true value, the pie chart will be drawn with a 3d look.
Default: 1.
pie_height
The thickness of the pie when 3d is true. Default: 0.1 x height.
start_angle
The angle at which the first data slice will be displayed, with 0
degrees being "6 o'clock". Default: 0.
suppress_angle
If a pie slice is smaller than this angle (in degrees), a label
will not be drawn on it. Default: 0.
label
Print this label below the pie. Default: undef.
COLOURS
All references to colours in the options for this module have been
shortened to clr. The main reason for this was that I didn't want to
support two spellings for the same word ('colour' and 'color')
Wherever a colour is required, a colour name should be used from the
package GD::Graph::colour. "perldoc GD::Graph::colour" should give you
the documentation for that module, containing all valid colour names. I
will probably change this to read the systems rgb.txt file if it is
available.
FONTS
Depending on your version of GD, this accepts both GD builtin fonts or
the name of a TrueType font file. In the case of a TrueType font, you
must specify the font size. See GD::Text for more details and other
things, since all font handling in GD::Graph is delegated to there.
Examples:
$graph->set_title_font('/fonts/arial.ttf', 18);
$graph->set_legend_font(gdTinyFont);
$graph->set_legend_font(
['verdana', 'arial', gdMediumBoldFont], 12)
(The above discussion is based on GD::Text 0.65. Older versions have
more restrictive behaviour).
HOTSPOTS
Note that this is an experimental feature, and its interface may, and
likely will, change in the future. It currently does not work for area
charts or pie charts.
A known problem with hotspots for GD::Graph::hbars is that the x and y
coordinate come out transposed. This probably won't be fixed until the
redesign of this section
GD::Graph keeps an internal set of coordinates for each data point and
for certain features of a chart, like the title and axis labels. This
specification is very similar to the HTML image map specification, and
in fact exists mainly for that purpose. You can get at these hotspots
with the "get_hotspot" method for data point, and
"get_feature_coordinates" for the chart features.
The <get_hotspot> method accepts two optional arguments, the number of
the dataset you're interested in, and the number of the point in that
dataset you're interested in. When called with two arguments, the
method returns a list of one of the following forms:
'rect', x1, y1, x2, y2
'poly', x1, y1, x2, y2, x3, y3, ....
'line', xs, ys, xe, ye, width
The parameters for "rect" are the coordinates of the corners of the
rectangle, the parameters for "poly" are the coordinates of the
vertices of the polygon, and the parameters for the "line" are the
coordinates for the start and end point, and the line width. It should
be possible to almost directly translate these lists into HTML image
map specifications.
If the second argument to "get_hotspot" is omitted, a list of
references to arrays will be returned. This list represents all the
points in the dataset specified, and each array referred to is of the
form outlined above.
['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
if both arguments to "get_hotspot" are omitted, the list that comes
back will contain references to arrays for each data set, which in turn
contain references to arrays for each point.
[
['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
],
[
['line', xs, ys, xe, ye, w], ['line', xs, ys, xe, ye, w], ...
],...
The "get_feature" method, when called with the name of a feature,
returns a single array reference with a type and coordinates as
described above. When called with no arguments, a hash reference is
returned with the keys being all the currently defined and set
features, and the values array references with the type and coordinates
for each of those features.
ERROR HANDLING
GD::Graph objects inherit from the GD::Graph::Error class (not the
other way around), so they behave in the same manner. The main feature
of that behaviour is that you have the error() method available to get
some information about what went wrong. The GD::Graph methods all
return undef if something went wrong, so you should be able to write
safe programs like this:
my $graph = GD::Graph->new() or die GD::Graph->error;
$graph->set( %attributes ) or die $graph->error;
$graph->plot($gdg_data) or die $graph->error;
More advanced usage is possible, and there are some caveats with this
error handling, which are all explained in GD::Graph::Error.
Unfortunately, it is almost impossible to gracefully recover from an
error in GD::Graph, so you really should get rid of the object, and
recreate it from scratch if you want to recover. For example, to adjust
the correct_width attribute if you get the error "Horizontal size too
small" or "Vertical size too small" (in the case of hbar), you could do
something like:
sub plot_graph
{
my $data = shift;
my %attribs = @_;
my $graph = GD::Graph::bars->new()
or die GD::Graph->error;
$graph->set(%attribs) or die $graph->error;
$graph->plot($data) or die $graph->error;
}
my $gd;
eval { $gd = plot_graph(\@data, %attribs) };
if ($@)
{
die $@ unless $@ =~ /size too small/;
$gd = plot_graph(\@data, %attribs, correct_width => 0);
}
Of course, you could also adjust the width this way, and you can check
for other errors.
NOTES
As with all Modules for Perl: Please stick to using the interface. If
you try to fiddle too much with knowledge of the internals of this
module, you could get burned. I may change them at any time.
BUGS
GD::Graph objects cannot be reused. To create a new plot, you have to
create a new GD::Graph object.
Rotated charts (ones with the X axis on the left) can currently only be
created for bars. With a little work, this will work for all others as
well. Please, be patient :)
Other outstanding bugs can (alas) probably be found in the RT queue for
this distribution, at
http://rt.cpan.org/Public/Dist/Display.html?Name=GDGraph
If you think you have found a bug, please check first to see if it has
already been reported. If it has not, please do (you can use the web
interface above or send e-mail to <bug-GDGraph@rt.cpan.org>). Bug
reports should contain as many as possible of the following:
• a concise description of the buggy behavior and how it differs from
what you expected,
• the versions of Perl, GD::Graph and GD that you are using,
• a short demonstration script that shows the bug in action,
• a patch that fixes it. :-)
Of all of these, the third is probably the single most important, since
producing a test case generally makes the explanation much more concise
and understandable, as well as making it much simpler to show that the
bug has been fixed. As an incidental benefit, if the bug is in fact
caused by some code outside of GD::Graph, it will become apparent while
you are writing the test case, thereby saving time and confusion for
all concerned.
AUTHOR
Martien Verbruggen <mgjv@tradingpost.com.au>
Current maintenance (including this release) by Benjamin Warfield
<bwarfield@cpan.org>
Copyright
GIFgraph: Copyright (c) 1995-1999 Martien Verbruggen.
Chart::PNGgraph: Copyright (c) 1999 Steve Bonds.
GD::Graph: Copyright (c) 1999 Martien Verbruggen.
All rights reserved. This package is free software; you can
redistribute it and/or modify it under the same terms as Perl itself.
Acknowledgements
Thanks to Steve Bonds for releasing Chart::PNGgraph, and keeping the
code alive when GD reached version 1.20, and I didn't have time to do
something about it.
Thanks to the following people for contributing code, or sending me
fixes: Dave Belcher, Steve Bonds, Mike Bremford, Damon Brodie, Gary
Deschaines, brian d foy, Edwin Hildebrand, Ari Jolma, Tim Meadowcroft,
Honza Pazdziora, Scott Prahl, Ben Tilly, Vegard Vesterheim, Jeremy
Wadsack.
And some people whose real name I don't know, and whose email address
I'd rather not publicise without their consent.
SEE ALSO
GD::Graph::FAQ, GD::Graph::Data, GD::Graph::Error, GD::Graph::colour
perl v5.34.0 2022-07-24 Graph(3pm)
Generated by dwww version 1.15 on Wed Jun 26 18:10:27 CEST 2024.