Debian Codegraph @

README

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