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.
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 heigth.
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 drawm 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_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 nteger n in x_tick_offset + n *
x_label_skip.
- 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 drawns 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 exis. Default: 0.
- y_max_value, y_min_value
- Maximum and minimum value displayed on the y axis. If
two_axes is a true value, then y1_min_value, y1_max_value (for the left
axis), and y2_min_value, y2_max_value (for the right axis) take precedence
over these.
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.
- 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.
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_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.
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