1Graph(3) User Contributed Perl Documentation Graph(3)
2
6 GD::Graph - Graph Plotting Module for Perl 5
7
9 use GD::Graph::moduleName;
10
12 GD::Graph is a perl5 module to create charts using the GD module. The
13 following classes for graphs with axes are defined:
14 "GD::Graph::lines"
16 Create a line chart.
17 "GD::Graph::bars" and "GD::Graph::hbars"
19 Create a bar chart with vertical or horizontal bars.
20 "GD::Graph::points"
22 Create an chart, displaying the data as points.
23 "GD::Graph::linespoints"
25 Combination of lines and points.
26 "GD::Graph::area"
28 Create a graph, representing the data as areas under a line.
29 "GD::Graph::mixed"
31 Create a mixed type graph, any combination of the above. At the
32 moment this is fairly limited. Some of the options that can be used
33 with some of the individual graph types won't work very well. Bar
34 graphs drawn after lines or points graphs may obscure the earlier
35 data, and specifying bar_width will not produce the results you
36 probably expected.
37 Additional types:
39 "GD::Graph::pie"
41 Create a pie chart.
42
44 Distribution has no releases since 2007. It has new maintainer starting
45 of 1.45 and my plan is to keep modules backwards compatible as much as
46 possible, fix bugs with test cases, apply patches and release new
47 versions to the CPAN.
48 I got repository from Martien without Benjamin's work, Benjamin
50 couldn't find his repository, so everything else is imported from CPAN
51 and BackPAN. Now it's all on github <https://github.com/ruz/GDGraph>.
52 May be at some point Benjamin will find his VCS backup and we can
53 restore full history.
54 Release 1.44_01 (development release) was released in 2007 by Benjamin,
56 but never made into production version. This dev version contains very
57 nice changes (truecolor, anti-aliasing and alpha support), but due to
58 nature of how GD and GD::Graph works authors had to add third optional
59 argument (truecolor) to all constructors in GD::Graph modules. I think
60 that this should be and can be adjusted to receive named arguments in
61 constructor and still be backwards compatible. If you were using that
62 dev release and want to fast forward inclusion of this work into
63 production release then contact ruz@cpan.org
64 Martien also has changes in his repository that were never published to
66 CPAN. These are smaller and well isolated, so I can merge them faster.
67 My goal at this moment is to merge existing versions together, get rid
69 of CVS reminders, do some repo cleanup, review existing tickets on
70 rt.cpan.org. Join if you want to help.
71
73 See the samples directory in the distribution, and read the Makefile
74 there.
75
77 Fill an array of arrays with the x values and the values of the data
78 sets. Make sure that every array is the same size, otherwise GD::Graph
79 will complain and refuse to compile the graph.
80 @data = (
82 ["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"],
83 [ 1, 2, 5, 6, 3, 1.5, 1, 3, 4],
84 [ sort { $a <=> $b } (1, 2, 5, 6, 3, 1.5, 1, 3, 4) ]
85 );
86 If you don't have a value for a point in a certain dataset, you can use
88 undef, and the point will be skipped.
89 Create a new GD::Graph object by calling the new method on the graph
91 type you want to create (chart is bars, hbars, lines, points,
92 linespoints, mixed or pie).
93 my $graph = GD::Graph::chart->new(400, 300);
95 Set the graph options.
97 $graph->set(
99 x_label => 'X Label',
100 y_label => 'Y label',
101 title => 'Some simple graph',
102 y_max_value => 8,
103 y_tick_number => 8,
104 y_label_skip => 2
105 ) or die $graph->error;
106 and plot the graph.
108 my $gd = $graph->plot(\@data) or die $graph->error;
110 Then do whatever your current version of GD allows you to do to save
112 the file. For versions of GD older than 1.19 (or more recent than
113 2.15), you'd do something like:
114 open(IMG, '>file.gif') or die $!;
116 binmode IMG;
117 print IMG $gd->gif;
118 close IMG;
119 and for newer versions (1.20 and up) you'd write
121 open(IMG, '>file.png') or die $!;
123 binmode IMG;
124 print IMG $gd->png;
125 or
127 open(IMG, '>file.gd2') or die $!;
129 binmode IMG;
130 print IMG $gd->gd2;
131 Then there's also of course the possibility of using a shorter version
133 (for each of the export functions that GD supports):
134 print IMG $graph->plot(\@data)->gif;
136 print IMG $graph->plot(\@data)->png;
137 print IMG $graph->plot(\@data)->gd;
138 print IMG $graph->plot(\@data)->gd2;
139 If you want to write something that doesn't require your code to 'know'
141 whether to use gif or png, you could do something like:
142 if ($gd->can('png')) { # blabla }
144 or you can use the convenience method "export_format":
146 my $format = $graph->export_format;
148 open(IMG, ">file.$format") or die $!;
149 binmode IMG;
150 print IMG $graph->plot(\@data)->$format();
151 close IMG;
152 or for CGI programs:
154 use CGI qw(:standard);
156 #...
157 my $format = $graph->export_format;
158 print header("image/$format");
159 binmode STDOUT;
160 print $graph->plot(\@data)->$format();
161 (the parentheses after $format are necessary, to help the compiler
163 decide that you mean a method name there)
164 See under "SEE ALSO" for references to other documentation, especially
166 the FAQ.
167
169 Methods for all graphs
170 GD::Graph::chart->new([width,height])
171 Create a new object $graph with optional width and height. Default
172 width = 400, default height = 300. chart is either bars, lines,
173 points, linespoints, area, mixed or pie.
174 $graph->set_text_clr(colour name)
176 Set the colour of the text. This will set the colour of the titles,
177 labels, and axis labels to colour name. Also see the options
178 textclr, labelclr and axislabelclr.
179 $graph->set_title_font(font specification)
181 Set the font that will be used for the title of the chart. See
182 "FONTS".
183 $graph->plot(\@data)
185 Plot the chart, and return the GD::Image object.
186 $graph->set(attrib1 => value1, attrib2 => value2 ...)
188 Set chart options. See OPTIONS section.
189 $graph->get(attrib1, attrib2)
191 Returns a list of the values of the attributes. In scalar context
192 returns the value of the first attribute only.
193 $graph->gd()
195 Get the GD::Image object that is going to be used to draw on. You
196 can do this either before or after calling the plot method, to do
197 your own drawing.
198 Note: as of the current version, this GD::Image object will always
200 be palette-based, even if the installed version of GD supports
201 true-color images.
202 Note also that if you draw on the GD::Image object before calling
204 the plot method, you are responsible for making sure that the
205 background colour is correct and for setting transparency.
206 $graph->export_format()
208 Query the export format of the GD library in use. In scalar
209 context, it returns 'gif', 'png' or undefined, which is sufficient
210 for most people's use. In a list context, it returns a list of all
211 the formats that are supported by the current version of GD. It can
212 be called as a class or object method
213 $graph->can_do_ttf()
215 Returns true if the current GD library supports TrueType fonts,
216 False otherwise. Can also be called as a class method or static
217 method.
218 Methods for Pie charts
220 $graph->set_label_font(font specification)
221 $graph->set_value_font(font specification)
222 Set the font that will be used for the label of the pie or the
223 values on the pie. See "FONTS".
224 Methods for charts with axes.
226 $graph->set_x_label_font(font specification)
227 $graph->set_y_label_font(font specification)
228 $graph->set_x_axis_font(font specification)
229 $graph->set_y_axis_font(font specification)
230 $graph->set_values_font(font specification)
231 Set the font for the x and y axis label, the x and y axis value
232 labels, and for the values printed above the data points. See
233 "FONTS".
234 $graph->get_hotspot($dataset, $point)
236 Experimental: Return a coordinate specification for a point in a
237 dataset. Returns a list. If the point is not specified, returns a
238 list of array references for all points in the dataset. If the
239 dataset is also not specified, returns a list of array references
240 for each data set. See "HOTSPOTS".
241 $graph->get_feature_coordinates($feature_name)
243 Experimental: Return a coordinate specification for a certain
244 feature in the chart. Currently, features that are defined are
245 axes, the coordinates of the rectangle within the axes; x_label,
246 y1_label and y2_label, the labels printed along the axes, with
247 y_label provided as an alias for y1_label; and title which is the
248 title text box. See "HOTSPOTS".
249
251 Options for all graphs
252 width, height
253 The width and height of the canvas in pixels Default: 400 x 300.
254 NB At the moment, these are read-only options. If you want to set
255 the size of a graph, you will have to do that with the new method.
256 t_margin, b_margin, l_margin, r_margin
258 Top, bottom, left and right margin of the canvas. These margins
259 will be left blank. Default: 0 for all.
260 logo
262 Name of a logo file. Generally, this should be the same format as
263 your version of GD exports images in. Currently, this file may be
264 in any format that GD can import, but please see GD if you use an
265 XPM file and get unexpected results.
266 Default: no logo.
268 logo_resize, logo_position
270 Factor to resize the logo by, and the position on the canvas of the
271 logo. Possible values for logo_position are 'LL', 'LR', 'UL', and
272 'UR'. (lower and upper left and right). Default: 'LR'.
273 transparent
275 If set to a true value, the produced image will have the background
276 colour marked as transparent (see also option bgclr). Default: 1.
277 interlaced
279 If set to a true value, the produced image will be interlaced.
280 Default: 1.
281 Note: versions of GD higher than 2.0 (that is, since GIF support
283 was restored after being removed owing to patent issues) do not
284 support interlacing of GIF images. Support for interlaced PNG and
285 progressive JPEG images remains available using this option.
286 Colours
288 bgclr, fgclr, boxclr, accentclr, shadowclr
289 Drawing colours used for the chart: background, foreground (axes
290 and grid), axis box fill colour, accents (bar, area and pie
291 outlines), and shadow (currently only for bars).
292 All colours should have a valid value as described in "COLOURS",
294 except boxclr, which can be undefined, in which case the box will
295 not be filled.
296 shadow_depth
298 Depth of a shadow, positive for right/down shadow, negative for
299 left/up shadow, 0 for no shadow (default). Also see the
300 "shadowclr" and "bar_spacing" options.
301 labelclr, axislabelclr, legendclr, valuesclr, textclr
303 Text Colours used for the chart: label (labels for the axes or
304 pie), axis label (misnomer: values printed along the axes, or on a
305 pie slice), legend text, shown values text, and all other text.
306 All colours should have a valid value as described in "COLOURS".
308 dclrs (short for datacolours)
310 This controls the colours for the bars, lines, markers, or pie
311 slices. This should be a reference to an array of colour names as
312 defined in GD::Graph::colour ("perldoc GD::Graph::colour" for the
313 names available).
314 $graph->set( dclrs => [ qw(green pink blue cyan) ] );
316 The first (fifth, ninth) data set will be green, the next pink,
318 etc.
319 A colour can be "undef", in which case the data set will not be
321 drawn. This can be useful for cumulative bar sets where you want
322 certain data series (often the first one) not to show up, which can
323 be used to emulate error bars (see examples 1-7 and 6-3 in the
324 distribution).
325 Default: [ qw(lred lgreen lblue lyellow lpurple cyan lorange) ]
327 borderclrs
329 This controls the colours of the borders of the bars data sets.
330 Like dclrs, it is a reference to an array of colour names as
331 defined in GD::Graph::colour. Setting a border colour to "undef"
332 means the border will not be drawn.
333 cycle_clrs
335 If set to a true value, bars will not have a colour from "dclrs"
336 per dataset, but per point. The colour sequence will be identical
337 for each dataset. Note that this may have a weird effect if you are
338 drawing more than one data set. If this is set to a value larger
339 than 1 the border colour of the bars will cycle through the colours
340 in "borderclrs".
341 accent_treshold
343 Not really a colour, but it does control a visual aspect: Accents
344 on bars are only drawn when the width of a bar is larger than this
345 number of pixels. Accents inside areas are only drawn when the
346 horizontal distance between points is larger than this number.
347 Default 4
348 Options for graphs with axes.
350 options for bars, lines, points, linespoints, mixed and area charts.
351 x_label, y_label
353 The labels to be printed next to, or just below, the axes. Note
354 that if you use the two_axes option that you need to use y1_label
355 and y2_label.
356 long_ticks, tick_length
358 If long_ticks is a true value, ticks will be drawn the same length
359 as the axes. Otherwise ticks will be drawn with length
360 tick_length. if tick_length is negative, the ticks will be drawn
361 outside the axes. Default: long_ticks = 0, tick_length = 4.
362 These attributes can also be set for x and y axes separately with
364 x_long_ticks, y_long_ticks, x_tick_length and y_tick_length.
365 x_ticks
367 If x_ticks is a true value, ticks will be drawn for the x axis.
368 These ticks are subject to the values of long_ticks and
369 tick_length. Default: 1.
370 y_tick_number
372 Number of ticks to print for the Y axis. Use this, together with
373 y_label_skip to control the look of ticks on the y axis. Default:
374 5.
375 y_number_format
377 This can be either a string, or a reference to a subroutine. If it
378 is a string, it will be taken to be the first argument to a
379 sprintf, with the value as the second argument:
380 $label = sprintf( $s->{y_number_format}, $value );
382 If it is a code reference, it will be executed with the value as
384 the argument:
385 $label = &{$s->{y_number_format}}($value);
387 This can be useful, for example, if you want to reformat your
389 values in currency, with the - sign in the right spot. Something
390 like:
391 sub y_format
393 {
394 my $value = shift;
395 my $ret;
396 if ($value >= 0)
398 {
399 $ret = sprintf("\$%d", $value * $refit);
400 }
401 else
402 {
403 $ret = sprintf("-\$%d", abs($value) * $refit);
404 }
405 return $ret;
407 }
408 $graph->set( 'y_number_format' => \&y_format );
410 (Yes, I know this can be much shorter and more concise)
412 Default: undef.
414 y1_number_format, y2_number_format
416 As with y_number_format, these can be either a string, or a
417 reference to a subroutine. These are used as formats for graphs
418 with two y-axis scales so that independent formats can be used.
419 For compatibility purposes, each of these will fall back on
421 y_number_format if not specified.
422 Default: undef for both.
424 x_label_skip, y_label_skip
426 Print every x_label_skipth number under the tick on the x axis, and
427 every y_label_skipth number next to the tick on the y axis.
428 Default: 1 for both.
429 x_last_label_skip
431 By default, when x_label_skip is set to something higher than 1,
432 the last label on the axis will be printed, even when it doesn't
433 belong to the normal series that should be printed. Setting this to
434 a true value prevents that.
435 For example, when your X values are the months of the year (i.e.
437 Jan - Dec), and you set x_label_skip to 3, the months printed on
438 the axis will be Jan, Apr, Jul, Oct and Dec; even though Dec does
439 not really belong to that sequence. If you do not like the last
440 month to be printed, set x_last_label_skip to a true value.
441 This option has no effect in other circumstances. Also see
443 x_tick_offset for another method to make this look better.
444 Default: 0 for both
445 x_tick_offset
447 When x_label_skip is used, this will skip the first x_tick_offset
448 values in the labels before starting to print. Let me give an
449 example. If you have a series of X labels like
450 qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
452 and you set x_label_skip to 3, you will see ticks on the X axis for
454 Jan, Apr, Jul, Oct and Dec. This is not always what is wanted. If
455 you set x_tick_offset to 1, you get Feb, May, Aug, Nov and Dec, and
456 if you set it to 2, you get Mar, Jun Sep and Dec, and this last one
457 definitely looks better. A combination of 6 and 5 also works nice
458 for months.
459 Note that the value for x_tick_offset is periodical. This means
461 that it will have the same effect for each integer n in
462 x_tick_offset + n * x_label_skip.
463 Also see x_last_label_skip for another method to influence this.
465 x_all_ticks
467 Force a print of all the x ticks, even if x_label_skip is set to a
468 value Default: 0.
469 x_label_position
471 Controls the position of the X axis label (title). The value for
472 this should be between 0 and 1, where 0 means aligned to the left,
473 1 means aligned to the right, and 1/2 means centered. Default: 3/4
474 y_label_position
476 Controls the position of both Y axis labels (titles). The value for
477 this should be between 0 and 1, where 0 means aligned to the
478 bottom, 1 means aligned to the top, and 1/2 means centered.
479 Default: 1/2
480 x_labels_vertical
482 If set to a true value, the X axis labels will be printed
483 vertically. This can be handy in case these labels get very long.
484 Default: 0.
485 x_plot_values, y_plot_values
487 If set to a true value, the values of the ticks on the x or y axes
488 will be plotted next to the tick. Also see x_label_skip,
489 y_label_skip. Default: 1 for both.
490 box_axis
492 Draw the axes as a box, if true. Default: 1.
493 no_axes
495 Draw no axes at all. If this is set to undef, all axes are drawn.
496 If it is set to 0, the zero axis will be drawn, for bar charts
497 only. If this is set to a true value, no axes will be drawn at
498 all. Value labels on the axes and ticks will also not be drawn, but
499 axis lables are drawn. Default: undef.
500 two_axes
502 Use two separate axes for the first and second data set. The first
503 data set will be set against the left axis, the second against the
504 right axis. If more than two data sets are being plotted, the
505 use_axis option should be used to specify which data sets use which
506 axis.
507 Note that if you use this option, that you need to use y1_label and
509 y2_label, instead of just y_label, if you want the two axes to have
510 different labels. The same goes for some other options starting
511 with the letter 'y' and an underscore.
512 Default: 0.
514 use_axis
516 If two y-axes are in use and more than two datasets are specified,
517 set this option to an array reference containing a value of 1 or 2
518 (for the left and right scales respectively) for each dataset being
519 plotted. That is, to plot three datasets with the second on a
520 different scale than the first and third, set this to "[1,2,1]".
521 Default: [1,2].
523 zero_axis
525 If set to a true value, the axis for y values of 0 will always be
526 drawn. This might be useful in case your graph contains negative
527 values, but you want it to be clear where the zero value is. (see
528 also zero_axis_only and box_axes). Default: 0.
529 zero_axis_only
531 If set to a true value, the zero axis will be drawn (see
532 zero_axis), and no axis at the bottom of the graph will be drawn.
533 The labels for X values will be placed on the zero axis. Default:
534 0.
535 y_max_value, y_min_value
537 Maximum and minimum value displayed on the y axis.
538 The range (y_min_value..y_max_value) has to include all the values
540 of the data points, or GD::Graph will die with a message.
541 For bar and area graphs, the range (y_min_value..y_max_value) has
543 to include 0. If it doesn't, the values will be adapted before
544 attempting to draw the graph.
545 Default: Computed from data sets.
547 y1_max_value, y1_min_value, y2_max_value, y2_min_value
549 Maximum and minimum values for left (y1) and right (y2) axes when
550 two_axes is a true value. Take precedence over y_min_value and
551 y_max_value.
552 By default 0 of the left axis is aligned with 0 of the right axis,
554 it's not true if any of these options is defined.
555 Otherwise behaviour and default values are as with y_max_value and
557 y_min_value.
558 y_min_range, y1_min_range, y2_min_range
560 Minimal range between min and max values on y axis that is used to
561 adjust computed y_min_value and y_max_value.
562 NOTE that author of the feature implemented this for two_axes case
564 only, patches are wellcome to expand over one y axis.
565 If two_axes is a true value, then y1_min_range and y2_min_range
567 take precedence over y_min_range value.
568 Default: undef
570 axis_space
572 This space will be left blank between the axes and the tick value
573 text. Default: 4.
574 text_space
576 This space will be left open between text elements and the graph
577 (text elements are title and axis labels.
578 Default: 8.
580 cumulate
582 If this attribute is set to a true value, the data sets will be
583 cumulated. This means that they will be stacked on top of each
584 other. A side effect of this is that "overwrite" will be set to a
585 true value.
586 Notes: This only works for bar and area charts at the moment.
588 If you have negative values in your data sets, setting this option
590 might produce odd results. Of course, the graph itself would be
591 quite meaningless.
592 overwrite
594 If set to 0, bars of different data sets will be drawn next to each
595 other. If set to 1, they will be drawn in front of each other.
596 Default: 0.
597 Note: Setting overwrite to 2 to produce cumulative sets is
599 deprecated, and may disappear in future versions of GD::Graph.
600 Instead see the "cumulate" attribute.
601 correct_width
603 If this is set to a true value and "x_tick_number" is false, then
604 the width of the graph (or the height for rotated graphs like
605 "GD::Graph::hbar") will be recalculated to make sure that each data
606 point is exactly an integer number of pixels wide. You probably
607 never want to fiddle with this.
608 When this value is true, you will need to make sure that the number
610 of data points is smaller than the number of pixels in the plotting
611 area of the chart. If you get errors saying that your horizontal
612 size if too small, you may need to manually switch this off, or
613 consider using something else than a bar type for your chart.
614 Default: 1 for bar, calculated at runtime for mixed charts, 0 for
616 others.
617 Plotting data point values with the data point
619 Sometimes you will want to plot the value of a data point or bar above
620 the data point for clarity. GD::Graph allows you to control this in a
621 generic manner, or even down to the single point.
622 show_values
624 Set this to 1 to display the value of each data point above the
625 point or bar itself. No effort is being made to ensure that there
626 is enough space for the text.
627 Set this to a GD::Graph::Data object, or an array reference of the
629 same shape, with the same dimensions as your data object that you
630 pass in to the plot method. The reason for this option is that it
631 allows you to make a copy of your data set, and selectively set
632 points to "undef" to disable plotting of them.
633 my $data = GD::Graph::Data->new(
635 [ [ 'A', 'B', 'C' ], [ 1, 2, 3 ], [ 11, 12, 13 ] ]);
636 my $values = $data->copy;
637 $values->set_y(1, 1, undef);
638 $values->set_y(2, 0, undef);
639 $graph->set(show_values => $values);
641 $graph->plot($data);
642 Default: 0.
644 values_vertical
646 If set to a true value, the values will be printed vertically,
647 instead of horizontally. This can be handy if the values are long
648 numbers. Default: 0.
649 values_space
651 Space to insert between the data point and the value to print.
652 Default: 4.
653 values_format
655 How to format the values for display. See y_number_format for more
656 information. Default: undef.
657 hide_overlapping_values
659 If set to a true value, the values that goes out of graph space are
660 hidden. Option is EXPERIMENTAL, works only for bars, text still
661 can overlap with other bars and labels, most useful only with text
662 in the same direction as bars. Default: undef
663 Options for graphs with a numerical X axis
665 First of all: GD::Graph does not support numerical x axis the way it
666 should. Data for X axes should be equally spaced. That understood:
667 There is some support to make the printing of graphs with numerical X
668 axis values a bit better, thanks to Scott Prahl. If the option
669 "x_tick_number" is set to a defined value, GD::Graph will attempt to
670 treat the X data as numerical.
671 Extra options are:
673 x_tick_number
675 If set to 'auto', GD::Graph will attempt to format the X axis in a
676 nice way, based on the actual X values. If set to a number, that's
677 the number of ticks you will get. If set to undef, GD::Graph will
678 treat X data as labels. Default: undef.
679 x_min_value, x_max_value
681 The minimum and maximum value to use for the X axis. Default:
682 computed.
683 x_min_range
685 Minimal range of x axis.
686 Default: undef
688 x_number_format
690 See y_number_format
691 x_label_skip
693 See y_label_skip
694 Options for graphs with bars
696 bar_width
697 The width of a bar in pixels. Also see "bar_spacing". Use
698 "bar_width" If you want to have fixed-width bars, no matter how
699 wide the chart gets. Default: as wide as possible, within the
700 constraints of the chart size and "bar_spacing" setting.
701 bar_spacing
703 Number of pixels to leave open between bars. This works well in
704 most cases, but on some platforms, a value of 1 will be rounded off
705 to 0. Use "bar_spacing" to get a fixed amount of space between
706 bars, with variable bar widths, depending on the width of the
707 chart. Note that if "bar_width" is also set, this setting will be
708 ignored, and automatically calculated. Default: 0
709 bargroup_spacing
711 Number of pixels (in addition to whatever is specified in
712 "bar_spacing") to leave between groups of bars when multiple
713 datasets are being displayed. Unlike "bar_spacing", however, this
714 parameter will hold its value if "bar_width" is set.
715 Options for graphs with lines
717 line_types
718 Which line types to use for lines and linespoints graphs. This
719 should be a reference to an array of numbers:
720 $graph->set( line_types => [3, 2, 4] );
722 Available line types are 1: solid, 2: dashed, 3: dotted, 4: dot-
724 dashed.
725 Default: [1] (always use solid)
727 line_type_scale
729 Controls the length of the dashes in the line types. default: 6.
730 line_width
732 The width of the line used in lines and linespoints graphs, in
733 pixels. Default: 1.
734 skip_undef
736 For all other axes graph types, the default behaviour is (by their
737 nature) to not draw a point when the Y value is "undef". For line
738 charts the point gets skipped as well, but the line is drawn
739 between the points n-1 to n+1 directly. If "skip_undef" has a true
740 value, there will be a gap in the chart where a Y value is
741 undefined.
742 Note that a line will not be drawn unless there are at least two
744 consecutive data points exist that have a defined value. The
745 following data set will only plot a very short line towards the end
746 if "skip_undef" is set:
747 @data = (
749 [ qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct ) ],
750 [ 1, undef, 2, undef, 3, undef, 4, undef, 5, 6 ]
751 );
752 This option is useful when you have a consecutive gap in your data,
754 or with linespoints charts. If you have data where you have
755 intermittent gaps, be careful when you use this. Default value: 0
756 Options for graphs with points
758 markers
759 This controls the order of markers in points and linespoints
760 graphs. This should be a reference to an array of numbers:
761 $graph->set( markers => [3, 5, 6] );
763 Available markers are: 1: filled square, 2: open square, 3:
765 horizontal cross, 4: diagonal cross, 5: filled diamond, 6: open
766 diamond, 7: filled circle, 8: open circle, 9: horizontal line, 10:
767 vertical line. Note that the last two are not part of the default
768 list.
769 Default: [1,2,3,4,5,6,7,8]
771 marker_size
773 The size of the markers used in points and linespoints graphs, in
774 pixels. Default: 4.
775 Options for mixed graphs
777 types
778 A reference to an array with graph types, in the same order as the
779 data sets. Possible values are:
780 $graph->set( types => [qw(lines bars points area linespoints)] );
782 $graph->set( types => ['lines', undef, undef, 'bars'] );
783 values that are undefined or unknown will be set to "default_type".
785 Default: all set to "default_type"
787 default_type
789 The type of graph to draw for data sets that either have no type
790 set, or that have an unknown type set.
791 Default: lines
793 Graph legends (axestype graphs only)
795 At the moment legend support is minimal.
796 Methods
798 $graph->set_legend(@legend_keys);
800 Sets the keys for the legend. The elements of @legend_keys
801 correspond to the data sets as provided to plot().
802 If a key is undef or an empty string, the legend entry will be
804 skipped.
805 $graph->set_legend_font(font name);
807 Sets the font for the legend text (see "FONTS"). Default:
808 GD::gdTinyFont.
809 Options
811 legend_placement
813 Where to put the legend. This should be a two letter key of the
814 form: 'B[LCR]|R[TCB]'. The first letter indicates the placement
815 (Bottom or Right), and the second letter the alignment (Left,
816 Right, Center, Top, or Bottom). Default: 'BC'
817 If the legend is placed at the bottom, some calculations will be
819 made to ensure that there is some 'intelligent' wrapping going on.
820 if the legend is placed at the right, all entries will be placed
821 below each other.
822 legend_spacing
824 The number of pixels to place around a legend item, and between a
825 legend 'marker' and the text. Default: 4
826 legend_marker_width, legend_marker_height
828 The width and height of a legend 'marker' in pixels. Defaults: 12,
829 8
830 lg_cols
832 If you, for some reason, need to force the legend at the bottom to
833 have a specific number of columns, you can use this. Default:
834 computed
835 Options for pie graphs
837 3d If set to a true value, the pie chart will be drawn with a 3d look.
838 Default: 1.
839 pie_height
841 The thickness of the pie when 3d is true. Default: 0.1 x height.
842 start_angle
844 The angle at which the first data slice will be displayed, with 0
845 degrees being "6 o'clock". Default: 0.
846 suppress_angle
848 If a pie slice is smaller than this angle (in degrees), a label
849 will not be drawn on it. Default: 0.
850 label
852 Print this label below the pie. Default: undef.
853
855 All references to colours in the options for this module have been
856 shortened to clr. The main reason for this was that I didn't want to
857 support two spellings for the same word ('colour' and 'color')
858 Wherever a colour is required, a colour name should be used from the
860 package GD::Graph::colour. "perldoc GD::Graph::colour" should give you
861 the documentation for that module, containing all valid colour names. I
862 will probably change this to read the systems rgb.txt file if it is
863 available.
864
866 Depending on your version of GD, this accepts both GD builtin fonts or
867 the name of a TrueType font file. In the case of a TrueType font, you
868 must specify the font size. See GD::Text for more details and other
869 things, since all font handling in GD::Graph is delegated to there.
870 Examples:
872 $graph->set_title_font('/fonts/arial.ttf', 18);
874 $graph->set_legend_font(gdTinyFont);
875 $graph->set_legend_font(
876 ['verdana', 'arial', gdMediumBoldFont], 12)
877 (The above discussion is based on GD::Text 0.65. Older versions have
879 more restrictive behaviour).
880
882 Note that this is an experimental feature, and its interface may, and
883 likely will, change in the future. It currently does not work for area
884 charts or pie charts.
885 A known problem with hotspots for GD::Graph::hbars is that the x and y
887 coordinate come out transposed. This probably won't be fixed until the
888 redesign of this section
889 GD::Graph keeps an internal set of coordinates for each data point and
891 for certain features of a chart, like the title and axis labels. This
892 specification is very similar to the HTML image map specification, and
893 in fact exists mainly for that purpose. You can get at these hotspots
894 with the "get_hotspot" method for data point, and
895 "get_feature_coordinates" for the chart features.
896 The <get_hotspot> method accepts two optional arguments, the number of
898 the dataset you're interested in, and the number of the point in that
899 dataset you're interested in. When called with two arguments, the
900 method returns a list of one of the following forms:
901 'rect', x1, y1, x2, y2
903 'poly', x1, y1, x2, y2, x3, y3, ....
904 'line', xs, ys, xe, ye, width
905 The parameters for "rect" are the coordinates of the corners of the
907 rectangle, the parameters for "poly" are the coordinates of the
908 vertices of the polygon, and the parameters for the "line" are the
909 coordinates for the start and end point, and the line width. It should
910 be possible to almost directly translate these lists into HTML image
911 map specifications.
912 If the second argument to "get_hotspot" is omitted, a list of
914 references to arrays will be returned. This list represents all the
915 points in the dataset specified, and each array referred to is of the
916 form outlined above.
917 ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
919 if both arguments to "get_hotspot" are omitted, the list that comes
921 back will contain references to arrays for each data set, which in turn
922 contain references to arrays for each point.
923 [
925 ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
926 ],
927 [
928 ['line', xs, ys, xe, ye, w], ['line', xs, ys, xe, ye, w], ...
929 ],...
930 The "get_feature" method, when called with the name of a feature,
932 returns a single array reference with a type and coordinates as
933 described above. When called with no arguments, a hash reference is
934 returned with the keys being all the currently defined and set
935 features, and the values array references with the type and coordinates
936 for each of those features.
937
939 GD::Graph objects inherit from the GD::Graph::Error class (not the
940 other way around), so they behave in the same manner. The main feature
941 of that behaviour is that you have the error() method available to get
942 some information about what went wrong. The GD::Graph methods all
943 return undef if something went wrong, so you should be able to write
944 safe programs like this:
945 my $graph = GD::Graph->new() or die GD::Graph->error;
947 $graph->set( %attributes ) or die $graph->error;
948 $graph->plot($gdg_data) or die $graph->error;
949 More advanced usage is possible, and there are some caveats with this
951 error handling, which are all explained in GD::Graph::Error.
952 Unfortunately, it is almost impossible to gracefully recover from an
954 error in GD::Graph, so you really should get rid of the object, and
955 recreate it from scratch if you want to recover. For example, to adjust
956 the correct_width attribute if you get the error "Horizontal size too
957 small" or "Vertical size too small" (in the case of hbar), you could do
958 something like:
959 sub plot_graph
961 {
962 my $data = shift;
963 my %attribs = @_;
964 my $graph = GD::Graph::bars->new()
965 or die GD::Graph->error;
966 $graph->set(%attribs) or die $graph->error;
967 $graph->plot($data) or die $graph->error;
968 }
969 my $gd;
971 eval { $gd = plot_graph(\@data, %attribs) };
972 if ($@)
973 {
974 die $@ unless $@ =~ /size too small/;
975 $gd = plot_graph(\@data, %attribs, correct_width => 0);
976 }
977 Of course, you could also adjust the width this way, and you can check
979 for other errors.
980
982 As with all Modules for Perl: Please stick to using the interface. If
983 you try to fiddle too much with knowledge of the internals of this
984 module, you could get burned. I may change them at any time.
985
987 GD::Graph objects cannot be reused. To create a new plot, you have to
988 create a new GD::Graph object.
989 Rotated charts (ones with the X axis on the left) can currently only be
991 created for bars. With a little work, this will work for all others as
992 well. Please, be patient :)
993 Other outstanding bugs can (alas) probably be found in the RT queue for
995 this distribution, at
996 http://rt.cpan.org/Public/Dist/Display.html?Name=GDGraph
997 If you think you have found a bug, please check first to see if it has
999 already been reported. If it has not, please do (you can use the web
1000 interface above or send e-mail to <bug-GDGraph@rt.cpan.org>). Bug
1001 reports should contain as many as possible of the following:
1002 • a concise description of the buggy behavior and how it differs from
1004 what you expected,
1005 • the versions of Perl, GD::Graph and GD that you are using,
1007 • a short demonstration script that shows the bug in action,
1009 • a patch that fixes it. :-)
1011 Of all of these, the third is probably the single most important, since
1013 producing a test case generally makes the explanation much more concise
1014 and understandable, as well as making it much simpler to show that the
1015 bug has been fixed. As an incidental benefit, if the bug is in fact
1016 caused by some code outside of GD::Graph, it will become apparent while
1017 you are writing the test case, thereby saving time and confusion for
1018 all concerned.
1019
1021 Martien Verbruggen <mgjv@tradingpost.com.au>
1022 Current maintenance (including this release) by Benjamin Warfield
1024 <bwarfield@cpan.org>
1025 Copyright
1027 GIFgraph: Copyright (c) 1995-1999 Martien Verbruggen.
1028 Chart::PNGgraph: Copyright (c) 1999 Steve Bonds.
1029 GD::Graph: Copyright (c) 1999 Martien Verbruggen.
1030 All rights reserved. This package is free software; you can
1032 redistribute it and/or modify it under the same terms as Perl itself.
1033 Acknowledgements
1035 Thanks to Steve Bonds for releasing Chart::PNGgraph, and keeping the
1036 code alive when GD reached version 1.20, and I didn't have time to do
1037 something about it.
1038 Thanks to the following people for contributing code, or sending me
1040 fixes: Dave Belcher, Steve Bonds, Mike Bremford, Damon Brodie, Gary
1041 Deschaines, brian d foy, Edwin Hildebrand, Ari Jolma, Tim Meadowcroft,
1042 Honza Pazdziora, Scott Prahl, Ben Tilly, Vegard Vesterheim, Jeremy
1043 Wadsack.
1044 And some people whose real name I don't know, and whose email address
1046 I'd rather not publicise without their consent.
1047
1049 GD::Graph::FAQ, GD::Graph::Data, GD::Graph::Error, GD::Graph::colour
1050perl v5.34.0 2022-02-01 Graph(3)