| 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 |
|