1Chart(3) User Contributed Perl Documentation Chart(3)
2
6 Chart - a series of charting modules
7
9 use Chart::type; (type is one of: Points, Lines, Bars, LinesPoints, Composite,
10 StackedBars, Mountain, Pie, HorizontalBars, Split, ErrorBars, Pareto, Direction)
11 $obj = Chart::type->new;
13 $obj = Chart::type->new ( $png_width, $png_height );
14 $obj->set ( $key_1, $val_1, ... ,$key_n, $val_n );
16 $obj->set ( $key_1 => $val_1,
17 ...
18 $key_n => $val_n );
19 $obj->set ( %hash );
20 # GIFgraph.pm-style API to produce png formatted charts
22 @data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
23 $obj->png ( "filename", \@data );
24 $obj->png ( $filehandle, \@data );
25 $obj->png ( FILEHANDLE, \@data );
26 $obj->cgi_png ( \@data );
27 # Graph.pm-style API
29 $obj->add_pt ($label, $val_1, ... , $val_n);
30 $obj->add_dataset ($val_1, ... , $val_n);
31 $obj->png ( "filename" );
32 $obj->png ( $filehandle );
33 $obj->png ( FILEHANDLE );
34 $obj->cgi_png ();
35 The similar functions are available for j-peg
37 # Retrieve image map information
39 $obj->set ( 'imagemap' => 'true' );
40 $imagemap_ref = $obj->imagemap_dump ();
41
43 Chart helps you to create PNG and JPG images with visualizations of
44 numeric data. This page gives you a summary how to use it. For a more
45 thorough documentation and lots of example code please visit the
46 Chart::Manual.
47 use-ing Chart
49 Okay, so you caught me. There's really no Chart::type module. All of
50 the different chart types (Points, Lines, Bars, LinesPoints, Composite,
51 StackedBars, Pie, Pareto, HorizontalBars, Split, ErrorBars, Direction
52 and Mountain so far) are classes by themselves, each inheriting a bunch
53 of methods from the Chart::Base class. Simply replace the word type
54 with the type of chart you want and you're on your way. For example,
55 use Chart::Lines;
57 would invoke the lines module. Alternatively load all chart types at
59 ones and write:
60 use Chart;
62 Getting an object
64 The new method can either be called without arguments, in which case it
65 returns an object with the default image size (400x300 pixels), or you
66 can specify the width and height of the image. Just remember to
67 replace type with the type of graph you want. For example,
68 $obj = Chart::Bars->new (600,400);
70 would return a Chart::Bars object containing a 600x400 pixel image.
72 New also initializes most of the default variables, which you can
73 subsequently change with the set method.
74 Setting different options
76 This is where the fun begins. Set looks for a hash of keys and values.
77 You can pass it a hash that you've already constructed, like
78 %hash = ( property_name => 'new value' );
80 $obj->set (%hash);
81 or you can try just constructing the hash inside the set call, like
83 $obj->set ( property_name => 'new value' );
85 Chart::Manual::Properties lists all currently supported keys and
87 values.
88 GIFgraph.pm-style API
90 Sending the image to a file
91 Invoking the png method causes the graph to be plotted and saved to
92 a file. It takes the name of the output file and a reference to
93 the data as arguments. For example,
94 $obj->png ("foo.png", \@data);
96 would plot the data in @data, and the save the image to foo.png.
98 Of course, this then beggars the question "What should @data look
99 like?". Well, just like GIFgraph, @data should contain references
100 to arrays of data, with the first array reference pointing to an
101 array of x-tick labels. For example,
102 @data = ( [ 'foo', 'bar', 'junk' ],
104 [ 30.2, 23.5, 92.1 ] );
105 would set up a graph with one dataset, and three data points in
107 that set. In general, the @data array should look something like
108 @data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
110 And no worries, I make my own internal copy of the data, so that it
112 doesn't mess with yours.
113 CGI and Chart
115 Okay, so you're probably thinking, "Do I always have to save these
116 images to disk? What if I want to use Chart to create dynamic
117 images for my web site?" Well, here's the answer to that.
118 $obj->cgi_png ( \@data );
120 The cgi_png method will print the chart, along with the appropriate
122 http header, to stdout, allowing you to call chart-generating
123 scripts directly from your html pages (ie. with a <lt>img
124 src=image.pl<gt> HTML tag). The @data array should be set up the
125 same way as for the normal png method.
126 column based API
128 You might ask, "But what if I just want to add a few points to the
129 graph, and then display it, without all those references to
130 references?". Well, friend, the solution is simple. Borrowing the
131 add_pt idea from Matt Kruse's Graph module, you simply make a few calls
132 to the add_pt method, like so:
133 $obj->add_pt ('foo', 30, 25);
135 $obj->add_pt ('bar', 16, 32);
136 Or, if you want to be able to add entire datasets, simply use the
138 add_dataset method:
139 $obj->add_dataset ('foo', 'bar');
141 $obj->add_dataset (30, 16);
142 $obj->add_dataset (25, 32);
143 These methods check to make sure that the points and datasets you are
145 adding are the same size as the ones already there. So, if you have
146 two datasets currently stored, and try to add a data point with three
147 different values, it will carp (per the Carp module) an error message.
148 Similarly, if you try to add a dataset with 4 data points, and all the
149 other datasets have 3 data points, it will carp an error message.
150 Don't forget, when using this API, that I treat the first dataset as a
152 series of x-tick labels. So, in the above examples, the graph would
153 have two x-ticks, labeled 'foo' and 'bar', each with two data points.
154 Pie and ErrorBars handle it different, look at the documentation to see
155 how it works.
156 Adding a datafile
158 You can also add a complete datafile to a chart object. Just use
159 the add_datafile() method.
160 $obj->add_datafile('file', 'set' or 'pt');
162 file can be the name of the data file or a filehandle. 'set' or
164 'pt is the type of the datafile. If the parameter is 'set' then
165 each line in the data file has to be a complete data set. The value
166 of the set has to be separated by white spaces. For example the
167 file looks like this:
168 'foo' 'bar'
170 30 16
171 25 32
172 If the parameter is 'pt', one line has to include all values of one
174 data point separated by white spaces. For example:
175 'foo' 30 25
177 'bar' 16 32
178 Clearing the data
180 A simple call to the clear_data method empties any values that may
181 have been entered.
182 $obj->clear_data ();
184 Getting a copy of the data
186 If you want a copy of the data that has been added so far, make a
187 call to the get_data method like so:
188 $dataref = $obj->get_data;
190 It returns (you guessed it!) a reference to an array of references
192 to datasets. So the x-tick labels would be stored as
193 @x_labels = @{$dataref->[0]};
195 Sending the image to a file
197 If you just want to print this chart to a file, all you have to do
198 is pass the name of the file to the png() method.
199 $obj->png ("foo.png");
201 Sending the image to a filehandle
203 If you want to do something else with the image, you can also pass
204 a filehandle (either a typeglob or a FileHandle object) to png, and
205 it will print directly to that.
206 $obj->png ($filehandle);
208 $obj->png (FILEHANDLE);
209 CGI and Chart
211 Okay, so you're probably thinking (again), "Do I always have to
212 save these images to disk? What if I want to use Chart to create
213 dynamic images for my web site?" Well, here's the answer to that.
214 $obj->cgi_png ();
216 The cgi_png method will print the chart, along with the appropriate
218 http header, to stdout, allowing you to call chart-generating
219 scripts directly from your html pages (ie. with a <lt>img
220 src=image.pl<gt> HTML tag).
221 Produce a png image as a scalar
223 Like scalar_jpeg() the image is produced as a scalar so that the
224 programmer-user can do whatever the heck s/he wants to with it:
225 $obj-scalar_png($dataref)
227 Produce a jpeg image as a scalar
229 Like scalar_png() the image is produced as a scalar so that the
230 programmer-user can do whatever the heck s/he wants to with it:
231 $obj-scalar_jpeg($dataref)
233 Imagemap Support
235 Chart can also return the pixel positioning information so that you can
236 create image maps from the pngs Chart generates. Simply set the
237 'imagemap' option to 'true' before you generate the png, then call the
238 imagemap_dump() method afterwards to retrieve the information. You
239 will be returned a data structure almost identical to the @data array
240 described above to pass the data into Chart.
241 $imagemap_data = $obj->imagemap_dump ();
243 Instead of single data values, you will be passed references to arrays
245 of pixel information. For Bars, HorizontalBars and StackedBars charts,
246 the arrays will contain two x-y pairs (specifying the upper left and
247 lower right corner of the bar), like so
248 ( $x1, $y1, $x2, $y2 ) = @{ $imagemap_data->[$dataset][$datapoint] };
250 For Lines, Points, ErrorBars, Split and LinesPoints, the arrays will
252 contain a single x-y pair (specifying the center of the point), like so
253 ( $x, $y ) = @{ $imagemap_data->[$dataset][$datapoint] };
255 A few caveats apply here. First of all, GD treats the upper-left
257 corner of the png as the (0,0) point, so positive y values are measured
258 from the top of the png, not the bottom. Second, these values will
259 most likely contain long decimal values. GD, of course, has to
260 truncate these to single pixel values. Since I don't know how GD does
261 it, I can't truncate it the same way he does. In a worst-case
262 scenario, this will result in an error of one pixel on your imagemap.
263 If this is really an issue, your only option is to either experiment
264 with it, or to contact Lincoln Stein and ask him. Third, please
265 remember that the 0th dataset will be empty, since that's the place in
266 the @data array for the data point labels.
267
269 This module is currently under a complete rebuild, that will take place
270 in two phases. First: rewrite all functionality within a modular
271 architecture and hierarchical property system. This will be accessed
272 via a central API using the so far unutilized Chart module 'my $c =
273 Chart->new(...);'. This API will have in part different method and
274 property names, but the old API will not be touched. In a second phase
275 we will see hoch much new code can be used by the old modules and which
276 new features can be brought to the legacy parts, which will be than
277 discouraged, but not scrapped.
278
280 • Include True Type Fonts
281 • Violine and Box plots
283 • Add some 3-D graphs.
285 For more please check the TODO file.
287
289 Probably quite a few, since it's been completely rewritten. As usual,
290 please mail me with any bugs, patches, suggestions, comments, flames,
291 death threats, etc.
292
294 David Bonner (dbonner@cs.bu.edu)
295
297 • Chart Group (Chart@fs.wettzell.de)
298 • Herbert Breunung (lichtkind@cpan.org)
300
302 • Gregor Herrmann (gregoa@debian.org)
303 • Chris Dolan (chris+rt@chrisdolan.net)
305 • (jarmzet@yahoo.com)
307 • Ricardo Signes (rjbs@cpan.org)
309 • Petr Pisar (ppisar@redhat.com)
311
313 Copyright(c) 1997-1998 by David Bonner, 1999 by Peter Clark, 2001 by
314 the Chart group at BKG-Wettzell. 2022 by Herbert Breunung and Chart
315 group
316 All rights reserved. This program is free software; you can
318 redistribute it and/or modify it under the same terms as Perl itself.
319perl v5.36.0 2023-01-20 Chart(3)