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