1Graph(3) User Contributed Perl Documentation Graph(3)
2
3
4
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
15 "GD::Graph::lines"
16 Create a line chart.
17
18 "GD::Graph::bars" and "GD::Graph::hbars"
19 Create a bar chart with vertical or horizontal bars.
20
21 "GD::Graph::points"
22 Create an chart, displaying the data as points.
23
24 "GD::Graph::linespoints"
25 Combination of lines and points.
26
27 "GD::Graph::area"
28 Create a graph, representing the data as areas under a line.
29
30 "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
38 Additional types:
39
40 "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
49 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
55 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
65 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
68 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
81 @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
87 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
90 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
94 my $graph = GD::Graph::chart->new(400, 300);
95
96 Set the graph options.
97
98 $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
107 and plot the graph.
108
109 my $gd = $graph->plot(\@data) or die $graph->error;
110
111 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
115 open(IMG, '>file.gif') or die $!;
116 binmode IMG;
117 print IMG $gd->gif;
118 close IMG;
119
120 and for newer versions (1.20 and up) you'd write
121
122 open(IMG, '>file.png') or die $!;
123 binmode IMG;
124 print IMG $gd->png;
125
126 or
127
128 open(IMG, '>file.gd2') or die $!;
129 binmode IMG;
130 print IMG $gd->gd2;
131
132 Then there's also of course the possibility of using a shorter version
133 (for each of the export functions that GD supports):
134
135 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
140 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
143 if ($gd->can('png')) { # blabla }
144
145 or you can use the convenience method "export_format":
146
147 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
153 or for CGI programs:
154
155 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
162 (the parentheses after $format are necessary, to help the compiler
163 decide that you mean a method name there)
164
165 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
175 $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
180 $graph->set_title_font(font specification)
181 Set the font that will be used for the title of the chart. See
182 "FONTS".
183
184 $graph->plot(\@data)
185 Plot the chart, and return the GD::Image object.
186
187 $graph->set(attrib1 => value1, attrib2 => value2 ...)
188 Set chart options. See OPTIONS section.
189
190 $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
194 $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
199 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
203 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
207 $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
214 $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
219 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
225 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
235 $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
242 $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
257 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
261 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
267 Default: no logo.
268
269 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
274 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
278 interlaced
279 If set to a true value, the produced image will be interlaced.
280 Default: 1.
281
282 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
287 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
293 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
297 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
302 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
307 All colours should have a valid value as described in "COLOURS".
308
309 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
315 $graph->set( dclrs => [ qw(green pink blue cyan) ] );
316
317 The first (fifth, ninth) data set will be green, the next pink,
318 etc.
319
320 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
326 Default: [ qw(lred lgreen lblue lyellow lpurple cyan lorange) ]
327
328 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
334 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
342 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
349 Options for graphs with axes.
350 options for bars, lines, points, linespoints, mixed and area charts.
351
352 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
357 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
363 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
366 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
371 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
376 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
381 $label = sprintf( $s->{y_number_format}, $value );
382
383 If it is a code reference, it will be executed with the value as
384 the argument:
385
386 $label = &{$s->{y_number_format}}($value);
387
388 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
392 sub y_format
393 {
394 my $value = shift;
395 my $ret;
396
397 if ($value >= 0)
398 {
399 $ret = sprintf("\$%d", $value * $refit);
400 }
401 else
402 {
403 $ret = sprintf("-\$%d", abs($value) * $refit);
404 }
405
406 return $ret;
407 }
408
409 $graph->set( 'y_number_format' => \&y_format );
410
411 (Yes, I know this can be much shorter and more concise)
412
413 Default: undef.
414
415 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
420 For compatibility purposes, each of these will fall back on
421 y_number_format if not specified.
422
423 Default: undef for both.
424
425 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
430 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
436 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
442 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
446 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
451 qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
452
453 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
460 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
464 Also see x_last_label_skip for another method to influence this.
465
466 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
470 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
475 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
481 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
486 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
491 box_axis
492 Draw the axes as a box, if true. Default: 1.
493
494 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
501 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
508 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
513 Default: 0.
514
515 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
522 Default: [1,2].
523
524 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
530 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
536 y_max_value, y_min_value
537 Maximum and minimum value displayed on the y axis.
538
539 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
542 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
546 Default: Computed from data sets.
547
548 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
553 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
556 Otherwise behaviour and default values are as with y_max_value and
557 y_min_value.
558
559 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
563 NOTE that author of the feature implemented this for two_axes case
564 only, patches are wellcome to expand over one y axis.
565
566 If two_axes is a true value, then y1_min_range and y2_min_range
567 take precedence over y_min_range value.
568
569 Default: undef
570
571 axis_space
572 This space will be left blank between the axes and the tick value
573 text. Default: 4.
574
575 text_space
576 This space will be left open between text elements and the graph
577 (text elements are title and axis labels.
578
579 Default: 8.
580
581 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
587 Notes: This only works for bar and area charts at the moment.
588
589 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
593 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
598 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
602 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
609 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
615 Default: 1 for bar, calculated at runtime for mixed charts, 0 for
616 others.
617
618 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
623 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
628 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
634 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
640 $graph->set(show_values => $values);
641 $graph->plot($data);
642
643 Default: 0.
644
645 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
650 values_space
651 Space to insert between the data point and the value to print.
652 Default: 4.
653
654 values_format
655 How to format the values for display. See y_number_format for more
656 information. Default: undef.
657
658 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
664 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
672 Extra options are:
673
674 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
680 x_min_value, x_max_value
681 The minimum and maximum value to use for the X axis. Default:
682 computed.
683
684 x_min_range
685 Minimal range of x axis.
686
687 Default: undef
688
689 x_number_format
690 See y_number_format
691
692 x_label_skip
693 See y_label_skip
694
695 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
702 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
710 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
716 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
721 $graph->set( line_types => [3, 2, 4] );
722
723 Available line types are 1: solid, 2: dashed, 3: dotted, 4: dot-
724 dashed.
725
726 Default: [1] (always use solid)
727
728 line_type_scale
729 Controls the length of the dashes in the line types. default: 6.
730
731 line_width
732 The width of the line used in lines and linespoints graphs, in
733 pixels. Default: 1.
734
735 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
743 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
748 @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
753 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
757 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
762 $graph->set( markers => [3, 5, 6] );
763
764 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
770 Default: [1,2,3,4,5,6,7,8]
771
772 marker_size
773 The size of the markers used in points and linespoints graphs, in
774 pixels. Default: 4.
775
776 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
781 $graph->set( types => [qw(lines bars points area linespoints)] );
782 $graph->set( types => ['lines', undef, undef, 'bars'] );
783
784 values that are undefined or unknown will be set to "default_type".
785
786 Default: all set to "default_type"
787
788 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
792 Default: lines
793
794 Graph legends (axestype graphs only)
795 At the moment legend support is minimal.
796
797 Methods
798
799 $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
803 If a key is undef or an empty string, the legend entry will be
804 skipped.
805
806 $graph->set_legend_font(font name);
807 Sets the font for the legend text (see "FONTS"). Default:
808 GD::gdTinyFont.
809
810 Options
811
812 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
818 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
823 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
827 legend_marker_width, legend_marker_height
828 The width and height of a legend 'marker' in pixels. Defaults: 12,
829 8
830
831 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
836 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
840 pie_height
841 The thickness of the pie when 3d is true. Default: 0.1 x height.
842
843 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
847 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
851 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
859 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
871 Examples:
872
873 $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
878 (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
886 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
890 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
897 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
902 'rect', x1, y1, x2, y2
903 'poly', x1, y1, x2, y2, x3, y3, ....
904 'line', xs, ys, xe, ye, width
905
906 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
913 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
918 ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
919
920 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
924 [
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
931 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
946 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
950 More advanced usage is possible, and there are some caveats with this
951 error handling, which are all explained in GD::Graph::Error.
952
953 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
960 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
970 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
978 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
990 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
994 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
998 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
1003 · a concise description of the buggy behavior and how it differs from
1004 what you expected,
1005
1006 · the versions of Perl, GD::Graph and GD that you are using,
1007
1008 · a short demonstration script that shows the bug in action,
1009
1010 · a patch that fixes it. :-)
1011
1012 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
1023 Current maintenance (including this release) by Benjamin Warfield
1024 <bwarfield@cpan.org>
1025
1026 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
1031 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
1034 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
1039 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
1045 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
1050
1051
1052
1053perl v5.30.1 2020-01-30 Graph(3)